python-hotspring 2.1.0__tar.gz → 3.0.0__tar.gz

{python_hotspring-2.1.0 → python_hotspring-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hotspring
-Version: 2.1.0
+Version: 3.0.0
 Summary: Asynchronous Python client for Hot Spring Connected Spa Kit 2.
 License: MIT
 License-File: LICENSE
@@ -46,6 +46,10 @@ Asynchronous Python client for Hot Spring Connected Spa Kit 2.
 > This library is currently in heavy development. Not all features might work
 > perfectly, and some features may not be fully tested as they depend on the
 > physical hardware available for testing.
+>
+> The spa's energy consumption estimates (watts, power draw) are not accurate
+> and are most likely incorrect, as the power calculation registers have not
+> been fully reverse-engineered.
 
 ## About
 
@@ -66,18 +70,13 @@ It is primarily designed to be used as the communication layer for an official
   plus the logo light
 - **Water care** — Monitor FreshWater IQ salt system metrics (pH, chlorine,
   ORP, sensor life)
-- **Diagnostics** — Read voltage, power consumption, and failure states
+- **Diagnostics & Test Metrics** — Read raw hardware test point currents, line voltages,
+  sensor flow/switch states, and failure diagnostics
+- **Runtime Tracking** — Cumulative heater runtime and individual jet pump runtime in hours
 - **Connection monitoring** — Check LoRA bridge and cloud connectivity status
 - **Energy saving schedules** — View configured energy saving time windows
 - **Clean cycle** — Start or stop the 10-minute clean cycle
 
-> [!CAUTION]
-> The spa's energy consumption and usage metrics are not always accurate. Most
-> values related to power (including current, amp, volt, etc) and values based
-> on time (like the amount of time the jet have been turned on) are most likely
-> incorrect, as I have not been able to fully reverse engineer these aspects of
-> the API.
-
 ### Compatible Spas
 
 This library works with any Hot Spring, Caldera, or Freeflow spa that supports

{python_hotspring-2.1.0 → python_hotspring-3.0.0}/README.md

@@ -13,6 +13,10 @@ Asynchronous Python client for Hot Spring Connected Spa Kit 2.
 > This library is currently in heavy development. Not all features might work
 > perfectly, and some features may not be fully tested as they depend on the
 > physical hardware available for testing.
+>
+> The spa's energy consumption estimates (watts, power draw) are not accurate
+> and are most likely incorrect, as the power calculation registers have not
+> been fully reverse-engineered.
 
 ## About
 
@@ -33,18 +37,13 @@ It is primarily designed to be used as the communication layer for an official
   plus the logo light
 - **Water care** — Monitor FreshWater IQ salt system metrics (pH, chlorine,
   ORP, sensor life)
-- **Diagnostics** — Read voltage, power consumption, and failure states
+- **Diagnostics & Test Metrics** — Read raw hardware test point currents, line voltages,
+  sensor flow/switch states, and failure diagnostics
+- **Runtime Tracking** — Cumulative heater runtime and individual jet pump runtime in hours
 - **Connection monitoring** — Check LoRA bridge and cloud connectivity status
 - **Energy saving schedules** — View configured energy saving time windows
 - **Clean cycle** — Start or stop the 10-minute clean cycle
 
-> [!CAUTION]
-> The spa's energy consumption and usage metrics are not always accurate. Most
-> values related to power (including current, amp, volt, etc) and values based
-> on time (like the amount of time the jet have been turned on) are most likely
-> incorrect, as I have not been able to fully reverse engineer these aspects of
-> the API.
-
 ### Compatible Spas
 
 This library works with any Hot Spring, Caldera, or Freeflow spa that supports

{python_hotspring-2.1.0 → python_hotspring-3.0.0}/pyproject.toml

@@ -22,7 +22,8 @@ packages = [
 ]
 readme = "README.md"
 repository = "https://github.com/Moustachauve/python-hotspring"
-version = "2.1.0"
+# The CI/CD and GitHub Actions release workflows are responsible for setting the version tag
+version = "3.0.0"
 
 [tool.poetry.dependencies]
 aiohttp = ">=3.0.0"
@@ -50,6 +51,7 @@ pytest-cov = "7.1.0"
 ruff = "0.15.11"
 safety = "3.7.0"
 yamllint = "1.38.0"
+syrupy = "^6.0.0"
 
 [tool.coverage.run]
 plugins = ["covdefaults"]

{python_hotspring-2.1.0 → python_hotspring-3.0.0}/src/hotspring/__init__.py

@@ -3,8 +3,10 @@
 from .const import (
     BrightnessLevel,
     DeviceType,
+    EnergySavingMode,
     HeatingMode,
     JetSpeed,
+    JetSpeedType,
     LightColor,
     LightWheelMode,
     SpaBrand,
@@ -35,6 +37,7 @@ from .models import (
     Spa,
     SpaInfo,
     SpaLock,
+    SpaTestData,
     Versions,
     WaterCare,
 )
@@ -47,6 +50,7 @@ __all__ = [
     "DeviceType",
     "Diagnostics",
     "EnergySaving",
+    "EnergySavingMode",
     "FreshWaterIQ",
     "Heater",
     "HeatingMode",
@@ -60,6 +64,7 @@ __all__ = [
     "HotSpringSNADetectedError",
     "Jet",
     "JetSpeed",
+    "JetSpeedType",
     "LightColor",
     "LightWheelMode",
     "LightZone",
@@ -69,6 +74,7 @@ __all__ = [
     "SpaFailureState",
     "SpaInfo",
     "SpaLock",
+    "SpaTestData",
     "TemperatureUnit",
     "Versions",
     "WaterCare",

{python_hotspring-2.1.0 → python_hotspring-3.0.0}/src/hotspring/const.py

@@ -75,6 +75,35 @@ class JetSpeed(Enum):
 _JET_SPEED_MAP: dict[str, JetSpeed] = {s.value: s for s in JetSpeed}
 
 
+class JetSpeedType(Enum):
+    """Configured speed capability of a jet pump."""
+
+    UNKNOWN = "unknown"
+    SINGLE_SPEED = "singleSpeed"
+    DUAL_SPEED = "dualSpeed"
+
+    @classmethod
+    def build(cls, value: str | None) -> JetSpeedType:
+        """Parse a raw API string into a JetSpeedType.
+
+        Args:
+        ----
+            value: The raw speed configuration string from the API, or None.
+
+        Returns:
+        -------
+            The matching JetSpeedType, or JetSpeedType.UNKNOWN for
+            unrecognized values.
+
+        """
+        if value is None:
+            return cls.UNKNOWN
+        return _JET_SPEED_TYPE_MAP.get(value, cls.UNKNOWN)
+
+
+_JET_SPEED_TYPE_MAP: dict[str, JetSpeedType] = {t.value: t for t in JetSpeedType}
+
+
 class LightColor(Enum):
     """Color setting for a spa light zone.
 
@@ -153,12 +182,13 @@ class BrightnessLevel(Enum):
     """
 
     UNKNOWN = "unknown"
+    AUTO = "auto"
     LEVEL_1 = "brightness_level_1"
     LEVEL_2 = "brightness_level_2"
     LEVEL_3 = "brightness_level_3"
 
     @classmethod
-    def build(cls, value: str | None) -> BrightnessLevel:
+    def build(cls, value: str | int | None) -> BrightnessLevel:
         """Parse a raw API string into a BrightnessLevel.
 
         Args:
@@ -173,10 +203,49 @@ class BrightnessLevel(Enum):
         """
         if value is None:
             return cls.UNKNOWN
-        return _BRIGHTNESS_MAP.get(value, cls.UNKNOWN)
+        val_str = str(value).strip().lower()
+        return _BRIGHTNESS_MAP.get(val_str, cls.UNKNOWN)
 
 
 _BRIGHTNESS_MAP: dict[str, BrightnessLevel] = {b.value: b for b in BrightnessLevel}
+_BRIGHTNESS_MAP.update(
+    {
+        "1": BrightnessLevel.LEVEL_1,
+        "2": BrightnessLevel.LEVEL_2,
+        "3": BrightnessLevel.LEVEL_3,
+        "auto": BrightnessLevel.AUTO,
+    }
+)
+
+_BRIGHTNESS_TO_WIRE: dict[BrightnessLevel, str] = {
+    BrightnessLevel.LEVEL_1: "1",
+    BrightnessLevel.LEVEL_2: "2",
+    BrightnessLevel.LEVEL_3: "3",
+    BrightnessLevel.AUTO: "auto",
+}
+
+MAX_ENERGY_SAVING_SCHEDULES = 2
+VALID_ENERGY_SAVING_SCHEDULE_IDS = (1, 2)
+
+
+class EnergySavingMode(Enum):
+    """Energy saving schedule mode."""
+
+    UNKNOWN = "unknown"
+    OFF = "off"
+    ON = "on"
+
+    @classmethod
+    def build(cls, value: object) -> EnergySavingMode:
+        """Parse raw mode from API into EnergySavingMode."""
+        if value is None:
+            return cls.UNKNOWN
+        val_str = str(value).strip().lower()
+        if val_str in ("1", "on", "enable", "true"):
+            return cls.ON
+        if val_str in ("0", "off", "disable", "false"):
+            return cls.OFF
+        return cls.UNKNOWN
 
 
 class TemperatureUnit(Enum):