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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hotspring
-Version: 2.0.1
+Version: 2.1.0
 Summary: Asynchronous Python client for Hot Spring Connected Spa Kit 2.
 License: MIT
 License-File: LICENSE

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

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

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

@@ -2,6 +2,7 @@
 
 from .const import (
     BrightnessLevel,
+    DeviceType,
     HeatingMode,
     JetSpeed,
     LightColor,
@@ -15,7 +16,9 @@ from .exceptions import (
     HotSpringConnectionError,
     HotSpringConnectionTimeoutError,
     HotSpringError,
+    HotSpringInvalidDeviceError,
     HotSpringNotReadyError,
+    HotSpringSNADetectedError,
 )
 from .hotspring import HotSpring
 from .models import (
@@ -41,6 +44,7 @@ __all__ = [
     "BrightnessLevel",
     "CleanCycle",
     "ConnectionStatus",
+    "DeviceType",
     "Diagnostics",
     "EnergySaving",
     "FreshWaterIQ",
@@ -51,7 +55,9 @@ __all__ = [
     "HotSpringConnectionError",
     "HotSpringConnectionTimeoutError",
     "HotSpringError",
+    "HotSpringInvalidDeviceError",
     "HotSpringNotReadyError",
+    "HotSpringSNADetectedError",
     "Jet",
     "JetSpeed",
     "LightColor",

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

@@ -408,3 +408,36 @@ def resolve_spa_model(
     model_name = SPA_MODEL_MAP.get((brand_id, collection_id, model_id), "Unknown")
 
     return (brand, collection, model_name)
+
+
+class DeviceType(Enum):
+    """Connected Spa kit adapter device type.
+
+    The Connected Spa Kit 2 consists of two modules:
+    - HNA (Home Network Adapter): Connected to home network, acts as API bridge.
+    - SNA (Spa Network Adapter): Located in the tub, physically wired to controller.
+    """
+
+    UNKNOWN = "unknown"
+    HNA = "hna"
+    SNA = "sna"
+
+    @classmethod
+    def build(cls, value: str | None) -> DeviceType:
+        """Parse a raw string into a DeviceType.
+
+        Args:
+        ----
+            value: The raw device type string, or None.
+
+        Returns:
+        -------
+            The matching DeviceType, or DeviceType.UNKNOWN for unrecognized values.
+
+        """
+        if value is None:
+            return cls.UNKNOWN
+        return _DEVICE_TYPE_MAP.get(value.lower(), cls.UNKNOWN)
+
+
+_DEVICE_TYPE_MAP: dict[str, DeviceType] = {d.value: d for d in DeviceType}

{python_hotspring-2.0.1 → python_hotspring-2.1.0}/src/hotspring/exceptions.py

@@ -26,3 +26,18 @@ class HotSpringCommandError(HotSpringError):
 
     Raised when a command sent to the spa is rejected or fails.
     """
+
+
+class HotSpringInvalidDeviceError(HotSpringError):
+    """Hot Spring invalid device exception.
+
+    Raised when attempting to connect to or command an unsupported device.
+    """
+
+
+class HotSpringSNADetectedError(HotSpringInvalidDeviceError):
+    """Hot Spring SNA detected exception.
+
+    Raised when connecting to a Spa Network Adapter (SNA) instead of
+    the Home Network Adapter (HNA). The HNA must be used as the API bridge.
+    """

{python_hotspring-2.0.1 → python_hotspring-2.1.0}/src/hotspring/hotspring.py

@@ -24,6 +24,7 @@ from .exceptions import (
     HotSpringConnectionTimeoutError,
     HotSpringError,
     HotSpringNotReadyError,
+    HotSpringSNADetectedError,
 )
 from .models import (
     ConnectionStatus,
@@ -54,6 +55,7 @@ class HotSpring:
     host: str
     session: aiohttp.ClientSession | None = None
     request_timeout: float = 10.0
+    validate_device: bool = True
     _close_session: bool = False
     _identity_loaded: bool = False
     spa: Spa | None = None
@@ -181,6 +183,8 @@ class HotSpring:
 
         Raises:
         ------
+            HotSpringSNADetectedError: If connected to a Spa Network Adapter (SNA)
+                and ``validate_device`` is True.
             HotSpringError: If no data is returned from the spa.
 
         """
@@ -206,6 +210,15 @@ class HotSpring:
             if connect_res:
                 self.spa.update_connection_status(connect_res)
 
+            if self.validate_device and self.spa.info.is_sna:
+                msg = (
+                    f"Connected to Spa Network Adapter (SNA) with hostname "
+                    f"'{self.spa.info.hostname}'. The Home Network Adapter (HNA) "
+                    f"with root topic '{self.spa.info.root_topic}' must be "
+                    f"used instead."
+                )
+                raise HotSpringSNADetectedError(msg)
+
             self._identity_loaded = True
             return self.spa
 
@@ -224,6 +237,26 @@ class HotSpring:
 
         return self.spa
 
+    async def get_device_info(self) -> SpaInfo:
+        """Fetch lightweight device identity directly from /startup.
+
+        Useful for discovery and pre-flight device validation without querying
+        the spa controller or LoRA radio endpoints.
+
+        Returns
+        -------
+            A SpaInfo instance parsed from the /startup response.
+
+        Raises
+        ------
+            HotSpringConnectionError: If connection fails.
+            HotSpringConnectionTimeoutError: If request times out.
+            HotSpringError: If the response is invalid.
+
+        """
+        data = await self.request("/startup")
+        return SpaInfo.from_dict(data)
+
     async def update_identity(self) -> SpaInfo:
         """Fetch and update static spa identity info (/startup and /spamodel).
 
@@ -233,6 +266,8 @@ class HotSpring:
 
         Raises
         ------
+            HotSpringSNADetectedError: If connected to a Spa Network Adapter (SNA)
+                and ``validate_device`` is True.
             HotSpringError: If the spa has not been initialized with update().
 
         """
@@ -254,6 +289,15 @@ class HotSpring:
         if identity_data:
             self.spa.update_info(identity_data)
 
+        if self.validate_device and self.spa.info.is_sna:
+            msg = (
+                f"Connected to Spa Network Adapter (SNA) with hostname "
+                f"'{self.spa.info.hostname}'. The Home Network Adapter (HNA) "
+                f"with root topic '{self.spa.info.root_topic}' must be "
+                f"used instead."
+            )
+            raise HotSpringSNADetectedError(msg)
+
         self._identity_loaded = True
         return self.spa.info
 

{python_hotspring-2.0.1 → python_hotspring-2.1.0}/src/hotspring/models.py

@@ -13,6 +13,7 @@ from typing import TYPE_CHECKING, NamedTuple
 
 from .const import (
     BrightnessLevel,
+    DeviceType,
     HeatingMode,
     JetSpeed,
     LightColor,
@@ -302,6 +303,44 @@ class SpaInfo:
             return ""
         return ":".join(f"{b:02X}" for b in mac_bytes)
 
+    @property
+    def device_type(self) -> DeviceType:
+        """Determine whether the device is an HNA or SNA.
+
+        The HNA (Home Network Adapter) is the intended API bridge.
+        The SNA (Spa Network Adapter) is the tub-side module.
+
+        On the HNA, the hostname suffix (last 6 characters, e.g. from
+        'ConnectedSpa_112233') matches the last 6 characters of the root_topic
+        (e.g. 'mySpaAABBCC112233').
+        On the SNA, root_topic still points to the paired HNA topic, but
+        the hostname reflects the SNA's own MAC address.
+
+        Returns
+        -------
+            DeviceType.HNA if hostname matches root_topic,
+            DeviceType.SNA if hostname differs from root_topic,
+            DeviceType.UNKNOWN if information is missing.
+
+        """
+        if not self.hostname or not self.root_topic:
+            return DeviceType.UNKNOWN
+
+        mac_suffix = self.hostname.rsplit("_", 1)[-1]
+        if self.root_topic.lower().endswith(mac_suffix.lower()):
+            return DeviceType.HNA
+        return DeviceType.SNA
+
+    @property
+    def is_hna(self) -> bool:
+        """Return True if this device is the Home Network Adapter (HNA)."""
+        return self.device_type == DeviceType.HNA
+
+    @property
+    def is_sna(self) -> bool:
+        """Return True if this device is the Spa Network Adapter (SNA)."""
+        return self.device_type == DeviceType.SNA
+
 
 @dataclass
 class Heater:  # pylint: disable=too-many-instance-attributes