span-panel-api 3.6.2__tar.gz → 3.8.0__tar.gz

{span_panel_api-3.6.2 → span_panel_api-3.8.0}/.gitignore

@@ -16,6 +16,7 @@ xnotes/*
 .env
 .envrc
 .venv
+.deps-installed
 .vscode/settings.json
 
 # mypy

{span_panel_api-3.6.2 → span_panel_api-3.8.0}/CHANGELOG.md

@@ -7,6 +7,40 @@ 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.
 
+## [3.8.0]
+
+Snapshot fields that held a fabricated constant can now be unknown, and with `span-panel-api-schema-0` 1.3.0 and `span-panel-api-schema-1` 1.4.0 or newer the parsers report them as unknown and stop synthesising unoccupied positions.
+
+### Added
+
+- **spanos3/r202639/03 batch 2: reads more of the data this firmware publishes.**
+- **`SpanMqttClient.masked_tree()` returns the panel's device tree with identifiers and site details masked**, for a consumer's diagnostics; `None` on a flat panel.
+- **`V2StatusInfo.hardware_version` reports the hardware version string from `GET /api/v2/status`.**
+- **`SpanEvseSnapshot.charge_current_limit_minimum_a` and `charge_current_limit_maximum_a` report the range a SPAN Drive declares for its charge-current limit**, `None` where undeclared.
+
+### Changed
+
+- **BREAKING FOR CONSUMERS: `SpanPanelSnapshot.proximity_proven` becomes `bool | None`**, and with `span-panel-api-schema-0` 1.3.0 and `span-panel-api-schema-1` 1.4.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`.
+- **BREAKING FOR CONSUMERS: `SpanCircuitSnapshot.is_240v` becomes `bool | None`**, and with `span-panel-api-schema-1` 1.4.0 or newer it is `None` where the pole count is unpublished.
+- **BREAKING FOR CONSUMERS: `SpanPanelSnapshot.lugs_at_service_entrance` becomes `bool | None`**, and with `span-panel-api-schema-1` 1.4.0 or newer it is `None` while the upstream lugs declare their feed but leave it unpublished.
+- **The `schema-0` extra requires `span-panel-api-schema-0` 1.3.0 or newer and the `schema-1` extra requires `span-panel-api-schema-1` 1.4.0 or newer**, the adapters that report these values as unknown; schema-1 1.4.0 also fills the snapshot fields this
+  release adds.
+
+### Removed
+
+- **BREAKING: with `span-panel-api-schema-0` 1.3.0 and `span-panel-api-schema-1` 1.4.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.
+- **A property the panel clears reads as unpublished** on a parent/child panel, where it read as an empty value until the panel published it again.
+
 ## [3.6.2]
 
 A reconnect waits for the panel's labels before handing out a snapshot, as connecting always has.
@@ -480,8 +514,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/README.md → span_panel_api-3.8.0/PKG-INFO

@@ -1,3 +1,30 @@
+Metadata-Version: 2.5
+Name: span-panel-api
+Version: 3.8.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
+Author: SpanPanel
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Home Automation
+Classifier: Typing :: Typed
+Requires-Python: <4.0,>=3.14
+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.3.0; extra == 'schema-0'
+Provides-Extra: schema-1
+Requires-Dist: span-panel-api-schema-1>=1.4.0; extra == 'schema-1'
+Description-Content-Type: text/markdown
+
 # SPAN Panel API
 
 [![GitHub Release](https://img.shields.io/github/v/release/SpanPanel/span-panel-api?filter=v*&style=flat-square&label=release)](https://github.com/SpanPanel/span-panel-api/releases)
@@ -129,35 +156,42 @@ The library defines structural subtyping protocols (PEP 544). All are `runtime_c
 | `CircuitControlProtocol`      | Relay and shed-priority control: `set_circuit_relay`, `set_circuit_priority`               |
 | `PanelControlProtocol`        | Panel-level control: `set_dominant_power_source`                                           |
 | `EvseControlProtocol`         | Per-charger control: `set_evse_charge_limit(node_id, amps)`                                |
+| `EvseLockControlProtocol`     | Per-charger connector lock: `set_evse_lock(node_id, locked)`                               |
 | `AdoptedControlProtocol`      | Write to a settable property of a device this library models nothing for                   |
 | `ControlInterceptionProtocol` | Install one veto-and-observe point for every control command: `set_control_interceptor`    |
 | `StreamingCapableProtocol`    | Push-based updates: `register_snapshot_callback`, `start_streaming`, `stop_streaming`      |
 
-The first five differ in subject, not just in name. `EvseControlProtocol` is separate from `PanelControlProtocol` because several chargers may be commissioned at once and every call names which one. `AdoptedControlProtocol` differs in kind: the curated
-setters name a control this library understands and translate or bound the value on the way out, while this one names a property by its wire address and passes the value through, because the declaration is all anybody here knows about it. That write is
-authorised by the snapshot rather than by its arguments — the transport resolves the property against the current `adopted_devices` and refuses anything it does not find carrying a set topic, so a device this library _does_ model cannot be addressed
-through it.
+The first six differ in subject, not just in name. `EvseControlProtocol` is separate from `PanelControlProtocol` because several chargers may be commissioned at once and every call names which one. `EvseLockControlProtocol` is separate from
+`EvseControlProtocol` so that protocol's implementers are unchanged, and its write is authorised by the snapshot: only a charger whose `SpanEvseSnapshot.lock_control` is set can be addressed, and only with a value its `lock_state_options` lists.
+`AdoptedControlProtocol` differs in kind: the curated setters name a control this library understands and translate or bound the value on the way out, while this one names a property by its wire address and passes the value through, because the declaration
+is all anybody here knows about it. That write is authorised by the snapshot rather than by its arguments — the transport resolves the property against the current `adopted_devices` and refuses anything it does not find carrying a set topic, so a device
+this library _does_ model cannot be addressed through it.
 
-`ControlInterceptionProtocol` is separate from the four control protocols rather than a member of them because adding it there would break every implementer of those protocols a second time in one release, and separate from `StreamingCapableProtocol`
-because a transport could reasonably offer one and not the other.
+`ControlInterceptionProtocol` is separate from the control protocols rather than a member of them because adding it there would break every implementer of those protocols a second time in one release, and separate from `StreamingCapableProtocol` because a
+transport could reasonably offer one and not the other.
 
 One further protocol, `SchemaAdapter`, is the bootstrap-to-parser contract rather than a consumer-facing one; it is what an adapter distribution implements and what discovery checks. Integration code programs against the protocols above, not against
 transport-specific classes.
 
+`TreeExportingAdapter` sits beside `SchemaAdapter` as an optional protocol, not one every adapter must implement: an adapter that offers `export_masked_tree()` lets `SpanMqttClient.masked_tree()` return the panel's device tree with serials, device ids and
+site details masked, and `None` otherwise.
+
 ### Snapshots
 
 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`,
-  `battery`, `pv`, `pv_inverters`, `evse`, `mid`, `pcs`, `adopted_devices` and `extension_properties`.
+- **`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, busbar current, line frequency, the rating of
+  the protection ahead of the upstream lugs, the first and last breaker positions, whether any circuit declares what it feeds, 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.
-- **`SpanBatterySnapshot`**: the BESS. SoE percentage and kWh, its own meter reading, communication state, link health, vendor / `model` / `part_number` / serial / version, nameplate capacity.
+  position, PCS management and priority, the `$target` pending state for relay and priority, nominal voltage, the breaker's protection functions, the role it declares for what it feeds, the other circuits its meter or relay is shared with, and whether it
+  is a meter outside the panel, which has no breaker space, relay or shed priority and reads import-positive.
+- **`SpanBatterySnapshot`**: the BESS. Whether the panel declares one, SoE percentage and kWh, its own meter reading, communication state, link health, the circuit that feeds it, vendor / `model` / `part_number` / serial / version, nameplate capacity.
 - **`SpanPVSnapshot`**: one PV inverter. Link health, vendor / `model` / serial / version, nameplate capacity (the array's DC size), feeding circuit, relative position, its wire `device_id` and its `node_id`, which is its key in `pv_inverters`.
   `SpanPanelSnapshot.pv` is the lone inverter, or describes several together.
-- **`SpanEvseSnapshot`**: one EV charger. `node_id`, feeding circuit, status, lock state, advertised current, link health, vendor / `model` / `part_number` / serial / version, charge-current limit, ceiling, pending target and settability, and the effective
-  limit it applies.
+- **`SpanEvseSnapshot`**: one EV charger. `node_id`, feeding circuit, status, lock state, advertised current, link health, vendor / `model` / `part_number` / serial / version, charge-current limit, ceiling, pending target and settability, the effective
+  limit it applies, the range it declares for that limit, and where its connector lock is commanded with the values it accepts.
 - **`SpanMidSnapshot`**: the Microgrid Interconnect Device. `node_id`, islanding state, grid state, grid-forming entity and its device name, vendor / `model` / serial / software and hardware version.
 - **`SpanPcsSnapshot`**: the Power Control System. Enabled and active, the enforced import limit and its binding constraint, and each import constraint's limit, enablement and active state (feed, operator, off-grid, requested).
 - **`AdoptedDevice`**: a device type this library models nothing for, carried whole. Identity (id, type, name, vendor, model, serial, versions), its declared parent, whether a peer proxies it, and its readings.
@@ -168,6 +202,13 @@ 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`.
+
+Two booleans can be unknown under the parent/child schema: `SpanCircuitSnapshot.is_240v` is `None` where no pole count is published, and `SpanPanelSnapshot.lugs_at_service_entrance` is `None` while the upstream lugs declare their feed and have not
+published it, so a consumer tests both against `None` before reading them as a boolean. `SpanPanelSnapshot.circuits` holds only circuits the panel publishes: no entry stands in for an unoccupied breaker position, and `panel_size`, with `first_position` and
+`last_position` under the parent/child schema, says which positions exist.
+
 ## Usage
 
 ### Factory Pattern (Recommended)
@@ -192,8 +233,11 @@ async def main():
         # The upstream lugs' own meter. That is grid flow only where the lugs are
         # the utility connection point; a BESS wired ahead of them, or a panel fed
         # by another panel, makes it this panel's feed instead. `power_flow_grid`
-        # is the site-level figure in every topology.
-        if snapshot.lugs_at_service_entrance:
+        # is the site-level figure in every topology. `None` means the lugs have
+        # not yet published what feeds them, so neither reading is known.
+        if snapshot.lugs_at_service_entrance is None:
+            print(f"Grid power: {snapshot.power_flow_grid}W")
+        elif snapshot.lugs_at_service_entrance:
             print(f"Grid power: {snapshot.instant_grid_power_w}W")
         else:
             print(f"Panel feed: {snapshot.instant_grid_power_w}W")
@@ -355,8 +399,9 @@ deliver it minutes later. `CONFIRMED` is strong evidence rather than proof: the
 idempotent in its physical effect.
 
 **A control the panel declares non-commandable raises rather than returning an outcome**, because there is no topic to publish to and so nothing to report on. `SpanPanelServerError` is raised for a relay on a circuit commissioned always-on, for the shed
-priority of a circuit commissioned never-backup, and for a charger with no settable charge-current limit. The same facts are on the snapshot ahead of the call — `SpanCircuitSnapshot.is_user_controllable` and `.is_never_backup` — so a consumer that offers
-the control only where the panel offers it will not meet this; it is the backstop for the case a setup-time gate cannot see, since re-commissioning a circuit in place changes its settability while an entity built from the earlier snapshot is still alive.
+priority of a circuit commissioned never-backup, and for a charger with no settable charge-current limit or connector lock. The same facts are on the snapshot ahead of the call — `SpanCircuitSnapshot.is_user_controllable` and `.is_never_backup` — so a
+consumer that offers the control only where the panel offers it will not meet this; it is the backstop for the case a setup-time gate cannot see, since re-commissioning a circuit in place changes its settability while an entity built from the earlier
+snapshot is still alive.
 
 ### Control Interception
 
@@ -502,6 +547,7 @@ All exceptions inherit from `SpanPanelError`:
 | `SpanPanelValidationError` | Data validation failure                                                                            |
 | `SpanPanelAPIError`        | Unexpected HTTP response from v2 endpoints                                                         |
 | `SpanPanelServerError`     | Panel answered 5xx, or answered `200` with a body that cannot be used — "not ready yet"            |
+| `SpanPanelRateLimitError`  | Panel refused a registration with HTTP 429; `retry_after_s` carries the wait it asked for          |
 
 Three more are specific to the hot-loading model, and they are separate because the remedy differs:
 
@@ -581,6 +627,7 @@ One repository, three distributions. The bootstrap is at the root; each parser i
 src/span_panel_api/          # distribution: span-panel-api (no parser)
 ├── __init__.py              # Public API exports
 ├── _http.py                 # Shared httpx plumbing / client ownership rules
+├── _ssl.py                  # The panel's trust anchor: SSL context, CA fingerprint, leaf-name probe
 ├── adapters.py              # installed_adapter_keys(), resolve_adapter() — metadata, then lazy import
 ├── auth.py                  # v2 HTTP provisioning (register, cert, schema, passphrase)
 ├── const.py                 # Panel state constants (DSM, relay)
@@ -598,6 +645,7 @@ src/span_panel_api/          # distribution: span-panel-api (no parser)
     ├── client.py            # SpanMqttClient (transport + control protocols)
     ├── connection.py        # AsyncMqttBridge (event-loop-driven, no threads)
     ├── const.py             # MQTT/Homie constants + UUID helpers
+    ├── control.py           # PublishOutcome, ControlCommand, ControlInterceptor
     └── models.py            # MqttClientConfig, MqttTransport
 
 packages/schema-0/           # distribution: span-panel-api-schema-0

span_panel_api-3.6.2/PKG-INFO → span_panel_api-3.8.0/README.md

@@ -1,30 +1,3 @@
-Metadata-Version: 2.5
-Name: span-panel-api
-Version: 3.6.2
-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
-Author: SpanPanel
-License-Expression: MIT
-License-File: LICENSE
-Classifier: Development Status :: 5 - Production/Stable
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Programming Language :: Python :: Implementation :: CPython
-Classifier: Topic :: Home Automation
-Classifier: Typing :: Typed
-Requires-Python: <4.0,>=3.14
-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'
-Provides-Extra: schema-1
-Requires-Dist: span-panel-api-schema-1>=1.2.2; extra == 'schema-1'
-Description-Content-Type: text/markdown
-
 # SPAN Panel API
 
 [![GitHub Release](https://img.shields.io/github/v/release/SpanPanel/span-panel-api?filter=v*&style=flat-square&label=release)](https://github.com/SpanPanel/span-panel-api/releases)
@@ -156,35 +129,42 @@ The library defines structural subtyping protocols (PEP 544). All are `runtime_c
 | `CircuitControlProtocol`      | Relay and shed-priority control: `set_circuit_relay`, `set_circuit_priority`               |
 | `PanelControlProtocol`        | Panel-level control: `set_dominant_power_source`                                           |
 | `EvseControlProtocol`         | Per-charger control: `set_evse_charge_limit(node_id, amps)`                                |
+| `EvseLockControlProtocol`     | Per-charger connector lock: `set_evse_lock(node_id, locked)`                               |
 | `AdoptedControlProtocol`      | Write to a settable property of a device this library models nothing for                   |
 | `ControlInterceptionProtocol` | Install one veto-and-observe point for every control command: `set_control_interceptor`    |
 | `StreamingCapableProtocol`    | Push-based updates: `register_snapshot_callback`, `start_streaming`, `stop_streaming`      |
 
-The first five differ in subject, not just in name. `EvseControlProtocol` is separate from `PanelControlProtocol` because several chargers may be commissioned at once and every call names which one. `AdoptedControlProtocol` differs in kind: the curated
-setters name a control this library understands and translate or bound the value on the way out, while this one names a property by its wire address and passes the value through, because the declaration is all anybody here knows about it. That write is
-authorised by the snapshot rather than by its arguments — the transport resolves the property against the current `adopted_devices` and refuses anything it does not find carrying a set topic, so a device this library _does_ model cannot be addressed
-through it.
+The first six differ in subject, not just in name. `EvseControlProtocol` is separate from `PanelControlProtocol` because several chargers may be commissioned at once and every call names which one. `EvseLockControlProtocol` is separate from
+`EvseControlProtocol` so that protocol's implementers are unchanged, and its write is authorised by the snapshot: only a charger whose `SpanEvseSnapshot.lock_control` is set can be addressed, and only with a value its `lock_state_options` lists.
+`AdoptedControlProtocol` differs in kind: the curated setters name a control this library understands and translate or bound the value on the way out, while this one names a property by its wire address and passes the value through, because the declaration
+is all anybody here knows about it. That write is authorised by the snapshot rather than by its arguments — the transport resolves the property against the current `adopted_devices` and refuses anything it does not find carrying a set topic, so a device
+this library _does_ model cannot be addressed through it.
 
-`ControlInterceptionProtocol` is separate from the four control protocols rather than a member of them because adding it there would break every implementer of those protocols a second time in one release, and separate from `StreamingCapableProtocol`
-because a transport could reasonably offer one and not the other.
+`ControlInterceptionProtocol` is separate from the control protocols rather than a member of them because adding it there would break every implementer of those protocols a second time in one release, and separate from `StreamingCapableProtocol` because a
+transport could reasonably offer one and not the other.
 
 One further protocol, `SchemaAdapter`, is the bootstrap-to-parser contract rather than a consumer-facing one; it is what an adapter distribution implements and what discovery checks. Integration code programs against the protocols above, not against
 transport-specific classes.
 
+`TreeExportingAdapter` sits beside `SchemaAdapter` as an optional protocol, not one every adapter must implement: an adapter that offers `export_masked_tree()` lets `SpanMqttClient.masked_tree()` return the panel's device tree with serials, device ids and
+site details masked, and `None` otherwise.
+
 ### Snapshots
 
 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`,
-  `battery`, `pv`, `pv_inverters`, `evse`, `mid`, `pcs`, `adopted_devices` and `extension_properties`.
+- **`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, busbar current, line frequency, the rating of
+  the protection ahead of the upstream lugs, the first and last breaker positions, whether any circuit declares what it feeds, 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.
-- **`SpanBatterySnapshot`**: the BESS. SoE percentage and kWh, its own meter reading, communication state, link health, vendor / `model` / `part_number` / serial / version, nameplate capacity.
+  position, PCS management and priority, the `$target` pending state for relay and priority, nominal voltage, the breaker's protection functions, the role it declares for what it feeds, the other circuits its meter or relay is shared with, and whether it
+  is a meter outside the panel, which has no breaker space, relay or shed priority and reads import-positive.
+- **`SpanBatterySnapshot`**: the BESS. Whether the panel declares one, SoE percentage and kWh, its own meter reading, communication state, link health, the circuit that feeds it, vendor / `model` / `part_number` / serial / version, nameplate capacity.
 - **`SpanPVSnapshot`**: one PV inverter. Link health, vendor / `model` / serial / version, nameplate capacity (the array's DC size), feeding circuit, relative position, its wire `device_id` and its `node_id`, which is its key in `pv_inverters`.
   `SpanPanelSnapshot.pv` is the lone inverter, or describes several together.
-- **`SpanEvseSnapshot`**: one EV charger. `node_id`, feeding circuit, status, lock state, advertised current, link health, vendor / `model` / `part_number` / serial / version, charge-current limit, ceiling, pending target and settability, and the effective
-  limit it applies.
+- **`SpanEvseSnapshot`**: one EV charger. `node_id`, feeding circuit, status, lock state, advertised current, link health, vendor / `model` / `part_number` / serial / version, charge-current limit, ceiling, pending target and settability, the effective
+  limit it applies, the range it declares for that limit, and where its connector lock is commanded with the values it accepts.
 - **`SpanMidSnapshot`**: the Microgrid Interconnect Device. `node_id`, islanding state, grid state, grid-forming entity and its device name, vendor / `model` / serial / software and hardware version.
 - **`SpanPcsSnapshot`**: the Power Control System. Enabled and active, the enforced import limit and its binding constraint, and each import constraint's limit, enablement and active state (feed, operator, off-grid, requested).
 - **`AdoptedDevice`**: a device type this library models nothing for, carried whole. Identity (id, type, name, vendor, model, serial, versions), its declared parent, whether a peer proxies it, and its readings.
@@ -195,6 +175,13 @@ 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`.
+
+Two booleans can be unknown under the parent/child schema: `SpanCircuitSnapshot.is_240v` is `None` where no pole count is published, and `SpanPanelSnapshot.lugs_at_service_entrance` is `None` while the upstream lugs declare their feed and have not
+published it, so a consumer tests both against `None` before reading them as a boolean. `SpanPanelSnapshot.circuits` holds only circuits the panel publishes: no entry stands in for an unoccupied breaker position, and `panel_size`, with `first_position` and
+`last_position` under the parent/child schema, says which positions exist.
+
 ## Usage
 
 ### Factory Pattern (Recommended)
@@ -219,8 +206,11 @@ async def main():
         # The upstream lugs' own meter. That is grid flow only where the lugs are
         # the utility connection point; a BESS wired ahead of them, or a panel fed
         # by another panel, makes it this panel's feed instead. `power_flow_grid`
-        # is the site-level figure in every topology.
-        if snapshot.lugs_at_service_entrance:
+        # is the site-level figure in every topology. `None` means the lugs have
+        # not yet published what feeds them, so neither reading is known.
+        if snapshot.lugs_at_service_entrance is None:
+            print(f"Grid power: {snapshot.power_flow_grid}W")
+        elif snapshot.lugs_at_service_entrance:
             print(f"Grid power: {snapshot.instant_grid_power_w}W")
         else:
             print(f"Panel feed: {snapshot.instant_grid_power_w}W")
@@ -382,8 +372,9 @@ deliver it minutes later. `CONFIRMED` is strong evidence rather than proof: the
 idempotent in its physical effect.
 
 **A control the panel declares non-commandable raises rather than returning an outcome**, because there is no topic to publish to and so nothing to report on. `SpanPanelServerError` is raised for a relay on a circuit commissioned always-on, for the shed
-priority of a circuit commissioned never-backup, and for a charger with no settable charge-current limit. The same facts are on the snapshot ahead of the call — `SpanCircuitSnapshot.is_user_controllable` and `.is_never_backup` — so a consumer that offers
-the control only where the panel offers it will not meet this; it is the backstop for the case a setup-time gate cannot see, since re-commissioning a circuit in place changes its settability while an entity built from the earlier snapshot is still alive.
+priority of a circuit commissioned never-backup, and for a charger with no settable charge-current limit or connector lock. The same facts are on the snapshot ahead of the call — `SpanCircuitSnapshot.is_user_controllable` and `.is_never_backup` — so a
+consumer that offers the control only where the panel offers it will not meet this; it is the backstop for the case a setup-time gate cannot see, since re-commissioning a circuit in place changes its settability while an entity built from the earlier
+snapshot is still alive.
 
 ### Control Interception
 
@@ -529,6 +520,7 @@ All exceptions inherit from `SpanPanelError`:
 | `SpanPanelValidationError` | Data validation failure                                                                            |
 | `SpanPanelAPIError`        | Unexpected HTTP response from v2 endpoints                                                         |
 | `SpanPanelServerError`     | Panel answered 5xx, or answered `200` with a body that cannot be used — "not ready yet"            |
+| `SpanPanelRateLimitError`  | Panel refused a registration with HTTP 429; `retry_after_s` carries the wait it asked for          |
 
 Three more are specific to the hot-loading model, and they are separate because the remedy differs:
 
@@ -608,6 +600,7 @@ One repository, three distributions. The bootstrap is at the root; each parser i
 src/span_panel_api/          # distribution: span-panel-api (no parser)
 ├── __init__.py              # Public API exports
 ├── _http.py                 # Shared httpx plumbing / client ownership rules
+├── _ssl.py                  # The panel's trust anchor: SSL context, CA fingerprint, leaf-name probe
 ├── adapters.py              # installed_adapter_keys(), resolve_adapter() — metadata, then lazy import
 ├── auth.py                  # v2 HTTP provisioning (register, cert, schema, passphrase)
 ├── const.py                 # Panel state constants (DSM, relay)
@@ -625,6 +618,7 @@ src/span_panel_api/          # distribution: span-panel-api (no parser)
     ├── client.py            # SpanMqttClient (transport + control protocols)
     ├── connection.py        # AsyncMqttBridge (event-loop-driven, no threads)
     ├── const.py             # MQTT/Homie constants + UUID helpers
+    ├── control.py           # PublishOutcome, ControlCommand, ControlInterceptor
     └── models.py            # MqttClientConfig, MqttTransport
 
 packages/schema-0/           # distribution: span-panel-api-schema-0

{span_panel_api-3.6.2 → span_panel_api-3.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "span-panel-api"
-version = "3.6.2"
+version = "3.8.0"
 description = "A client library for SPAN Panel API"
 authors = [
     {name = "SpanPanel"}
@@ -62,11 +62,16 @@ 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.0 for 3.8.0: 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.0"]
 # 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.4.0 for 3.8.0: for the same reason as schema-0's, and because that
+# adapter fills the snapshot fields this bootstrap adds and exports the masked
+# device tree.
+schema-1 = ["span-panel-api-schema-1>=1.4.0"]
 
 [project.urls]
 Homepage = "https://github.com/SpanPanel/span-panel-api"
@@ -90,7 +95,7 @@ dev = [
     # known. Dependabot raises the bump on its own; the bump PR re-runs
     # `scripts/capture_parent_child_reference.py` and the suite then says whether
     # the wire moved.
-    "ebus-panel-sim==0.8.0",
+    "ebus-panel-sim==0.9.0",
     "pytest>=9.0.2",
     "pytest-asyncio>=1.3.0",
     "pytest-cov",
@@ -245,7 +250,17 @@ 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"
+# paho ships `py.typed` but leaves its topic matcher unannotated, so every call
+# into it would be an untyped call. The schema-1 route table resolves what the
+# matcher yields through a typed dict at once, which keeps its `Any` from going
+# further; `warn_return_any` does not police that for you (a union or a
+# `yield from` passes it), so keep it to that shape.
+untyped_calls_exclude = ["paho.mqtt.matcher"]
 # 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.8.0}/src/span_panel_api/__init__.py

@@ -29,6 +29,7 @@ from .exceptions import (
     SpanPanelError,
     SpanPanelInsufficientPrivilegeError,
     SpanPanelPassphraseUnavailableError,
+    SpanPanelRateLimitError,
     SpanPanelSchemaVersionError,
     SpanPanelServerError,
     SpanPanelStaleDataError,
@@ -41,15 +42,22 @@ from .models import (
     ADOPTION_IDENTITY_NODE,
     ADOPTION_TOPOLOGY_NODE,
     DISCOVERY_NAMESPACE,
+    FEEDS_ROLES,
+    PROTECTION_FUNCTIONS,
     AdoptedDevice,
     AdoptedProperty,
     ControlTarget,
     DiscoveredMetadata,
     ExtensionProperty,
     ExtensionSubject,
+    FeedsRole,
     FieldMetadata,
     HomieSchemaTypes,
+    MaskedTree,
+    MaskedTreeDevice,
+    MaskedTreeMetadata,
     PassphraseRotation,
+    ProtectionFunction,
     SpanBatterySnapshot,
     SpanCircuitSnapshot,
     SpanEvseSnapshot,
@@ -57,10 +65,12 @@ from .models import (
     SpanPanelSnapshot,
     SpanPcsSnapshot,
     SpanPVSnapshot,
+    UndescribedDevice,
     V2AuthResponse,
     V2HomieSchema,
     V2StatusInfo,
     is_discovery_path,
+    shared_meter_groups,
 )
 from .mqtt import (
     ControlCommand,
@@ -84,10 +94,12 @@ from .protocol import (
     CircuitControlProtocol,
     ControlInterceptionProtocol,
     EvseControlProtocol,
+    EvseLockControlProtocol,
     PanelCapability,
     PanelControlProtocol,
     SpanPanelClientProtocol,
     StreamingCapableProtocol,
+    TreeExportingAdapter,
 )
 
 __version__ = _pkg_version("span-panel-api")
@@ -106,6 +118,9 @@ __all__ = [  # noqa: RUF022
     # snapshot rather than by its arguments -- a device the adapter models
     # produces no AdoptedDevice and so cannot be addressed through it.
     "AdoptedControlProtocol",
+    # A charger's connector lock, authorised by `SpanEvseSnapshot.lock_control`.
+    # A protocol of its own so `EvseControlProtocol`'s implementers are unchanged.
+    "EvseLockControlProtocol",
     # Added 2026-08-25 (3.1.0): one veto/observe point for every control
     # command. A protocol of its own rather than a member on the four control
     # protocols, which would break their implementers a second time in one
@@ -137,6 +152,15 @@ __all__ = [  # noqa: RUF022
     "ControlTarget",
     "ExtensionProperty",
     "ExtensionSubject",
+    # Added 2026-10-31: the masked device tree a consumer forwards in diagnostics,
+    # and the optional protocol an adapter offers it through. Deliberately not a
+    # SchemaAdapter member: the protocol derives its required set from itself, so a
+    # member there would invalidate every built adapter wheel.
+    "MaskedTree",
+    "MaskedTreeDevice",
+    "MaskedTreeMetadata",
+    "UndescribedDevice",
+    "TreeExportingAdapter",
     # Snapshots
     "SpanBatterySnapshot",
     "SpanCircuitSnapshot",
@@ -145,6 +169,16 @@ __all__ = [  # noqa: RUF022
     "SpanPVSnapshot",
     "SpanPanelSnapshot",
     "SpanPcsSnapshot",
+    # What a circuit's `connection/feeds-role` declares, read into
+    # `SpanCircuitSnapshot.feeds_role`.
+    "FEEDS_ROLES",
+    "FeedsRole",
+    # What a circuit's `breaker/protection-functions` lists, read into
+    # `SpanCircuitSnapshot.protection_functions`.
+    "PROTECTION_FUNCTIONS",
+    "ProtectionFunction",
+    # The circuits one meter measures, from `SpanCircuitSnapshot.meter_shared_with`.
+    "shared_meter_groups",
     # Factory
     "create_span_client",
     # Detection
@@ -216,6 +250,10 @@ __all__ = [  # noqa: RUF022
     # keep their meaning; deliberately not a SpanPanelAuthError, because the
     # passphrase the user supplied may be correct.
     "SpanPanelPassphraseUnavailableError",
+    # Registration refused with HTTP 429, carrying the panel's `Retry-After` in
+    # seconds. A subclass of SpanPanelAPIError, so existing except clauses keep
+    # their meaning; not a SpanPanelAuthError, because no credential was judged.
+    "SpanPanelRateLimitError",
     "SpanPanelServerError",
     "SpanPanelStaleDataError",
     # Added 2026-08-31 (3.4.0): a bootstrap REST call that failed verification