span-panel-api 3.6.2__tar.gz → 3.7.0b1__tar.gz

{span_panel_api-3.6.2 → span_panel_api-3.7.0b1}/CHANGELOG.md

@@ -7,6 +7,33 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 Pre-releases are not listed separately. A beta is a step towards the next public version, so its changes are folded into that version's entry as they land and are described against the **last public release**, never against the beta before it. What one
 beta corrected in an earlier beta does not appear at all: from the point of view of somebody upgrading between released versions, it never happened.
 
+## [Unreleased]
+
+Snapshot fields that held a fabricated constant can now be unknown, and with `span-panel-api-schema-0` and `span-panel-api-schema-1` 1.3.0 or newer the parsers report them as unknown and stop synthesising unoccupied positions.
+
+### Added
+
+- **`V2StatusInfo.hardware_version` reports the hardware version string from `GET /api/v2/status`.**
+
+### Changed
+
+- **BREAKING FOR CONSUMERS: `SpanPanelSnapshot.proximity_proven` becomes `bool | None`**, and with `span-panel-api-schema-0` and `span-panel-api-schema-1` 1.3.0 or newer it is always `None`, where it was effectively a constant `True`, because neither MQTT
+  schema publishes a proximity property and the panel's own answer is `V2StatusInfo.proximity_proven`.
+- **BREAKING FOR CONSUMERS: `SpanPanelSnapshot.uptime_s` becomes `int | None`**, and with those parsers it is `None` on a parent/child panel and before a flat panel first reports ready, where it was a constant `0`.
+- **BREAKING FOR CONSUMERS: `SpanCircuitSnapshot.instant_power_update_time_s` and `energy_accum_update_time_s` become `int | None` and default to `None`**, and with those parsers they are `None` until the reading has arrived and always on a parent/child
+  panel, where they were `0`.
+- **The `schema-0` and `schema-1` extras require `span-panel-api-schema-0` and `span-panel-api-schema-1` 1.3.0 or newer**, the adapters that report these values as unknown.
+
+### Removed
+
+- **BREAKING: with `span-panel-api-schema-0` and `span-panel-api-schema-1` 1.3.0 or newer, snapshots no longer include synthesised `unmapped_tab_N` entries for unoccupied breaker positions, which carried no measured data**, so `SpanPanelSnapshot.circuits`
+  holds only real circuits and `panel_size` alone states the panel's total positions.
+
+### Fixed
+
+- **`V2HomieSchema.types_schema_hash` on data model 1.0 is the panel's published `deviceClassesSchemaHash`, or a hash of `deviceClasses` when none is published, where it was one constant for every such panel**; a flat panel's value is unchanged, and a
+  value stored from 3.6.x differs once on a data model 1.0 panel.
+
 ## [3.6.2]
 
 A reconnect waits for the panel's labels before handing out a snapshot, as connecting always has.
@@ -480,8 +507,7 @@ Everything below is additive. Each field is `None` or empty on a panel that publ
   `MQTT_FULL_REBUILD_AFTER_FAILURES` (3) consecutive failures, or immediately on any `ssl.SSLError`. The previous behavior pinned the panel's CA certificate into the paho client once at `connect()` time and re-used it across all reconnect attempts; if the
   panel rotated its private CA — most plausibly during a firmware upgrade — every subsequent reconnect raised `ssl.SSLCertVerificationError` (caught by the broad `OSError` clause and silently retried) and the bridge could not recover without a config-entry
   reload. The rebuild mirrors what a manual reload does without going through HA's `config_entry` teardown, so entities stay registered and the integration's grace-period logic continues to apply unchanged. The threshold-cadence design (counter reset on
-  every rebuild attempt, success or fail) keeps the recovery path active throughout extended outages — multi-day disconnections recover whenever the panel becomes usable again, including if the CA rotates a second time mid-outage. See
-  `SpanPanel_Docs/span-panel-api/2026-05-17-mqtt-ca-refresh-on-reconnect-design.md` for the full design.
+  every rebuild attempt, success or fail) keeps the recovery path active throughout extended outages — multi-day disconnections recover whenever the panel becomes usable again, including if the CA rotates a second time mid-outage.
 
 ### Added
 

