span-panel-api 3.8.0b1__tar.gz → 3.9.0b1__tar.gz

{span_panel_api-3.8.0b1 → span_panel_api-3.9.0b1}/.gitignore

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

{span_panel_api-3.8.0b1 → span_panel_api-3.9.0b1}/CHANGELOG.md

@@ -7,19 +7,28 @@ 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.9.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.
+### Added
+
+- **`SpanCircuitSnapshot.breaker_rating_declared`** says whether a circuit declares a breaker rating, so a consumer can tell a rating the panel does not publish from one that has not arrived yet; `None` where the adapter does not say.
+- **`SpanPanelSnapshot.publishes_shared_meters`** says whether any circuit declares `meter/shared-with-device-ids`, so a consumer can tell a panel that describes its multi-load breakers from one, such as MAIN 32, that publishes each as a single circuit.
+
+## [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` 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`.
@@ -30,13 +39,14 @@ Snapshot fields that held a fabricated constant can now be unknown, and with `sp
 
 ### 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.8.0b1/README.md → span_panel_api-3.9.0b1/PKG-INFO

@@ -1,3 +1,30 @@
+Metadata-Version: 2.5
+Name: span-panel-api
+Version: 3.9.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.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`.
-- **`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.
+  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 or a shared meter, 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 and whether it declares one, current, priority, user controllability, sheddable / never-backup / always-on
+  flags, device type, relative 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.8.0b1/PKG-INFO → span_panel_api-3.9.0b1/README.md

@@ -1,30 +1,3 @@
-Metadata-Version: 2.5
-Name: span-panel-api
-Version: 3.8.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.4.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`.
-- **`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.
+  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 or a shared meter, 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 and whether it declares one, current, priority, user controllability, sheddable / never-backup / always-on
+  flags, device type, relative 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.8.0b1 → span_panel_api-3.9.0b1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "span-panel-api"
-version = "3.8.0b1"
+version = "3.9.0b1"
 description = "A client library for SPAN Panel API"
 authors = [
     {name = "SpanPanel"}
@@ -62,16 +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.
-# Raised to 1.4.0b1 for 3.8.0b1: that adapter fills the snapshot fields this
-# bootstrap adds.
-schema-1 = ["span-panel-api-schema-1>=1.4.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"
@@ -95,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",
@@ -255,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.8.0b1 → span_panel_api-3.9.0b1}/src/span_panel_api/__init__.py

@@ -53,6 +53,9 @@ from .models import (
     FeedsRole,
     FieldMetadata,
     HomieSchemaTypes,
+    MaskedTree,
+    MaskedTreeDevice,
+    MaskedTreeMetadata,
     PassphraseRotation,
     ProtectionFunction,
     SpanBatterySnapshot,
@@ -62,6 +65,7 @@ from .models import (
     SpanPanelSnapshot,
     SpanPcsSnapshot,
     SpanPVSnapshot,
+    UndescribedDevice,
     V2AuthResponse,
     V2HomieSchema,
     V2StatusInfo,
@@ -95,6 +99,7 @@ from .protocol import (
     PanelControlProtocol,
     SpanPanelClientProtocol,
     StreamingCapableProtocol,
+    TreeExportingAdapter,
 )
 
 __version__ = _pkg_version("span-panel-api")
@@ -147,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",

{span_panel_api-3.8.0b1 → span_panel_api-3.9.0b1}/src/span_panel_api/models.py

@@ -12,7 +12,7 @@ from __future__ import annotations
 from collections.abc import Mapping
 from dataclasses import dataclass, field
 import re
-from typing import Final, Literal
+from typing import Final, Literal, NotRequired, TypedDict
 
 # Homie schema type: {type_name: {property_name: {attribute: value}}}
 # Values are heterogeneous JSON (str, int, bool, nested dicts).
@@ -64,6 +64,13 @@ class SpanCircuitSnapshot:
     is_240v: bool | None = False
     current_a: float | None = None
     breaker_rating_a: float | None = None
+    # Whether the circuit's description declares a breaker rating, as distinct
+    # from whether its value has arrived. `True`: declared, so `breaker_rating_a`
+    # is `None` only until the retained value lands. `False`: the panel
+    # publishes no rating for this circuit. `None`: the adapter does not say
+    # (flat, REST, a hand-built snapshot) and the consumer must treat it as
+    # not known, never as `False`.
+    breaker_rating_declared: bool | None = None
     always_on: bool = False  # v2 new: circuit/always-on
     relay_requester: str = "UNKNOWN"  # v2 new: circuit/relay-requester
     # Epoch seconds at which the reading last changed, as received over MQTT.
@@ -465,6 +472,36 @@ class SpanEvseSnapshot:
     set topic when it is not.
     """
 
+    charge_current_limit_minimum_a: int | None = None
+    """The lowest charge-current limit the charger declares a user may set, in amps. v1.0 only.
+
+    The minimum of the `<min>:<max>` range the limit's declaration states in
+    `$format`, from the same resolution as `charge_current_limit_a`; firmware
+    r202639 declares `6:<commissioned maximum>`. A write below it is refused
+    rather than published, so a control offers nothing under it.
+
+    A declaration, not a reading: it is reported as soon as the charger
+    describes itself, and whether or not the limit is settable, which
+    `charge_current_limit_settable` answers. `None` where the charger declares
+    no limit, no `$format`, or the format leaves this side open, and where the
+    format cannot be read as an integer range (not `integer`, not `<min>:<max>`,
+    a bound that is not a plain integer, or a minimum above the maximum). `None`
+    on the flat schema, which declares no range.
+    """
+
+    charge_current_limit_maximum_a: int | None = None
+    """The highest charge-current limit the charger declares a user may set, in amps. v1.0 only.
+
+    The maximum of the same declared range, `None` on the same terms. A write
+    above it is refused rather than published.
+
+    **Not `charge_current_ceiling_a`.** That is the commissioned ceiling, a
+    published value; this is the declared range, part of the limit's
+    description. Every r202639 capture declares a maximum equal to the ceiling
+    it publishes, but they are separate facts, and a write must satisfy both: a
+    control's upper bound is the lower of the two where both are present.
+    """
+
     lock_control: ControlTarget | None = None
     """Where the charger's connector lock is commanded, and which property reports it. v1.0 only.
 
@@ -1310,6 +1347,17 @@ class SpanPanelSnapshot:
     which declares no roles.
     """
 
+    publishes_shared_meters: bool = False
+    """Whether any circuit declares `meter/shared-with-device-ids`.
+
+    The declaration decides, not the value: a panel model that describes its
+    multi-load breakers declares the list on every circuit, a standard breaker
+    included, and publishes a value only where a meter is shared. Such a panel
+    publishes each circuit of a multi-load breaker as its own device with its
+    own rating. `False` where no circuit declares the list, as on MAIN 32, and
+    on the flat schema, which declares none.
+    """
+
     # `shed/policy`, v1.0 only: how the panel decides what to shed, and the two
     # SoC thresholds that make its behaviour predictable. The wire carries one
     # `json` document; these are the parsed answer plus the document itself.
@@ -1506,3 +1554,65 @@ class SpanPanelSnapshot:
     the feeding device is another panel with its own tree, not a child of this
     one.
     """
+
+
+class MaskedTreeMetadata(TypedDict):
+    """What produced a `MaskedTree` and whether it can be trusted to be whole.
+
+    `masked` is always `True`: the tree never carries a serial, a credential or
+    an address, and the marker lets whoever reads a forwarded diagnostic see that
+    without inspecting the values. `tree_complete` is `False` when the panel had
+    not finished publishing its tree, so what follows is a partial reading.
+    """
+
+    schema: Literal["tree-v1"]
+    masked: Literal[True]
+    producer: str
+    tree_complete: bool
+
+
+class MaskedTreeDevice(TypedDict):
+    """One described device in a `MaskedTree`, as a consumer forwards it in diagnostics.
+
+    Values are keyed `"<node>/<property>"` and kept as the wire strings the
+    panel published, masked where they identify the device or the site.
+    `numeric_properties` holds the values of declared `integer` and `float`
+    properties, `properties` the values of every other declared property,
+    `undeclared_properties` values the panel published that its own description
+    does not declare, and `targets` its `$target` values. A declared property
+    with no value has no key: never `None`, and never a `""` the panel did not
+    send, because a placeholder would read as a reading. A `""` the panel did
+    publish is kept as `""`.
+    """
+
+    description: dict[str, object]
+    properties: dict[str, str]
+    numeric_properties: dict[str, str]
+    targets: dict[str, str]
+    undeclared_properties: dict[str, str]
+    state: NotRequired[str]
+
+
+class UndescribedDevice(TypedDict):
+    """A device the panel published values for but never described.
+
+    With no `$description` there is nothing to say which node a property belongs
+    to, so `values` keeps each as `"<node>/<property>"` -> wire string, unsplit.
+    """
+
+    values: dict[str, str]
+    targets: dict[str, str]
+    state: NotRequired[str]
+
+
+class MaskedTree(TypedDict):
+    """The masked device tree a consumer forwards in diagnostics.
+
+    Produced by an adapter that offers `TreeExportingAdapter`. Described devices
+    and undescribed ones are kept apart so a reader never mistakes one for the
+    other.
+    """
+
+    metadata: MaskedTreeMetadata
+    devices: dict[str, MaskedTreeDevice]
+    undescribed_devices: dict[str, UndescribedDevice]