diff --git a/README.md b/README.md index f9304de..7b10c7f 100644 --- a/README.md +++ b/README.md @@ -13,10 +13,6 @@ Asynchronous Python client for Hot Spring Connected Spa Kit 2. > This library is currently in heavy development. Not all features might work > perfectly, and some features may not be fully tested as they depend on the > physical hardware available for testing. -> -> The spa's energy consumption estimates (watts, power draw) are not accurate -> and are most likely incorrect, as the power calculation registers have not -> been fully reverse-engineered. ## About @@ -37,9 +33,11 @@ It is primarily designed to be used as the communication layer for an official plus the logo light - **Water care** — Monitor FreshWater IQ salt system metrics (pH, chlorine, ORP, sensor life) -- **Diagnostics & Test Metrics** — Read raw hardware test point currents, line voltages, - sensor flow/switch states, and failure diagnostics -- **Runtime Tracking** — Cumulative heater runtime and individual jet pump runtime in hours +- **Power & Diagnostics**: Read per-circuit power and current metrics (on spas equipped + with current-sensing hardware), filter cycle durations, sensor flow/switch states, and + failure diagnostics +- **Runtime Tracking**: System uptime and cumulative runtime for supported jet pumps and + blower in hours - **Connection monitoring** — Check LoRA bridge and cloud connectivity status - **Energy saving schedules** — View configured energy saving time windows - **Clean cycle** — Start or stop the 10-minute clean cycle diff --git a/demo/demo_print_data.py b/demo/demo_print_data.py index 08b8b07..292c62b 100644 --- a/demo/demo_print_data.py +++ b/demo/demo_print_data.py @@ -33,6 +33,11 @@ def print_identity(s: Spa) -> None: print(f"SNA Ready: {s.info.sna_ready}") +def _format_runtime(hours: float | None, seconds: int | None) -> str: + """Format runtime hours and seconds, or N/A when unavailable.""" + return f"{hours:.2f}h ({seconds}s)" if hours is not None else "N/A" + + def print_heater_and_jets(s: Spa) -> None: """Print heater and jets info.""" print("\n" + "=" * 20) @@ -43,11 +48,10 @@ def print_heater_and_jets(s: Spa) -> None: print(f"Current Temp: {s.heater.current_temperature} {unit}") print(f"Set Temp: {s.heater.set_temperature} {unit}") print(f"Heating Mode: {s.heater.heating_mode.value}") - print( - f"Heater Hours: {s.heater.heater_on_hours:.2f} hrs ({s.heater.heater_on_seconds} s)" - ) print(f"Heater Lock: {s.heater.heater_lock}") print(f"Heat Pump: {s.heater.heatpump_installed}") + uptime = _format_runtime(s.system_uptime_hours, s.system_uptime_seconds) + print(f"System Uptime: {uptime}") print("\n" + "=" * 20) print(" JETS & BLOWER") @@ -57,14 +61,16 @@ def print_heater_and_jets(s: Spa) -> None: extra = "" if jet.concurrent_mode: extra += " Concurrent=True" + runtime = _format_runtime(jet.on_hours, jet.on_seconds) print( f"Jet {jet.jet_id:1}: Available={jet.is_available!s:5} " f"SpeedType={jet.speed_type.value:11} State={jet.speed.value:10} " - f"Supported=[{supported}] Runtime={jet.on_hours:.2f}h ({jet.on_seconds}s){extra}" + f"Supported=[{supported}] Runtime={runtime}{extra}" ) + blower_runtime = _format_runtime(s.blower.on_hours, s.blower.on_seconds) print( f"Blower: Status={'ON' if s.blower.is_on else 'OFF':3} " - f"Enabled={s.blower.is_enabled}" + f"Enabled={s.blower.is_enabled} Runtime={blower_runtime}" ) @@ -104,26 +110,40 @@ def print_lighting_and_watercare(s: Spa) -> None: def print_diagnostics(s: Spa) -> None: - """Print diagnostics info.""" + """Print power and diagnostics info.""" + print("\n" + "=" * 20) + print(" POWER & CURRENT") + print("=" * 20) + print(f"Supported: {s.power.supported}") + print(f"Total Power: {s.power.total_power} VA/W") + print( + f"Small Loads: {s.power.small_loads_power} W ({s.power.small_loads_current} A)" + ) + print( + f"J1+J2+Blower: {s.power.jet1_jet2_blower_power} VA " + f"({s.power.jet1_jet2_blower_current} A)" + ) + print(f"Heater: {s.power.heater_power} W ({s.power.heater_current} A)") + print(f"Jet 3: {s.power.jet3_power} VA ({s.power.jet3_current} A)") + print("\n" + "=" * 20) print(" DIAGNOSTICS (DEBUG)") print("=" * 20) print(f"Failure State: {s.diagnostics.spa_failure_state.value}") - print(f"L1 Volts: {s.diagnostics.l1_n_volts:.1f} V") - print(f"L2 Volts: {s.diagnostics.l2_n_volts:.1f} V") - print(f"Heater Volts: {s.diagnostics.heater_volts:.1f} V") - print(f"Jet 3 Volts: {s.diagnostics.jet3_volts:.1f} V") - print(f"Frequency: {s.diagnostics.power_frequency} Hz") + print(f"Jet 3 Volts: {s.diagnostics.jet3_volts} V") + print( + f"Filter 1 / 2: {s.diagnostics.filter_1_minutes} / {s.diagnostics.filter_2_minutes} min" + ) + print(f"Frequency Flag: {s.diagnostics.power_frequency}") print(f"Circ Flow: {s.diagnostics.circulation_pump_flow_status}") print(f"Pressure Switch: {s.diagnostics.pressure_switch_status}") print("\n" + "=" * 20) - print(" RAW TEST METRICS") + print(" CALIBRATION METRICS") print("=" * 20) - print(f"Heater Current: {s.test_metrics.heater_current:.2f} A") - print(f"Jet 3 Current: {s.test_metrics.jet3_current:.2f} A") - print(f"Small Loads: {s.test_metrics.small_loads_current:.2f} A") - print(f"J1+J2+Blower: {s.test_metrics.jet1_jet2_blower_current:.2f} A") + print(f"Heater Test: {s.test_metrics.heater_test_status}") + print(f"Temp Offset: {s.test_metrics.temp_offset}") + print(f"Vsense Cal: {s.test_metrics.vsense_cal}") print("\n" + "=" * 20) print(" VERSIONS") diff --git a/src/hotspring/__init__.py b/src/hotspring/__init__.py index 0bbf311..59f07b9 100644 --- a/src/hotspring/__init__.py +++ b/src/hotspring/__init__.py @@ -35,6 +35,7 @@ Jet, LightZone, LogoLight, + PowerMetrics, Spa, SpaInfo, SpaLock, @@ -71,6 +72,7 @@ "LightWheelMode", "LightZone", "LogoLight", + "PowerMetrics", "Spa", "SpaBrand", "SpaFailureState", diff --git a/src/hotspring/hotspring.py b/src/hotspring/hotspring.py index 525a2fb..11ba1a3 100644 --- a/src/hotspring/hotspring.py +++ b/src/hotspring/hotspring.py @@ -258,7 +258,9 @@ async def update(self, *, refresh_identity: bool = False) -> Spa: On subsequent routine polling cycles, it queries /status and /spaConnectStatus sequentially, avoiding redundant radio (LoRA) queries for static identity data - while keeping telemetry and connection status fresh. + while keeping telemetry and connection status fresh. When power monitoring is + supported and /addDebugData is needed for initial baseline current or active + loads, it is also fetched opportunistically. Args: ---- @@ -314,6 +316,7 @@ async def update(self, *, refresh_identity: bool = False) -> Spa: ) raise HotSpringSNADetectedError(msg) + await self._refresh_power_diagnostics(self.spa) self._identity_loaded = True return self.spa @@ -334,8 +337,19 @@ async def update(self, *, refresh_identity: bool = False) -> Spa: ): self.spa.connection_status.spa_connected = True + await self._refresh_power_diagnostics(self.spa) return self.spa + async def _refresh_power_diagnostics(self, spa: Spa) -> None: + """Fetch /addDebugData when needed for baseline current or active loads.""" + if ( + not spa.connection_status.spa_connected + or not spa.needs_diagnostics_for_power + ): + return + with contextlib.suppress(HotSpringError): + await self._fetch(Endpoint.DEBUG_DATA, spa.update_diagnostics) + async def get_device_info(self) -> SpaInfo: """Fetch lightweight device identity directly from /startup. diff --git a/src/hotspring/models.py b/src/hotspring/models.py index f31902d..e5d5e5f 100644 --- a/src/hotspring/models.py +++ b/src/hotspring/models.py @@ -9,6 +9,7 @@ from __future__ import annotations import contextlib +import itertools from dataclasses import dataclass, replace from typing import TYPE_CHECKING, NamedTuple @@ -30,6 +31,14 @@ if TYPE_CHECKING: from collections.abc import Callable +type _WordBlock = tuple[int | None, ...] +type _PumpBlowerState = tuple[JetSpeed, JetSpeed, bool] | None +type _CircuitStates = tuple[bool, bool, _PumpBlowerState] + +_NO_HEAD_WORDS: _WordBlock = (None, None, None) +_NO_STATUS_WORDS: _WordBlock = (None, None, None, None) +_NO_TAIL_WORDS: _WordBlock = (None, None) + class Spa: """Object holding all information from a Hot Spring Spa. @@ -53,6 +62,9 @@ class Spa: connection_status: ConnectionStatus diagnostics: Diagnostics test_metrics: SpaTestData + power: PowerMetrics + system_uptime_seconds: int | None + _pending_status_words: _WordBlock def __init__(self, data: dict[str, object]) -> None: """Initialize a Spa from the API response. @@ -72,11 +84,14 @@ def __init__(self, data: dict[str, object]) -> None: self.water_care = WaterCare() self.freshwater_iq = FreshWaterIQ() self.test_metrics = SpaTestData() + self.power = PowerMetrics() + self.system_uptime_seconds = None self.energy_savings = {} self.versions = Versions() self.info = SpaInfo() self.connection_status = ConnectionStatus() self.diagnostics = Diagnostics() + self._pending_status_words = _NO_STATUS_WORDS if data: self.update_from_dict(data) @@ -93,6 +108,9 @@ def update_from_dict(self, data: dict[str, object]) -> set[str]: """ updated: set[str] = set() + prior_states = self._circuit_states + previous_power = self.power + previous_uptime = self.system_uptime_seconds for section in _SECTION_PARSERS: if section.json_key in data and isinstance(data[section.json_key], dict): @@ -142,8 +160,38 @@ def update_from_dict(self, data: dict[str, object]) -> set[str]: updated.add("freshwater_iq") updated.add("versions") + self._apply_shifted_runtimes(data, updated) + if self.system_uptime_seconds != previous_uptime: + updated.add("system_uptime_seconds") + + self._update_power_from_status(data, prior_states) + if self.power != previous_power: + updated.add("power") + return updated + def _update_power_from_status( + self, data: dict[str, object], prior_states: _CircuitStates + ) -> None: + """Update power metrics and pending words from a /status or echo dict.""" + status_words = _extract_status_words(data) + if status_words is None: + if self._circuit_states == prior_states: + return + self._pending_status_words = _NO_STATUS_WORDS + self._apply_power_words({}, prior_states=prior_states) + return + + fresh_power = _decode_registers(_NO_HEAD_WORDS, status_words, _NO_TAIL_WORDS) + if fresh_power["small_loads_power"] <= 0: + self.power = PowerMetrics() + self._pending_status_words = _NO_STATUS_WORDS + return + + self._pending_status_words = status_words + self.power = replace(self.power, supported=True) + self._apply_power_words(fresh_power, prior_states=prior_states) + def update_info(self, data: dict[str, object]) -> None: """Update spa identity from /startup and /spamodel responses. @@ -196,14 +244,26 @@ def update_connection_status(self, data: dict[str, object]) -> None: self.connection_status = ConnectionStatus.from_dict(data) def update_diagnostics(self, data: dict[str, object]) -> None: - """Update diagnostics from /addDebugData response. + """Update diagnostics and power metrics from /addDebugData response. Args: ---- data: The JSON response from GET /addDebugData. """ - self.diagnostics = Diagnostics.from_dict(data) + self.diagnostics, debug_integers = _parse_diagnostics_and_electrical( + data, existing=self.diagnostics + ) + if debug_integers is None: + return + status_words = self._pending_status_words + self._pending_status_words = _NO_STATUS_WORDS + fresh_power = _decode_registers( + tuple(debug_integers.get(key) for key in _DEBUG_HEAD_KEYS), + status_words, + tuple(debug_integers.get(key) for key in _DEBUG_TAIL_KEYS), + ) + self._apply_power_words(fresh_power, prior_states=self._circuit_states) def update_freshwater_iq(self, data: dict[str, object]) -> None: """Update FreshWater IQ data from /getFWIQData response. @@ -227,6 +287,95 @@ def _apply_fwiq_firmware_installed(self) -> bool: return True return False + def _apply_shifted_runtimes( + self, data: dict[str, object], updated: set[str] + ) -> None: + """Route misaligned 24-bit runtime fields to their actual components.""" + decoded = { + target: _decode_runtime_seconds(raw) + for path, target in _RUNTIME_ROUTES + if (raw := _dig(data, path)) is not None + } + if not decoded: + return + if not ( + self.versions.control_box + or self.system_uptime_seconds is not None + or any(decoded.values()) + ): + return + + if "uptime" in decoded: + self.system_uptime_seconds = decoded["uptime"] + if (blower_seconds := decoded.get("blower")) is not None and ( + self.blower.on_seconds != blower_seconds + ): + self.blower = replace(self.blower, on_seconds=blower_seconds) + updated.add("blower") + for target, jet_id in (("jet1", 1), ("jet3", 3)): + if ( + (seconds := decoded.get(target)) is not None + and jet_id in self.jets + and self.jets[jet_id].on_seconds != seconds + ): + self.jets[jet_id] = replace(self.jets[jet_id], on_seconds=seconds) + updated.add("jets") + + def _apply_power_words( + self, + fresh: dict[str, int], + *, + prior_states: _CircuitStates, + ) -> None: + """Merge freshly decoded power/current words and apply circuit gating.""" + if not self.power.supported: + return + + updates: dict[str, int | None] = dict(fresh) + for state, before, fields in zip( + self._circuit_states, prior_states, _CIRCUIT_FIELDS, strict=True + ): + if not state: + updates.update(dict.fromkeys(fields, 0)) + elif state != before: + for field in fields: + updates[field] = fresh.get(field) + self.power = replace(self.power, **updates) + + @property + def _circuit_states(self) -> _CircuitStates: + """Return active-state snapshot for (heater, jet3, jet1+jet2+blower).""" + return (self.heater.is_on, self._is_jet3_on, self._pump_blower_state) + + @property + def _is_jet3_on(self) -> bool: + """Return True if an enabled Jet 3 is currently running.""" + return bool((jet3 := self.jets.get(3)) and jet3.is_enabled and jet3.is_on) + + @property + def _pump_blower_state(self) -> _PumpBlowerState: + """Return normalized active state of (Jet 1, Jet 2, Blower), or None if off.""" + jet1 = self.jets.get(1) + jet2 = self.jets.get(2) + state = ( + jet1.speed if jet1 is not None and jet1.is_on else JetSpeed.OFF, + jet2.speed if jet2 is not None and jet2.is_on else JetSpeed.OFF, + self.blower.is_on, + ) + return None if state == (JetSpeed.OFF, JetSpeed.OFF, False) else state + + @property + def system_uptime_hours(self) -> float | None: + """Return system uptime in hours when available.""" + return _seconds_to_hours(self.system_uptime_seconds) + + @property + def needs_diagnostics_for_power(self) -> bool: + """Return True when /addDebugData is needed for power or current readings.""" + return self.power.supported and ( + self.power.small_loads_current is None or any(self._circuit_states) + ) + @property def is_hna(self) -> bool: """Return True if this device is the Home Network Adapter (HNA).""" @@ -361,24 +510,17 @@ def is_hna(self) -> bool: @dataclass -class Heater: # pylint: disable=too-many-instance-attributes +class Heater: """Heater status and configuration.""" is_on: bool = False heater_lock: bool = False heatpump_installed: bool = False heating_mode: HeatingMode = HeatingMode.UNKNOWN - heater_current: float = 0.0 - heater_on_seconds: int = 0 set_temperature: float | None = None current_temperature: float | None = None temperature_unit: TemperatureUnit = TemperatureUnit.UNKNOWN - @property - def heater_on_hours(self) -> float: - """Return cumulative heater runtime in hours.""" - return round(self.heater_on_seconds / 3600.0, 2) - @staticmethod def from_dict(data: dict[str, object], existing: Heater | None = None) -> Heater: """Create a Heater from API response data. @@ -415,8 +557,7 @@ class Jet: speed_type: JetSpeedType = JetSpeedType.UNKNOWN is_enabled: bool = True concurrent_mode: bool = False - current: float = 0.0 - on_seconds: int = 0 + on_seconds: int | None = None @property def is_available(self) -> bool: @@ -448,9 +589,9 @@ def supported_speeds(self) -> list[JetSpeed]: return [JetSpeed.OFF, JetSpeed.HIGH_SPEED] @property - def on_hours(self) -> float: - """Return cumulative jet runtime in hours.""" - return round(self.on_seconds / 3600.0, 2) + def on_hours(self) -> float | None: + """Return cumulative jet runtime in hours when available.""" + return _seconds_to_hours(self.on_seconds) @staticmethod def from_dict( @@ -486,22 +627,8 @@ def from_dict( ) status = data.get("status") - if isinstance(status, dict): - if "speed" in status: - kwargs["speed"] = JetSpeed.build(status.get("speed")) - if "current" in status: - kwargs["current"] = int(status.get("current", 0)) / 2560.0 - on_sec_key = f"jet_{jet_id}_ON_sec" - if on_sec_key in status: - # The ESP32 firmware tracks runtime using an unsigned 32-bit counter - # in units of 1/256 seconds (Q24.8 fixed-point), but formats it as a - # signed 32-bit integer (`%d`) in the JSON output. Once runtime - # exceeds 2^31 ticks (~97.1 days), it overflows into a negative value. - # Masking with `& 0xFFFFFFFF` restores the true unsigned 32-bit counter - # before dividing by 256 to convert to whole elapsed seconds. - kwargs["on_seconds"] = ( - int(status.get(on_sec_key, 0)) & 0xFFFFFFFF - ) // 256 + if isinstance(status, dict) and "speed" in status: + kwargs["speed"] = JetSpeed.build(status["speed"]) control = data.get("control") if isinstance(control, str): @@ -509,7 +636,7 @@ def from_dict( if speed != JetSpeed.UNKNOWN: kwargs["speed"] = speed elif isinstance(control, dict) and "speed" in control: - speed = JetSpeed.build(control.get("speed")) + speed = JetSpeed.build(control["speed"]) if speed != JetSpeed.UNKNOWN: kwargs["speed"] = speed @@ -555,6 +682,12 @@ class Blower: is_enabled: bool = False is_on: bool = False + on_seconds: int | None = None + + @property + def on_hours(self) -> float | None: + """Return cumulative blower runtime in hours when available.""" + return _seconds_to_hours(self.on_seconds) @staticmethod def from_dict(data: dict[str, object], existing: Blower | None = None) -> Blower: @@ -573,17 +706,17 @@ def from_dict(data: dict[str, object], existing: Blower | None = None) -> Blower kwargs: dict[str, object] = {} config = data.get("config") if isinstance(config, dict) and "blower" in config: - kwargs["is_enabled"] = config.get("blower", "disable") != "disable" + kwargs["is_enabled"] = config["blower"] != "disable" status = data.get("status") if isinstance(status, dict) and "blower" in status: - kwargs["is_on"] = status.get("blower", "off") not in ("off", "disable") + kwargs["is_on"] = status["blower"] not in ("off", "disable") control = data.get("control") if isinstance(control, str): kwargs["is_on"] = _is_truthy(control) elif isinstance(control, dict) and "blower" in control: - raw_blower = control.get("blower") + raw_blower = control["blower"] if raw_blower is not None: kwargs["is_on"] = _is_truthy(raw_blower) @@ -1086,17 +1219,52 @@ def from_dict(data: dict[str, object]) -> ConnectionStatus: return ConnectionStatus(spa_connected=connected) +@dataclass +class PowerMetrics: # pylint: disable=too-many-instance-attributes + """Reconstructed electrical power and current telemetry. + + On IQ2020/Eagle control boards equipped with current-sensing hardware, + power readings reflect apparent power (``V_rms * I_rms`` in VA, equal to + real Watts for the resistive heater and within ~1-25% of real Watts on + pump motors depending on power factor), and ``*_current`` fields report + whole Amps (``A``). ``small_loads_current`` is sampled at initial baseline + and refreshed while heater or pump loads are active. On entry-level + control boards without current sensors or before initial controller sync, + ``supported`` is ``False`` and all reading fields remain ``None``. + """ + + supported: bool = False + small_loads_power: int | None = None + jet1_jet2_blower_power: int | None = None + heater_power: int | None = None + jet3_power: int | None = None + jet1_jet2_blower_current: int | None = None + small_loads_current: int | None = None + heater_current: int | None = None + jet3_current: int | None = None + + @property + def total_power(self) -> int | None: + """Return combined power across all four spa circuits when known.""" + parts = ( + self.small_loads_power, + self.jet1_jet2_blower_power, + self.heater_power, + self.jet3_power, + ) + if None in parts: + return None + # Filter narrows int | None for mypy. + return sum(part for part in parts if part is not None) + + @dataclass class SpaTestData: - """Test data metrics from the spa, including raw current readings.""" + """Factory calibration and test-status values from the spa.""" heater_test_status: str = "off" temp_offset: float = 0.0 vsense_cal: float = 0.0 - jet1_jet2_blower_current: float = 0.0 - small_loads_current: float = 0.0 - heater_current: float = 0.0 - jet3_current: float = 0.0 @staticmethod def from_dict( @@ -1118,28 +1286,11 @@ def from_dict( status = data.get("status") if isinstance(status, dict): if "heaterTestStatus" in status: - kwargs["heater_test_status"] = str( - status.get("heaterTestStatus", "off") - ) + kwargs["heater_test_status"] = str(status["heaterTestStatus"]) if "tempOffset" in status: - kwargs["temp_offset"] = float(status.get("tempOffset", 0.0)) + kwargs["temp_offset"] = float(status["tempOffset"]) if "VsenseCal" in status: - kwargs["vsense_cal"] = float(status.get("VsenseCal", 0.0)) - # Current metrics are encoded in Q8.8 fixed-point deciapps (0.1 A units - # left-shifted by 8 bits / multiplied by 256). - # Dividing by 2560.0 (256 * 10) scales the raw integer to Amperes (A). - if "jet1+jet2+blowerCurrent" in status: - kwargs["jet1_jet2_blower_current"] = ( - int(status.get("jet1+jet2+blowerCurrent", 0)) / 2560.0 - ) - if "smallLoadsCurrent" in status: - kwargs["small_loads_current"] = ( - int(status.get("smallLoadsCurrent", 0)) / 2560.0 - ) - if "heaterCurrent" in status: - kwargs["heater_current"] = int(status.get("heaterCurrent", 0)) / 2560.0 - if "jet3Current" in status: - kwargs["jet3_current"] = int(status.get("jet3Current", 0)) / 2560.0 + kwargs["vsense_cal"] = float(status["VsenseCal"]) base = existing or SpaTestData() return replace(base, **kwargs) @@ -1147,12 +1298,7 @@ def from_dict( @dataclass class Diagnostics: # pylint: disable=too-many-instance-attributes - """Diagnostic and power metrics from the spa. - - Availability depends on the spa model and whether the main control - board (IQ2020/Eagle) is equipped with current-sensing transformers. - Values may be ``0`` if sensors are not installed. - """ + """Hardware diagnostic status flags and filter settings from /addDebugData.""" spa_failure_state: SpaFailureState = SpaFailureState.UNKNOWN heater_error: str = "0" @@ -1161,70 +1307,192 @@ class Diagnostics: # pylint: disable=too-many-instance-attributes circulation_pump_flow_status: str = "0" regulation_thermistor_temp_status: str = "0" limit_thermistor_status: str = "0" - l1_n_volts: float = 0.0 - l2_n_volts: float = 0.0 - heater_volts: float = 0.0 - jet3_volts: float = 0.0 - jet1_jet2_blower_power: str = "0" - small_loads_power: str = "0" - heater_power: str = "0" - jet3_power: str = "0" + jet3_volts: int | None = None + daily_clean_cycle: int | None = None + filter_1_minutes: int | None = None + filter_2_minutes: int | None = None @staticmethod - def from_dict(data: dict[str, object]) -> Diagnostics: - """Create a Diagnostics from API response data. + def from_dict( + data: dict[str, object], existing: Diagnostics | None = None + ) -> Diagnostics: + """Create a Diagnostics instance from a GET /addDebugData response.""" + diagnostics, _ = _parse_diagnostics_and_electrical(data, existing=existing) + return diagnostics + + +_STATUS_ELECTRICAL_KEYS: tuple[str, ...] = ( + "jet1+jet2+blowerCurrent", + "smallLoadsCurrent", + "heaterCurrent", + "jet3Current", +) - Args: - ---- - data: The JSON response from GET /addDebugData, or an empty - dict for default values. +_DEBUG_HEAD_KEYS: tuple[str, ...] = ( + "L2_N_Volts", + "Heater_Volts", + "jet3_Volts", +) - Returns: - ------- - A Diagnostics instance. +_DEBUG_TAIL_KEYS: tuple[str, ...] = ( + "jet1_jet2_blowerPower", + "smallLoadsPower", +) - """ - debug_data = data.get("debugData") - if not isinstance(debug_data, dict): - return Diagnostics() - - debug = debug_data.get("status") - if not isinstance(debug, dict) or not debug: - return Diagnostics() - - volt_keys = { - "L1_N_Volts": "l1_n_volts", - "L2_N_Volts": "l2_n_volts", - "Heater_Volts": "heater_volts", - "jet3_Volts": "jet3_volts", - } - str_keys = { - "heaterError": "heater_error", - "powerFrequency": "power_frequency", - "pressureSwitchStatus": "pressure_switch_status", - "circulationPumpFlowStatus": "circulation_pump_flow_status", - "regulationThermistorTempStatus": "regulation_thermistor_temp_status", - "limitThermistorStatus": "limit_thermistor_status", - "jet1_jet2_blowerPower": "jet1_jet2_blower_power", - "smallLoadsPower": "small_loads_power", - "heaterPower": "heater_power", - "jet3Power": "jet3_power", - } - kwargs: dict[str, object] = {} - if "spaFailureState" in debug: - kwargs["spa_failure_state"] = SpaFailureState.build( - debug.get("spaFailureState") - ) - for json_key, attr in str_keys.items(): - if json_key in debug: - kwargs[attr] = str(debug[json_key]) - # Voltage registers use Q11.5 fixed-point format (1/32 V resolution). - # Dividing raw integer by 32.0 converts to Volts. - for json_key, attr in volt_keys.items(): - if json_key in debug: - kwargs[attr] = int(debug.get(json_key) or 0) / 32.0 +# HNA JSON is one byte out of phase with the controller register block. +# Together, 3 debug head words + 4 /status test_data words + 2 debug tail words +# form one 9-word sequence whose adjacent pairs yield these 8 registers. +_REGISTER_NAMES: tuple[str, ...] = ( + "jet1_jet2_blower_current", + "small_loads_current", + "heater_current", + "jet3_current", + "jet1_jet2_blower_power", + "small_loads_power", + "heater_power", + "jet3_power", +) + +_CIRCUIT_FIELDS: tuple[tuple[str, str], ...] = ( + ("heater_power", "heater_current"), + ("jet3_power", "jet3_current"), + ("jet1_jet2_blower_power", "jet1_jet2_blower_current"), +) - return replace(Diagnostics(), **kwargs) +_RUNTIME_ROUTES: tuple[tuple[tuple[str, ...], str], ...] = ( + # HNA shifts each 24-bit runtime counter into its neighboring JSON field. + (("heater", "status", "heaterHours"), "jet1"), + (("JET", "JET1", "status", "jet_1_ON_sec"), "uptime"), + (("JET", "JET2", "status", "jet_2_ON_sec"), "jet3"), + (("JET", "JET3", "status", "jet_3_ON_sec"), "blower"), +) + +_DEBUG_STRING_KEYS: dict[str, str] = { + "heaterError": "heater_error", + "powerFrequency": "power_frequency", + "pressureSwitchStatus": "pressure_switch_status", + "circulationPumpFlowStatus": "circulation_pump_flow_status", + "regulationThermistorTempStatus": "regulation_thermistor_temp_status", + "limitThermistorStatus": "limit_thermistor_status", +} + +_DEBUG_INTEGER_KEYS: tuple[str, ...] = ( + "L1_N_Volts", + *_DEBUG_HEAD_KEYS, + *_DEBUG_TAIL_KEYS, + "heaterPower", + "jet3Power", +) + + +def _seconds_to_hours(seconds: int | None) -> float | None: + """Convert elapsed seconds to rounded hours, preserving None.""" + if seconds is None: + return None + return round(seconds / 3600.0, 2) + + +def _dig(data: dict[str, object], path: tuple[str, ...]) -> object: + """Return nested dict value along ``path``, or ``None`` if absent.""" + cursor: object = data + for key in path: + if not isinstance(cursor, dict) or key not in cursor: + return None + cursor = cursor[key] + return cursor + + +def _reconstruct_uint16(low_byte_word: int, high_byte_word: int) -> int: + """Reconstruct a 16-bit register split across two adjacent misaligned words.""" + return ((high_byte_word & 0xFF) << 8) | ((low_byte_word >> 8) & 0xFF) + + +def _decode_registers( + head: _WordBlock, status: _WordBlock, tail: _WordBlock +) -> dict[str, int]: + """Reconstruct 16-bit registers across the contiguous 9-word API stream.""" + words = (*head, *status, *tail) + return { + name: _reconstruct_uint16(low_word, high_word) + for name, (low_word, high_word) in zip( + _REGISTER_NAMES, itertools.pairwise(words), strict=True + ) + if low_word is not None and high_word is not None + } + + +def _decode_runtime_seconds(raw: object) -> int: + """Decode a 24-bit runtime counter shifted by 8 bits into signed 32-bit JSON. + + Runtime counters are left-shifted by 8 bits and formatted as signed 32-bit + integers, wrapping negative past ~97.1 days. Masking with ``0xFFFFFFFF`` + and shifting right by 8 recovers elapsed whole seconds. + """ + raw_value: int = int(raw) + return (raw_value & 0xFFFFFFFF) >> 8 + + +def _extract_status_words(data: dict[str, object]) -> _WordBlock | None: + """Extract the 4 contiguous electrical words from /status when complete.""" + test_data = data.get("test_data") + if not isinstance(test_data, dict): + return None + test_data_status = test_data.get("status") + if not isinstance(test_data_status, dict) or not all( + key in test_data_status for key in _STATUS_ELECTRICAL_KEYS + ): + return None + return tuple(int(test_data_status[key]) for key in _STATUS_ELECTRICAL_KEYS) + + +def _parse_diagnostics_and_electrical( + data: dict[str, object], + existing: Diagnostics | None = None, +) -> tuple[Diagnostics, dict[str, int] | None]: + """Parse /addDebugData into Diagnostics and raw integer electrical words.""" + base = existing or Diagnostics() + debug_data = data.get("debugData") + if not isinstance(debug_data, dict): + return base, None + + debug = debug_data.get("status") + if not isinstance(debug, dict) or not debug: + return base, None + + string_fields = { + attribute_name: str(debug[json_key]) + for json_key, attribute_name in _DEBUG_STRING_KEYS.items() + if json_key in debug + } + parsed_integers = { + json_key: int(debug[json_key]) + for json_key in _DEBUG_INTEGER_KEYS + if json_key in debug + } + + raw_failure = debug.get("spaFailureState") + if not ( + (raw_failure is not None and str(raw_failure) not in ("", "Spa_Ok")) + or any(value != "0" for value in string_fields.values()) + or any(value != 0 for value in parsed_integers.values()) + ): + return base, None + + kwargs: dict[str, object] = dict(string_fields) + if "spaFailureState" in debug: + kwargs["spa_failure_state"] = SpaFailureState.build(raw_failure) + if (l1_volts := parsed_integers.get("L1_N_Volts")) is not None and ( + l2_volts := parsed_integers.get("L2_N_Volts") + ) is not None: + kwargs["jet3_volts"] = _reconstruct_uint16(l1_volts, l2_volts) + if "smallLoadsPower" in parsed_integers: + kwargs["daily_clean_cycle"] = (parsed_integers["smallLoadsPower"] >> 8) & 0xFF + if "heaterPower" in parsed_integers: + kwargs["filter_1_minutes"] = parsed_integers["heaterPower"] + if "jet3Power" in parsed_integers: + kwargs["filter_2_minutes"] = parsed_integers["jet3Power"] + + return replace(base, **kwargs), parsed_integers class _SectionParser(NamedTuple): @@ -1298,17 +1566,6 @@ def _parse_heater_status(status: dict[str, object]) -> dict[str, object]: mode = HeatingMode.build(raw_mode) if mode != HeatingMode.UNKNOWN or str(raw_mode).strip().lower() == "invalid": kwargs["heating_mode"] = mode - if "heaterCurrent" in status: - # Motherboard current registers use Q8.8 fixed point in deciapps (0.1 A): - # raw / 256 / 10.0 = raw / 2560.0 Amperes. - kwargs["heater_current"] = int(status.get("heaterCurrent", 0)) / 2560.0 - if "heaterHours" in status: - # Like jet runtime counters, `heaterHours` is an unsigned 32-bit counter - # in 1/256 seconds (Q24.8) formatted as signed `%d` in ESP32 JSON. - # Mask with `& 0xFFFFFFFF` to handle 32-bit integer overflow and divide by 256. - kwargs["heater_on_seconds"] = ( - int(status.get("heaterHours", 0)) & 0xFFFFFFFF - ) // 256 kwargs.update(_parse_heater_temperatures(status)) return kwargs diff --git a/tests/__snapshots__/test_hotspring.ambr b/tests/__snapshots__/test_hotspring.ambr index 87eca2e..8335d08 100644 --- a/tests/__snapshots__/test_hotspring.ambr +++ b/tests/__snapshots__/test_hotspring.ambr @@ -4,6 +4,7 @@ blower=Blower( is_enabled=False, is_on=False, + on_seconds=0, ), clean_cycle=CleanCycle( clean_timer_enabled=False, @@ -18,20 +19,16 @@ device_type=, diagnostics=Diagnostics( circulation_pump_flow_status='0', + daily_clean_cycle=0, + filter_1_minutes=60, + filter_2_minutes=30, heater_error='0', - heater_power='0', - heater_volts=0.0, - jet1_jet2_blower_power='0', - jet3_power='0', - jet3_volts=0.0, - l1_n_volts=0.0, - l2_n_volts=0.0, + jet3_volts=0, limit_thermistor_status='0', power_frequency='0', - pressure_switch_status='0', + pressure_switch_status='1', regulation_thermistor_temp_status='0', - small_loads_power='0', - spa_failure_state=, + spa_failure_state=, ), energy_savings=dict({ 1: EnergySaving( @@ -63,9 +60,7 @@ ), heater=Heater( current_temperature=100.0, - heater_current=7.5, heater_lock=False, - heater_on_seconds=52046, heating_mode=, heatpump_installed=False, is_on=True, @@ -89,25 +84,22 @@ jets=dict({ 1: Jet( concurrent_mode=False, - current=0.0, is_enabled=True, jet_id=1, - on_seconds=1061668, + on_seconds=52046, speed=, speed_type=, ), 2: Jet( concurrent_mode=False, - current=0.0, is_enabled=True, jet_id=2, - on_seconds=0, + on_seconds=None, speed=, speed_type=, ), 3: Jet( concurrent_mode=False, - current=0.0, is_enabled=False, jet_id=3, on_seconds=0, @@ -172,15 +164,25 @@ logo_light=LogoLight( brightness=, ), + needs_diagnostics_for_power=True, + power=PowerMetrics( + heater_current=14, + heater_power=3584, + jet1_jet2_blower_current=15, + jet1_jet2_blower_power=0, + jet3_current=0, + jet3_power=0, + small_loads_current=0, + small_loads_power=75, + supported=True, + ), spa_lock=SpaLock( is_locked=False, ), + system_uptime_hours=294.91, + system_uptime_seconds=1061668, test_metrics=SpaTestData( - heater_current=7.5, heater_test_status='off', - jet1_jet2_blower_current=0.0, - jet3_current=0.0, - small_loads_current=0.0, temp_offset=0.0, vsense_cal=0.0, ), @@ -213,19 +215,15 @@ # name: TestUpdateDiagnostics.test_update_diagnostics Diagnostics( circulation_pump_flow_status='0', + daily_clean_cycle=0, + filter_1_minutes=60, + filter_2_minutes=30, heater_error='0', - heater_power='60', - heater_volts=0.0, - jet1_jet2_blower_power='14', - jet3_power='30', - jet3_volts=112.0, - l1_n_volts=0.0, - l2_n_volts=120.0, + jet3_volts=0, limit_thermistor_status='0', power_frequency='0', pressure_switch_status='1', regulation_thermistor_temp_status='0', - small_loads_power='0', spa_failure_state=, ) # --- diff --git a/tests/__snapshots__/test_models.ambr b/tests/__snapshots__/test_models.ambr index db541ea..66fa4cf 100644 --- a/tests/__snapshots__/test_models.ambr +++ b/tests/__snapshots__/test_models.ambr @@ -3,12 +3,14 @@ Blower( is_enabled=False, is_on=False, + on_seconds=None, ) # --- # name: TestBlower.test_from_dict_enabled_on Blower( is_enabled=True, is_on=True, + on_seconds=None, ) # --- # name: TestCleanCycle.test_from_dict @@ -28,19 +30,15 @@ # name: TestDiagnostics.test_from_dict Diagnostics( circulation_pump_flow_status='0', + daily_clean_cycle=0, + filter_1_minutes=60, + filter_2_minutes=30, heater_error='0', - heater_power='60', - heater_volts=0.0, - jet1_jet2_blower_power='14', - jet3_power='30', - jet3_volts=112.0, - l1_n_volts=0.0, - l2_n_volts=120.0, + jet3_volts=0, limit_thermistor_status='0', power_frequency='0', pressure_switch_status='1', regulation_thermistor_temp_status='0', - small_loads_power='0', spa_failure_state=, ) # --- @@ -121,9 +119,7 @@ # name: TestHeater.test_from_dict Heater( current_temperature=100.0, - heater_current=7.5, heater_lock=False, - heater_on_seconds=52046, heating_mode=, heatpump_installed=False, is_on=True, @@ -135,28 +131,25 @@ dict({ 1: Jet( concurrent_mode=False, - current=0.0, is_enabled=True, jet_id=1, - on_seconds=1061668, + on_seconds=None, speed=, speed_type=, ), 2: Jet( concurrent_mode=False, - current=0.0, is_enabled=True, jet_id=2, - on_seconds=0, + on_seconds=None, speed=, speed_type=, ), 3: Jet( concurrent_mode=False, - current=0.0, is_enabled=False, jet_id=3, - on_seconds=0, + on_seconds=None, speed=, speed_type=, ), @@ -165,10 +158,9 @@ # name: TestJet.test_jet3_concurrent_and_current Jet( concurrent_mode=True, - current=3.6, is_enabled=True, jet_id=3, - on_seconds=2, + on_seconds=None, speed=, speed_type=, ) @@ -249,11 +241,233 @@ brightness=, ) # --- +# name: TestPowerMetrics.test_reconstructed_load_states[both_jets_high] + PowerMetrics( + heater_current=0, + heater_power=0, + jet1_jet2_blower_current=14, + jet1_jet2_blower_power=3870, + jet3_current=0, + jet3_power=0, + small_loads_current=0, + small_loads_power=61, + supported=True, + ) +# --- +# name: TestPowerMetrics.test_reconstructed_load_states[heater_and_jet1_high] + PowerMetrics( + heater_current=15, + heater_power=3903, + jet1_jet2_blower_current=7, + jet1_jet2_blower_power=1806, + jet3_current=0, + jet3_power=0, + small_loads_current=0, + small_loads_power=71, + supported=True, + ) +# --- +# name: TestPowerMetrics.test_reconstructed_load_states[heater_only] + PowerMetrics( + heater_current=15, + heater_power=3958, + jet1_jet2_blower_current=0, + jet1_jet2_blower_power=0, + jet3_current=0, + jet3_power=0, + small_loads_current=0, + small_loads_power=63, + supported=True, + ) +# --- +# name: TestPowerMetrics.test_reconstructed_load_states[idle_synced] + PowerMetrics( + heater_current=0, + heater_power=0, + jet1_jet2_blower_current=0, + jet1_jet2_blower_power=0, + jet3_current=0, + jet3_power=0, + small_loads_current=0, + small_loads_power=63, + supported=True, + ) +# --- +# name: TestPowerMetrics.test_reconstructed_load_states[jet1_low] + PowerMetrics( + heater_current=0, + heater_power=0, + jet1_jet2_blower_current=1, + jet1_jet2_blower_power=520, + jet3_current=0, + jet3_power=0, + small_loads_current=0, + small_loads_power=72, + supported=True, + ) +# --- +# name: TestPowerMetrics.test_reconstructed_load_states[jet3_active] + PowerMetrics( + heater_current=0, + heater_power=0, + jet1_jet2_blower_current=0, + jet1_jet2_blower_power=0, + jet3_current=8, + jet3_power=1992, + small_loads_current=0, + small_loads_power=70, + supported=True, + ) +# --- +# name: TestPowerMetrics.test_reconstructed_load_states[missing_debug_key] + PowerMetrics( + heater_current=0, + heater_power=0, + jet1_jet2_blower_current=None, + jet1_jet2_blower_power=520, + jet3_current=0, + jet3_power=0, + small_loads_current=None, + small_loads_power=72, + supported=True, + ) +# --- +# name: TestPowerMetrics.test_status_only_power_metrics[heating_awaiting_debug] + PowerMetrics( + heater_current=None, + heater_power=None, + jet1_jet2_blower_current=0, + jet1_jet2_blower_power=0, + jet3_current=0, + jet3_power=0, + small_loads_current=None, + small_loads_power=63, + supported=True, + ) +# --- +# name: TestPowerMetrics.test_status_only_power_metrics[idle_awaiting_baseline_debug] + PowerMetrics( + heater_current=0, + heater_power=0, + jet1_jet2_blower_current=0, + jet1_jet2_blower_power=0, + jet3_current=0, + jet3_power=0, + small_loads_current=None, + small_loads_power=63, + supported=True, + ) +# --- +# name: TestPowerMetrics.test_status_only_power_metrics[jet1_awaiting_debug] + PowerMetrics( + heater_current=0, + heater_power=0, + jet1_jet2_blower_current=None, + jet1_jet2_blower_power=1819, + jet3_current=0, + jet3_power=0, + small_loads_current=None, + small_loads_power=72, + supported=True, + ) +# --- +# name: TestPowerMetrics.test_status_only_power_metrics[jet3_awaiting_debug] + PowerMetrics( + heater_current=0, + heater_power=0, + jet1_jet2_blower_current=0, + jet1_jet2_blower_power=0, + jet3_current=8, + jet3_power=None, + small_loads_current=None, + small_loads_power=70, + supported=True, + ) +# --- +# name: TestPowerMetrics.test_status_transitions_on_active_spa[all_jets_off_echo_zeroes_pumps] + PowerMetrics( + heater_current=14, + heater_power=3792, + jet1_jet2_blower_current=0, + jet1_jet2_blower_power=0, + jet3_current=0, + jet3_power=0, + small_loads_current=0, + small_loads_power=70, + supported=True, + ) +# --- +# name: TestPowerMetrics.test_status_transitions_on_active_spa[heater_off_echo_zeroes_heater] + PowerMetrics( + heater_current=0, + heater_power=0, + jet1_jet2_blower_current=14, + jet1_jet2_blower_power=3870, + jet3_current=0, + jet3_power=0, + small_loads_current=0, + small_loads_power=70, + supported=True, + ) +# --- +# name: TestPowerMetrics.test_status_transitions_on_active_spa[incomplete_test_data_status_ignored] + PowerMetrics( + heater_current=14, + heater_power=3792, + jet1_jet2_blower_current=14, + jet1_jet2_blower_power=3870, + jet3_current=0, + jet3_power=0, + small_loads_current=0, + small_loads_power=70, + supported=True, + ) +# --- +# name: TestPowerMetrics.test_status_transitions_on_active_spa[jet_speed_change_echo_invalidates_pumps] + PowerMetrics( + heater_current=14, + heater_power=3792, + jet1_jet2_blower_current=None, + jet1_jet2_blower_power=None, + jet3_current=0, + jet3_power=0, + small_loads_current=0, + small_loads_power=70, + supported=True, + ) +# --- +# name: TestPowerMetrics.test_status_transitions_on_active_spa[standalone_heater_current_ignored] + PowerMetrics( + heater_current=14, + heater_power=3792, + jet1_jet2_blower_current=14, + jet1_jet2_blower_power=3870, + jet3_current=0, + jet3_power=0, + small_loads_current=0, + small_loads_power=70, + supported=True, + ) +# --- +# name: TestPowerMetrics.test_status_transitions_on_active_spa[unpaired_status_poll_preserves_heater_without_tearing] + PowerMetrics( + heater_current=14, + heater_power=3792, + jet1_jet2_blower_current=None, + jet1_jet2_blower_power=8, + jet3_current=0, + jet3_power=0, + small_loads_current=0, + small_loads_power=74, + supported=True, + ) +# --- # name: TestSpa.test_full_status_parsing Spa( blower=Blower( is_enabled=False, is_on=False, + on_seconds=0, ), clean_cycle=CleanCycle( clean_timer_enabled=False, @@ -268,19 +482,15 @@ device_type=, diagnostics=Diagnostics( circulation_pump_flow_status='0', + daily_clean_cycle=None, + filter_1_minutes=None, + filter_2_minutes=None, heater_error='0', - heater_power='0', - heater_volts=0.0, - jet1_jet2_blower_power='0', - jet3_power='0', - jet3_volts=0.0, - l1_n_volts=0.0, - l2_n_volts=0.0, + jet3_volts=None, limit_thermistor_status='0', power_frequency='0', pressure_switch_status='0', regulation_thermistor_temp_status='0', - small_loads_power='0', spa_failure_state=, ), energy_savings=dict({ @@ -313,9 +523,7 @@ ), heater=Heater( current_temperature=100.0, - heater_current=7.5, heater_lock=False, - heater_on_seconds=52046, heating_mode=, heatpump_installed=False, is_on=True, @@ -339,25 +547,22 @@ jets=dict({ 1: Jet( concurrent_mode=False, - current=0.0, is_enabled=True, jet_id=1, - on_seconds=1061668, + on_seconds=52046, speed=, speed_type=, ), 2: Jet( concurrent_mode=False, - current=0.0, is_enabled=True, jet_id=2, - on_seconds=0, + on_seconds=None, speed=, speed_type=, ), 3: Jet( concurrent_mode=False, - current=0.0, is_enabled=False, jet_id=3, on_seconds=0, @@ -422,15 +627,25 @@ logo_light=LogoLight( brightness=, ), + needs_diagnostics_for_power=True, + power=PowerMetrics( + heater_current=None, + heater_power=None, + jet1_jet2_blower_current=None, + jet1_jet2_blower_power=0, + jet3_current=0, + jet3_power=0, + small_loads_current=None, + small_loads_power=75, + supported=True, + ), spa_lock=SpaLock( is_locked=False, ), + system_uptime_hours=294.91, + system_uptime_seconds=1061668, test_metrics=SpaTestData( - heater_current=7.5, heater_test_status='off', - jet1_jet2_blower_current=0.0, - jet3_current=0.0, - small_loads_current=0.0, temp_offset=0.0, vsense_cal=0.0, ), @@ -460,6 +675,28 @@ ), ) # --- +# name: TestSpa.test_shifted_runtime_routing[pre_sync_all_zero] + tuple( + None, + None, + None, + None, + None, + None, + None, + ) +# --- +# name: TestSpa.test_shifted_runtime_routing[synced_with_signed_overflow] + tuple( + 11520034, + 3200.01, + 236234, + None, + 3600, + 1800, + 0.5, + ) +# --- # name: TestSpaInfo.test_from_dict SpaInfo( brand=, @@ -482,11 +719,7 @@ # --- # name: TestSpaTestData.test_from_dict SpaTestData( - heater_current=7.5, heater_test_status='off', - jet1_jet2_blower_current=0.0, - jet3_current=0.0, - small_loads_current=0.0, temp_offset=0.0, vsense_cal=0.0, ) diff --git a/tests/test_hotspring.py b/tests/test_hotspring.py index bbd39a0..66eba7c 100644 --- a/tests/test_hotspring.py +++ b/tests/test_hotspring.py @@ -56,6 +56,15 @@ def _json_response(fixture_name: str, status: int = 200) -> Response: ) +def _raw_json(payload: object, status: int = 200) -> Response: + """Create a JSON response from an inline payload.""" + return Response( + status=status, + headers={"Content-Type": "application/json"}, + text=json.dumps(payload), + ) + + async def _timeout_handler(_: aiohttp.web.Request) -> Response: """Simulate a slow endpoint that exceeds request_timeout.""" await asyncio.sleep(0.2) @@ -67,16 +76,21 @@ def _add_update_mocks( # noqa: PLR0913 aresponses: ResponsesMockServer, *, status_fixture: str = "status.json", + status_payload: dict[str, object] | None = None, startup_status: int = 200, startup_fixture: str = "startup.json", connect_payload: str | None = None, spamodel_status: int = 200, + debug_response: Response | None = None, ) -> None: """Add mock responses for a full update() call.""" host = "192.168.1.100" - aresponses.add( - host, Endpoint.STATUS, HTTPMethod.GET, _json_response(status_fixture) + status_response = ( + _raw_json(status_payload) + if status_payload is not None + else _json_response(status_fixture) ) + aresponses.add(host, Endpoint.STATUS, HTTPMethod.GET, status_response) aresponses.add( host, Endpoint.STARTUP, @@ -100,6 +114,12 @@ def _add_update_mocks( # noqa: PLR0913 HTTPMethod.GET, _json_response("spamodel.json", status=spamodel_status), ) + aresponses.add( + host, + Endpoint.DEBUG_DATA, + HTTPMethod.GET, + debug_response or _json_response("debug_data.json"), + ) class TestUpdate: @@ -570,7 +590,7 @@ async def test_update_water_care_without_update( class TestUpdateDiagnostics: - """Tests for the update_diagnostics() method.""" + """Tests for update_diagnostics() and opportunistic /addDebugData polling.""" async def test_update_diagnostics( self, aresponses: ResponsesMockServer, snapshot: SnapshotAssertion @@ -590,14 +610,119 @@ async def test_update_diagnostics( assert diag == snapshot + @pytest.mark.parametrize( + ("heater_current", "connect_payload", "expected_supported"), + [ + pytest.param(0, None, False, id="power_unsupported"), + pytest.param( + 19200, '{"spaConnectStatus": "false"}', True, id="spa_disconnected" + ), + ], + ) + async def test_update_skips_debug_data_when_not_needed( + self, + aresponses: ResponsesMockServer, + heater_current: int, + connect_payload: str | None, + expected_supported: bool, + ) -> None: + """Test update() skips /addDebugData when disconnected or unsupported.""" + status = json.loads(_load("status.json")) + status["test_data"]["status"]["heaterCurrent"] = heater_current + + _add_update_mocks( + aresponses, + status_payload=status, + connect_payload=connect_payload, + ) -def _raw_json(payload: object) -> Response: - """Create a JSON response from an inline payload.""" - return Response( - status=200, - headers={"Content-Type": "application/json"}, - text=json.dumps(payload), + async with aiohttp.ClientSession() as session: + client = HotSpring(host="192.168.1.100", session=session) + spa = await client.update() + + assert spa.power.supported is expected_supported + assert spa.power.total_power is None + assert Endpoint.DEBUG_DATA not in [ + entry.request.path for entry in aresponses.history + ] + + @pytest.mark.parametrize( + "debug_response", + [ + pytest.param(Response(status=500, text="error"), id="http_500"), + pytest.param( + _raw_json({"debugData": {"status": {"L1_N_Volts": "n/a"}}}), + id="malformed_payload", + ), + ], ) + async def test_update_debug_data_failure_is_non_critical( + self, aresponses: ResponsesMockServer, debug_response: Response + ) -> None: + """Test /addDebugData HTTP or parse errors do not fail update().""" + _add_update_mocks(aresponses, debug_response=debug_response) + async with aiohttp.ClientSession() as session: + client = HotSpring(host="192.168.1.100", session=session) + spa = await client.update() + + assert spa.power.supported is True + assert spa.power.small_loads_power == 75 + assert spa.power.heater_power is None + + @pytest.mark.parametrize( + ("heater_state", "jet1_speed", "expected_debug_calls", "expected_values"), + [ + pytest.param("off", "off", 1, (0, 0), id="idle_skips_after_baseline"), + pytest.param("on", "off", 2, (3584, 0), id="heater_on"), + pytest.param("off", "highSpeed", 2, (0, 15), id="jet1_high_heater_off"), + ], + ) + async def test_routine_poll_debug_data_behavior( + self, + aresponses: ResponsesMockServer, + heater_state: str, + jet1_speed: str, + expected_debug_calls: int, + expected_values: tuple[int, int], + ) -> None: + """Test routine poll skips /addDebugData while idle and fetches when active.""" + idle_status = json.loads(_load("status.json")) + idle_status["heater"]["status"]["heater"] = "off" + idle_status["JET"]["JET1"]["status"]["speed"] = "off" + + next_status = json.loads(_load("status.json")) + next_status["heater"]["status"]["heater"] = heater_state + next_status["JET"]["JET1"]["status"]["speed"] = jet1_speed + + _add_update_mocks(aresponses, status_payload=idle_status) + aresponses.add( + "192.168.1.100", Endpoint.STATUS, HTTPMethod.GET, _raw_json(next_status) + ) + aresponses.add( + "192.168.1.100", + Endpoint.SPA_CONNECT_STATUS, + HTTPMethod.GET, + _json_response("spa_connect_status.json"), + ) + aresponses.add( + "192.168.1.100", + Endpoint.DEBUG_DATA, + HTTPMethod.GET, + _json_response("debug_data.json"), + ) + + async with aiohttp.ClientSession() as session: + client = HotSpring(host="192.168.1.100", session=session) + await client.update() + spa = await client.update() + + assert ( + spa.power.heater_power, + spa.power.jet1_jet2_blower_current, + ) == expected_values + assert [entry.request.path for entry in aresponses.history].count( + Endpoint.DEBUG_DATA + ) == expected_debug_calls class TestMalformedResponse: @@ -607,12 +732,12 @@ class TestMalformedResponse: ("payload", "cause_type"), [ pytest.param( - {"heater": {"status": {"heaterCurrent": ""}}}, + {"heater": {"status": {"heaterHours": ""}}}, ValueError, id="empty_string_number", ), pytest.param( - {"heater": {"status": {"heaterCurrent": None}}}, + {"test_data": {"status": {"tempOffset": None}}}, TypeError, id="null_number", ), @@ -743,7 +868,7 @@ async def test_malformed_command_echo( "192.168.1.100", Endpoint.SPA_MANAGER, HTTPMethod.POST, - _raw_json({"heater": {"status": {"heaterCurrent": ""}}}), + _raw_json({"heater": {"status": {"heaterHours": ""}}}), ) async with aiohttp.ClientSession() as session: client = HotSpring(host="192.168.1.100", session=session) diff --git a/tests/test_models.py b/tests/test_models.py index e539512..356d1a7 100644 --- a/tests/test_models.py +++ b/tests/test_models.py @@ -30,6 +30,7 @@ Jet, LightZone, LogoLight, + PowerMetrics, Spa, SpaInfo, SpaLock, @@ -216,7 +217,7 @@ def test_jets_dict_keys(self) -> None: assert jets[3].jet_id == 3 def test_jet3_concurrent_and_current(self, snapshot: SnapshotAssertion) -> None: - """Test parsing Jet 3 concurrent mode and electrical current.""" + """Test parsing Jet 3 concurrent mode and single-speed configuration.""" jet = Jet.from_dict( 3, { @@ -226,20 +227,6 @@ def test_jet3_concurrent_and_current(self, snapshot: SnapshotAssertion) -> None: ) assert jet == snapshot - def test_jet_negative_runtime_overflow(self) -> None: - """Test graceful handling of negative signed integer overflow in runtime.""" - jet = Jet.from_dict( - 1, - { - "config": {"speed": "dualSpeed"}, - "status": {"speed": "off", "jet_1_ON_sec": -1568323328}, - }, - ) - assert jet.on_seconds == 10650953 - assert jet.on_hours == 2958.6 - assert jet.is_on is False - assert jet.speed_type == JetSpeedType.DUAL_SPEED - def test_jet_properties(self) -> None: """Test computed properties on Jet.""" dual_jet = Jet( @@ -247,7 +234,6 @@ def test_jet_properties(self) -> None: speed=JetSpeed.HIGH_SPEED, speed_type=JetSpeedType.DUAL_SPEED, is_enabled=True, - current=10.4, on_seconds=7200, ) assert dual_jet.is_available is True @@ -271,6 +257,7 @@ def test_jet_properties(self) -> None: assert single_jet.is_on is False assert single_jet.is_dual_speed is False assert single_jet.is_single_speed is True + assert single_jet.on_hours is None assert single_jet.supported_speeds == [JetSpeed.OFF, JetSpeed.HIGH_SPEED] disabled_jet = Jet( @@ -654,45 +641,62 @@ def test_from_dict( def test_from_empty_dict(self) -> None: """Test parsing diagnostics from empty dict uses defaults.""" - diag = Diagnostics.from_dict({}) - assert diag.spa_failure_state == SpaFailureState.UNKNOWN - assert diag.heater_power == "0" - - def test_from_invalid_dict(self) -> None: - """Test parsing diagnostics with invalid/null nested objects.""" - invalid_cases: list[dict[str, object]] = [ - {"debugData": None}, - {"debugData": "invalid"}, - {"debugData": {"status": None}}, - {"debugData": {"status": "invalid"}}, - {"debugData": {"status": {}}}, - ] - for invalid_data in invalid_cases: - diag = Diagnostics.from_dict(invalid_data) - assert diag.spa_failure_state == SpaFailureState.UNKNOWN - assert diag.heater_power == "0" + assert Diagnostics.from_dict({}) == Diagnostics() + + @pytest.mark.parametrize( + "invalid_data", + [ + pytest.param({"debugData": None}, id="null_debug_data"), + pytest.param({"debugData": "invalid"}, id="string_debug_data"), + pytest.param({"debugData": {"status": None}}, id="null_status"), + pytest.param({"debugData": {"status": "invalid"}}, id="string_status"), + pytest.param({"debugData": {"status": {}}}, id="empty_status"), + pytest.param( + { + "debugData": { + "status": { + "spaFailureState": "Spa_Ok", + "heaterError": "0", + "L1_N_Volts": "0", + "heaterPower": "0", + } + } + }, + id="pre_sync_all_zero", + ), + ], + ) + def test_from_invalid_dict(self, invalid_data: dict[str, object]) -> None: + """Test parsing diagnostics with invalid, empty, or pre-sync objects.""" + assert Diagnostics.from_dict(invalid_data) == Diagnostics() - def test_voltages_and_extended_keys(self) -> None: - """Test voltage computed properties and extended diagnostic keys.""" + def test_decoded_voltage_clean_cycle_and_filter_times(self) -> None: + """Test decoding shifted voltage, clean-cycle, and filter fields.""" data: dict[str, object] = { "debugData": { "status": { "spaFailureState": "Spa_Ok", "circulationPumpFlowStatus": "1", - "regulationThermistorTempStatus": "2", - "limitThermistorStatus": "3", - "L1_N_Volts": "3840", - "L2_N_Volts": "3584", - "jet3_Volts": "3840", + "regulationThermistorTempStatus": "1", + "limitThermistorStatus": "1", + "L1_N_Volts": "61441", + "L2_N_Volts": "1792", + "smallLoadsPower": "256", + "heaterPower": "90", + "jet3Power": "45", } } } - diag = Diagnostics.from_dict(data) - assert diag.circulation_pump_flow_status == "1" - assert diag.regulation_thermistor_temp_status == "2" - assert diag.limit_thermistor_status == "3" - assert diag.l1_n_volts == 120.0 - assert diag.l2_n_volts == 112.0 + assert Diagnostics.from_dict(data) == Diagnostics( + spa_failure_state=SpaFailureState.OK, + circulation_pump_flow_status="1", + regulation_thermistor_temp_status="1", + limit_thermistor_status="1", + jet3_volts=240, + daily_clean_cycle=1, + filter_1_minutes=90, + filter_2_minutes=45, + ) class TestSpaTestData: @@ -707,8 +711,327 @@ def test_from_dict( def test_from_empty_dict(self) -> None: """Test parsing test data from empty dict uses defaults.""" - test_metrics = SpaTestData.from_dict({}) - assert test_metrics.small_loads_current == 0.0 + assert SpaTestData.from_dict({}) == SpaTestData() + + def test_calibration_fields_preserved_on_partial_update(self) -> None: + """Test partial SpaTestData update preserves existing calibration values.""" + existing = SpaTestData( + heater_test_status="on", temp_offset=0.5, vsense_cal=-1.2 + ) + updated = SpaTestData.from_dict( + {"status": {"heaterTestStatus": "off"}}, existing=existing + ) + assert updated == SpaTestData( + heater_test_status="off", temp_offset=0.5, vsense_cal=-1.2 + ) + + +def _power_status( + electrical_words: tuple[int, int, int, int] = (0, 0, 0, 0), + *, + heater: str = "off", + jet1: str = "off", + jet2: str = "off", + jet3: str | None = None, +) -> dict[str, object]: + """Build a minimal /status payload for power reconstruction tests.""" + ( + jet1_jet2_blower_current_word, + small_loads_current_word, + heater_current_word, + jet3_current_word, + ) = electrical_words + jets: dict[str, object] = { + "JET1": {"status": {"speed": jet1}}, + "JET2": {"status": {"speed": jet2}}, + } + if jet3 is not None: + jets["JET3"] = {"config": {"JET3": "enable"}, "status": {"speed": jet3}} + return { + "heater": {"status": {"heater": heater}}, + "JET": jets, + "test_data": { + "status": { + "jet1+jet2+blowerCurrent": jet1_jet2_blower_current_word, + "smallLoadsCurrent": small_loads_current_word, + "heaterCurrent": heater_current_word, + "jet3Current": jet3_current_word, + } + }, + } + + +def _power_debug( + *, + l2_volts: int = 0, + heater_volts: int | None = 0, + jet3_volts: int = 0, + jet1_jet2_blower_power: int = 0, + small_loads_power: int = 0, +) -> dict[str, object]: + """Build a minimal synced /addDebugData payload for power reconstruction tests.""" + words = { + "L2_N_Volts": l2_volts, + "Heater_Volts": heater_volts, + "jet3_Volts": jet3_volts, + "jet1_jet2_blowerPower": jet1_jet2_blower_power, + "smallLoadsPower": small_loads_power, + } + return { + "debugData": { + "status": { + "spaFailureState": "Spa_Ok", + "pressureSwitchStatus": "1", + **{k: str(v) for k, v in words.items() if v is not None}, + } + } + } + + +class TestPowerMetrics: + """Tests for reconstructed PowerMetrics across /status and /addDebugData.""" + + @pytest.mark.parametrize( + "status_data", + [ + pytest.param({}, id="empty"), + pytest.param(_power_status(heater="on"), id="unsupported_board"), + ], + ) + def test_unsupported_status_returns_default_power_metrics( + self, status_data: dict[str, object] + ) -> None: + """Test missing or zeroed electrical status keeps PowerMetrics unsupported.""" + assert Spa(status_data).power == PowerMetrics() + + @pytest.mark.parametrize( + "status_data", + [ + pytest.param( + _power_status((0, 0, 16128, 0)), + id="idle_awaiting_baseline_debug", + ), + pytest.param( + _power_status((0, 6912, 18439, 0), jet1="highSpeed"), + id="jet1_awaiting_debug", + ), + pytest.param( + _power_status((0, 0, 16128, 30208), heater="on"), + id="heating_awaiting_debug", + ), + pytest.param( + _power_status((2048, 0, 17920, 0), jet3="highSpeed"), + id="jet3_awaiting_debug", + ), + ], + ) + def test_status_only_power_metrics( + self, + status_data: dict[str, object], + snapshot: SnapshotAssertion, + ) -> None: + """Test power state derived from /status alone before /addDebugData.""" + assert Spa(status_data).power == snapshot + + @pytest.mark.parametrize( + ("status_data", "debug_data"), + [ + pytest.param( + _power_status((0, 0, 16128, 0)), + _power_debug(), + id="idle_synced", + ), + pytest.param( + _power_status((0, 2048, 18434, 0), jet1="lowSpeed"), + _power_debug(l2_volts=256), + id="jet1_low", + ), + pytest.param( + _power_status((0, 7680, 15631, 0), jet1="highSpeed", jet2="highSpeed"), + _power_debug(l2_volts=3584), + id="both_jets_high", + ), + pytest.param( + _power_status((0, 0, 16128, 30208), heater="on"), + _power_debug(jet3_volts=3840, jet1_jet2_blower_power=15), + id="heater_only", + ), + pytest.param( + _power_status((0, 3584, 18183, 16128), heater="on", jet1="highSpeed"), + _power_debug(l2_volts=1792, jet3_volts=3840, jet1_jet2_blower_power=15), + id="heater_and_jet1_high", + ), + pytest.param( + _power_status((2048, 0, 17920, 0), jet3="highSpeed"), + _power_debug(jet1_jet2_blower_power=51200, small_loads_power=7), + id="jet3_active", + ), + pytest.param( + _power_status((0, 2048, 18434, 0), jet1="lowSpeed"), + _power_debug(l2_volts=256, heater_volts=None), + id="missing_debug_key", + ), + ], + ) + def test_reconstructed_load_states( + self, + status_data: dict[str, object], + debug_data: dict[str, object], + snapshot: SnapshotAssertion, + ) -> None: + """Test byte-reconstructed power and current across active spa circuits.""" + spa = Spa(status_data) + spa.update_diagnostics(debug_data) + assert spa.power == snapshot + + @pytest.mark.parametrize( + ("status_data", "debug_data", "expected"), + [ + pytest.param({}, {}, False, id="empty"), + pytest.param(_power_status(heater="on"), {}, False, id="unsupported"), + pytest.param(_power_status((0, 0, 16128, 0)), {}, True, id="idle_unsynced"), + pytest.param( + _power_status((0, 0, 16128, 0)), _power_debug(), False, id="idle_synced" + ), + pytest.param( + _power_status((0, 0, 16128, 30208), heater="on"), + _power_debug(jet3_volts=3840, jet1_jet2_blower_power=15), + True, + id="heater_synced", + ), + pytest.param( + _power_status((0, 0, 16128, 0)), + _power_debug(heater_volts=None), + True, + id="missing_debug_key", + ), + ], + ) + def test_needs_diagnostics_for_power( + self, + status_data: dict[str, object], + debug_data: dict[str, object], + expected: bool, + ) -> None: + """Test when /addDebugData polling is required for baseline or active loads.""" + spa = Spa(status_data) + spa.update_diagnostics(debug_data) + assert spa.needs_diagnostics_for_power is expected + + @pytest.mark.parametrize( + ("power", "expected_total"), + [ + pytest.param( + PowerMetrics( + supported=True, + small_loads_power=63, + jet1_jet2_blower_power=1806, + heater_power=3903, + jet3_power=0, + ), + 5772, + id="all_circuits_known", + ), + pytest.param( + PowerMetrics(supported=True, small_loads_power=63), + None, + id="partial_circuits", + ), + ], + ) + def test_total_power(self, power: PowerMetrics, expected_total: int | None) -> None: + """Test derived total_power across known and incomplete circuit readings.""" + assert power.total_power == expected_total + + @pytest.mark.parametrize( + "status_update", + [ + pytest.param( + {"heater": {"status": {"heater": "off"}}}, + id="heater_off_echo_zeroes_heater", + ), + pytest.param( + {"JET": {"JET1": {"control": "lowSpeed"}}}, + id="jet_speed_change_echo_invalidates_pumps", + ), + pytest.param( + {"JET": {"JET1": {"control": "off"}, "JET2": {"control": "off"}}}, + id="all_jets_off_echo_zeroes_pumps", + ), + pytest.param( + _power_status((0, 2048, 18944, 5120), heater="on", jet1="lowSpeed"), + id="unpaired_status_poll_preserves_heater_without_tearing", + ), + pytest.param( + {"heater": {"status": {"heater": "on", "heaterCurrent": 16128}}}, + id="standalone_heater_current_ignored", + ), + pytest.param( + { + "test_data": { + "status": { + "jet1+jet2+blowerCurrent": 0, + "smallLoadsCurrent": 0, + "heaterCurrent": 16128, + } + } + }, + id="incomplete_test_data_status_ignored", + ), + ], + ) + def test_status_transitions_on_active_spa( + self, + status_update: dict[str, object], + snapshot: SnapshotAssertion, + ) -> None: + """Test follow-up status and command-echo updates on an active spa.""" + spa = Spa( + _power_status( + (0, 7680, 17935, 53248), + heater="on", + jet1="highSpeed", + jet2="highSpeed", + ) + ) + spa.update_diagnostics( + _power_debug(l2_volts=3584, jet3_volts=3584, jet1_jet2_blower_power=14) + ) + spa.update_from_dict(status_update) + assert spa.power == snapshot + + def test_unsynced_debug_data_preserves_active_power_and_diagnostics(self) -> None: + """Test empty /addDebugData keeps cached active power and diagnostics.""" + spa = Spa(_power_status((0, 0, 16128, 30208), heater="on")) + spa.update_diagnostics(_power_debug(jet3_volts=3840, jet1_jet2_blower_power=15)) + expected = (spa.power, spa.diagnostics) + + spa.update_diagnostics({}) + assert (spa.power, spa.diagnostics) == expected + + def test_echo_invalidates_pending_status_words(self) -> None: + """Test a circuit-changing echo discards pending /status electrical words.""" + spa = Spa(_power_status((0, 0, 16128, 0), heater="off")) + spa.update_from_dict({"heater": {"status": {"heater": "on"}}}) + spa.update_diagnostics(_power_debug(jet3_volts=3840, jet1_jet2_blower_power=15)) + + assert ( + spa.power.small_loads_current, + spa.power.heater_power, + spa.power.heater_current, + ) == (0, None, None) + + def test_pending_status_words_consumed_on_first_diagnostics(self) -> None: + """Test pending /status electrical words are paired with at most one poll.""" + spa = Spa(_power_status((0, 0, 16128, 30208), heater="on")) + spa.update_diagnostics(_power_debug(jet3_volts=3840, jet1_jet2_blower_power=14)) + spa.update_diagnostics(_power_debug(jet3_volts=3840, jet1_jet2_blower_power=15)) + + assert ( + spa.power.small_loads_current, + spa.power.heater_power, + spa.power.heater_current, + ) == (0, 3702, 15) class TestSpaInfo: @@ -1105,6 +1428,8 @@ def test_update_from_dict_full_reparse( assert "test_metrics" in updated assert "energy_savings" in updated assert "versions" in updated + assert "power" in updated + assert "system_uptime_seconds" in updated def test_update_from_dict_non_dict_section( self, status_response: dict[str, object] @@ -1133,7 +1458,7 @@ def test_update_from_dict_multiple_sections( "blower": {"config": {"blower": "enable"}, "status": {"blower": "on"}}, } updated = spa.update_from_dict(payload) - assert updated == {"heater", "blower"} + assert updated == {"heater", "blower", "power"} assert spa.heater.is_on is False assert spa.blower.is_on is True @@ -1272,6 +1597,7 @@ def test_partial_update_single_jet( assert len(spa.jets) == 3 assert spa.jets[1].speed == JetSpeed.HIGH_SPEED initial_on_seconds = spa.jets[1].on_seconds + assert initial_on_seconds is not None assert initial_on_seconds > 0 # Simulate a command response updating JET1 to off @@ -1286,7 +1612,7 @@ def test_partial_update_single_jet( } } updated = spa.update_from_dict(partial_payload) - assert updated == {"jets"} + assert updated == {"jets", "power"} assert len(spa.jets) == 3 assert spa.jets[1].speed == JetSpeed.OFF @@ -1295,6 +1621,44 @@ def test_partial_update_single_jet( assert spa.jets[2].jet_id == 2 assert spa.jets[3].jet_id == 3 + @pytest.mark.parametrize( + "raw_runtimes", + [ + pytest.param( + (60475904, -1345838592, 921600, 460800), + id="synced_with_signed_overflow", + ), + pytest.param((0, 0, 0, 0), id="pre_sync_all_zero"), + ], + ) + def test_shifted_runtime_routing( + self, + raw_runtimes: tuple[int, int, int, int], + snapshot: SnapshotAssertion, + ) -> None: + """Test shifted runtime routing, signed overflow, and pre-sync zeros.""" + heater_hours, jet1_raw, jet2_raw, jet3_raw = raw_runtimes + spa = Spa( + { + "heater": {"status": {"heater": "off", "heaterHours": heater_hours}}, + "JET": { + "JET1": {"status": {"speed": "off", "jet_1_ON_sec": jet1_raw}}, + "JET2": {"status": {"speed": "off", "jet_2_ON_sec": jet2_raw}}, + "JET3": {"status": {"speed": "off", "jet_3_ON_sec": jet3_raw}}, + }, + "blower": {"config": {"blower": "enable"}, "status": {"blower": "off"}}, + } + ) + assert ( + spa.system_uptime_seconds, + spa.system_uptime_hours, + spa.jets[1].on_seconds, + spa.jets[2].on_seconds, + spa.jets[3].on_seconds, + spa.blower.on_seconds, + spa.blower.on_hours, + ) == snapshot + def test_partial_update_versions(self, status_response: dict[str, object]) -> None: """Test updating product versions partially retains cached fields.""" spa = Spa(status_response)