span-panel-api 2.5.3__tar.gz → 2.6.0__tar.gz

{span_panel_api-2.5.3 → span_panel_api-2.6.0}/CHANGELOG.md

@@ -4,17 +4,48 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [2.5.3] - 04/2026
+## [2.6.0] - 04/2026
+
+### Added
+
+- **`SpanMqttClient.register_connection_callback(cb)`** — subscribe to broker connection state transitions. Callback fires with `False` on broker disconnect and `True` on reconnect; returns an idempotent unregister function. Added to
+  `SpanPanelClientProtocol` so any transport that claims the protocol must implement it.
+- **`SpanPanelStaleDataError`** exception — raised by `get_snapshot()` when the client is not fully live. Derives from `SpanPanelError` (not from `SpanPanelConnectionError`), because "never connected" and "running but data not currently live" are
+  semantically distinct states.
+
+### Changed
+
+- **`get_snapshot()` contract** — now raises `SpanPanelStaleDataError` when the bridge is not connected or the Homie device has not reached ready state. Previously, the method silently returned a snapshot built from whatever the in-memory accumulator
+  happened to hold, which made offline panels indistinguishable from online ones. This is the primary reason the span integration could not detect panel-offline transitions.
+
+### Fixed
+
+- **Stale snapshot dispatch after bridge disconnect** — a pending snapshot-debounce timer scheduled just before a bridge disconnect could fire afterwards, delivering a snapshot built from the still-`ready()` accumulator to subscribers.
+  `_on_connection_change(False)` now cancels the pending timer, and `_dispatch_snapshot` is now guarded by the same liveness predicate as `get_snapshot()`, so push consumers never receive a post-disconnect stale snapshot.
+
+### Breaking
+
+- Consumers of `get_snapshot()` must now handle `SpanPanelStaleDataError`. Any consumer with a broad `except Exception` (or `except SpanPanelError`) branch already handles this correctly.
+
+## [2.5.4] - 04/2026
+
+### Reverted
+
+- **Revert accumulator to 2.5.1 behavior** — the 2.5.2 lifecycle changes (property clearing, unconditional lifecycle transition on `$state=init`, generation counter) caused false energy dip spikes on panel reboots and network interruptions. The 2.5.3
+  partial fix (removing the clearing) was insufficient — the unconditional lifecycle disruption on transient `$state=init` events still triggered snapshot pipeline resets that produced 0.0 energy readings. Reverted `accumulator.py` and `homie.py` to their
+  stable 2.5.1 state. The existing dirty-node tracking handles reboot transitions correctly without special-case lifecycle management.
+
+## [2.5.3] - 04/2026 (retired)
+
+> **Retired:** Partial fix for 2.5.2 — removed property clearing but kept the lifecycle disruption that still caused false dips. Superseded by 2.5.4.
 
 ### Fixed
 
-- **Preserve property values on lifecycle reset** — the 2.5.2 property clear caused `_parse_float('')` to return `0.0` for energy counters during panel reboots or network interruptions, triggering false dip-compensation offsets in the integration that
-  permanently inflated energy sensor values. Removed the property/timestamp/target clearing from `_handle_description()`. Pre-reboot values now serve as safe placeholders until the panel re-publishes fresh data.
-- **Snapshot cache invalidated on reboot** — the generation counter still increments on lifecycle resets, forcing consumers to discard cached snapshots and rebuild from current accumulator state.
+- **Preserve property values on lifecycle reset** — removed the property/timestamp/target clearing from `_handle_description()`.
 
 ## [2.5.2] - 04/2026 (retired)
 
-> **Retired:** The property-clearing behavior introduced in this release caused false energy dip spikes. Superseded by 2.5.3.
+> **Retired:** Lifecycle changes caused false energy dip spikes. Superseded by 2.5.4.
 
 ### Fixed
 
@@ -344,30 +375,31 @@ Package versions prior to 2.0.0 depend on the SPAN v1 REST API. SPAN will sunset
 
 ## Version History Summary
 
-| Version    | Date    | Transport  | Summary                                                                                   |
-| ---------- | ------- | ---------- | ----------------------------------------------------------------------------------------- |
-| **2.5.3**  | 04/2026 | MQTT/Homie | Preserve property values on lifecycle reset; fix false energy dip spikes from 2.5.2 clear |
-| **2.5.2**  | 04/2026 | MQTT/Homie | _(retired)_ Clear stale property values on panel reboot; caused false energy dip spikes   |
-| **2.5.1**  | 04/2026 | MQTT/Homie | Replace assert with RuntimeError; fix bandit pre-commit hook                              |
-| **2.5.0**  | 03/2026 | MQTT/Homie | Homie accumulator layer, $target support, dirty-node snapshot caching                     |
-| **2.4.2**  | 03/2026 | MQTT/Homie | SSL context creation moved to executor                                                    |
-| **2.4.1**  | 03/2026 | MQTT/Homie | License metadata, loosened httpx constraint                                               |
-| **2.4.0**  | 03/2026 | MQTT/Homie | proximityProven, injected HTTP client, executor file I/O, type alias, test cleanup        |
-| **2.3.2**  | 03/2026 | MQTT/Homie | FQDN management endpoints                                                                 |
-| **2.3.1**  | 03/2026 | MQTT/Homie | MQTT connection errors wrapped as SpanPanelConnectionError                                |
-| **2.3.0**  | 03/2026 | MQTT/Homie | Simulation engine removed                                                                 |
-| **2.2.4**  | 03/2026 | MQTT/Homie | Negative zero fix on idle circuits                                                        |
-| **2.2.3**  | 03/2026 | MQTT/Homie | Panel size from Homie schema; `panel_size` always populated on snapshot                   |
-| **2.0.2**  | 03/2026 | MQTT/Homie | EVSE (EV charger) snapshot model, Homie parsing, simulation support                       |
-| **2.0.1**  | 03/2026 | MQTT/Homie | Full BESS metadata parsing, README documentation                                          |
-| **2.0.0**  | 02/2026 | MQTT/Homie | Ground-up rewrite: MQTT-only, protocol-based API, real-time push, PV/BESS metadata        |
-| **1.1.14** | 12/2025 | REST       | Keep-Alive and RemoteProtocolError handling                                               |
-| **1.1.9**  | 9/2025  | REST       | Simulation sign corrections                                                               |
-| **1.1.8**  | 2024    | REST       | Simulation power sign fix                                                                 |
-| **1.1.6**  | 2024    | REST       | YAML simulation API, battery simulation                                                   |
-| **1.1.5**  | 2024    | REST       | Simulation edge cases                                                                     |
-| **1.1.4**  | 2024    | REST       | Formatting and linting                                                                    |
-| **1.1.3**  | 2024    | REST       | Test and lint fixes                                                                       |
-| **1.1.2**  | 2024    | REST       | Simulation mode added                                                                     |
-| **1.1.1**  | 2024    | REST       | Dependency updates                                                                        |
-| **1.1.0**  | 2024    | REST       | Initial release                                                                           |
+| Version    | Date    | Transport  | Summary                                                                            |
+| ---------- | ------- | ---------- | ---------------------------------------------------------------------------------- |
+| **2.5.4**  | 04/2026 | MQTT/Homie | Revert accumulator to stable 2.5.1 behavior; fixes false energy dip spikes         |
+| **2.5.3**  | 04/2026 | MQTT/Homie | _(retired)_ Partial fix — still caused false dips from lifecycle disruption        |
+| **2.5.2**  | 04/2026 | MQTT/Homie | _(retired)_ Lifecycle changes caused false energy dip spikes                       |
+| **2.5.1**  | 04/2026 | MQTT/Homie | Replace assert with RuntimeError; fix bandit pre-commit hook                       |
+| **2.5.0**  | 03/2026 | MQTT/Homie | Homie accumulator layer, $target support, dirty-node snapshot caching              |
+| **2.4.2**  | 03/2026 | MQTT/Homie | SSL context creation moved to executor                                             |
+| **2.4.1**  | 03/2026 | MQTT/Homie | License metadata, loosened httpx constraint                                        |
+| **2.4.0**  | 03/2026 | MQTT/Homie | proximityProven, injected HTTP client, executor file I/O, type alias, test cleanup |
+| **2.3.2**  | 03/2026 | MQTT/Homie | FQDN management endpoints                                                          |
+| **2.3.1**  | 03/2026 | MQTT/Homie | MQTT connection errors wrapped as SpanPanelConnectionError                         |
+| **2.3.0**  | 03/2026 | MQTT/Homie | Simulation engine removed                                                          |
+| **2.2.4**  | 03/2026 | MQTT/Homie | Negative zero fix on idle circuits                                                 |
+| **2.2.3**  | 03/2026 | MQTT/Homie | Panel size from Homie schema; `panel_size` always populated on snapshot            |
+| **2.0.2**  | 03/2026 | MQTT/Homie | EVSE (EV charger) snapshot model, Homie parsing, simulation support                |
+| **2.0.1**  | 03/2026 | MQTT/Homie | Full BESS metadata parsing, README documentation                                   |
+| **2.0.0**  | 02/2026 | MQTT/Homie | Ground-up rewrite: MQTT-only, protocol-based API, real-time push, PV/BESS metadata |
+| **1.1.14** | 12/2025 | REST       | Keep-Alive and RemoteProtocolError handling                                        |
+| **1.1.9**  | 9/2025  | REST       | Simulation sign corrections                                                        |
+| **1.1.8**  | 2024    | REST       | Simulation power sign fix                                                          |
+| **1.1.6**  | 2024    | REST       | YAML simulation API, battery simulation                                            |
+| **1.1.5**  | 2024    | REST       | Simulation edge cases                                                              |
+| **1.1.4**  | 2024    | REST       | Formatting and linting                                                             |
+| **1.1.3**  | 2024    | REST       | Test and lint fixes                                                                |
+| **1.1.2**  | 2024    | REST       | Simulation mode added                                                              |
+| **1.1.1**  | 2024    | REST       | Dependency updates                                                                 |
+| **1.1.0**  | 2024    | REST       | Initial release                                                                    |

