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

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

@@ -7,9 +7,16 @@ 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
 
@@ -20,8 +27,8 @@ Snapshot fields that held a fabricated constant can now be unknown, and with `sp
 
 ### 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`.
@@ -32,8 +39,8 @@ 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
 

{span_panel_api-3.8.0b2 → span_panel_api-3.9.0b1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: span-panel-api
-Version: 3.8.0b2
+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
@@ -20,9 +20,9 @@ Requires-Dist: httpx<1.0,>=0.28.1
 Requires-Dist: paho-mqtt<3.0.0,>=2.0.0
 Requires-Dist: pyyaml>=6.0.0
 Provides-Extra: schema-0
-Requires-Dist: span-panel-api-schema-0>=1.3.0b1; 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.0b4; extra == 'schema-1'
+Requires-Dist: span-panel-api-schema-1>=1.4.0; extra == 'schema-1'
 Description-Content-Type: text/markdown
 
 # SPAN Panel API
@@ -156,17 +156,19 @@ 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.
@@ -179,15 +181,17 @@ site details masked, and `None` otherwise.
 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.
@@ -201,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)
@@ -225,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")
@@ -388,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
 
@@ -535,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:
 
@@ -614,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)
@@ -631,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.0b2 → span_panel_api-3.9.0b1}/README.md

@@ -129,17 +129,19 @@ 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.
@@ -152,15 +154,17 @@ site details masked, and `None` otherwise.
 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.
@@ -174,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)
@@ -198,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")
@@ -361,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
 
@@ -508,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:
 
