python-hotspring 2.1.0__py3-none-any.whl → 3.0.1__py3-none-any.whl

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

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):

hotspring/hotspring.py

@@ -9,10 +9,12 @@ from dataclasses import dataclass
 from typing import Self
 
 import aiohttp
-import backoff
 from yarl import URL
 
 from .const import (
+    _BRIGHTNESS_TO_WIRE,
+    VALID_ENERGY_SAVING_SCHEDULE_IDS,
+    BrightnessLevel,
     HeatingMode,
     JetSpeed,
     LightColor,
@@ -36,7 +38,7 @@ from .models import (
 
 
 @dataclass
-class HotSpring:
+class HotSpring:  # pylint: disable=too-many-public-methods
     """Main class for handling connections with a Hot Spring Spa.
 
     The Hot Spring Connected Spa Kit 2 uses a Home Network Adapter (HNA)
@@ -55,17 +57,12 @@ class HotSpring:
     host: str
     session: aiohttp.ClientSession | None = None
     request_timeout: float = 10.0
+    request_retries: int = 0
     validate_device: bool = True
     _close_session: bool = False
     _identity_loaded: bool = False
     spa: Spa | None = None
 
-    @backoff.on_exception(
-        backoff.expo,
-        HotSpringConnectionError,
-        max_tries=3,
-        logger=None,
-    )
     async def request(
         self,
         uri: str = "",
@@ -75,7 +72,8 @@ class HotSpring:
         """Handle a request to the Hot Spring HNA.
 
         A generic method for sending/handling HTTP requests done against
-        the Hot Spring Home Network Adapter.
+        the Hot Spring Home Network Adapter. If `request_retries > 0`, failed
+        connection attempts are retried using exponential backoff.
 
         Args:
         ----
@@ -107,53 +105,65 @@ class HotSpring:
             self.session = aiohttp.ClientSession()
             self._close_session = True
 
-        try:
-            async with asyncio.timeout(self.request_timeout):
-                response = await self.session.request(
-                    method,
-                    url,
-                    json=data,
-                    headers=headers,
-                )
-
-            if response.status // 100 in [4, 5]:
-                contents = await response.read()
-                response.close()
+        attempts = 0
+        while True:
+            try:
+                async with asyncio.timeout(self.request_timeout):
+                    response = await self.session.request(
+                        method,
+                        url,
+                        json=data,
+                        headers=headers,
+                    )
 
+                if response.status // 100 in [4, 5]:
+                    contents = await response.read()
+                    response.close()
+
+                    try:
+                        raise HotSpringError(
+                            response.status,
+                            json.loads(contents.decode("utf8")),
+                        )
+                    except json.JSONDecodeError:
+                        raise HotSpringError(
+                            response.status,
+                            {"message": contents.decode("utf8")},
+                        ) from None
+
+                # The spa returns JSON with text/html Content-Type,
+                # so always try JSON parsing first.
+                body = await response.text()
                 try:
-                    raise HotSpringError(
-                        response.status,
-                        json.loads(contents.decode("utf8")),
+                    response_data = json.loads(body)
+                except json.JSONDecodeError as exc:
+                    msg = f"Invalid JSON response from {uri}: {body[:200]}"
+                    raise HotSpringError(msg) from exc
+
+                if not isinstance(response_data, dict):
+                    msg = f"Unexpected response type from {uri}"
+                    raise HotSpringError(msg)
+
+            except asyncio.TimeoutError as exception:  # noqa: PERF203
+                attempts += 1
+                if attempts > self.request_retries:
+                    msg = (
+                        f"Timeout occurred while connecting to Hot Spring HNA at "
+                        f"{self.host}"
                     )
-                except json.JSONDecodeError:
-                    raise HotSpringError(
-                        response.status,
-                        {"message": contents.decode("utf8")},
-                    ) from None
-
-            # The spa returns JSON with text/html Content-Type,
-            # so always try JSON parsing first.
-            body = await response.text()
-            try:
-                response_data = json.loads(body)
-            except json.JSONDecodeError as exc:
-                msg = f"Invalid JSON response from {uri}: {body[:200]}"
-                raise HotSpringError(msg) from exc
-
-        except asyncio.TimeoutError as exception:
-            msg = f"Timeout occurred while connecting to Hot Spring HNA at {self.host}"
-            raise HotSpringConnectionTimeoutError(msg) from exception
-        except aiohttp.ClientError as exception:
-            msg = (
-                f"Error occurred while communicating with Hot Spring HNA at {self.host}"
-            )
-            raise HotSpringConnectionError(msg) from exception
-
-        if not isinstance(response_data, dict):
-            msg = f"Unexpected response type from {uri}"
-            raise HotSpringError(msg)
-
-        return response_data
+                    raise HotSpringConnectionTimeoutError(msg) from exception
+                await asyncio.sleep(0.5 * (2 ** (attempts - 1)))
+            except aiohttp.ClientError as exception:
+                attempts += 1
+                if attempts > self.request_retries:
+                    msg = (
+                        f"Error occurred while communicating with Hot Spring HNA at "
+                        f"{self.host}"
+                    )
+                    raise HotSpringConnectionError(msg) from exception
+                await asyncio.sleep(0.5 * (2 ** (attempts - 1)))
+            else:
+                return response_data
 
     async def _safe_request(self, uri: str) -> dict[str, object] | None:
         """Fetch an endpoint, returning None on error."""
@@ -165,11 +175,12 @@ class HotSpring:
         """Get all spa information.
 
         On the initial call (or when `refresh_identity=True`), this method fetches
-        the main /status endpoint concurrently with /startup, /spaConnectStatus,
-        and /spamodel.
+        the main /status endpoint sequentially followed by /startup, /spaConnectStatus,
+        and /spamodel. Sequential execution prevents socket exhaustion and LoRA radio
+        congestion on the ESP32.
 
         On subsequent routine polling cycles, it queries /status and /spaConnectStatus
-        concurrently, avoiding redundant radio (LoRA) queries for static identity data
+        sequentially, avoiding redundant radio (LoRA) queries for static identity data
         while keeping telemetry and connection status fresh.
 
         Args:
@@ -189,12 +200,10 @@ class HotSpring:
 
         """
         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"),
-            )
+            status_res = await self.request("/status")
+            startup_res = await self._safe_request("/startup")
+            connect_res = await self._safe_request("/spaConnectStatus")
+            model_res = await self._safe_request("/spamodel")
 
             if self.spa is None:
                 self.spa = Spa(status_res)
@@ -209,6 +218,11 @@ class HotSpring:
 
             if connect_res:
                 self.spa.update_connection_status(connect_res)
+            elif (
+                self.spa.connection_status
+                and not self.spa.connection_status.spa_connected
+            ):
+                self.spa.connection_status.spa_connected = True
 
             if self.validate_device and self.spa.info.is_sna:
                 msg = (
@@ -222,10 +236,8 @@ class HotSpring:
             self._identity_loaded = True
             return self.spa
 
-        status_res, connect_res = await asyncio.gather(
-            self.request("/status"),
-            self._safe_request("/spaConnectStatus"),
-        )
+        status_res = await self.request("/status")
+        connect_res = await self._safe_request("/spaConnectStatus")
 
         if self.spa is None:  # Safety guard; spa is always set after cold sync
             self.spa = Spa(status_res)
@@ -234,6 +246,10 @@ class HotSpring:
 
         if connect_res:
             self.spa.update_connection_status(connect_res)
+        elif (
+            self.spa.connection_status and not self.spa.connection_status.spa_connected
+        ):
+            self.spa.connection_status.spa_connected = True
 
         return self.spa
 
@@ -275,10 +291,8 @@ class HotSpring:
             msg = "Call update() before update_identity()"
             raise HotSpringError(msg)
 
-        startup_res, model_res = await asyncio.gather(
-            self._safe_request("/startup"),
-            self._safe_request("/spamodel"),
-        )
+        startup_res = await self._safe_request("/startup")
+        model_res = await self._safe_request("/spamodel")
 
         identity_data: dict[str, object] = {}
         if startup_res:
@@ -408,13 +422,13 @@ class HotSpring:
             msg = f"Command failed: {payload}"
             raise HotSpringCommandError(msg) from exception
 
-    async def set_temperature(self, temperature: int) -> None:
+    async def set_temperature(self, temperature: float) -> None:
         """Set the target water temperature.
 
         Args:
         ----
             temperature: Target temperature in the spa's configured unit
-                (Fahrenheit or Celsius).
+                (Fahrenheit or Celsius). Supports integer or half-degree float values.
 
         """
         await self._send_command(
@@ -627,6 +641,229 @@ class HotSpring:
         value = "on" if on else "off"
         await self._send_command({"blower": {"control": value}})
 
+    async def set_spa_lock(self, *, locked: bool) -> None:
+        """Lock or unlock all spa controls (Spa Lock).
+
+        Args:
+        ----
+            locked: True to lock, False to unlock.
+
+        """
+        value = "on" if locked else "off"
+        await self._send_command({"spaLock": {"control": value}})
+
+    async def set_temperature_lock(self, *, locked: bool) -> None:
+        """Lock or unlock the spa heater temperature setting (Temperature Lock).
+
+        Args:
+        ----
+            locked: True to lock, False to unlock.
+
+        """
+        value = "on" if locked else "off"
+        await self._send_command({"heater": {"control": {"temperatureLock": value}}})
+
+    async def set_heater_lock(self, *, locked: bool) -> None:
+        """Alias for set_temperature_lock."""
+        await self.set_temperature_lock(locked=locked)
+
+    async def set_vanishing_act(self, *, enabled: bool) -> None:
+        """Enable or disable Vanishing Act (calcium remover cycle).
+
+        Args:
+        ----
+            enabled: True to enable, False to disable.
+
+        """
+        value = "on" if enabled else "off"
+        await self._send_command({"cleanCycle": {"control": {"vanishingAct": value}}})
+
+    async def toggle_water_care_boost(self) -> None:
+        """Trigger or toggle the water care chlorine boost.
+
+        Note:
+        ----
+            The underlying ESP32 firmware endpoint only supports toggling
+            the boost state via ``{"waterCare": {"control": {"boost": "toggle"}}}``.
+
+        """
+        await self._send_command({"waterCare": {"control": {"boost": "toggle"}}})
+
+    async def set_water_care_boost(self) -> None:
+        """Alias for toggle_water_care_boost."""
+        await self.toggle_water_care_boost()
+
+    async def set_water_care_level(self, level: int) -> None:
+        """Set the salt water care cartridge output level (0-10).
+
+        Args:
+        ----
+            level: The output level (0 = off/disabled, 1-10 = active output).
+
+        Raises:
+        ------
+            ValueError: If level is not an integer between 0 and 10.
+
+        """
+        if not 0 <= level <= 10:
+            msg = f"Water care level must be between 0 and 10, got {level}"
+            raise ValueError(msg)
+        await self._send_command({"waterCare": {"control": {"level": str(level)}}})
+
+    async def set_salt_system_power(
+        self,
+        *,
+        power_a: bool | None = None,
+        power_b: bool | None = None,
+    ) -> None:
+        """Set the salt system power configuration states.
+
+        Args:
+        ----
+            power_a: Enable or disable saltSystemPowerA, or None to leave unchanged.
+            power_b: Enable or disable saltSystemPowerB, or None to leave unchanged.
+
+        Raises:
+        ------
+            ValueError: If neither power_a nor power_b is specified.
+
+        """
+        cfg: dict[str, object] = {}
+        if power_a is not None:
+            cfg["saltSystemPowerA"] = "enable" if power_a else "disable"
+        if power_b is not None:
+            cfg["saltSystemPowerB"] = "enable" if power_b else "disable"
+        if not cfg:
+            msg = "At least one of power_a or power_b must be provided"
+            raise ValueError(msg)
+        await self._send_command({"waterCare": {"config": cfg}})
+
+    async def set_logo_light(self, level: BrightnessLevel | str | int) -> None:
+        """Set the brightness level of the spa logo light.
+
+        Args:
+        ----
+            level: BrightnessLevel enum, integer (1-3), or string
+                ("1", "2", "3", "auto").
+
+        Raises:
+        ------
+            ValueError: If the brightness level is unrecognized.
+
+        """
+        brightness = (
+            level
+            if isinstance(level, BrightnessLevel)
+            else BrightnessLevel.build(level)
+        )
+        if (
+            brightness == BrightnessLevel.UNKNOWN
+            or brightness not in _BRIGHTNESS_TO_WIRE
+        ):
+            msg = f"Invalid logo light brightness level: {level}"
+            raise ValueError(msg)
+
+        wire_val = _BRIGHTNESS_TO_WIRE[brightness]
+        await self._send_command({"logoLight": {"control": wire_val}})
+
+    async def set_energy_saving_schedule(  # pylint: disable=too-many-arguments,too-many-positional-arguments
+        self,
+        schedule_id: int,
+        *,
+        enabled: bool,
+        start_hour: int,
+        start_minute: int,
+        duration: int,
+    ) -> None:
+        """Configure an Energy Saving schedule (schedule 1 or 2).
+
+        Args:
+        ----
+            schedule_id: Schedule number (1 or 2).
+            enabled: Whether the schedule should be active.
+            start_hour: Start hour in 24-hour format (0-23).
+            start_minute: Start minute (0-59).
+            duration: Duration in hours (1-24).
+
+        Raises:
+        ------
+            ValueError: If schedule_id or time/duration parameters are invalid.
+
+        """
+        if schedule_id not in VALID_ENERGY_SAVING_SCHEDULE_IDS:
+            msg = (
+                f"Schedule ID must be one of {VALID_ENERGY_SAVING_SCHEDULE_IDS}, "
+                f"got {schedule_id}"
+            )
+            raise ValueError(msg)
+        if not 0 <= start_hour <= 23:
+            msg = f"start_hour must be between 0 and 23, got {start_hour}"
+            raise ValueError(msg)
+        if not 0 <= start_minute <= 59:
+            msg = f"start_minute must be between 0 and 59, got {start_minute}"
+            raise ValueError(msg)
+        if not 1 <= duration <= 24:
+            msg = f"duration must be between 1 and 24, got {duration}"
+            raise ValueError(msg)
+
+        # Note: The ESP32 HNA firmware energySavings handler expects startHour,
+        # startMinute, and duration formatted as strings in the control object.
+        mode_val = "on" if enabled else "off"
+        await self._send_command(
+            {
+                "energySavings": {
+                    f"energySaving{schedule_id}": {
+                        "control": {
+                            "mode": mode_val,
+                            "startHour": str(start_hour),
+                            "startMinute": str(start_minute),
+                            "duration": str(duration),
+                        }
+                    }
+                }
+            }
+        )
+
+    async def set_clean_cycle_schedule(
+        self,
+        *,
+        enabled: bool,
+        start_hour: int,
+        start_minute: int,
+    ) -> None:
+        """Configure the recurring clean cycle timer schedule.
+
+        Args:
+        ----
+            enabled: True to enable 24-hour clean cycle schedule, False to disable.
+            start_hour: Start hour in 24-hour format (0-23).
+            start_minute: Start minute (0-59).
+
+        Raises:
+        ------
+            ValueError: If time parameters are out of range.
+
+        """
+        if not 0 <= start_hour <= 23:
+            msg = f"start_hour must be between 0 and 23, got {start_hour}"
+            raise ValueError(msg)
+        if not 0 <= start_minute <= 59:
+            msg = f"start_minute must be between 0 and 59, got {start_minute}"
+            raise ValueError(msg)
+
+        # Note: Unlike energySavings, the ESP32 HNA cleanCycleTimer endpoint
+        # parses startHour and startMinute as raw integers.
+        clean_timer = "enable" if enabled else "disable"
+        await self._send_command(
+            {
+                "cleanCycleTimer": {
+                    "cleanTimer": clean_timer,
+                    "startHour": start_hour,
+                    "startMinute": start_minute,
+                }
+            }
+        )
+
     async def close(self) -> None:
         """Close open client session."""
         if self.session and self._close_session: