python-hotspring 1.1.0__tar.gz → 1.3.0__tar.gz

{python_hotspring-1.1.0 → python_hotspring-1.3.0}/PKG-INFO

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

{python_hotspring-1.1.0 → python_hotspring-1.3.0}/pyproject.toml

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

{python_hotspring-1.1.0 → python_hotspring-1.3.0}/src/hotspring/__init__.py

@@ -6,6 +6,7 @@ from .const import (
     JetSpeed,
     LightColor,
     LightWheelMode,
+    SpaBrand,
     SpaFailureState,
     TemperatureUnit,
 )
@@ -58,6 +59,7 @@ __all__ = [
     "LightZone",
     "LogoLight",
     "Spa",
+    "SpaBrand",
     "SpaFailureState",
     "SpaInfo",
     "SpaLock",

{python_hotspring-1.1.0 → python_hotspring-1.3.0}/src/hotspring/const.py

@@ -235,3 +235,177 @@ class SpaFailureState(Enum):
 
 
 _FAILURE_STATE_MAP: dict[str, SpaFailureState] = {s.value: s for s in SpaFailureState}
+
+
+class SpaBrand(Enum):
+    """Brand of the spa (e.g. HotSpring, Caldera)."""
+
+    UNKNOWN = "Unknown"
+    HOTSPRING = "HotSpring"
+    CALDERA = "Caldera"
+
+    @classmethod
+    def build(cls, value: str | int | None) -> SpaBrand:
+        """Parse a raw API string or integer into a SpaBrand.
+
+        Args:
+        ----
+            value: The raw brand ID from the API, or None.
+
+        Returns:
+        -------
+            The matching SpaBrand enum.
+
+        """
+        if value is None:
+            return cls.UNKNOWN
+        try:
+            val_int = int(str(value).strip())
+        except ValueError:
+            return cls.UNKNOWN
+
+        if val_int == 0:
+            return cls.HOTSPRING
+        if val_int == 1:
+            return cls.CALDERA
+        return cls.UNKNOWN
+
+
+SPA_COLLECTION_MAP: dict[tuple[int, int], str] = {
+    # HotSpring (Brand 0)
+    (0, 0): "HighLife",
+    (0, 1): "Limelight",
+    (0, 2): "Hot Spot",
+    # Caldera (Brand 1)
+    (1, 1): "Utopia",
+    (1, 3): "Paradise",
+    (1, 4): "Vacanza",
+}
+
+SPA_MODEL_MAP: dict[tuple[int, int, int], str] = {
+    # Brand 0: HotSpring | Collection 0: HighLife
+    (0, 0, 0): "HotSpring HighLife",
+    (0, 0, 1): "HighLife Jetsetter",
+    (0, 0, 2): "HighLife Jetsetter Canada",
+    (0, 0, 3): "HighLife Jetsetter LX",
+    (0, 0, 4): "HighLife Prodigy",
+    (0, 0, 5): "HighLife Sovereign",
+    (0, 0, 6): "HighLife Aria",
+    (0, 0, 7): "HighLife Envoy",
+    (0, 0, 8): "HighLife Vanguard",
+    (0, 0, 9): "HighLife Grandee",
+    (0, 0, 10): "HighLife Jetsetter International",
+    (0, 0, 11): "HighLife Jetsetter LX International",
+    (0, 0, 12): "HighLife Prodigy International",
+    (0, 0, 13): "HighLife Sovereign International",
+    (0, 0, 14): "HighLife Aria International",
+    (0, 0, 15): "HighLife Envoy International",
+    (0, 0, 16): "HighLife Vanguard International",
+    (0, 0, 17): "HighLife Grandee International",
+    # Brand 0: HotSpring | Collection 1: Limelight
+    (0, 1, 0): "HotSpring Limelight",
+    (0, 1, 1): "Limelight Beam",
+    (0, 1, 2): "Limelight Beam II",
+    (0, 1, 3): "Limelight Beam International",
+    (0, 1, 4): "Limelight Beam Canada",
+    (0, 1, 5): "Limelight Strobe",
+    (0, 1, 6): "Limelight Strobe International",
+    (0, 1, 7): "Limelight Flair",
+    (0, 1, 8): "Limelight Flair International",
+    (0, 1, 9): "Limelight Flash",
+    (0, 1, 10): "Limelight Flash International",
+    (0, 1, 11): "Limelight Pulse",
+    (0, 1, 12): "Limelight Pulse International",
+    (0, 1, 13): "Limelight Prism",
+    (0, 1, 14): "Limelight Prism International",
+    # Brand 0: HotSpring | Collection 2: Hot Spot
+    (0, 2, 0): "Hot Spot Sx",
+    (0, 2, 1): "Hot Spot Tx",
+    (0, 2, 2): "Hot Spot Pace",
+    (0, 2, 3): "Hot Spot Stride",
+    (0, 2, 4): "Hot Spot Relay",
+    (0, 2, 5): "Hot Spot Rhythm",
+    (0, 2, 6): "Hot Spot Sx",
+    (0, 2, 7): "Hot Spot Tx",
+    (0, 2, 8): "Hot Spot Propel",
+    (0, 2, 9): "Hot Spot Stride",
+    (0, 2, 10): "Hot Spot Relay",
+    (0, 2, 11): "Hot Spot Rhythm",
+    # Brand 1: Caldera | Collection 1: Utopia
+    (1, 1, 0): "Caldera Utopia",
+    (1, 1, 1): "Utopia Ravello International",
+    (1, 1, 2): "Utopia Niagara International",
+    (1, 1, 3): "Utopia Tahitian International",
+    (1, 1, 4): "Utopia Florence International",
+    (1, 1, 5): "Utopia Geneva International",
+    (1, 1, 6): "Utopia Cantabria International",
+    (1, 1, 7): "Utopia Ravello",
+    (1, 1, 8): "Utopia Niagara",
+    (1, 1, 9): "Utopia Tahitian",
+    (1, 1, 10): "Utopia Florence",
+    (1, 1, 11): "Utopia Geneva",
+    (1, 1, 12): "Utopia Cantabria",
+    # Brand 1: Caldera | Collection 3: Paradise
+    (1, 3, 0): "Caldera Paradise",
+    (1, 3, 1): "Paradise Kauai",
+    (1, 3, 2): "Paradise Kauai International",
+    (1, 3, 3): "Paradise Martinique",
+    (1, 3, 4): "Paradise Martinique International",
+    (1, 3, 5): "Paradise Makena",
+    (1, 3, 6): "Paradise Makena International",
+    (1, 3, 7): "Paradise Salina",
+    (1, 3, 8): "Paradise Salina International",
+    (1, 3, 9): "Paradise Reunion",
+    (1, 3, 10): "Paradise Reunion International",
+    (1, 3, 11): "Paradise Seychelles",
+    (1, 3, 12): "Paradise Seychelles International",
+    # Brand 1: Caldera | Collection 4: Vacanza
+    (1, 4, 0): "Vacanza Aventine",
+    (1, 4, 1): "Vacanza Tarino",
+    (1, 4, 2): "Vacanza Capitolo",
+    (1, 4, 3): "Vacanza Celio",
+    (1, 4, 4): "Vacanza Platino",
+    (1, 4, 5): "Vacanza Vanto",
+    (1, 4, 6): "Vacanza Marino",
+    (1, 4, 7): "Vacanza Tarino_can",
+    (1, 4, 8): "Vacanza Aventine",
+    (1, 4, 9): "Vacanza Tarino",
+    (1, 4, 10): "Vacanza Capitolo",
+    (1, 4, 11): "Vacanza Celio",
+    (1, 4, 12): "Vacanza Marino",
+    (1, 4, 13): "Vacanza Platino",
+    (1, 4, 14): "Vacanza Vanto",
+}
+
+
+def resolve_spa_model(
+    brand_raw: str | int | None,
+    collection_raw: str | int | None,
+    model_raw: str | int | None,
+) -> tuple[SpaBrand, str, str]:
+    """Resolve raw API brand, collection, and model IDs to human-readable strings.
+
+    Args:
+    ----
+        brand_raw: Raw brand string or int from API (e.g. "0" or "1").
+        collection_raw: Raw collection string or int from API (e.g. "1").
+        model_raw: Raw model string or int from API (e.g. "4").
+
+    Returns:
+    -------
+        Tuple of (SpaBrand enum, collection name, model name).
+
+    """
+    brand = SpaBrand.build(brand_raw)
+
+    try:
+        brand_id = int(str(brand_raw)) if brand_raw is not None else -1
+        collection_id = int(str(collection_raw)) if collection_raw is not None else -1
+        model_id = int(str(model_raw)) if model_raw is not None else -1
+    except ValueError:
+        return (brand, "Unknown", "Unknown")
+
+    collection = SPA_COLLECTION_MAP.get((brand_id, collection_id), "Unknown")
+    model_name = SPA_MODEL_MAP.get((brand_id, collection_id, model_id), "Unknown")
+
+    return (brand, collection, model_name)

{python_hotspring-1.1.0 → python_hotspring-1.3.0}/src/hotspring/models.py

@@ -16,8 +16,10 @@ from .const import (
     JetSpeed,
     LightColor,
     LightWheelMode,
+    SpaBrand,
     SpaFailureState,
     TemperatureUnit,
+    resolve_spa_model,
 )
 
 
@@ -118,13 +120,20 @@ class Spa:
                 status = model_data.get("status", {})
                 if isinstance(status, dict):
                     if "brandName" in status:
-                        self.info.brand_name = str(status["brandName"])
+                        self.info.brand_id = str(status["brandName"])
                     if "collectionType" in status:
-                        self.info.collection_type = str(status["collectionType"])
+                        self.info.collection_id = str(status["collectionType"])
                     if "modelType" in status:
-                        self.info.model_type = str(status["modelType"])
+                        self.info.model_id = str(status["modelType"])
                     if "volume" in status:
                         self.info.volume = int(status["volume"] or 0)
+                    brand, collection, model_name = resolve_spa_model(
+                        self.info.brand_id, self.info.collection_id, self.info.model_id
+                    )
+                    self.info.brand = brand
+                    self.info.brand_name = brand.value
+                    self.info.collection = collection
+                    self.info.model_name = model_name
 
     def update_connection_status(self, data: dict[str, object]) -> None:
         """Update connection status from /spaConnectStatus response.
@@ -167,11 +176,25 @@ class SpaInfo:
     hostname: str
     root_topic: str
     sna_ready: bool
+    brand: SpaBrand
     brand_name: str
-    collection_type: str
-    model_type: str
+    collection: str
+    model_name: str
+    brand_id: str
+    collection_id: str
+    model_id: str
     volume: int
 
+    @property
+    def collection_type(self) -> str:
+        """Alias for collection_id for backward compatibility."""
+        return self.collection_id
+
+    @property
+    def model_type(self) -> str:
+        """Alias for model_id for backward compatibility."""
+        return self.model_id
+
     @staticmethod
     def from_dict(data: dict[str, object]) -> SpaInfo:
         """Create a SpaInfo from API response data.
@@ -192,16 +215,53 @@ class SpaInfo:
             if isinstance(status, dict):
                 model_status = status
 
+        brand_id = str(model_status.get("brandName", ""))
+        collection_id = str(model_status.get("collectionType", ""))
+        model_id = str(model_status.get("modelType", ""))
+        brand, collection, model_name = resolve_spa_model(
+            brand_id, collection_id, model_id
+        )
+
         return SpaInfo(
             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", "")),
+            brand=brand,
+            brand_name=brand.value,
+            collection=collection,
+            model_name=model_name,
+            brand_id=brand_id,
+            collection_id=collection_id,
+            model_id=model_id,
             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