python-hotspring 1.2.0__py3-none-any.whl → 2.0.0__py3-none-any.whl

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",

hotspring/const.py

@@ -82,8 +82,7 @@ class LightColor(Enum):
     """
 
     UNKNOWN = "unknown"
-    OFF = "WHEEL_OFF"
-    ON = "WHEEL_ON"
+    CUSTOM = "CUSTOM"
     RED = "RED"
     BLUE = "BLUE"
     GREEN = "GREEN"
@@ -96,7 +95,7 @@ class LightColor(Enum):
     def build(cls, value: str | None) -> LightColor:
         """Parse a raw API string into a LightColor.
 
-        Case-insensitive matching (real API returns e.g. "BLUE").
+        Case-insensitive matching (real API returns e.g. "BLUE", "custom").
 
         Args:
         ----
@@ -235,3 +234,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)

hotspring/hotspring.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import asyncio
+import contextlib
 import json
 from dataclasses import dataclass
 from typing import Self
@@ -11,6 +12,12 @@ import aiohttp
 import backoff
 from yarl import URL
 
+from .const import (
+    HeatingMode,
+    JetSpeed,
+    LightColor,
+    LightWheelMode,
+)
 from .exceptions import (
     HotSpringCommandError,
     HotSpringConnectionError,
@@ -23,6 +30,7 @@ from .models import (
     Diagnostics,
     FreshWaterIQ,
     Spa,
+    SpaInfo,
 )
 
 
@@ -47,6 +55,7 @@ class HotSpring:
     session: aiohttp.ClientSession | None = None
     request_timeout: float = 10.0
     _close_session: bool = False
+    _identity_loaded: bool = False
     spa: Spa | None = None
 
     @backoff.on_exception(
@@ -144,55 +153,102 @@ class HotSpring:
 
         return response_data
 
-    async def update(self) -> Spa:
-        """Get all spa information in a single polling cycle.
+    async def _safe_request(self, uri: str) -> dict[str, object] | None:
+        """Fetch an endpoint, returning None on error."""
+        with contextlib.suppress(HotSpringError):
+            return await self.request(uri)
+        return None
 
-        This method fetches the main /status endpoint and combines it with
-        identity information from /startup and /spamodel. Use this for
-        the primary 15-second polling cycle.
+    async def update(self, *, refresh_identity: bool = False) -> Spa:
+        """Get all spa information.
 
-        Returns
+        On the initial call (or when `refresh_identity=True`), this method fetches
+        the main /status endpoint concurrently with /startup, /spaConnectStatus,
+        and /spamodel.
+
+        On subsequent routine polling cycles, it only queries the fast /status
+        endpoint, avoiding redundant radio (LoRA) queries for static identity data.
+
+        Args:
+        ----
+            refresh_identity: Force re-fetching static identity from /startup
+                and /spamodel.
+
+        Returns:
         -------
             The updated Spa data object.
 
-        Raises
+        Raises:
         ------
             HotSpringError: If no data is returned from the spa.
 
         """
-        # Fetch main status
+        if not self._identity_loaded or refresh_identity:
+            status_res, startup_res, connect_res, model_res = await asyncio.gather(
+                self.request("/status"),
+                self._safe_request("/startup"),
+                self._safe_request("/spaConnectStatus"),
+                self._safe_request("/spamodel"),
+            )
+
+            if self.spa is None:
+                self.spa = Spa(status_res)
+            else:
+                self.spa.update_from_dict(status_res)
+
+            if startup_res:
+                self.spa.update_info(startup_res)
+
+            if model_res:
+                self.spa.update_info(model_res)
+
+            if connect_res:
+                self.spa.update_connection_status(connect_res)
+
+            self._identity_loaded = True
+            return self.spa
+
         status_data = await self.request("/status")
 
-        if self.spa is None:
+        if self.spa is None:  # Safety guard; spa is always set after cold sync
             self.spa = Spa(status_data)
         else:
             self.spa.update_from_dict(status_data)
 
-        # Fetch identity/startup info
-        identity_data: dict[str, object] = {}
-        try:
-            startup_data = await self.request("/startup")
-            identity_data.update(startup_data)
-        except HotSpringError:
-            pass
+        return self.spa
 
-        try:
-            model_data = await self.request("/spamodel")
-            identity_data.update(model_data)
-        except HotSpringError:
-            pass
+    async def update_identity(self) -> SpaInfo:
+        """Fetch and update static spa identity info (/startup and /spamodel).
+
+        Returns
+        -------
+            The updated SpaInfo data.
+
+        Raises
+        ------
+            HotSpringError: If the spa has not been initialized with update().
+
+        """
+        if self.spa is None:
+            msg = "Call update() before update_identity()"
+            raise HotSpringError(msg)
+
+        startup_res, model_res = await asyncio.gather(
+            self._safe_request("/startup"),
+            self._safe_request("/spamodel"),
+        )
+
+        identity_data: dict[str, object] = {}
+        if startup_res:
+            identity_data.update(startup_res)
+        if model_res:
+            identity_data.update(model_res)
 
         if identity_data:
             self.spa.update_info(identity_data)
 
-        # Fetch connection status
-        try:
-            connect_data = await self.request("/spaConnectStatus")
-            self.spa.update_connection_status(connect_data)
-        except HotSpringError:
-            pass  # Non-critical
-
-        return self.spa
+        self._identity_loaded = True
+        return self.spa.info
 
     async def update_water_care(self) -> FreshWaterIQ:
         """Update FreshWater IQ water quality data.
@@ -292,7 +348,11 @@ class HotSpring:
             raise HotSpringNotReadyError(msg)
 
         try:
-            await self.request("/spaManager", method="POST", data=payload)
+            response_data = await self.request(
+                "/spaManager", method="POST", data=payload
+            )
+            if self.spa is not None:
+                self.spa.update_from_dict(response_data)
         except HotSpringError as exception:
             msg = f"Command failed: {payload}"
             raise HotSpringCommandError(msg) from exception
@@ -310,57 +370,53 @@ class HotSpring:
             {"heater": {"control": {"temperatureABS": str(temperature)}}}
         )
 
-    async def set_heating_mode(self, mode: str) -> None:
+    async def set_heating_mode(self, mode: str | HeatingMode) -> None:
         """Set the heating mode.
 
         Args:
         ----
-            mode: The heating mode value. Use HeatingMode enum values,
-                e.g. ``HeatingMode.HEAT_WITH_BOOST.value``.
+            mode: The heating mode value. Use HeatingMode enum values or string,
+                e.g. ``HeatingMode.HEAT_WITH_BOOST.value`` or ``"heatWithBoost"``.
 
         """
-        await self._send_command({"heater": {"control": {"heatingMode": mode}}})
+        mode_val = mode.value if isinstance(mode, HeatingMode) else str(mode)
+        await self._send_command({"heater": {"control": {"heatingMode": mode_val}}})
 
-    async def set_jet(self, jet: int, speed: str) -> None:
+    async def set_jet(self, jet: int, speed: str | JetSpeed) -> None:
         """Set the speed of a jet pump.
 
         Args:
         ----
             jet: The jet number (1-based).
-            speed: The speed value. Use JetSpeed enum values,
-                e.g. ``JetSpeed.HIGH_SPEED.value``.
+            speed: The speed value. Use JetSpeed enum values or string,
+                e.g. ``JetSpeed.HIGH_SPEED.value`` or ``"highSpeed"``.
 
         """
-        await self._send_command({"JET": {f"JET{jet}": {"control": speed}}})
+        speed_val = speed.value if isinstance(speed, JetSpeed) else str(speed)
+        await self._send_command({"JET": {f"JET{jet}": {"control": speed_val}}})
 
     async def set_light_color(
         self,
         zone: int,
-        color: str,
-        intensity: int = 5,
-        light_wheel: str = "off",
+        color: str | LightColor,
     ) -> None:
         """Set the color of a light zone.
 
         Args:
         ----
             zone: The light zone number (1-based).
-            color: The color value. Use LightColor enum values,
-                e.g. ``LightColor.BLUE.value``.
-            intensity: The brightness intensity (0-5). Defaults to 5.
-            light_wheel: The light wheel mode. Use LightWheelMode enum values,
-                e.g. ``LightWheelMode.OFF.value``. Defaults to "off".
+            color: The color value. Use LightColor enum values or string,
+                e.g. ``LightColor.BLUE.value`` or ``"BLUE"``.
 
         """
+        color_val = color.value if isinstance(color, LightColor) else str(color)
         await self._send_command(
             {
                 "lights": {
                     "control": {
                         f"Zone{zone}": {
                             "control": {
-                                "color": color.upper(),
-                                "IntensityAbs": intensity,
-                                "lightWheel": light_wheel,
+                                "color": color_val.upper(),
                             }
                         }
                     }
@@ -390,23 +446,60 @@ class HotSpring:
             }
         )
 
-    async def set_light_brightness(self, zone: int, *, full: bool = True) -> None:
-        """Set the brightness of a light zone.
+    async def set_light_brightness(self, zone: int, brightness: int) -> None:
+        """Set the brightness intensity of a light zone (0-5).
 
         Args:
         ----
             zone: The light zone number (1-based).
-            full: True to set to full brightness ("fullon"), False to turn off ("off").
+            brightness: The brightness level (0 = off, 1 = lowest, 5 = maximum).
+
+        Raises:
+        ------
+            ValueError: If brightness is not an integer between 0 and 5.
 
         """
-        intensity = "fullon" if full else "off"
+        if not 0 <= brightness <= 5:
+            msg = f"Brightness must be between 0 and 5, got {brightness}"
+            raise ValueError(msg)
+
         await self._send_command(
             {
                 "lights": {
                     "control": {
                         f"Zone{zone}": {
                             "control": {
-                                "Intensity": intensity,
+                                "IntensityAbs": brightness,
+                            }
+                        }
+                    }
+                }
+            }
+        )
+
+    async def set_light_wheel(
+        self,
+        zone: int,
+        mode: str | LightWheelMode = LightWheelMode.ON,
+    ) -> None:
+        """Set the light wheel (color cycle / rainbow loop) mode for a light zone.
+
+        Args:
+        ----
+            zone: The light zone number (1-based).
+            mode: The light wheel mode. Use LightWheelMode enum values or string,
+                e.g. ``LightWheelMode.ON.value``, ``"loopUp"``,
+                ``"loopDown"``, or ``"off"``. Defaults to LightWheelMode.ON.
+
+        """
+        mode_val = mode.value if isinstance(mode, LightWheelMode) else str(mode)
+        await self._send_command(
+            {
+                "lights": {
+                    "control": {
+                        f"Zone{zone}": {
+                            "control": {
+                                "lightWheel": mode_val,
                             }
                         }
                     }
@@ -430,7 +523,19 @@ class HotSpring:
             green: Green value (0-255).
             blue: Blue value (0-255).
 
+        Raises:
+        ------
+            ValueError: If any RGB component is not between 0 and 255.
+
         """
+        for component in (red, green, blue):
+            if not 0 <= component <= 255:
+                msg = (
+                    f"RGB values must be between 0 and 255, "
+                    f"got ({red}, {green}, {blue})"
+                )
+                raise ValueError(msg)
+
         await self._send_command(
             {
                 "lights": {