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

{span_panel_api-3.7.0b1 → 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.7.0b1 → span_panel_api-3.8.0}/CHANGELOG.md

@@ -7,32 +7,39 @@ 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]
+## [3.8.0]
 
-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.
+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` 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.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`.
-- **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.
+- **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` 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.
+- **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]
 

span_panel_api-3.7.0b1/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 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`.
+  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.
@@ -171,6 +205,10 @@ see the changelog, because `battery.model` changes value for existing flat users
 `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)
@@ -195,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")
@@ -358,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
 
@@ -505,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:
 
@@ -584,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)
@@ -601,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.7.0b1/PKG-INFO → span_panel_api-3.8.0/README.md

@@ -1,30 +1,3 @@
-Metadata-Version: 2.5
-Name: span-panel-api
-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
-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.0b1; extra == 'schema-0'
-Provides-Extra: schema-1
-Requires-Dist: span-panel-api-schema-1>=1.3.0b1; 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 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`.
+  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.
@@ -198,6 +178,10 @@ see the changelog, because `battery.model` changes value for existing flat users
 `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)
@@ -222,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")
@@ -385,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
 
@@ -532,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:
 
@@ -611,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)
@@ -628,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.7.0b1 → span_panel_api-3.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "span-panel-api"
-version = "3.7.0b1"
+version = "3.8.0"
 description = "A client library for SPAN Panel API"
 authors = [
     {name = "SpanPanel"}
@@ -62,14 +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.
-# Raised to 1.3.0b1 for 3.7.0b1: that adapter reports the unknown values this
+# 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.0b1"]
+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.
-# 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"]
+# 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"
@@ -93,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",
@@ -253,6 +255,12 @@ explicit_package_bases = true
 # `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.7.0b1 → 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

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

@@ -10,9 +10,12 @@ from __future__ import annotations
 
 import asyncio
 from collections.abc import Collection, Mapping
+from datetime import UTC, datetime
+from email.utils import parsedate_to_datetime
 import hashlib
 import json
 import logging
+import math
 import ssl
 import uuid
 
@@ -24,6 +27,7 @@ from .exceptions import (
     SpanPanelAuthError,
     SpanPanelInsufficientPrivilegeError,
     SpanPanelPassphraseUnavailableError,
+    SpanPanelRateLimitError,
     SpanPanelServerError,
 )
 from .models import HomieSchemaTypes, PassphraseRotation, V2AuthResponse, V2HomieSchema, V2StatusInfo
@@ -216,21 +220,37 @@ CA_CERT_MAX_ATTEMPTS = 5
 CA_CERT_BACKOFF_S = 1.5
 
 
-def _retry_delay(retry_after: str | None, attempt: int, backoff_s: float) -> float:
-    """Return how long to wait before retrying a rate-limited request.
+def _retry_after_s(retry_after: str | None, now: datetime) -> float | None:
+    """The wait a ``Retry-After`` header asks for, in seconds, or None if it asks for none.
 
-    Prefers the panel's ``Retry-After`` header (delta-seconds form) and falls
-    back to exponential backoff. Malformed or negative values fall back too,
-    so a bad header can never stall or skip the retry.
+    Both forms RFC 9110 allows: delta-seconds, taken as given, and an HTTP-date,
+    taken as the seconds from `now` until then (0.0 once it has passed). A
+    negative, infinite or unparseable value is no answer, so a bad header can
+    never stall or skip a retry.
     """
-    fallback = backoff_s * (2.0 ** (attempt - 1))
     if retry_after is None:
-        return fallback
+        return None
     try:
-        parsed = float(retry_after)
-    except (TypeError, ValueError):
-        return fallback
-    return parsed if parsed >= 0 else fallback
+        seconds = float(retry_after)
+    except ValueError:
+        try:
+            until = parsedate_to_datetime(retry_after)
+        except (TypeError, ValueError):
+            return None
+        if until.tzinfo is None:
+            return None
+        return max((until - now).total_seconds(), 0.0)
+    return seconds if math.isfinite(seconds) and seconds >= 0 else None
+
+
+def _retry_delay(retry_after: str | None, attempt: int, backoff_s: float) -> float:
+    """Return how long to wait before retrying a rate-limited request.
+
+    Prefers the panel's ``Retry-After`` header and falls back to exponential
+    backoff where it gives no usable wait.
+    """
+    parsed = _retry_after_s(retry_after, datetime.now(UTC))
+    return backoff_s * (2.0 ** (attempt - 1)) if parsed is None else parsed
 
 
 async def register_v2(
@@ -276,6 +296,7 @@ async def register_v2(
     Raises:
         SpanPanelAuthError: Invalid passphrase or auth failure
         SpanPanelPassphraseUnavailableError: The panel cannot read its own passphrase
+        SpanPanelRateLimitError: HTTP 429; the panel is limiting registrations. Not retried
         SpanPanelServerError: The panel is not ready to register clients (any 5xx,
             including the 503 it answers before its serial number is known); retryable
         SpanPanelConnectionError: Cannot reach panel
@@ -314,6 +335,16 @@ async def register_v2(
             status_code=reply.status_code,
         )
 
+    if reply.status_code == HTTP_TOO_MANY_REQUESTS:
+        # Not retried: the panel limits registrations per client address, and a
+        # retry here would spend the caller's next attempt on its behalf.
+        _log_auth_failure(reply.endpoint, reply.response, sent)
+        raise SpanPanelRateLimitError(
+            f"Panel is rate-limiting registration (HTTP {reply.status_code})",
+            status_code=reply.status_code,
+            retry_after_s=_retry_after_s(reply.headers.get("retry-after"), datetime.now(UTC)),
+        )
+
     if reply.status_code == 422 and _error_detail(reply.response) == REGISTRATION_UNAVAILABLE_DETAIL:
         # Checked before the general 422 below, which means "credential not
         # accepted". This one is the panel failing to read its own passphrase,
@@ -613,8 +644,8 @@ async def rotate_passphrase(
     Raises:
         SpanPanelInsufficientPrivilegeError: HTTP 403; the token is reduced-privilege
         SpanPanelAuthError: HTTP 401 (token invalid or stale) or 412 (no bearer token)
-        SpanPanelServerError: HTTP 5xx. After a 500 the outcome is unknown: the
-            passphrase may or may not have changed.
+        SpanPanelServerError: HTTP 5xx. After a 500 or a 504 the outcome is unknown:
+            the passphrase may or may not have changed.
         SpanPanelConnectionError: Cannot reach panel
         SpanPanelTimeoutError: Request timed out
         SpanPanelAPIError: Unexpected response