python-hotspring 1.0.1__tar.gz → 1.2.0__tar.gz

{python_hotspring-1.0.1 → python_hotspring-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hotspring
-Version: 1.0.1
+Version: 1.2.0
 Summary: Asynchronous Python client for Hot Spring Connected Spa Kit 2.
 License: MIT
 License-File: LICENSE
@@ -71,6 +71,13 @@ It is primarily designed to be used as the communication layer for an official
 - **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-1.0.1 → python_hotspring-1.2.0}/README.md

@@ -38,6 +38,13 @@ It is primarily designed to be used as the communication layer for an official
 - **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-1.0.1 → python_hotspring-1.2.0}/pyproject.toml

@@ -22,7 +22,7 @@ packages = [
 ]
 readme = "README.md"
 repository = "https://github.com/Moustachauve/python-hotspring"
-version = "1.0.1"
+version = "1.2.0"
 
 [tool.poetry.dependencies]
 aiohttp = ">=3.0.0"

{python_hotspring-1.0.1 → python_hotspring-1.2.0}/src/hotspring/const.py

@@ -30,7 +30,7 @@ class HeatingMode(Enum):
         Returns:
         -------
             The matching HeatingMode, or HeatingMode.UNKNOWN for
-            unrecognised values.
+            unrecognized values.
 
         """
         if value is None:
@@ -64,7 +64,7 @@ class JetSpeed(Enum):
         Returns:
         -------
             The matching JetSpeed, or JetSpeed.UNKNOWN for
-            unrecognised values.
+            unrecognized values.
 
         """
         if value is None:
@@ -105,7 +105,7 @@ class LightColor(Enum):
         Returns:
         -------
             The matching LightColor, or LightColor.UNKNOWN for
-            unrecognised values.
+            unrecognized values.
 
         """
         if value is None:
@@ -136,7 +136,7 @@ class LightWheelMode(Enum):
         Returns:
         -------
             The matching LightWheelMode, or LightWheelMode.UNKNOWN for
-            unrecognised values.
+            unrecognized values.
 
         """
         if value is None:
@@ -169,7 +169,7 @@ class BrightnessLevel(Enum):
         Returns:
         -------
             The matching BrightnessLevel, or BrightnessLevel.UNKNOWN for
-            unrecognised values.
+            unrecognized values.
 
         """
         if value is None:
@@ -198,7 +198,7 @@ class TemperatureUnit(Enum):
         Returns:
         -------
             The matching TemperatureUnit, or TemperatureUnit.UNKNOWN for
-            unrecognised values.
+            unrecognized values.
 
         """
         if value is None:
@@ -226,7 +226,7 @@ class SpaFailureState(Enum):
         Returns:
         -------
             The matching SpaFailureState, or SpaFailureState.UNKNOWN for
-            unrecognised values.
+            unrecognized values.
 
         """
         if value is None:

{python_hotspring-1.0.1 → python_hotspring-1.2.0}/src/hotspring/hotspring.py

@@ -169,11 +169,21 @@ class HotSpring:
             self.spa.update_from_dict(status_data)
 
         # Fetch identity/startup info
+        identity_data: dict[str, object] = {}
         try:
             startup_data = await self.request("/startup")
-            self.spa.update_info(startup_data)
+            identity_data.update(startup_data)
         except HotSpringError:
-            pass  # Non-critical; identity may already be populated
+            pass
+
+        try:
+            model_data = await self.request("/spamodel")
+            identity_data.update(model_data)
+        except HotSpringError:
+            pass
+
+        if identity_data:
+            self.spa.update_info(identity_data)
 
         # Fetch connection status
         try:

{python_hotspring-1.0.1 → python_hotspring-1.2.0}/src/hotspring/models.py

@@ -42,6 +42,7 @@ class Spa:
     versions: Versions
     connection_status: ConnectionStatus
     diagnostics: Diagnostics
+    test_metrics: SpaTestData
 
     def __init__(self, data: dict[str, object]) -> None:
         """Initialize a Spa from the full API response.
@@ -74,6 +75,7 @@ class Spa:
         self.spa_lock = SpaLock.from_dict(data.get("spaLock", {}))
         self.water_care = WaterCare.from_dict(data.get("waterCare", {}))
         self.freshwater_iq = FreshWaterIQ.from_dict(data.get("FWIQ_Parameters", {}))