{span_panel_api-3.6.2 → span_panel_api-3.7.0b1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: span-panel-api
-Version: 3.6.2
+Version: 3.7.0b1
 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
@@ -20,9 +20,9 @@ Requires-Dist: httpx<1.0,>=0.28.1
 Requires-Dist: paho-mqtt<3.0.0,>=2.0.0
 Requires-Dist: pyyaml>=6.0.0
 Provides-Extra: schema-0
-Requires-Dist: span-panel-api-schema-0>=1.2.0; extra == 'schema-0'
+Requires-Dist: span-panel-api-schema-0>=1.3.0b1; extra == 'schema-0'
 Provides-Extra: schema-1
-Requires-Dist: span-panel-api-schema-1>=1.2.2; extra == 'schema-1'
+Requires-Dist: span-panel-api-schema-1>=1.3.0b1; extra == 'schema-1'
 Description-Content-Type: text/markdown
 
 # SPAN Panel API
@@ -175,8 +175,8 @@ transport-specific classes.
 
 All panel state is represented as immutable, frozen dataclasses:
 
-- **`SpanPanelSnapshot`**: complete panel state. Identity (serial, firmware, vendor, model, hardware version), panel size, main breaker rating, main relay, door and proximity state, uptime, network links with the Wi-Fi SSID and vendor cloud, grid and
-  feedthrough power and energy, grid/DSM state, run configuration, dominant power source, grid islandability, per-leg voltages, power flows, lugs current and whether the lugs are the service entrance, shed policy and forecast. It holds `circuits`,
+- **`SpanPanelSnapshot`**: complete panel state. Identity (serial, firmware, vendor, model, hardware version), panel size, main breaker rating, main relay, door state, connection uptime on a flat panel, network links with the Wi-Fi SSID and vendor cloud,
+  grid and feedthrough power and energy, grid/DSM state, run configuration, dominant power source, grid islandability, per-leg voltages, power flows, lugs current and whether the lugs are the service entrance, shed policy and forecast. It holds `circuits`,
   `battery`, `pv`, `pv_inverters`, `evse`, `mid`, `pcs`, `adopted_devices` and `extension_properties`.
 - **`SpanCircuitSnapshot`**: one circuit. Id, name, relay state and requester, power, energy and their update times, tabs, 240 V, breaker rating, current, priority, user controllability, sheddable / never-backup / always-on flags, device type, relative
   position, PCS management and priority, and the `$target` pending state for relay and priority.
@@ -195,6 +195,9 @@ see the changelog, because `battery.model` changes value for existing flat users
 
 `mid`, `pcs`, `adopted_devices`, `extension_properties` and the per-DER link-health fields exist only under the parent/child schema. They are `None` or empty on a flat panel rather than absent, so a consumer reads the same snapshot type either way.
 
+`uptime_s` and a circuit's update times are the reverse: only the flat parser measures them, and they are `None` under the parent/child schema. Neither schema publishes proximity, so `SpanPanelSnapshot.proximity_proven` is always `None`; the panel's own
+answer is `V2StatusInfo.proximity_proven`, from `GET /api/v2/status`.
+
 ## Usage
 
 ### Factory Pattern (Recommended)

{span_panel_api-3.6.2 → span_panel_api-3.7.0b1}/README.md

@@ -148,8 +148,8 @@ transport-specific classes.
 
 All panel state is represented as immutable, frozen dataclasses:
 
-- **`SpanPanelSnapshot`**: complete panel state. Identity (serial, firmware, vendor, model, hardware version), panel size, main breaker rating, main relay, door and proximity state, uptime, network links with the Wi-Fi SSID and vendor cloud, grid and
-  feedthrough power and energy, grid/DSM state, run configuration, dominant power source, grid islandability, per-leg voltages, power flows, lugs current and whether the lugs are the service entrance, shed policy and forecast. It holds `circuits`,
+- **`SpanPanelSnapshot`**: complete panel state. Identity (serial, firmware, vendor, model, hardware version), panel size, main breaker rating, main relay, door state, connection uptime on a flat panel, network links with the Wi-Fi SSID and vendor cloud,
+  grid and feedthrough power and energy, grid/DSM state, run configuration, dominant power source, grid islandability, per-leg voltages, power flows, lugs current and whether the lugs are the service entrance, shed policy and forecast. It holds `circuits`,
   `battery`, `pv`, `pv_inverters`, `evse`, `mid`, `pcs`, `adopted_devices` and `extension_properties`.
 - **`SpanCircuitSnapshot`**: one circuit. Id, name, relay state and requester, power, energy and their update times, tabs, 240 V, breaker rating, current, priority, user controllability, sheddable / never-backup / always-on flags, device type, relative
   position, PCS management and priority, and the `$target` pending state for relay and priority.
@@ -168,6 +168,9 @@ see the changelog, because `battery.model` changes value for existing flat users
 
 `mid`, `pcs`, `adopted_devices`, `extension_properties` and the per-DER link-health fields exist only under the parent/child schema. They are `None` or empty on a flat panel rather than absent, so a consumer reads the same snapshot type either way.
 
+`uptime_s` and a circuit's update times are the reverse: only the flat parser measures them, and they are `None` under the parent/child schema. Neither schema publishes proximity, so `SpanPanelSnapshot.proximity_proven` is always `None`; the panel's own
+answer is `V2StatusInfo.proximity_proven`, from `GET /api/v2/status`.
+
 ## Usage
 
 ### Factory Pattern (Recommended)

{span_panel_api-3.6.2 → span_panel_api-3.7.0b1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "span-panel-api"
-version = "3.6.2"
+version = "3.7.0b1"
 description = "A client library for SPAN Panel API"
 authors = [
     {name = "SpanPanel"}
@@ -62,11 +62,14 @@ dependencies = [
 # so a 1.1.x adapter is still accepted, but it fills neither `pv_inverters` nor
 # the inverter identity fields 3.6.0 adds. Upgrading through the extra is what
 # brings the adapters that do.
-schema-0 = ["span-panel-api-schema-0>=1.2.0"]
+# Raised to 1.3.0b1 for 3.7.0b1: that adapter reports the unknown values this
+# bootstrap's snapshot fields now accept, and stops synthesising unoccupied positions.
+schema-0 = ["span-panel-api-schema-0>=1.3.0b1"]
 # Raised to 1.2.1 for 3.6.1: that adapter builds the `pv` that `SpanPanelSnapshot.pv` now documents.
 # Raised to 1.2.2 for 3.6.2: the readiness gate every snapshot passes asks that
 # adapter what is still missing, and 1.2.2 restarts its feed grace correctly.
-schema-1 = ["span-panel-api-schema-1>=1.2.2"]
+# Raised to 1.3.0b1 for 3.7.0b1, for the same reason as schema-0's.
+schema-1 = ["span-panel-api-schema-1>=1.3.0b1"]
 
 [project.urls]
 Homepage = "https://github.com/SpanPanel/span-panel-api"
@@ -245,7 +248,11 @@ warn_return_any = true
 warn_unused_configs = true
 disallow_untyped_defs = true
 explicit_package_bases = true
-mypy_path = "src"
+# `tests` because the suite imports its support packages top-level
+# (`from reference_payloads.schema_one import ...`), the way pytest's rootdir puts
+# `tests/` on `sys.path`; the support packages the mypy hook checks resolve the same
+# way here.
+mypy_path = "src:tests"
 # Excluded by name for the reason `[tool.ruff]` gives above: the capture script is
 # checked like the library, and the hand-run tools written before that was expected
 # are not.

{span_panel_api-3.6.2 → span_panel_api-3.7.0b1}/src/span_panel_api/auth.py

@@ -9,7 +9,7 @@ client (which only covers v1 endpoints).
 from __future__ import annotations
 
 import asyncio
-from collections.abc import Collection
+from collections.abc import Collection, Mapping
 import hashlib
 import json
 import logging
@@ -454,6 +454,32 @@ async def download_ca_cert(
     raise SpanPanelAPIError(f"Failed to download CA cert: HTTP {last_status}")
 
 
+def _schema_hash(data: Mapping[str, object]) -> str:
+    """The schema hash ``V2HomieSchema.types_schema_hash`` reports.
+
+    A parent/child panel publishes its schema as ``deviceClasses``, with its own
+    ``deviceClassesSchemaHash`` over that block, in place of flat firmware's
+    ``types``. Hashing ``types`` there hashed an absent block, so every such
+    panel got one constant key. The published hash is taken as is when it is a
+    non-empty string; otherwise ``deviceClasses`` is hashed here.
+
+    SPAN's public API changelog states that ``deviceClassesSchemaHash`` is
+    computed over the new structure, so it differs from a ``typesSchemaHash``
+    even where the property content is unchanged, and that a cached
+    ``typesSchemaHash`` is not to be compared against it. A key held from a
+    release that hashed ``types`` therefore differs once on such a panel.
+
+    A flat panel's key is exactly what earlier releases computed, so a value
+    stored for a flat panel still matches.
+    """
+    published = data.get("deviceClassesSchemaHash")
+    if isinstance(published, str) and published:
+        return published
+    hashed = data["deviceClasses"] if "deviceClasses" in data else data.get("types", {})
+    canonical = json.dumps(hashed, sort_keys=True)
+    return "sha256:" + hashlib.sha256(canonical.encode()).hexdigest()[:16]
+
+
 async def get_homie_schema(
     host: str,
     timeout: float = 10.0,
@@ -527,15 +553,9 @@ async def get_homie_schema(
             if isinstance(props, dict):
                 types[str(type_name)] = {str(k): v for k, v in props.items()}
 
-    # Compute schema hash from types key names for change detection
-    # The panel provides this implicitly via the firmware version + types structure
-    # We derive a hash for caching; the fixture README documents the expected value
-    types_json = json.dumps(data.get("types", {}), sort_keys=True)
-    schema_hash = "sha256:" + hashlib.sha256(types_json.encode()).hexdigest()[:16]
-
     # Read before anything else interprets the payload. A parent/child response
-    # carries `deviceClasses` where this one reads `types`, so every field below
-    # degrades to empty for such a panel — which is harmless only because this
+    # carries `deviceClasses` where this one reads `types`, so `types` degrades
+    # to empty for such a panel — which is harmless only because this
     # value routes it to a different parser before those fields are used.
     # Absence is the flat signal and must stay distinct from an empty string.
     raw_data_model_version = data.get("dataModelVersion")
@@ -543,7 +563,7 @@ async def get_homie_schema(
 
     return V2HomieSchema(
         firmware_version=str(data.get("firmwareVersion", "")),
-        types_schema_hash=schema_hash,
+        types_schema_hash=_schema_hash(data),
         types=types,
         data_model_version=data_model_version,
     )

{span_panel_api-3.6.2 → span_panel_api-3.7.0b1}/src/span_panel_api/models.py

@@ -49,8 +49,12 @@ class SpanCircuitSnapshot:
     breaker_rating_a: float | None = None
     always_on: bool = False  # v2 new: circuit/always-on
     relay_requester: str = "UNKNOWN"  # v2 new: circuit/relay-requester
-    energy_accum_update_time_s: int = 0  # v1: poll timestamp | v2: MQTT arrival time
-    instant_power_update_time_s: int = 0  # v1: poll timestamp | v2: MQTT arrival time
+    # Epoch seconds at which the reading last changed, as received over MQTT.
+    # Flat only: the tree adapter records no such time, and a reading that has
+    # not arrived has no time either, so both are `None` rather than a `0` that
+    # reads as 1970.
+    energy_accum_update_time_s: int | None = None  # flat: MQTT receipt time
+    instant_power_update_time_s: int | None = None  # flat: MQTT receipt time
     relay_state_target: str | None = None  # v2: $target for relay (desired state)
     priority_target: str | None = None  # v2: $target for shed-priority (desired state)
 
@@ -210,8 +214,10 @@ class SpanMidSnapshot:
 
     The raw value above is a Homie device id, which means nothing on a dashboard — it is
     not a Home Assistant device id, and an opaque string is worse than none. This is the
-    device's own `$description.name` (`Battery`, `Solar`, `SPAN Drive - Garage`), which
-    is the part a person can read. The literal stays available beside it.
+    device's own `$description.name` (`Battery`, `Solar`, `SPAN Drive - Garage`) where
+    that is not the id itself, else its vendor and model (`Tesla Powerwall 2 AC`), which
+    is the part a person can read; `None` when it publishes nothing that names it. The
+    literal stays available beside it.
     """
 
 
@@ -616,6 +622,7 @@ class V2StatusInfo:
     serial_number: str
     firmware_version: str
     proximity_proven: bool | None = None  # Added in firmware 202609; None on older panels
+    hardware_version: str | None = None  # Added in firmware r202639: `1.2`, `2.0` or `UNKNOWN`; None on older panels
 
     @classmethod
     def from_status_payload(cls, payload: Mapping[str, object]) -> V2StatusInfo:
@@ -633,16 +640,21 @@ class V2StatusInfo:
         panel that may not fully support it, so a partial body is information,
         not a failure.
 
-        ``proximity_proven`` is the exception and stays ``None`` unless the panel
+        ``proximity_proven`` is an exception and stays ``None`` unless the panel
         published a real boolean. Absent and false are different facts there —
         firmware below 202609 does not report it at all — and coercing whatever
-        arrived would turn a string ``"false"`` into ``True``.
+        arrived would turn a string ``"false"`` into ``True``. ``hardware_version``
+        is likewise ``None`` unless the panel published a real string: firmware
+        below r202639 omits it, and a stringified number or object would read as
+        a version the panel never reported.
         """
         raw_proximity = payload.get("proximityProven")
+        raw_hardware_version = payload.get("hardwareVersion")
         return cls(
             serial_number=str(payload.get("serialNumber", "")),
             firmware_version=str(payload.get("firmwareVersion", "")),
             proximity_proven=raw_proximity if isinstance(raw_proximity, bool) else None,
+            hardware_version=raw_hardware_version if isinstance(raw_hardware_version, str) else None,
         )
 
 
@@ -654,7 +666,10 @@ class V2HomieSchema:
     """Response from GET /api/v2/homie/schema."""
 
     firmware_version: str
-    types_schema_hash: str  # SHA-256, first 16 hex chars
+    # SHA-256, first 16 hex chars, compared by the client between connects: over
+    # ``types`` on a flat panel, and over ``deviceClasses`` on parent/child, where
+    # the panel's own ``deviceClassesSchemaHash`` is used when it publishes one.
+    types_schema_hash: str
     types: HomieSchemaTypes
     # The flat-vs-parent/child discriminator, and the reason this endpoint is
     # fetched before MQTT is opened rather than during connect(). Absent on flat
@@ -1072,8 +1087,16 @@ class SpanPanelSnapshot:
 
     # Hardware status — v1 field names preserved
     door_state: str  # v1: direct | v2: core/door
-    proximity_proven: bool  # v1: proximity sensor | v2: MQTT auth + $state==ready
-    uptime_s: int  # v1: panel uptime | v2: connection uptime since $state==ready
+    # Neither MQTT schema publishes a proximity property, so a snapshot never
+    # knows: always `None`. Being connected and ready proves the client holds
+    # broker credentials, not that anyone stood at the panel. The panel's own
+    # answer is `V2StatusInfo.proximity_proven`, from the REST status endpoint.
+    proximity_proven: bool | None
+    # Seconds since this client last saw the panel's `$state` turn `ready`: a
+    # connection uptime measured here, not the panel's own uptime, which no
+    # schema publishes. Flat only; `None` from the tree adapter, and before the
+    # first `ready`.
+    uptime_s: int | None
     eth0_link: bool  # v1: direct | v2: core/ethernet
     wlan_link: bool  # v1: direct | v2: core/wifi
     wwan_link: bool  # v1: direct | v2: vendor-cloud == "CONNECTED"

{span_panel_api-3.6.2 → span_panel_api-3.7.0b1}/src/span_panel_api/mqtt/connection.py

@@ -846,8 +846,7 @@ class AsyncMqttBridge:
         retrying with it.
 
         Recovery target: CA rotation (firmware upgrade), stale paho client
-        internal state, stuck Homie accumulator. See the design doc at
-        SpanPanel_Docs/span-panel-api/2026-05-17-mqtt-ca-refresh-on-reconnect-design.md.
+        internal state, stuck Homie accumulator.
         """
         if self._loop is None:
             return False

span_panel_api-3.7.0b1/tests/adapter_fidelity/__init__.py

@@ -0,0 +1,5 @@
+"""Adapter fidelity: captured device trees replayed through the schema-1 adapter.
+
+`harness` measures one capture and names no panel, model or capture; `rules`
+documents why each measured outcome is right; the test modules pick captures.
+"""