@@ -587,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)
@@ -604,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.0b2 → span_panel_api-3.9.0b1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "span-panel-api"
-version = "3.8.0b2"
+version = "3.9.0b1"
 description = "A client library for SPAN Panel API"
 authors = [
     {name = "SpanPanel"}
@@ -62,17 +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.
-# Raised to 1.4.0b4 for 3.8.0b2: that adapter exports the masked device tree.
-schema-1 = ["span-panel-api-schema-1>=1.4.0b4"]
+# 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"

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

@@ -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.
@@ -1340,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.

{span_panel_api-3.8.0b2 → span_panel_api-3.9.0b1}/tests/adapter_fidelity/rules.py

@@ -500,10 +500,18 @@ _DERIVATIONS: Final = (
         "circuit.measures_outside_panel",
         "circuits.declares_spaces: whether the description declares info/spaces, not a value",
     ),
+    Derivation(
+        "circuit.breaker_rating_declared",
+        "circuits.build_circuit: whether the description declares breaker/rating, not a value",
+    ),
     Derivation(
         "panel.publishes_solar_roles",
         "snapshot.build_snapshot: whether any circuit's description declares connection/feeds-role, not a value",
     ),
+    Derivation(
+        "panel.publishes_shared_meters",
+        "snapshot.build_snapshot: whether any circuit's description declares meter/shared-with-device-ids, not a value",
+    ),
     Derivation("pv.device_id", "devices.build_pv: the inverter's device id"),
     Derivation("pv.node_id", "devices.pv_inverter_key: the feeding circuit's id, else the inverter's device id"),
     Derivation("pv_inverter.device_id", "devices.build_pv: the inverter's device id"),

{span_panel_api-3.8.0b2 → span_panel_api-3.9.0b1}/tests/adapter_fidelity/rules_captured.py

@@ -9,7 +9,7 @@ here rather than inherited.
 Four of them are exceptions rather than derivations, and say so: the snapshot
 holds `"UNKNOWN"` in a `str` field where the panel publishes nothing for it.
 That is the field's long-standing absence value, not a reading; whether those
-fields become optional is a type question deferred past 3.8.0b1.
+fields become optional is a type question deferred past 3.8.0.
 """
 
 from __future__ import annotations
@@ -22,6 +22,7 @@ from .rules import DROPS, MAIN32_RULES, TRANSFORMS
 _SHARED: Final = frozenset(
     {
         "battery.present",
+        "circuit.breaker_rating_declared",
         "circuit.circuit_id",
         "circuit.device_type",
         "circuit.is_never_backup",
@@ -29,6 +30,7 @@ _SHARED: Final = frozenset(
         "circuit.measures_outside_panel",
         "ctl.dps_target",
         "ctl.priority_target",
+        "panel.publishes_shared_meters",
         "panel.publishes_solar_roles",
     }
 )
@@ -38,7 +40,7 @@ _NO_RELAY = (
     "circuits.build_circuit: a device that declares no switch node has no relay, "
     "so it is not controllable, not sheddable and not always on"
 )
-_STR_SENTINEL = "pre-existing str sentinel; type question deferred past 3.8.0b1"
+_STR_SENTINEL = "pre-existing str sentinel; type question deferred past 3.8.0"
 
 _DERIVATIONS: Final = (
     *(derivation for derivation in MAIN32_RULES.derivations if derivation.family in _SHARED),

{span_panel_api-3.8.0b2 → span_panel_api-3.9.0b1}/tests/test_schema_one_circuits.py

@@ -15,13 +15,18 @@ expecting the capture to carry every enum member.
 from __future__ import annotations
 
 import json
+from dataclasses import replace
 from pathlib import Path
 
 import pytest
 
 from ebus_sdk.homie import DiscoveredDevice
 
+from conftest import flat_schema
 from reference_payloads.schema_one import device_from_topics, parent_child_tree
+from reference_payloads.synthetic_trees import SyntheticDevice, discovered, hosted_circuit, space_less_meter, without_values
+from span_panel_api_schema_0 import SchemaZeroAdapter
+from span_panel_api_schema_0.const import TYPE_CIRCUIT
 from span_panel_api_schema_1.circuits import build_circuit
 
 _TREE = parent_child_tree()
@@ -116,6 +121,57 @@ def test_breaker_rating_and_current(kitchen: DiscoveredDevice) -> None:
     assert circuit.current_a == pytest.approx(1.00833, rel=1e-4)
 
 
+# ---------------------------------------------------------------------------
+# Whether the breaker rating is declared
+# ---------------------------------------------------------------------------
+
+
+def _undeclared_rating(device: SyntheticDevice) -> SyntheticDevice:
+    """The same circuit, its `breaker` node kept but `rating` neither declared nor valued."""
+    breaker = {prop: declaration for prop, declaration in device.nodes["breaker"].items() if prop != "rating"}
+    values = {path: value for path, value in device.values.items() if path != "breaker/rating"}
+    return replace(device, nodes={**device.nodes, "breaker": breaker}, values=values)
+
+
+def test_rating_declared_and_valued() -> None:
+    circuit = build_circuit(discovered(hosted_circuit("c-1", (1,))))
+
+    assert circuit.breaker_rating_a == 20.0
+    assert circuit.breaker_rating_declared is True
+
+
+def test_rating_declared_not_yet_valued() -> None:
+    """Declared before it is valued: the rating is coming, which is not the same as never."""
+    circuit = build_circuit(discovered(without_values(hosted_circuit("c-1", (1,)), "breaker/rating")))
+
+    assert circuit.breaker_rating_a is None
+    assert circuit.breaker_rating_declared is True
+
+
+def test_rating_not_declared() -> None:
+    circuit = build_circuit(discovered(_undeclared_rating(hosted_circuit("c-1", (1,)))))
+
+    assert circuit.breaker_rating_a is None
+    assert circuit.breaker_rating_declared is False
+
+
+def test_no_breaker_node() -> None:
+    circuit = build_circuit(discovered(space_less_meter("meter-a")))
+
+    assert circuit.breaker_rating_a is None
+    assert circuit.breaker_rating_declared is False
+
+
+def test_schema_zero_does_not_say() -> None:
+    serial = "sim-40t-001"
+    circuit_id = "ac3dccda46a94b98878a227df6fed588"
+    adapter = SchemaZeroAdapter(serial_number=serial, schema=flat_schema(40))
+    adapter.handle_message(f"ebus/5/{serial}/$description", json.dumps({"nodes": {circuit_id: {"type": TYPE_CIRCUIT}}}))
+    adapter.handle_message(f"ebus/5/{serial}/$state", "ready")
+
+    assert adapter.build_snapshot().circuits[circuit_id].breaker_rating_declared is None
+
+
 # ---------------------------------------------------------------------------
 # The three flat booleans v1.0 retired
 # ---------------------------------------------------------------------------

{span_panel_api-3.8.0b2 → span_panel_api-3.9.0b1}/tests/test_schema_one_shared_meters.py

@@ -113,3 +113,44 @@ def test_a_flat_panel_shares_nothing() -> None:
 
     assert all(circuit.meter_shared_with is None for circuit in snapshot.circuits.values())
     assert shared_meter_groups(snapshot.circuits) == {}
+
+
+# --- whether a panel publishes shared meters structurally ---------------------
+
+
+def test_a_panel_whose_circuits_declare_a_shared_meter_publishes_shared_meters() -> None:
+    assert _snapshot(*shared_pair("c-1", "c-2")).publishes_shared_meters is True
+
+
+def test_a_declared_list_with_no_value_still_marks_the_panel() -> None:
+    """The declaration decides: a standard breaker declares the list and publishes no value."""
+    first, second = shared_pair("c-1", "c-2")
+    snapshot = _snapshot(
+        without_values(first, "meter/shared-with-device-ids"),
+        without_values(second, "meter/shared-with-device-ids"),
+    )
+
+    assert snapshot.publishes_shared_meters is True
+
+
+def test_a_list_naming_no_known_circuit_still_marks_the_panel() -> None:
+    assert _snapshot(hosted_circuit("c-1", (1,), meter_shared_with=("ghost",))).publishes_shared_meters is True
+
+
+def test_only_the_meter_list_counts() -> None:
+    """A relay shared with nothing on the meter says nothing about how the meters are described."""
+    snapshot = _snapshot(hosted_circuit("c-1", (1,), relay_shared_with=("c-2",)), hosted_circuit("c-2", (3,)))
+
+    assert snapshot.publishes_shared_meters is False
+
+
+def test_a_panel_with_no_circuit_declaring_the_list_does_not() -> None:
+    assert _snapshot(hosted_circuit("c-1", (1,)), hosted_circuit("c-2", (3,))).publishes_shared_meters is False
+
+
+def test_main_32_and_the_flat_schema_do_not() -> None:
+    reference = replay(parent_child_tree(), _REFERENCE_PANEL).build_snapshot()
+    flat = SchemaZeroAdapter(serial_number="sim-40t-001", schema=flat_schema(40)).build_snapshot()
+
+    assert reference.publishes_shared_meters is False
+    assert flat.publishes_shared_meters is False

{span_panel_api-3.8.0b2 → span_panel_api-3.9.0b1}/tests/test_shared_meters_captures.py

@@ -50,6 +50,16 @@ def test_the_captures_hold_shared_meters() -> None:
     assert any(shared_meter_groups(capture_snapshot(stem).circuits) for stem in CAPTURES)
 
 
+@pytest.mark.parametrize("stem", CAPTURES)
+def test_shared_meters_are_published_exactly_where_a_circuit_declares_the_list(stem: str) -> None:
+    """Every one of these models declares the list, on standard breakers too, whether or not any group exists."""
+    tree = capture_tree(stem)
+    declared = any(tree.declares(circuit_id, _SHARED_WITH[0]) for circuit_id in tree.circuits())
+
+    assert declared
+    assert capture_snapshot(stem).publishes_shared_meters is declared
+
+
 @pytest.mark.parametrize("stem", CAPTURES)
 def test_shared_with_is_neither_discovered_nor_an_extension_reading(stem: str) -> None:
     adapter = capture_adapter(stem)