{span_panel_api-2.5.3 → span_panel_api-2.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: span-panel-api
-Version: 2.5.3
+Version: 2.6.0
 Summary: A client library for SPAN Panel API
 Project-URL: Homepage, https://github.com/SpanPanel/span-panel-api
 Project-URL: Issues, https://github.com/SpanPanel/span-panel-api/issues
@@ -86,12 +86,12 @@ This ensures that the first `get_snapshot()` after connect returns human-readabl
 
 The library defines three structural subtyping protocols (PEP 544) that both the MQTT transport and the simulation engine implement:
 
-| Protocol                   | Purpose                                                                               |
-| -------------------------- | ------------------------------------------------------------------------------------- |
-| `SpanPanelClientProtocol`  | Core lifecycle: `connect`, `close`, `ping`, `get_snapshot`                            |
-| `CircuitControlProtocol`   | Relay and shed-priority control: `set_circuit_relay`, `set_circuit_priority`          |
-| `PanelControlProtocol`     | Panel-level control: `set_dominant_power_source`                                      |
-| `StreamingCapableProtocol` | Push-based updates: `register_snapshot_callback`, `start_streaming`, `stop_streaming` |
+| Protocol                   | Purpose                                                                                    |
+| -------------------------- | ------------------------------------------------------------------------------------------ |
+| `SpanPanelClientProtocol`  | Core lifecycle: `connect`, `close`, `ping`, `get_snapshot`, `register_connection_callback` |
+| `CircuitControlProtocol`   | Relay and shed-priority control: `set_circuit_relay`, `set_circuit_priority`               |
+| `PanelControlProtocol`     | Panel-level control: `set_dominant_power_source`                                           |
+| `StreamingCapableProtocol` | Push-based updates: `register_snapshot_callback`, `start_streaming`, `stop_streaming`      |
 
 Integration code programs against these protocols, not transport-specific classes.
 
@@ -175,6 +175,29 @@ async def main():
 asyncio.run(main())
 ```
 
+### Connection State Monitoring
+
+Push consumers that need to react to broker disconnect/reconnect events — for example, to mark downstream entities offline within a second of a dropped connection rather than waiting on a fallback poll — can register a connection callback. The callback
+fires `False` on disconnect and `True` on reconnect, edge-only (no synthetic call at registration time):
+
+```python
+def on_connection_change(connected: bool) -> None:
+    if connected:
+        print("Broker connection restored")
+    else:
+        print("Broker connection lost")
+
+unsubscribe_connection = client.register_connection_callback(on_connection_change)
+
+# Later, during teardown:
+unsubscribe_connection()
+```
+
+To check the current connection state on demand (for example, just after registering), call `await client.ping()`.
+
+When the client is not fully live (broker disconnected, or Homie device not yet ready), `await client.get_snapshot()` raises `SpanPanelStaleDataError` instead of returning cached data. Treat that exception as the canonical "panel currently unreachable"
+signal — see [Error Handling](#error-handling) below.
+
 ### Pre-Built Config Pattern
 
 If you already have MQTT broker credentials (e.g., stored from a previous registration):
@@ -310,17 +333,25 @@ await delete_fqdn("192.168.1.100", token=auth.access_token)
 
 All exceptions inherit from `SpanPanelError`:
 
-| Exception                  | Cause                                                     |
-| -------------------------- | --------------------------------------------------------- |
-| `SpanPanelAuthError`       | Invalid passphrase, expired token, or missing credentials |
-| `SpanPanelConnectionError` | Cannot reach the panel (network/DNS)                      |
-| `SpanPanelTimeoutError`    | Request or connection timed out                           |
-| `SpanPanelValidationError` | Data validation failure                                   |
-| `SpanPanelAPIError`        | Unexpected HTTP response from v2 endpoints                |
-| `SpanPanelServerError`     | Panel returned HTTP 500                                   |
+| Exception                  | Cause                                                                                              |
+| -------------------------- | -------------------------------------------------------------------------------------------------- |
+| `SpanPanelAuthError`       | Invalid passphrase, expired token, or missing credentials                                          |
+| `SpanPanelConnectionError` | Cannot reach the panel (network/DNS) during initial connect                                        |
+| `SpanPanelStaleDataError`  | `get_snapshot()` called while the broker is disconnected or the Homie device has not reached ready |
+| `SpanPanelTimeoutError`    | Request or connection timed out                                                                    |
+| `SpanPanelValidationError` | Data validation failure                                                                            |
+| `SpanPanelAPIError`        | Unexpected HTTP response from v2 endpoints                                                         |
+| `SpanPanelServerError`     | Panel returned HTTP 500                                                                            |
+
+`SpanPanelStaleDataError` is distinct from `SpanPanelConnectionError`: the former means the client is running but data cannot be trusted right now (transient disconnect, or panel-declared not-ready); the latter means the initial connect failed and the
+client cannot be used at all.
 
 ```python
-from span_panel_api import SpanPanelAuthError, SpanPanelConnectionError
+from span_panel_api import (
+    SpanPanelAuthError,
+    SpanPanelConnectionError,
+    SpanPanelStaleDataError,
+)
 
 try:
     client = await create_span_client(host="192.168.1.100", passphrase="wrong")
@@ -328,6 +359,14 @@ except SpanPanelAuthError:
     print("Invalid passphrase")
 except SpanPanelConnectionError:
     print("Cannot reach panel")
+
+# Later, during normal operation:
+try:
+    snapshot = await client.get_snapshot()
+except SpanPanelStaleDataError as err:
+    # Broker dropped or panel declared not-ready — fall back to last-known
+    # data, a grace-period value, or mark downstream state unavailable.
+    print(f"Snapshot unavailable: {err}")
 ```
 
 ## Capabilities

{span_panel_api-2.5.3 → span_panel_api-2.6.0}/README.md

@@ -71,12 +71,12 @@ This ensures that the first `get_snapshot()` after connect returns human-readabl
 
 The library defines three structural subtyping protocols (PEP 544) that both the MQTT transport and the simulation engine implement:
 
-| Protocol                   | Purpose                                                                               |
-| -------------------------- | ------------------------------------------------------------------------------------- |
-| `SpanPanelClientProtocol`  | Core lifecycle: `connect`, `close`, `ping`, `get_snapshot`                            |
-| `CircuitControlProtocol`   | Relay and shed-priority control: `set_circuit_relay`, `set_circuit_priority`          |
-| `PanelControlProtocol`     | Panel-level control: `set_dominant_power_source`                                      |
-| `StreamingCapableProtocol` | Push-based updates: `register_snapshot_callback`, `start_streaming`, `stop_streaming` |
+| Protocol                   | Purpose                                                                                    |
+| -------------------------- | ------------------------------------------------------------------------------------------ |
+| `SpanPanelClientProtocol`  | Core lifecycle: `connect`, `close`, `ping`, `get_snapshot`, `register_connection_callback` |
+| `CircuitControlProtocol`   | Relay and shed-priority control: `set_circuit_relay`, `set_circuit_priority`               |
+| `PanelControlProtocol`     | Panel-level control: `set_dominant_power_source`                                           |
+| `StreamingCapableProtocol` | Push-based updates: `register_snapshot_callback`, `start_streaming`, `stop_streaming`      |
 
 Integration code programs against these protocols, not transport-specific classes.
 
@@ -160,6 +160,29 @@ async def main():
 asyncio.run(main())
 ```
 
+### Connection State Monitoring
+
+Push consumers that need to react to broker disconnect/reconnect events — for example, to mark downstream entities offline within a second of a dropped connection rather than waiting on a fallback poll — can register a connection callback. The callback
+fires `False` on disconnect and `True` on reconnect, edge-only (no synthetic call at registration time):
+
+```python
+def on_connection_change(connected: bool) -> None:
+    if connected:
+        print("Broker connection restored")
+    else:
+        print("Broker connection lost")
+
+unsubscribe_connection = client.register_connection_callback(on_connection_change)
+
+# Later, during teardown:
+unsubscribe_connection()
+```
+
+To check the current connection state on demand (for example, just after registering), call `await client.ping()`.
+
+When the client is not fully live (broker disconnected, or Homie device not yet ready), `await client.get_snapshot()` raises `SpanPanelStaleDataError` instead of returning cached data. Treat that exception as the canonical "panel currently unreachable"
+signal — see [Error Handling](#error-handling) below.
+
 ### Pre-Built Config Pattern
 
 If you already have MQTT broker credentials (e.g., stored from a previous registration):
@@ -295,17 +318,25 @@ await delete_fqdn("192.168.1.100", token=auth.access_token)
 
 All exceptions inherit from `SpanPanelError`:
 
-| Exception                  | Cause                                                     |
-| -------------------------- | --------------------------------------------------------- |
-| `SpanPanelAuthError`       | Invalid passphrase, expired token, or missing credentials |
-| `SpanPanelConnectionError` | Cannot reach the panel (network/DNS)                      |
-| `SpanPanelTimeoutError`    | Request or connection timed out                           |
-| `SpanPanelValidationError` | Data validation failure                                   |
-| `SpanPanelAPIError`        | Unexpected HTTP response from v2 endpoints                |
-| `SpanPanelServerError`     | Panel returned HTTP 500                                   |
+| Exception                  | Cause                                                                                              |
+| -------------------------- | -------------------------------------------------------------------------------------------------- |
+| `SpanPanelAuthError`       | Invalid passphrase, expired token, or missing credentials                                          |
+| `SpanPanelConnectionError` | Cannot reach the panel (network/DNS) during initial connect                                        |
+| `SpanPanelStaleDataError`  | `get_snapshot()` called while the broker is disconnected or the Homie device has not reached ready |
+| `SpanPanelTimeoutError`    | Request or connection timed out                                                                    |
+| `SpanPanelValidationError` | Data validation failure                                                                            |
+| `SpanPanelAPIError`        | Unexpected HTTP response from v2 endpoints                                                         |
+| `SpanPanelServerError`     | Panel returned HTTP 500                                                                            |
+
+`SpanPanelStaleDataError` is distinct from `SpanPanelConnectionError`: the former means the client is running but data cannot be trusted right now (transient disconnect, or panel-declared not-ready); the latter means the initial connect failed and the
+client cannot be used at all.
 
 ```python
-from span_panel_api import SpanPanelAuthError, SpanPanelConnectionError
+from span_panel_api import (
+    SpanPanelAuthError,
+    SpanPanelConnectionError,
+    SpanPanelStaleDataError,
+)
 
 try:
     client = await create_span_client(host="192.168.1.100", passphrase="wrong")
@@ -313,6 +344,14 @@ except SpanPanelAuthError:
     print("Invalid passphrase")
 except SpanPanelConnectionError:
     print("Cannot reach panel")
+
+# Later, during normal operation:
+try:
+    snapshot = await client.get_snapshot()
+except SpanPanelStaleDataError as err:
+    # Broker dropped or panel declared not-ready — fall back to last-known
+    # data, a grace-period value, or mark downstream state unavailable.
+    print(f"Snapshot unavailable: {err}")
 ```
 
 ## Capabilities

{span_panel_api-2.5.3 → span_panel_api-2.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "span-panel-api"
-version = "2.5.3"
+version = "2.6.0"
 description = "A client library for SPAN Panel API"
 authors = [
     {name = "SpanPanel"}

{span_panel_api-2.5.3 → span_panel_api-2.6.0}/src/span_panel_api/__init__.py

@@ -23,6 +23,7 @@ from .exceptions import (
     SpanPanelConnectionError,
     SpanPanelError,
     SpanPanelServerError,
+    SpanPanelStaleDataError,
     SpanPanelTimeoutError,
     SpanPanelValidationError,
 )
@@ -109,6 +110,7 @@ __all__ = [  # noqa: RUF022
     "SpanPanelConnectionError",
     "SpanPanelError",
     "SpanPanelServerError",
+    "SpanPanelStaleDataError",
     "SpanPanelTimeoutError",
     "SpanPanelValidationError",
 ]

{span_panel_api-2.5.3 → span_panel_api-2.6.0}/src/span_panel_api/exceptions.py

@@ -34,3 +34,12 @@ class SpanPanelAPIError(SpanPanelError):
 
 class SpanPanelServerError(SpanPanelAPIError):
     """Server error (500)."""
+
+
+class SpanPanelStaleDataError(SpanPanelError):
+    """Raised when get_snapshot() is called while the client isn't live.
+
+    Distinct from SpanPanelConnectionError: this means the client is running
+    but data cannot be trusted right now (broker disconnected, or the Homie
+    device has declared $state=disconnected/lost).
+    """

{span_panel_api-2.5.3 → span_panel_api-2.6.0}/src/span_panel_api/mqtt/accumulator.py

@@ -56,11 +56,6 @@ class HomiePropertyAccumulator:
         # Node type mapping from $description
         self._node_types: dict[str, str] = {}
 
-        # Generation counter — incremented whenever a new lifecycle's
-        # $description is accepted (including initial boot) so consumers
-        # can invalidate snapshot caches built from prior-lifecycle data.
-        self._generation: int = 0
-
         # Dirty tracking
         self._dirty_nodes: set[str] = set()
 
@@ -84,11 +79,6 @@ class HomiePropertyAccumulator:
         """Monotonic timestamp of the last READY transition, 0.0 if never ready."""
         return self._ready_since
 
-    @property
-    def generation(self) -> int:
-        """Counter incremented on each new lifecycle's ``$description`` to invalidate consumer caches."""
-        return self._generation
-
     def is_ready(self) -> bool:
         """True when lifecycle is READY."""
         return self._lifecycle == HomieLifecycle.READY
@@ -201,17 +191,10 @@ class HomiePropertyAccumulator:
             self._received_state_ready = False
             self._received_description = False
         else:
-            # init, sleeping, alert, etc. — connected but not ready.
-            # Always move out of READY/DESCRIPTION_RECEIVED into a
-            # non-ready connected lifecycle state.
-            #
-            # Reset _received_description so that the upcoming $description
-            # triggers a property clear.  This covers fast reboots where
-            # the broker's LWT ($state=disconnected) may not reach us
-            # before the panel publishes $state=init.
-            self._lifecycle = HomieLifecycle.CONNECTED
+            # init, sleeping, alert, etc. — connected but not ready
+            if self._lifecycle == HomieLifecycle.DISCONNECTED:
+                self._lifecycle = HomieLifecycle.CONNECTED
             self._received_state_ready = False
-            self._received_description = False
 
         _LOGGER.debug("Homie $state: %s → lifecycle=%s", payload, self._lifecycle.value)
 
@@ -223,25 +206,6 @@ class HomiePropertyAccumulator:
             _LOGGER.warning("Invalid $description JSON")
             return
 
-        # _handle_state() already reset _received_description to False due to
-        # a state change that starts a new panel lifecycle, including
-        # $state=disconnected/lost and other non-ready states such as init.
-        # Increment the generation counter to invalidate consumer snapshot
-        # caches, but preserve property values — pre-reboot readings serve
-        # as safe placeholders until the panel re-publishes.  Clearing values
-        # would emit 0.0 for energy counters via _parse_float(""), triggering
-        # false dip-compensation offsets in the integration.
-        #
-        # On a pure MQTT reconnect (no panel reboot), _received_description
-        # is still True from the previous session so we skip this block —
-        # the retained property messages carry the correct (unchanged) values.
-        if not self._received_description:
-            self._generation += 1
-            _LOGGER.debug(
-                "Panel reboot detected (generation %d); preserving property values as placeholders",
-                self._generation,
-            )
-
         self._received_description = True
         self._node_types.clear()
 
@@ -256,11 +220,7 @@ class HomiePropertyAccumulator:
         # Mark all known nodes dirty
         self._dirty_nodes.update(self._node_types.keys())
 
-        _LOGGER.debug(
-            "Parsed $description with %d nodes (generation %d)",
-            len(self._node_types),
-            self._generation,
-        )
+        _LOGGER.debug("Parsed $description with %d nodes", len(self._node_types))
 
         # Lifecycle transition
         if self._received_state_ready:

{span_panel_api-2.5.3 → span_panel_api-2.6.0}/src/span_panel_api/mqtt/client.py

@@ -9,10 +9,11 @@ from __future__ import annotations
 
 import asyncio
 from collections.abc import Awaitable, Callable
+import contextlib
 import logging
 
 from ..auth import get_homie_schema
-from ..exceptions import SpanPanelConnectionError, SpanPanelServerError
+from ..exceptions import SpanPanelConnectionError, SpanPanelServerError, SpanPanelStaleDataError
 from ..models import FieldMetadata, HomieSchemaTypes, SpanPanelSnapshot
 from ..protocol import PanelCapability
 from .accumulator import HomiePropertyAccumulator
@@ -52,6 +53,8 @@ class SpanMqttClient:
         self._homie: HomieDeviceConsumer | None = None
         self._streaming = False
         self._snapshot_callbacks: list[Callable[[SpanPanelSnapshot], Awaitable[None]]] = []
+        self._connection_callbacks: list[Callable[[bool], None]] = []
+        self._live = False
         self._ready_event: asyncio.Event | None = None
         self._loop: asyncio.AbstractEventLoop | None = None
         self._background_tasks: set[asyncio.Task[None]] = set()
@@ -190,6 +193,7 @@ class SpanMqttClient:
             await self._bridge.disconnect()
             self._bridge = None
         self._accumulator = None
+        self._live = False
 
     async def ping(self) -> bool:
         """Check if MQTT connection is alive and device is ready."""
@@ -197,12 +201,43 @@ class SpanMqttClient:
             return False
         return self._bridge.is_connected() and self._homie.is_ready()
 
+    def register_connection_callback(self, callback: Callable[[bool], None]) -> Callable[[], None]:
+        """Subscribe to broker connection state transitions.
+
+        Callback fires with False on broker disconnect and True on reconnect.
+        No synthetic call is made at registration time — callbacks only fire
+        on real state edges. To check current connection state on registration,
+        await ping().
+
+        Returns an unregister function that removes the callback from the
+        dispatch list. Calling unregister twice is safe.
+        """
+        self._connection_callbacks.append(callback)
+
+        def unregister() -> None:
+            with contextlib.suppress(ValueError):
+                self._connection_callbacks.remove(callback)
+
+        return unregister
+
     async def get_snapshot(self) -> SpanPanelSnapshot:
         """Return current snapshot from accumulated MQTT state.
 
-        No network call — snapshot is built from in-memory property values.
+        Raises SpanPanelStaleDataError if the client is not fully live.
+        "Live" means: the bridge is connected AND the Homie accumulator
+        has reached ready state. Callers can treat SpanPanelStaleDataError
+        as the canonical "panel currently unreachable" signal.
+
+        No network call — snapshot is built from in-memory property values
+        when the liveness checks pass.
         """
-        return self._require_homie().build_snapshot()
+        if self._bridge is None or self._homie is None:
+            raise SpanPanelStaleDataError("Client not connected — call connect() first")
+        if not self._bridge.is_connected():
+            raise SpanPanelStaleDataError("MQTT broker disconnected")
+        if not self._homie.is_ready():
+            raise SpanPanelStaleDataError("Homie device not ready")
+        return self._homie.build_snapshot()
 
     # -- CircuitControlProtocol --------------------------------------------
 
@@ -296,15 +331,42 @@ class SpanMqttClient:
                 self._snapshot_timer = self._loop.call_later(self._snapshot_interval, self._fire_snapshot)
 
     def _on_connection_change(self, connected: bool) -> None:
-        """Handle MQTT connection state change (called from asyncio loop)."""
+        """Handle MQTT connection state change (called from asyncio loop).
+
+        Re-subscribes to the wildcard topic on reconnect (pre-existing
+        behavior), then fans out an edge-only notification to registered
+        connection callbacks. Duplicate state transitions are suppressed
+        so subscribers only see real edges.
+
+        On disconnect, any pending snapshot-debounce timer is cancelled
+        so a stale timer cannot dispatch a post-disconnect snapshot.
+        """
+        # Re-subscribe runs on every connected=True, including duplicates —
+        # paho may re-emit connected events after session restoration, and
+        # re-subscribing is broker-benign. Callback fan-out below is
+        # edge-only (see the guard after this block).
         if connected:
             _LOGGER.debug("MQTT connection established")
-            # Re-subscribe on reconnect
             if self._bridge is not None:
                 wildcard = WILDCARD_TOPIC_FMT.format(serial=self._serial_number)
                 self._bridge.subscribe(wildcard, qos=0)
         else:
             _LOGGER.debug("MQTT connection lost")
+            # Cancel any pending snapshot-debounce timer so it cannot
+            # fire post-disconnect with a stale snapshot.
+            self._cancel_snapshot_timer()
+
+        # Edge-only dispatch
+        if connected == self._live:
+            return
+        self._live = connected
+
+        # Iterate a copy — subscribers may unregister during their callback
+        for cb in list(self._connection_callbacks):
+            try:
+                cb(connected)
+            except Exception:  # pylint: disable=broad-exception-caught
+                _LOGGER.exception("Connection callback raised")
 
     async def _wait_for_circuit_names(self, timeout: float) -> None:
         """Wait for all circuit-like nodes to have a ``name`` property.
@@ -364,8 +426,24 @@ class SpanMqttClient:
         self._cancel_snapshot_timer()
 
     async def _dispatch_snapshot(self) -> None:
-        """Build snapshot and send to all registered callbacks."""
-        snapshot = self._require_homie().build_snapshot()
+        """Build snapshot and send to all registered callbacks.
+
+        Guarded by the same liveness predicate as get_snapshot() — if the
+        bridge has disconnected or the Homie device is not ready, no
+        dispatch occurs. This prevents a pending debounce timer that was
+        scheduled just before a disconnect from delivering a stale
+        snapshot to subscribers after the fact.
+        """
+        bridge = self._bridge
+        homie = self._homie
+        if bridge is None or not bridge.is_connected() or homie is None or not homie.is_ready():
+            _LOGGER.debug(
+                "Skipping stale snapshot dispatch (bridge_connected=%s, homie_ready=%s)",
+                bridge is not None and bridge.is_connected(),
+                homie is not None and homie.is_ready(),
+            )
+            return
+        snapshot = homie.build_snapshot()
         for cb in list(self._snapshot_callbacks):
             try:
                 await cb(snapshot)

{span_panel_api-2.5.3 → span_panel_api-2.6.0}/src/span_panel_api/mqtt/homie.py

@@ -64,7 +64,6 @@ class HomieDeviceConsumer:
         self._acc = accumulator
         self._panel_size = panel_size
         self._cached_snapshot: SpanPanelSnapshot | None = None
-        self._cache_generation: int = 0
 
     # -- Delegation to accumulator -------------------------------------------
     # These thin wrappers allow SpanMqttClient (and legacy test code) to
@@ -119,12 +118,6 @@ class HomieDeviceConsumer:
 
         Must be called after accumulator is_ready() returns True.
         """
-        # Invalidate cache when the accumulator generation advances
-        # (panel reboot cleared all property values).
-        if self._acc.generation != self._cache_generation:
-            self._cached_snapshot = None
-            self._cache_generation = self._acc.generation
-
         dirty = self._acc.dirty_node_ids()
 
         if not dirty and self._cached_snapshot is not None:

{span_panel_api-2.5.3 → span_panel_api-2.6.0}/src/span_panel_api/protocol.py

@@ -46,6 +46,8 @@ class SpanPanelClientProtocol(Protocol):
 
     async def get_snapshot(self) -> SpanPanelSnapshot: ...
 
+    def register_connection_callback(self, callback: Callable[[bool], None]) -> Callable[[], None]: ...
+
 
 @runtime_checkable
 class CircuitControlProtocol(Protocol):