fix(coordinator): poll-only devices refresh — always_update=True (fixes #93) (#94)

* fix(coordinator): set always_update=True so poll-only devices refresh (fixes #93)

_async_update_data returns the same self._states dict instance every poll.
With always_update=False, HA's coordinator refresh gate compares
previous_data != self.data by object identity, which is always False after
the first poll, so async_update_listeners never fires. MQTT-capable devices
were masked by async_set_updated_data, but BLE-only thermometers (H5109)
with no MQTT push froze their reading until the integration was reloaded.
Regression test asserts always_update stays True.

* docs(research): root-cause analysis for #93 thermometer staleness

---------

Co-authored-by: Tom Lasswell <tom@calcyon.com>

Author: lasswellt

custom_components/govee/coordinator.py

@@ -144,7 +144,13 @@ def __init__(
             config_entry=config_entry,
             name=DOMAIN,
             update_interval=timedelta(seconds=poll_interval),
-            always_update=False,
+            # _async_update_data mutates and returns the same self._states dict
+            # every poll. With always_update=False, HA's refresh gate compares
+            # previous_data != self.data by identity (same object) and never
+            # fires listeners after the first poll, so poll-only devices (BLE
+            # thermometers like H5109 with no MQTT push) freeze until reload.
+            # MQTT devices are masked via async_set_updated_data. (fixes #93)
+            always_update=True,
         )
 
         self._config_entry = config_entry

docs/_research/2026-06-04_h5109-thermometer-stale-update.md

@@ -0,0 +1,84 @@
+<!-- no-registry: single-bug root-cause research; no quantified multi-item scope -->
+# Research: H5109 Thermometer Temperature Stale Until Reload (issue #93)
+
+## Summary
+
+H5109 Pool Thermometer `sensor_temperature` updates on integration load, then never refreshes until reload. Root cause is **client-side**, high confidence, verified in repo: `GoveeDataUpdateCoordinator` is constructed with `always_update=False` (`coordinator.py:147`) and `_async_update_data` returns the **same `self._states` dict instance** every poll (`coordinator.py:951`). HA's coordinator refresh gate (`update_coordinator.py:473-478`) fires `async_update_listeners()` only when `always_update`, `last_update_success` flipped, or `previous_data != self.data` — all three are `False` after poll 1 (same object identity), so entities are never told to re-render. Symptom is thermometer-specific because MQTT-capable devices reach `async_set_updated_data` (line 865), which fires listeners unconditionally; H5109 is BLE→gateway→cloud with no MQTT delivery (`transport_health.mqtt.last_success = null`), so polling is its only update path — exactly the path the bug disables. Recommended fix: `always_update=True` (one line).
+
+## Research Questions
+
+1. **Temp value flow API→coordinator→entity?** Poll → `_fetch_device_state` → `state.update_from_api` parses `devices.capabilities.property`/`sensorTemperature` into `state.sensor_temperature` (`state.py:287-298`) → stored in `self._states[device_id]` → `_async_update_data` returns `self._states` (`coordinator.py:951`) → HA gate decides whether to notify listeners. **Parsing is correct**; break is at listener dispatch.
+2. **Why no entity update despite fresh raw value?** HA gate `previous_data != self.data` compares the coordinator's own `self.data` against itself; both reference the same mutated dict → equal → no notify. `always_update=False` removes the override. (`coordinator.py:147`, `update_coordinator.py:473-478`)
+3. **Does sensor subscribe / write state?** `GoveeTemperatureSensor` (`sensor.py:227-253`) is a `CoordinatorEntity`; `_handle_coordinator_update` → `async_write_ha_state` only runs when listeners fire. They never fire post-poll-1, so state machine is frozen.
+4. **Are thermometers polled each cycle?** Yes — API parse path is exercised and `raw_api_state` carries fresh `80.63`. Polling works; notification does not.
+5. **Stale-overwrite / optimistic preservation?** Secondary, **not causal**. `coordinator.py:1077-1086` only preserves `sensor_temperature` when the **new** value is `None`; a real API value is written correctly into the (identity-stable) dict.
+6. **MQTT available-but-silent skips API?** No. MQTT path (`coordinator.py:865`, `async_set_updated_data`) would rescue via unconditional notify, but `mqtt.last_success = null` → never executes for H5109.
+
+## Findings
+
+### F1 — Root cause: coordinator never notifies listeners after first poll (client-side)
+`always_update=False` (`coordinator.py:147`) + `return self._states` (`coordinator.py:951`, same dict object every call). HA gate (`update_coordinator.py:473-478`):
+```python
+if (
+    self.always_update                              # False
+    or self.last_update_success != previous_update_success   # False (stays healthy)
+    or previous_data != self.data                   # False — same object identity
+):
+    self.async_update_listeners()                   # never reached after poll 1
+```
+**Why initial load works:** `self.data` initialises to `None` (`update_coordinator.py:104`); first poll `None != self._states` → `True` → listeners fire once. **Why reload "fixes" it:** reload reconstructs the coordinator, resetting `data` to `None`, re-arming the one-shot first fire. Source: codebase-analyst trace, verified against repo + venv HA source.
+
+### F2 — Thermometer-specific exposure
+Lights/plugs receive MQTT pushes → `async_set_updated_data(self._states)` (`coordinator.py:865`) → `update_coordinator.py:514` notifies **unconditionally**, masking F1. H5109 is BLE-only with no MQTT message (`transport_health.mqtt.last_success = null`), so its sole update path is the broken poll-notify path. This is why the bug surfaces on the thermometer and not on lights.
+
+### F3 — Upstream cadence is a separate, real concern (not the issue-#93 root cause)
+web-researcher: H5109 architecture is BLE → WiFi gateway → cloud; Govee `/device/state` returns whatever the gateway last batched, refreshed on the gateway's undocumented schedule (~30-60s+). govee2mqtt shows similar staleness (govee2mqtt#228, #392). **This caps freshness but does NOT explain "stale until reload"** — if the API value never changed, reload wouldn't help. The reload-fixes-it symptom is dispositive evidence the root cause is F1 (client notify), not API caching. Cadence remains relevant for choosing a sane poll interval.
+
+## Compatibility Analysis
+
+- Fix touches only coordinator construction; no schema/model/entity API change. Python 3.12+, HA DataUpdateCoordinator contract unchanged.
+- `always_update=True` is the documented HA default for coordinators whose data object is mutated in place rather than replaced — matches this coordinator's `self._states` pattern.
+- No dependency changes. Existing tests in `test_coordinator.py` (32) should be extended, not rewritten.
+
+## Recommendation
+
+**Apply Option A: set `always_update=True` at `coordinator.py:147`.** One line, guarantees every successful poll notifies listeners, mirrors HA convention for in-place-mutated coordinator data. Resolves the thermometer staleness and any other poll-only device silently affected.
+
+| Option | Change | Pros | Cons |
+|---|---|---|---|
+| **A (recommended)** | `coordinator.py:147` `always_update=True` | 1 line; explicit; HA-idiomatic for mutated data | Listeners fire even when nothing changed (cheap; HA dedupes on entity state) |
+| B | `coordinator.py:951` `return dict(self._states)` | Distinct object each poll satisfies `previous_data != self.data` | Shallow copy per poll; relies on dict-value comparison which can still miss in-place mutation of nested `GoveeDeviceState`; subtler |
+
+Option A is preferred: B's value-comparison path can mis-fire if a nested mutable state object is reused, whereas A is unconditional and unambiguous.
+
+## Implementation Sketch
+
+1. `custom_components/govee/coordinator.py:147` — `always_update=False` → `always_update=True`.
+2. Pair with a sane minimum poll interval given F3 gateway cadence; confirm options `CONF_POLL_INTERVAL` floor (`min=30` per config_flow) is acceptable — document that thermometer freshness is bounded by Govee gateway sync (~30-60s+), not the integration.
+3. Regression test in `tests/test_coordinator.py`: assert `async_update_listeners` (or an observer's update callback) fires on the **second** consecutive successful poll, not only the first. Use a thermometer-shaped `GoveeDeviceState` whose `sensor_temperature` changes across polls.
+4. Optional: changelog / README known-limitation note on gateway-bounded cadence (F3).
+
+## Risks
+
+- **Increased listener churn:** `always_update=True` fires entity updates every poll even when unchanged. Impact is low — HA's state machine deduplicates identical states, and poll cadence is ≥30s. Mitigation: none required; if churn ever matters, switch to Option B.
+- **Masked second bug:** F3 means even after the fix, displayed temperature can lag real water temperature by the gateway's batch interval. This is upstream and not fixable client-side; document it so it isn't mistaken for a regression.
+- **Other poll-only devices:** any non-MQTT device (BLE-only sensors, some plugs) was equally affected and silently stale; the fix corrects all of them, which may change long-standing observed behavior — call out in release notes.
+
+## Open Questions
+
+- Exact Govee gateway → cloud sync interval for H5109 (undocumented; community estimates 30-60s+). Affects only the recommended minimum poll interval, not the fix.
+- Whether any existing test asserts the buggy single-fire behavior and would need updating alongside the fix.
+
+## References
+
+- `custom_components/govee/coordinator.py:147` — `always_update=False` (root cause)
+- `custom_components/govee/coordinator.py:951` — `return self._states` (same dict identity)
+- `custom_components/govee/coordinator.py:865` — MQTT `async_set_updated_data` (unconditional notify, masks bug on lights)
+- `custom_components/govee/coordinator.py:1077-1086` — sensor preservation (secondary, non-causal)
+- `custom_components/govee/models/state.py:287-298` — `update_from_api` sensorTemperature parse (correct)
+- `custom_components/govee/sensor.py:227-253` — `GoveeTemperatureSensor`
+- `homeassistant/helpers/update_coordinator.py:473-478` — refresh gate; `:514` unconditional notify; `:104` `data=None` init
+- [Govee Get Device State](https://developer.govee.com/reference/get-devices-status)
+- [govee2mqtt #228 — H5109 support](https://github.com/wez/govee2mqtt/issues/228)
+- [govee2mqtt #392 — H5179 polling](https://github.com/wez/govee2mqtt/issues/392)
+- [HA core #88775 — H5071 stale data](https://github.com/home-assistant/core/issues/88775)

tests/test_coordinator.py

@@ -1851,3 +1851,32 @@ def test_humidity_only_change_restamps(self):
         coord._note_sensor_reading_change("x", new, prev)
         assert coord.sensor_reading_changed_at("x").year > 2020
         assert t1 is not None
+
+
+class TestCoordinatorAlwaysUpdate:
+    """Regression for #93: poll-only devices (BLE thermometers like H5109 with
+    no MQTT push) froze until reload because the coordinator returned the same
+    self._states dict every poll while always_update=False — HA's refresh gate
+    (previous_data != self.data) compared the object to itself and never fired
+    listeners after the first poll. always_update=True forces the notify."""
+
+    def _build(self):
+        import custom_components.govee.coordinator as coord_mod
+
+        hass = MagicMock()
+        config_entry = MagicMock()
+        config_entry.entry_id = "test_entry"
+        api_client = MagicMock()
+        return coord_mod.GoveeCoordinator(
+            hass=hass,
+            config_entry=config_entry,
+            api_client=api_client,
+            iot_credentials=None,
+            poll_interval=60,
+        )
+
+    def test_always_update_is_true(self):
+        """always_update must stay True so each successful poll notifies
+        listeners even when _async_update_data returns the same dict instance."""
+        coord = self._build()
+        assert coord.always_update is True