Python-hotspring

⚠️ Breaking Changes

* Removed `is_hna` and `is_sna` properties on `Spa` and `SpaInfo` in favor of `DeviceType`.
* Moved `device_type` strictly to `spa.info.device_type`.

🚀 Enhancements & Bug Fixes

* Fix HNA incorrectly detected as an SNA when the SNA has a numerically higher MAC address than the HNA (21).
* Preserve HNA identification during temporary radio link drops by checking cached control box firmware version (21).
* Prevent non-critical `/startup` response errors from falsely triggering `HotSpringSNADetectedError` (21).

What’s Changed

* Refactor adapter role detection and remove redundant SNA properties Moustachauve (21)

What’s changed

🚀 Enhancements

- feat(client): allow float values for set_temperature to support Celsius half-degree steps Moustachauve (20)

Version `3.0.0` is a major release that significantly improves connection stability over the LoRA radio link, protects against device configuration errors, expands spa control capabilities, and modernizes collection data structures.

---

🚨 Breaking Changes & Migration Guide

- **Collections are now dictionaries keyed by hardware ID (`int`) instead of lists**:
- `Spa.jets`: now `dict[int, Jet]` (previously `list[Jet]`)
- `Spa.light_zones`: now `dict[int, LightZone]` (previously `list[LightZone]`)
- `Spa.energy_savings`: now `dict[int, EnergySavingSchedule]` (previously `list[...]`)

**Migration:**
python
Before (v2.x)
jet_1 = spa.jets[0]
for jet in spa.jets:
...

After (v3.0.0)
jet_1 = spa.jets[1] Direct access by hardware ID (1, 2, ...)
for jet in spa.jets.values(): Iterate values
...


---

🌟 Highlights & Key Improvements

1. **LoRA Link Stability & Dropout Prevention (19)**:
- Queries (`/status`, `/spaConnectStatus`) are now executed sequentially instead of in parallel via `asyncio.gather`, avoiding socket starvation and radio queue contention on the HNA's single-threaded web server.
- Removed aggressive backoff retry storms on routine polling (`request_retries=0` default). Polling failures now fail fast instead of locking up the radio for 30+ seconds.
- Added automatic fallback for `spa_connected` if `/spaConnectStatus` temporarily drops while `/status` succeeds.

2. **HNA vs. SNA Adapter Detection (18)**:
- Added automatic validation to ensure connections target the **Home Network Adapter (HNA)** rather than the **Spa Network Adapter (SNA)**. Connecting to an SNA will now raise a clear `HotSpringSNADetectedError`.

3. **Expanded Controls & Capabilities (13, 15)**:
- Added controls for spa locks (temperature lock, spa lock), clean cycle, and energy savings schedule configuration.
- Added jet speed types (single-speed, two-speed, blower), capabilities, and concurrent mode support.

4. **Telemetry, Diagnostics & Runtime Tracking (16)**:
- Added runtime hours tracking for the heater and individual jet pumps (with 16-bit hardware counter rollover handling).
- Added raw test point metrics (currents, voltages, sensor flow/limits, and board diagnostics).

---

What’s changed

- test: adopt syrupy snapshot testing for models and client Moustachauve (14)

🚨 Breaking changes

- refactor(models)!: store jets, light_zones, and energy_savings as dicts keyed by ID Moustachauve (17)

✨ New features

- feat(jets): expose jet capabilities, speed types, and runtime status Moustachauve (13)
- feat(controls): add switch, lock, and schedule controls Moustachauve (15)
- feat(models): add runtime tracking, fix counter overflow, and expand diagnostics Moustachauve (16)
- feat(client): detect HNA vs SNA and guard against connecting to SNA Moustachauve (18)

🐛 Bug fixes

- fix(client): serialize queries sequentially and prevent retry storms on LoRA link Moustachauve (19)

What’s changed

✨ New features
- **HNA vs. SNA Device Detection**: Automatically detect whether a target device is the Home Network Adapter (HNA) or the tub-side Spa Network Adapter (SNA) by comparing `HOSTNAME` against `rootTopic`.
- **`DeviceType` & Helper Properties**: Added `DeviceType` enum (`HNA`, `SNA`, `UNKNOWN`) and `spa.info.device_type`, `spa.info.is_hna`, and `spa.info.is_sna` properties to `SpaInfo`.
- **Fast Discovery Helper**: Added `HotSpring.get_device_info()` to fetch lightweight device identity from `/startup` without querying the LoRA radio endpoints (`/status`, etc.)—ideal for Home Assistant mDNS/zeroconf/DHCP discovery flows.
- **Custom Exceptions**: Added `HotSpringSNADetectedError` (subclass of `HotSpringInvalidDeviceError` and `HotSpringError`) when an SNA device is encountered.

🛡️ Safety & Reliability
- **Guarded Connection**: `HotSpring.update()` and `HotSpring.update_identity()` now guard against connecting to an SNA by default (`validate_device=True`), preventing silent failures and communication timeouts with the tub. An opt-out is available via `validate_device=False`.

**Full Changelog**: https://github.com/Moustachauve/python-hotspring/compare/v2.0.1...v2.1.0

What’s changed

🐛 Bug fixes

- fix(hotspring): refresh connection status on routine update polling Moustachauve (12)

🚨 Breaking Changes & Migration

- **Lighting Controls**:
- `set_light_color(zone, color)` now only sets the color (`intensity` and `light_wheel` kwargs removed).
- `set_light_brightness(zone, brightness)` now accepts discrete levels `0`–`5` (replacing `full: bool`).
- Added `set_light_wheel(zone, mode)` for rainbow / color cycle modes (`LightWheelMode`).
- `LightColor.OFF` removed; `LightZone.is_on` is now determined by `intensity > 0`.
- **Identity Data Caching**:
- `HotSpring.update()` only polls dynamic telemetry endpoints on routine updates.
- Static identity endpoints (`/startup`, `/spamodel`) are cached after initial sync. Use `await client.update_identity()` to refresh static info.

✨ Features & Enhancements

- **Reactive Command Responses**: Commands sent to `/spaManager` now immediately update the internal `spa` state model from response payloads (9).
- **Enum Flexibility**: `set_jet()` and `set_heating_mode()` now accept both Enum instances (`JetSpeed`, `HeatingMode`) and raw strings (9).
- **Custom RGB Support**: Added custom RGB state parsing in `LightZone` and strict `0-255` validation in `set_light_rgb()` (8).
- **Concurrent Initial Sync**: Initial identity queries (`/startup` and `/spamodel`) are fetched concurrently (10).

🐛 Bug Fixes

- Fixed parsing of control payloads in command responses to preserve valid local state (11).
- Improved versions partial update, FWIQ installation state detection, and safe diagnostics parsing (11).

📦 Changes

- fix(lights): improve lighting controls, discrete brightness levels, and state evaluation (8)
- feat: declarative partial state updates and reactive command responses (9)
- perf(hotspring): cache static identity data on routine status updates (10)
- fix(models): parse control payloads in command responses and preserve valid state (11)

All changes

- fix(lights): improve lighting controls, discrete brightness levels, and state evaluation Moustachauve (8)
- feat: declarative partial state updates and reactive command responses Moustachauve (9)
- perf(hotspring): cache static identity data on routine status updates Moustachauve (10)
- fix(models): parse control payloads in command responses and preserve valid state Moustachauve (11)