+        self.test_metrics = SpaTestData.from_dict(data.get("test_data", {}))
         self.energy_savings = EnergySaving.list_from_dict(data.get("energySavings", {}))
         self.versions = Versions.from_dict(
             data.get("productVersions", {}).get("status", {})
@@ -85,6 +87,8 @@ class Spa:
             self.connection_status = ConnectionStatus.from_dict({})
         if not hasattr(self, "diagnostics"):
             self.diagnostics = Diagnostics.from_dict({})
+        if not hasattr(self, "test_metrics"):
+            self.test_metrics = SpaTestData.from_dict({})
 
         return self
 
@@ -96,7 +100,31 @@ class Spa:
             data: Combined data from /startup and /spamodel endpoints.
 
         """
-        self.info = SpaInfo.from_dict(data)
+        if not hasattr(self, "info"):
+            self.info = SpaInfo.from_dict(data)
+            return
+
+        # Update existing info fields if present in data
+        if "HOSTNAME" in data:
+            self.info.hostname = str(data["HOSTNAME"])
+        if "rootTopic" in data:
+            self.info.root_topic = str(data["rootTopic"])
+        if "SNAready" in data:
+            self.info.sna_ready = data["SNAready"] in ("Ready", "Yes")
+
+        if "SPAModelData" in data:
+            model_data = data["SPAModelData"]
+            if isinstance(model_data, dict):
+                status = model_data.get("status", {})
+                if isinstance(status, dict):
+                    if "brandName" in status:
+                        self.info.brand_name = str(status["brandName"])
+                    if "collectionType" in status:
+                        self.info.collection_type = str(status["collectionType"])
+                    if "modelType" in status:
+                        self.info.model_type = str(status["modelType"])
+                    if "volume" in status:
+                        self.info.volume = int(status["volume"] or 0)
 
     def update_connection_status(self, data: dict[str, object]) -> None:
         """Update connection status from /spaConnectStatus response.
@@ -137,10 +165,12 @@ class SpaInfo:
     """
 
     hostname: str
-    mac_address: str
-    model: str
-    ssid: str
+    root_topic: str
     sna_ready: bool
+    brand_name: str
+    collection_type: str
+    model_type: str
+    volume: int
 
     @staticmethod
     def from_dict(data: dict[str, object]) -> SpaInfo:
@@ -155,14 +185,49 @@ class SpaInfo:
             A SpaInfo instance.
 
         """
+        model_status: dict[str, object] = {}
+        model_data = data.get("SPAModelData")
+        if isinstance(model_data, dict):
+            status = model_data.get("status")
+            if isinstance(status, dict):
+                model_status = status
+
         return SpaInfo(
-            hostname=data.get("HOSTNAME", ""),
-            mac_address=data.get("MAC", ""),
-            model=data.get("model", ""),
-            ssid=data.get("SSID", ""),
+            hostname=str(data.get("HOSTNAME", "")),
+            root_topic=str(data.get("rootTopic", "")),
             sna_ready=data.get("SNAready", "") in ("Ready", "Yes"),
+            brand_name=str(model_status.get("brandName", "")),
+            collection_type=str(model_status.get("collectionType", "")),
+            model_type=str(model_status.get("modelType", "")),
+            volume=int(model_status.get("volume") or 0),
         )
 
+    @property
+    def mac_address(self) -> str:
+        """Derive the MAC address from root_topic.
+
+        The HNA firmware builds root_topic as ``mySpa%02X%02X%02X%02X%02X%02X``
+        using the device's 6-byte WiFi MAC, so the 12 hex characters after the
+        ``mySpa`` prefix are the full MAC address.
+
+        Returns
+        -------
+            Colon-separated uppercase MAC (e.g. ``"AA:BB:CC:11:22:33"``),
+            or ``""`` if root_topic does not match the expected format.
+
+        """
+        prefix = "mySpa"
+        if not self.root_topic.startswith(prefix):
+            return ""
+        mac_hex = self.root_topic[len(prefix) :]
+        try:
+            mac_bytes = bytes.fromhex(mac_hex)
+        except ValueError:
+            return ""
+        if len(mac_bytes) != 6:
+            return ""
+        return ":".join(f"{b:02X}" for b in mac_bytes)
+
 
 @dataclass
 class Heater:  # pylint: disable=too-many-instance-attributes
@@ -172,8 +237,8 @@ class Heater:  # pylint: disable=too-many-instance-attributes
     heater_lock: bool
     heatpump_installed: bool
     heating_mode: HeatingMode
-    heater_current: int
-    heater_hours: int
+    heater_current: float
+    heater_on_seconds: int
     set_temperature: float | None
     current_temperature: float | None
     temperature_unit: TemperatureUnit
@@ -198,8 +263,8 @@ class Heater:  # pylint: disable=too-many-instance-attributes
             heatpump_installed=status.get("heatpumpInstalled", "notinstalled")
             != "notinstalled",
             heating_mode=HeatingMode.build(status.get("heatingMode")),
-            heater_current=int(status.get("heaterCurrent", 0)),
-            heater_hours=int(status.get("heaterHours", 0)),
+            heater_current=int(status.get("heaterCurrent", 0)) / 2560.0,
+            heater_on_seconds=int(status.get("heaterHours", 0)) // 256,
             set_temperature=_parse_temperature(status.get("setWaterTemperature")),
             current_temperature=_parse_temperature(
                 status.get("currentWaterTemperature")
@@ -240,7 +305,7 @@ class Jet:
 
         # Find the on_seconds key dynamically (e.g., jet_1_ON_sec)
         on_sec_key = f"jet_{jet_id}_ON_sec"
-        on_seconds = int(status.get(on_sec_key, 0))
+        on_seconds = int(status.get(on_sec_key, 0)) // 256
 
         return Jet(
             jet_id=jet_id,
@@ -462,7 +527,6 @@ class WaterCare:  # pylint: disable=too-many-instance-attributes
     system_enabled: bool
     ace_mode: str
     boost_active: bool
-    salt_level: str
     salt_value: int
 
     @staticmethod
@@ -486,9 +550,8 @@ class WaterCare:  # pylint: disable=too-many-instance-attributes
             one_twenty_day_timer=int(status.get("120DayTimer", 0)),
             level=int(status.get("level", 0)),
             system_enabled=status.get("SystemEnable", "disable") == "enable",
-            ace_mode=status.get("AceMode", "inactive"),
+            ace_mode=str(status.get("AceMode", "inactive")),
             boost_active=status.get("boost", "inactive") != "inactive",
-            salt_level=status.get("saltLevel", ""),
             salt_value=int(status.get("saltValue", 0)),
         )
 
@@ -676,6 +739,45 @@ class ConnectionStatus:
         )
 
 
+@dataclass
+class SpaTestData:
+    """Test data metrics from the spa, including raw current readings."""
+
+    heater_test_status: str
+    temp_offset: float
+    vsense_cal: float
+    jet1_jet2_blower_current: float
+    small_loads_current: float
+    heater_current: float
+    jet3_current: float
+
+    @staticmethod
+    def from_dict(data: dict[str, object]) -> SpaTestData:
+        """Create a SpaTestData from API response data.
+
+        Args:
+        ----
+            data: The ``test_data`` dict from the /status response.
+
+        Returns:
+        -------
+            A SpaTestData instance.
+
+        """
+        status = data.get("status", {})
+        return SpaTestData(
+            heater_test_status=str(status.get("heaterTestStatus", "off")),
+            temp_offset=float(status.get("tempOffset", 0.0)),
+            vsense_cal=float(status.get("VsenseCal", 0.0)),
+            jet1_jet2_blower_current=(
+                int(status.get("jet1+jet2+blowerCurrent", 0)) / 2560.0
+            ),
+            small_loads_current=int(status.get("smallLoadsCurrent", 0)) / 2560.0,
+            heater_current=int(status.get("heaterCurrent", 0)) / 2560.0,
+            jet3_current=int(status.get("jet3Current", 0)) / 2560.0,
+        )
+
+
 @dataclass
 class Diagnostics:  # pylint: disable=too-many-instance-attributes
     """Diagnostic and power metrics from the spa.
@@ -689,10 +791,10 @@ class Diagnostics:  # pylint: disable=too-many-instance-attributes
     heater_error: str
     power_frequency: str
     pressure_switch_status: str
-    l1_n_volts: str
-    l2_n_volts: str
-    heater_volts: str
-    jet3_volts: str
+    l1_n_volts: float
+    l2_n_volts: float
+    heater_volts: float
+    jet3_volts: float
     jet1_jet2_blower_power: str
     small_loads_power: str
     heater_power: str
@@ -718,10 +820,13 @@ class Diagnostics:  # pylint: disable=too-many-instance-attributes
             heater_error=debug.get("heaterError", "0"),
             power_frequency=debug.get("powerFrequency", "0"),
             pressure_switch_status=debug.get("pressureSwitchStatus", "0"),
-            l1_n_volts=debug.get("L1_N_Volts", "0"),
-            l2_n_volts=debug.get("L2_N_Volts", "0"),
-            heater_volts=debug.get("Heater_Volts", "0"),
-            jet3_volts=debug.get("jet3_Volts", "0"),
+            # NOTE: The /32 scaling for volts is likely incorrect for all models or
+            # specific configurations, as real-world readings (e.g., 56V on L2)
+            # do not match expectations. This needs further investigation.
+            l1_n_volts=int(debug.get("L1_N_Volts") or 0) / 32.0,
+            l2_n_volts=int(debug.get("L2_N_Volts") or 0) / 32.0,
+            heater_volts=int(debug.get("Heater_Volts") or 0) / 32.0,
+            jet3_volts=int(debug.get("jet3_Volts") or 0) / 32.0,
             jet1_jet2_blower_power=debug.get("jet1_jet2_blowerPower", "0"),
             small_loads_power=debug.get("smallLoadsPower", "0"),
             heater_power=debug.get("heaterPower", "0"),