cryptk / cryptk/python-omnilogic-local
[BUG] - Telemetry parsing fails in Service Mode — bow is required, but the controller intentionally omits <BodyOfWater> during the safety lockout
- Dominant language
- Python
- Stars
- 10
- Forks
- 13
- Avg merge
- 5m
- Merged PRs (30d)
- 2
Description
## Disclosure / Notes
Claude did all the heavy lifting for me from a claude code session running on my Home Assistant docker host to review logs, code and HA history. Filing the bug here and not in haomnilogic-local since the issue is part of python-omnilogic-local. I've reviewed what claude did and the information provided. Also, of note, my controller is connected via ethernet, not wifi.
## Summary
`Telemetry.bow` is declared as a required field. When the OmniLogic controller is placed in
**Service Mode** from the front panel, it stops emitting `` elements entirely — the
telemetry document reduces to just ``. `Telemetry.model_validate` then raises
`OmniParsingError`, and the library returns nothing at all for the whole duration of the lockout.
This is not a malformed or corrupted response. Service Mode is a **safety interlock**: it locks out
every remote client so that equipment cannot be started while someone is physically working on it.
The Hayward mobile app is equally locked out during Service Mode, which suggests the controller is
deliberately withholding body-of-water state from all clients rather than glitching. The library is
modelling an intentional, documented operating state as a parse failure.
Related but distinct from #155 (that one is an enum range issue on `valveActuatorState`; this is a
required-field issue on a structurally different response shape). Same downstream symptom.
## Environment
| | |
|---|---|
| `python-omnilogic-local` | 5.0.0 |
| pydantic | 2.13.4 |
| Controller firmware (`mspVersion`) | `R0502000`, build revision 28706 |
| Telemetry `STATUS version` | 1.12 (`statusVersion="12"`) |
| Downstream | `haomnilogic-local` 2.0.1 on Home Assistant 2026.8.3 |
## Evidence
Entering Service Mode from the front panel, per the controller's own USB log export:
```
[2026/08/25 18:53:23][Warn][UI][Current Link: node://UIFlow/shutdown.node, PreviousScreen: 2, Current Screen: 38, Running Mode: 3]
[2026/08/25 18:53:29][Notify][PoolLogic][[ 115] UI_SET_SYSTEM_STATE]
[2026/08/25 18:53:29][Warn][UI][[UI_ServiceMode_RemoveTimedServiceEvent:613]ServiceModeTimerFindAndRemoveByEvent]
[2026/08/25 18:53:29][Warn][UI][Current Link: node://UIFlow/serviceMode/serviceModeTop.node, PreviousScreen: 38, Current Screen: 41]
[2026/08/25 18:53:29][Warn][Term-Handler][HPN_SystemStateSet():194, Set System State: "Enter Service Mode", NodeId: 65021]
```
Thirteen seconds later, the next telemetry poll failed, and kept failing until Service Mode was
exited:
```
2026-08-25 18:53:42 OmniParsingError: Failed to parse Telemetry: 1 validation error for Telemetry
BodyOfWater
Field required [type=missing, input_value={'@version': '1.12', 'Bac...spVersion': 'R0502000'}}, input_type=dict]
For further information visit https://errors.pydantic.dev/2.13/v/missing
```
Note the truncated `input_value`: the document that arrived contained the `Backyard` element and
nothing else. Exactly **one** validation error is reported, because every other equipment
collection is already optional — `bow` is the only required one, so it is the only thing that
fails.
Timeline, cross-referencing the panel log against the client:
| Time | Event |
|---|---|
| 18:53:29 | "Enter Service Mode" set on the front panel |
| 18:53:42 | First `OmniParsingError` — `BodyOfWater` missing |
| 18:53:42 → 18:55:26 | Every poll fails; 12 consecutive `OmniParsingError` in total |
| 18:55:26 | Service Mode exited → `BodyOfWater` returns → parsing resumes immediately |
Nothing else was wrong: the controller was healthy throughout, the pool equipment kept running,
and the network path was unaffected.
## Minimal reproduction
The XML below is a constructed minimal case, not a captured document — but it reproduces the exact
error above. `state="2"` is `BackyardState.SERVICE_MODE`.
```python
from pyomnilogic_local.models.telemetry import Telemetry
from pyomnilogic_local.models.exceptions import OmniParsingError
SERVICE_MODE = """
"""
try:
t = Telemetry.load_xml(SERVICE_MODE)
print("parsed OK, backyard state =", t.backyard.state)
except OmniParsingError as e:
print(f"{type(e).__name__}: {e}")
```
Output:
```
OmniParsingError: Failed to parse Telemetry: 1 validation error for Telemetry
BodyOfWater
Field required [type=missing, input_value={'@version': '1.12', 'Backyard': {'@systemId': '0', ...}}, input_type=dict]
```
## Root cause
`models/telemetry.py` L503:
```python
bow: list[TelemetryBoW] = Field(alias="BodyOfWater")
```
No default, so pydantic treats it as required. The class docstring 24 lines above states the
intent explicitly:
> All equipment collections except backyard and bow are optional and will be None
So `bow` being required is deliberate — it just doesn't account for Service Mode, where the
controller legitimately reports no bodies of water.
## Proposed fix
Give `bow` a default so a Service Mode document parses:
```python
bow: list[TelemetryBoW] = Field(alias="BodyOfWater", default_factory=list)
```
I've suggested `default_factory=list` rather than `| None = None` because existing consumers
iterate `telemetry.bow` directly and an empty list keeps them working unchanged. That said,
`None` would match the convention already used for the other optional collections and would let
callers distinguish "Service Mode" from "no bodies of water configured."
Callers that want to detect the lockout explicitly can then read
`telemetry.backyard.state == BackyardState.SERVICE_MODE`, which already parses correctly
(`BackyardState` defines `SERVICE_MODE = 2` and `TIMED_SERVICE_MODE = 4`).
I verified this by applying the change in-memory against 5.0.0 and re-validating the same
Service Mode document:
```
parsed OK -> backyard.state = Service Mode | is SERVICE_MODE: True | bow = []
```
So the one-line change is sufficient: nothing else in the Service Mode document fails to
validate, and the resulting object carries exactly the signal a caller needs to report the
lockout rather than an error.
## Downstream impact
In `haomnilogic-local`, `OmniLogicEntity.available` is:
```python
return super().available and self.equipment._omni.backyard.is_ready
```
and the integration ships a dedicated `binary_sensor` for backyard Service Mode. So there is
already purpose-built handling for exactly this state — and none of it can execute, because
telemetry parsing fails before any of it is reached.
The practical result is that the one operating mode the safety interlock exists to make visible is
the mode Home Assistant cannot report. Instead of entities cleanly showing unavailable *because the
system is in Service Mode*, the coordinator raises `UpdateFailed` and every entity for the config
entry drops out with a generic fetch error. Measured on my system: 90 seconds of full blackout
across all 73 entities for a ~2 minute Service Mode session.
---
*Identifiers (device ID, MSP ID, local IP) redacted from the log excerpts above; happy to supply a
full unredacted log privately if useful.*
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.