Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 5 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
Expand Down
52 changes: 36 additions & 16 deletions demo/demo_print_data.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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")
Expand All @@ -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}"
)


Expand Down Expand Up @@ -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")
Expand Down
2 changes: 2 additions & 0 deletions src/hotspring/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@
Jet,
LightZone,
LogoLight,
PowerMetrics,
Spa,
SpaInfo,
SpaLock,
Expand Down Expand Up @@ -71,6 +72,7 @@
"LightWheelMode",
"LightZone",
"LogoLight",
"PowerMetrics",
"Spa",
"SpaBrand",
"SpaFailureState",
Expand Down
16 changes: 15 additions & 1 deletion src/hotspring/hotspring.py
Original file line number Diff line number Diff line change
Expand Up @@ -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:
----
Expand Down Expand Up @@ -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

Expand All @@ -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.

Expand Down
Loading
Loading