span-panel-api 3.6.0__tar.gz → 3.6.1__tar.gz

{span_panel_api-3.6.0 → span_panel_api-3.6.1}/CHANGELOG.md

@@ -7,13 +7,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 Pre-releases are not listed separately. A beta is a step towards the next public version, so its changes are folded into that version's entry as they land and are described against the **last public release**, never against the beta before it. What one
 beta corrected in an earlier beta does not appear at all: from the point of view of somebody upgrading between released versions, it never happened.
 
-## [3.6.0]
+## [3.6.1]
 
 The snapshot carries every PV inverter a panel commissions, and registration copes with a panel that cannot read its own passphrase.
 
 ### Added
 
-- **`SpanPanelSnapshot.pv_inverters`** carries every commissioned PV inverter, keyed by its feeding circuit's id, which stays put when firmware r202639 renames a panel's inverters, or by its device id where no circuit feeds it.
+- **`SpanPanelSnapshot.pv_inverters`** carries every commissioned PV inverter, keyed by its feeding circuit's id, which stays put when firmware r202639 changes a panel's PV device ids, or by its device id where no circuit feeds it.
 - **`SpanPVSnapshot.serial_number`, `device_id` and `node_id`** give an inverter's serial number when one is published, its id on the wire, and its key in `pv_inverters`.
 - **`SpanEvseSnapshot.effective_charge_current_limit_a`** is the charge-current limit a charger is applying, its user limit when one is published and its ceiling otherwise, since from firmware r202639 a SPAN Drive publishes a user limit only once someone
   sets one.
@@ -21,10 +21,16 @@ The snapshot carries every PV inverter a panel commissions, and registration cop
 
 ### Changed
 
+- **`SpanPanelSnapshot.pv` describes the inverters together when more than one is commissioned**, carrying only their shared vendor and model, the sum of their installed DC sizes and a link that is down if any is down, rather than whichever one the adapter
+  met first.
+- **`SpanPVSnapshot.nameplate_capacity_w` is documented as the array's DC size recorded at installation**, an informational figure and never a ceiling on PV power.
 - **`V2AuthResponse.ebus_broker_password` and `hop_passphrase` are `str | None`**, `None` when a panel on firmware r202639 or later cannot read its passphrase yet still issues a valid access token.
 - **`register_v2` raises `SpanPanelServerError` with `status_code` for any 5xx**, including the 503 a panel on firmware r202639 answers until it knows its serial number, where it raised a plain `SpanPanelAPIError`.
-- **`SpanPanelSnapshot.pv` is the inverter on the lowest breaker space when more than one is commissioned**, rather than whichever one the adapter met first.
-- **`SpanPVSnapshot.nameplate_capacity_w` is documented as the array's DC size recorded at installation**, an informational figure and never a ceiling on PV power.
+- **The `schema-0` and `schema-1` extras require `span-panel-api-schema-0` 1.2.0 and `span-panel-api-schema-1` 1.2.1 or newer**, the adapters that fill `pv_inverters`.
+
+## [3.6.0] [YANKED]
+
+Withdrawn from PyPI; 3.6.1 replaces it.
 
 ## [3.5.0]
 

{span_panel_api-3.6.0 → span_panel_api-3.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: span-panel-api
-Version: 3.6.0
+Version: 3.6.1
 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
@@ -22,7 +22,7 @@ Requires-Dist: pyyaml>=6.0.0
 Provides-Extra: schema-0
 Requires-Dist: span-panel-api-schema-0>=1.2.0; extra == 'schema-0'
 Provides-Extra: schema-1
-Requires-Dist: span-panel-api-schema-1>=1.2.0; extra == 'schema-1'
+Requires-Dist: span-panel-api-schema-1>=1.2.1; extra == 'schema-1'
 Description-Content-Type: text/markdown
 
 # SPAN Panel API
@@ -175,21 +175,25 @@ transport-specific classes.
 
 All panel state is represented as immutable, frozen dataclasses:
 
-| Dataclass             | Content                                                                                                                                                            |
-| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `SpanPanelSnapshot`   | Complete panel state: power, energy, grid/DSM state, hardware status, per-leg voltages, power flows, lugs current, shed forecast, circuits, battery, PV, EVSE, MID |
-| `SpanCircuitSnapshot` | Per-circuit: power, energy, relay state, priority, tabs, device type, breaker rating, current, `$target` pending state                                             |
-| `SpanBatterySnapshot` | BESS: SoC percentage, SoE kWh, own meter reading, communication state, link health, `model` / `part_number`, nameplate capacity                                    |
-| `SpanPVSnapshot`      | PV inverter: link health, `model` / `part_number`, nameplate capacity                                                                                              |
-| `SpanEvseSnapshot`    | EVSE (EV charger): status, lock state, advertised current, link health, `model` / `part_number` / serial / version metadata                                        |
-| `SpanMidSnapshot`     | Microgrid Interconnect Device: islanding state, grid state, grid-forming entity                                                                                    |
-| `AdoptedDevice`       | A device type this library models nothing for, carried whole: identity, readings, proxy link                                                                       |
-| `ExtensionProperty`   | A vendor property on a device this library _does_ model, with its value and the subject it hangs off                                                               |
-
-Identity is normalised across every DER class: **`model` is the human designation and `part_number` is the SKU**, on `battery`, `evse` and `pv` alike. `product_name` was retired in 3.0.0 — see the changelog, because `battery.model` changes value for
-existing flat users at that upgrade.
-
-`mid`, `adopted_devices`, `extension_properties` and the per-DER link-health fields exist only under the parent/child schema. They are `None` or empty on a flat panel rather than absent, so a consumer reads the same snapshot type either way.
+- **`SpanPanelSnapshot`**: complete panel state. Identity (serial, firmware, vendor, model, hardware version), panel size, main breaker rating, main relay, door and proximity state, uptime, network links with the Wi-Fi SSID and vendor cloud, grid and
+  feedthrough power and energy, grid/DSM state, run configuration, dominant power source, grid islandability, per-leg voltages, power flows, lugs current and whether the lugs are the service entrance, shed policy and forecast. It holds `circuits`,
+  `battery`, `pv`, `pv_inverters`, `evse`, `mid`, `pcs`, `adopted_devices` and `extension_properties`.
+- **`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.
+- **`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.
+- **`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.
+- **`ExtensionProperty`**: a vendor property on a device this library _does_ model. The subject it hangs off, its node and property ids and its `path`, datatype / unit / format, settability, value, and whether its node has curated siblings.
+
+Identity is normalised across every DER class: **`model` is the human designation**, on `battery`, `evse` and `pv` alike, and **`part_number` is the SKU**, on `battery` and `evse`; `SpanPVSnapshot` has no SKU field. `product_name` was retired in 3.0.0 —
+see the changelog, because `battery.model` changes value for existing flat users at that upgrade.
+
+`mid`, `pcs`, `adopted_devices`, `extension_properties` and the per-DER link-health fields exist only under the parent/child schema. They are `None` or empty on a flat panel rather than absent, so a consumer reads the same snapshot type either way.
 
 ## Usage
 
@@ -611,7 +615,7 @@ src/span_panel_api/          # distribution: span-panel-api (no parser)
 ├── dispatch.py              # select_adapter_key() — what does this panel need?
 ├── exceptions.py            # Exception hierarchy
 ├── factory.py               # create_span_client() → SpanMqttClient
-├── models.py                # Snapshot dataclasses (panel, circuit, battery, PV, EVSE, MID, adopted)
+├── models.py                # Snapshot dataclasses (panel, circuit, battery, PV, EVSE, MID, PCS, adopted, extension)
 ├── phase_validation.py      # Electrical phase utilities
 ├── protocol.py              # PEP 544 protocols, SchemaAdapter, PanelCapability flags
 ├── schema_drift.py          # Reporting a panel that outruns what we can read

{span_panel_api-3.6.0 → span_panel_api-3.6.1}/README.md

@@ -148,21 +148,25 @@ transport-specific classes.
 
 All panel state is represented as immutable, frozen dataclasses:
 
-| Dataclass             | Content                                                                                                                                                            |
-| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `SpanPanelSnapshot`   | Complete panel state: power, energy, grid/DSM state, hardware status, per-leg voltages, power flows, lugs current, shed forecast, circuits, battery, PV, EVSE, MID |
-| `SpanCircuitSnapshot` | Per-circuit: power, energy, relay state, priority, tabs, device type, breaker rating, current, `$target` pending state                                             |
-| `SpanBatterySnapshot` | BESS: SoC percentage, SoE kWh, own meter reading, communication state, link health, `model` / `part_number`, nameplate capacity                                    |
-| `SpanPVSnapshot`      | PV inverter: link health, `model` / `part_number`, nameplate capacity                                                                                              |
-| `SpanEvseSnapshot`    | EVSE (EV charger): status, lock state, advertised current, link health, `model` / `part_number` / serial / version metadata                                        |
-| `SpanMidSnapshot`     | Microgrid Interconnect Device: islanding state, grid state, grid-forming entity                                                                                    |
-| `AdoptedDevice`       | A device type this library models nothing for, carried whole: identity, readings, proxy link                                                                       |
-| `ExtensionProperty`   | A vendor property on a device this library _does_ model, with its value and the subject it hangs off                                                               |
-
-Identity is normalised across every DER class: **`model` is the human designation and `part_number` is the SKU**, on `battery`, `evse` and `pv` alike. `product_name` was retired in 3.0.0 — see the changelog, because `battery.model` changes value for
-existing flat users at that upgrade.
-
-`mid`, `adopted_devices`, `extension_properties` and the per-DER link-health fields exist only under the parent/child schema. They are `None` or empty on a flat panel rather than absent, so a consumer reads the same snapshot type either way.
+- **`SpanPanelSnapshot`**: complete panel state. Identity (serial, firmware, vendor, model, hardware version), panel size, main breaker rating, main relay, door and proximity state, uptime, network links with the Wi-Fi SSID and vendor cloud, grid and
+  feedthrough power and energy, grid/DSM state, run configuration, dominant power source, grid islandability, per-leg voltages, power flows, lugs current and whether the lugs are the service entrance, shed policy and forecast. It holds `circuits`,
+  `battery`, `pv`, `pv_inverters`, `evse`, `mid`, `pcs`, `adopted_devices` and `extension_properties`.
+- **`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.
+- **`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.
+- **`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.
+- **`ExtensionProperty`**: a vendor property on a device this library _does_ model. The subject it hangs off, its node and property ids and its `path`, datatype / unit / format, settability, value, and whether its node has curated siblings.
+
+Identity is normalised across every DER class: **`model` is the human designation**, on `battery`, `evse` and `pv` alike, and **`part_number` is the SKU**, on `battery` and `evse`; `SpanPVSnapshot` has no SKU field. `product_name` was retired in 3.0.0 —
+see the changelog, because `battery.model` changes value for existing flat users at that upgrade.
+
+`mid`, `pcs`, `adopted_devices`, `extension_properties` and the per-DER link-health fields exist only under the parent/child schema. They are `None` or empty on a flat panel rather than absent, so a consumer reads the same snapshot type either way.
 
 ## Usage
 
@@ -584,7 +588,7 @@ src/span_panel_api/          # distribution: span-panel-api (no parser)
 ├── dispatch.py              # select_adapter_key() — what does this panel need?
 ├── exceptions.py            # Exception hierarchy
 ├── factory.py               # create_span_client() → SpanMqttClient
-├── models.py                # Snapshot dataclasses (panel, circuit, battery, PV, EVSE, MID, adopted)
+├── models.py                # Snapshot dataclasses (panel, circuit, battery, PV, EVSE, MID, PCS, adopted, extension)
 ├── phase_validation.py      # Electrical phase utilities
 ├── protocol.py              # PEP 544 protocols, SchemaAdapter, PanelCapability flags
 ├── schema_drift.py          # Reporting a panel that outruns what we can read

{span_panel_api-3.6.0 → span_panel_api-3.6.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "span-panel-api"
-version = "3.6.0"
+version = "3.6.1"
 description = "A client library for SPAN Panel API"
 authors = [
     {name = "SpanPanel"}
@@ -63,7 +63,8 @@ dependencies = [
 # the inverter identity fields 3.6.0 adds. Upgrading through the extra is what
 # brings the adapters that do.
 schema-0 = ["span-panel-api-schema-0>=1.2.0"]
-schema-1 = ["span-panel-api-schema-1>=1.2.0"]
+# Raised to 1.2.1 for 3.6.1: that adapter builds the `pv` that `SpanPanelSnapshot.pv` now documents.
+schema-1 = ["span-panel-api-schema-1>=1.2.1"]
 
 [project.urls]
 Homepage = "https://github.com/SpanPanel/span-panel-api"

{span_panel_api-3.6.0 → span_panel_api-3.6.1}/src/span_panel_api/__init__.py

@@ -211,7 +211,7 @@ __all__ = [  # noqa: RUF022
     # Added 2026-10-02 (3.5.0): a 403 from a reduced-privilege token. A subclass
     # of SpanPanelAuthError, so every existing except clause keeps its meaning.
     "SpanPanelInsufficientPrivilegeError",
-    # Added 2026-10-06 (3.6.0): registration reached a panel that cannot read its own
+    # Added 2026-10-06 (3.6.1): registration reached a panel that cannot read its own
     # passphrase. A subclass of SpanPanelAPIError, so existing except clauses
     # keep their meaning; deliberately not a SpanPanelAuthError, because the
     # passphrase the user supplied may be correct.

{span_panel_api-3.6.0 → span_panel_api-3.6.1}/src/span_panel_api/models.py

@@ -78,7 +78,8 @@ class SpanPVSnapshot:
 
     A panel may commission more than one inverter, and from firmware r202639 each
     is published as its own device. `SpanPanelSnapshot.pv_inverters` carries all
-    of them; `SpanPanelSnapshot.pv` carries one, chosen as that field documents.
+    of them; `SpanPanelSnapshot.pv` is the lone inverter, or describes several
+    together, as that field documents.
     """
 
     vendor_name: str | None = None  # pv/vendor-name
@@ -117,6 +118,10 @@ class SpanPVSnapshot:
     it does not know) and is deliberately distinct from `False`. The enum has
     three members, `OK,LOST,DEGRADED`, and no UNKNOWN, so absence is the only
     way to say it.
+
+    On a `pv` that describes several inverters together, `None` also means no
+    link is reported down and not every one is reported up, so it is never
+    `True` while any inverter's link is unreported; see `SpanPanelSnapshot.pv`.
     """
 
     serial_number: str | None = None
@@ -141,7 +146,8 @@ class SpanPVSnapshot:
     Named after `SpanEvseSnapshot.node_id`, which plays the same role for
     chargers. It is the feeding circuit's id when a circuit feeds the inverter,
     because that id stays put when the inverter's own device id changes, and
-    `device_id` otherwise.
+    `device_id` otherwise. `None` also on a `pv` that describes several
+    inverters together.
     """
 
 
@@ -1182,13 +1188,13 @@ class SpanPanelSnapshot:
     circuits: dict[str, SpanCircuitSnapshot] = field(default_factory=dict)
     battery: SpanBatterySnapshot = field(default_factory=SpanBatterySnapshot)
     pv: SpanPVSnapshot = field(default_factory=SpanPVSnapshot)
-    """One PV inverter, or the empty snapshot when none is commissioned.
+    """The lone PV inverter, or the inverters together; the empty snapshot when none is commissioned.
 
-    With a single inverter it is that inverter. With several it is the one whose
-    feeding circuit occupies the lowest breaker space; an inverter with no
-    feeding circuit ranks after every circuit-fed one, and remaining ties go to
-    the lowest device id. Kept for consumers written before `pv_inverters`,
-    which carries every inverter, this one included.
+    With one inverter it is that inverter, identical to its `pv_inverters` entry. With several it describes them together
+    and identifies none of them: vendor and model where every inverter shares one, the sum of their installed DC sizes where
+    every inverter publishes one, and their link down if any is reported down, up if every one is reported up, unknown
+    otherwise. It never carries an inverter's device id, key, serial, firmware, feeding circuit or position. A consumer that
+    needs one inverter reads `pv_inverters`.
     """
     pv_inverters: dict[str, SpanPVSnapshot] = field(default_factory=dict)
     """Every commissioned PV inverter, keyed by `SpanPVSnapshot.node_id`.

{span_panel_api-3.6.0 → span_panel_api-3.6.1}/tests/test_public_api_unchanged.py

@@ -161,7 +161,7 @@ EXPECTED_PUBLIC_API = {
     # Added 2026-10-02 (3.5.0): a 403 from a reduced-privilege token. A subclass
     # of SpanPanelAuthError, so every existing except clause keeps its meaning.
     "SpanPanelInsufficientPrivilegeError",
-    # Added 2026-10-06 (3.6.0): registration reached a panel that cannot read its own
+    # Added 2026-10-06 (3.6.1): registration reached a panel that cannot read its own
     # passphrase. Additive, and a SpanPanelAPIError subclass rather than a
     # SpanPanelAuthError, so no existing except clause starts telling a user
     # their passphrase is wrong.

{span_panel_api-3.6.0 → span_panel_api-3.6.1}/tests/test_schema_one_snapshot.py

@@ -40,7 +40,6 @@ def test_roles_are_sorted_by_declared_type_not_device_id() -> None:
     assert len(roles.lugs) == 2
     assert len(roles.evse) == 2
     assert roles.bess is not None and roles.bess.device_id == "bess"
-    assert roles.pv is not None and roles.pv.device_id == "pv"
     assert [device.device_id for device in roles.pvs] == ["pv"]
     assert roles.mid is not None and roles.mid.device_id == "bess-mid"
 
@@ -161,9 +160,9 @@ def _multi_inverter_children() -> list[DiscoveredDevice]:
     """The capture with three inverters: two fed by a circuit each, one fed by none.
 
     The second inverter's circuit sits on lower breaker spaces than the captured
-    solar circuit, so the rule choosing `snapshot.pv` has a reason to pick it.
-    Only the second inverter publishes a serial; the others leave it unpublished,
-    which is the common case.
+    solar circuit, which once made the library rank it first; nothing ranks
+    inverters now. Only the second inverter publishes a serial; the others leave
+    it unpublished, which is the common case.
     """
     tree = {device_id: dict(topics) for device_id, topics in _TREE.items()}
     pv_topics = tree.pop("pv")
@@ -195,7 +194,7 @@ def test_every_inverter_is_a_snapshot_keyed_by_its_feeding_circuit_or_its_device
 
 
 def test_every_inverters_feeding_circuit_is_labeled_pv() -> None:
-    """Not only the one `snapshot.pv` describes: an unlabeled PV circuit reads as a load."""
+    """Every inverter's circuit, however many are commissioned: an unlabeled PV circuit reads as a load."""
     snapshot = build_snapshot(_device(PANEL), _multi_inverter_children())
 
     assert {cid for cid, c in snapshot.circuits.items() if c.device_type == "pv"} == {SOLAR_CIRCUIT, SECOND_SOLAR_CIRCUIT}
@@ -235,34 +234,88 @@ def test_every_circuit_feeding_an_inverter_is_labeled_pv_whatever_the_order() ->
         assert snapshot.pv_inverters[SOLAR_CIRCUIT].device_id == FIRST_PV
 
 
-def test_the_primary_inverter_is_chosen_by_breaker_space_not_by_tree_order() -> None:
+def test_with_several_inverters_pv_describes_them_together() -> None:
+    """No inverter is primary: `pv` identifies none of them, whatever the tree order."""
     children = _multi_inverter_children()
     forward = build_snapshot(_device(PANEL), children)
     backward = build_snapshot(_device(PANEL), list(reversed(children)))
 
-    assert forward.pv.device_id == SECOND_PV
-    assert backward.pv == forward.pv
-    assert forward.pv == forward.pv_inverters[SECOND_SOLAR_CIRCUIT]
+    assert forward.pv == backward.pv
+    assert forward.pv.device_id is None
+    assert forward.pv.node_id is None
+    assert forward.pv.feed_circuit_id is None
+    assert forward.pv.serial_number is None
+    assert forward.pv.software_version is None
+    assert forward.pv.relative_position is None
+    assert forward.pv.vendor_name == forward.pv_inverters[SOLAR_CIRCUIT].vendor_name
+    assert forward.pv.model == forward.pv_inverters[SOLAR_CIRCUIT].model
+    assert forward.pv.nameplate_capacity_w == 24000.0
+    # Two links reported up and one unreported: not known to be all up, not known down.
+    assert forward.pv.connected is None
+
+
+def test_one_link_down_is_the_link_down() -> None:
+    """Three-valued: a link known down decides, whatever the others say.
+
+    The lost link is the first inverter's, on the higher breaker spaces, so the
+    removed lowest-space rule, which described the second inverter, read it up.
+    """
+    lost = device_from_topics(
+        SOLAR_CIRCUIT,
+        {**_TREE[SOLAR_CIRCUIT], "connection/feeds-device-id": FIRST_PV, "connection/feeds-device-status": "LOST"},
+    )
+    children = [lost if device.device_id == SOLAR_CIRCUIT else device for device in _multi_inverter_children()]
 
+    assert build_snapshot(_device(PANEL), children).pv.connected is False
 
-def test_an_inverter_without_a_feeding_circuit_is_primary_only_when_alone() -> None:
-    lone = [device for device in _multi_inverter_children() if device.device_id not in (FIRST_PV, SECOND_PV)]
 
-    snapshot = build_snapshot(_device(PANEL), lone)
+def test_every_link_up_is_the_link_up() -> None:
+    fed = [device for device in _multi_inverter_children() if device.device_id != UNFED_PV]
+
+    assert build_snapshot(_device(PANEL), fed).pv.connected is True
+
+
+def test_one_unpublished_nameplate_leaves_the_sum_unknown() -> None:
+    unsized = {topic: value for topic, value in _TREE["pv"].items() if topic != "info/nominal-power"}
+    children = [
+        device_from_topics(SECOND_PV, unsized) if device.device_id == SECOND_PV else device
+        for device in _multi_inverter_children()
+    ]
+
+    assert build_snapshot(_device(PANEL), children).pv.nameplate_capacity_w is None
+
+
+def test_a_vendor_not_shared_is_unknown() -> None:
+    children = [
+        (
+            device_from_topics(SECOND_PV, {**_TREE["pv"], "info/vendor-name": "SolarEdge"})
+            if device.device_id == SECOND_PV
+            else device
+        )
+        for device in _multi_inverter_children()
+    ]
 
-    assert snapshot.pv.device_id == UNFED_PV
-    assert set(snapshot.pv_inverters) == {UNFED_PV}
+    assert build_snapshot(_device(PANEL), children).pv.vendor_name is None
 
 
-def test_unfed_inverters_fall_back_to_the_lowest_device_id() -> None:
-    first = [device for device in _children() if device.device_id != "pv"]
-    pv_topics = _TREE["pv"]
-    unfed = [device_from_topics(device_id, pv_topics) for device_id in ("pv-b", "pv-a")]
+def test_what_several_inverters_do_not_share_is_unknown() -> None:
+    children = [
+        device_from_topics(SECOND_PV, {**_TREE["pv"], "info/model": "SE7600H"}) if device.device_id == SECOND_PV else device
+        for device in _multi_inverter_children()
+    ]
 
-    primary = TreeRoles([*first, *unfed]).pv
+    snapshot = build_snapshot(_device(PANEL), children)
+
+    assert snapshot.pv.model is None
+    assert snapshot.pv.vendor_name == snapshot.pv_inverters[SOLAR_CIRCUIT].vendor_name
+
+
+def test_a_lone_inverter_is_pv_whatever_feeds_it() -> None:
+    lone = [device for device in _multi_inverter_children() if device.device_id not in (FIRST_PV, SECOND_PV)]
+
+    snapshot = build_snapshot(_device(PANEL), lone)
 
-    assert primary is not None
-    assert primary.device_id == "pv-a"
+    assert snapshot.pv == snapshot.pv_inverters[UNFED_PV]
 
 
 def test_the_serial_is_carried_where_published_and_absent_otherwise() -> None:

span_panel_api-3.6.1/tests/test_schema_one_undeclared_devices.py

@@ -0,0 +1,166 @@
+"""A device the panel no longer declares is not part of the panel, whatever it left behind.
+
+Firmware r202639 renames a panel's inverters once it publishes more than one: the
+single inverter's `<panel>-se7600h-us` becomes `<panel>-se7600h-us-<n>`, one per
+inverter. The upgrade does not clear the old device's retained topics, so the
+broker keeps replaying a `$description` that still names the panel as its root
+and parent, beside the new devices, until something removes it.
+
+Membership comes from the parent's `$description.children` alone. The SDK
+subscribes to a child only once its parent declares it (and drops one the parent
+stops declaring), and `ControllerRoutes` holds a message no route has asked for
+rather than delivering it. A stale device's own claim to a parent is never read.
+These tests pin that through the adapter's real `handle_message` path, so an
+`ebus-sdk` upgrade that changed how the tree is walked would fail here rather than
+surface as a ghost inverter.
+"""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from reference_payloads.schema_one import RetainedTopicTree, parent_child_tree
+from span_panel_api.models import V2HomieSchema
+from span_panel_api_schema_1 import SchemaOneAdapter
+
+PANEL = "example-40t-001"
+SOLAR_CIRCUIT = "573066aaddd7b75114c4563ce3af18c4"
+SECOND_SOLAR_CIRCUIT = "5be1d2c3a4f5061728394a5b6c7d8e9f"
+
+# Illustrative ids in the shape firmware r202639 uses.
+STALE_PV = f"{PANEL}-se7600h-us"
+FIRST_PV = f"{PANEL}-se7600h-us-1"
+SECOND_PV = f"{PANEL}-se7600h-us-2"
+STALE_MODEL = "SE7600H-STALE"
+
+
+def _schema() -> V2HomieSchema:
+    return V2HomieSchema(
+        firmware_version="spanos2/r202639/01",
+        types_schema_hash="sha256:test",
+        types={},
+        data_model_version="1.0",
+    )
+
+
+def _with_children(tree: dict[str, dict[str, str]], children: list[str]) -> None:
+    description = json.loads(tree[PANEL]["$description"])
+    description["children"] = children
+    tree[PANEL] = {**tree[PANEL], "$description": json.dumps(description)}
+
+
+def _upgraded_tree(stale_state: str | None) -> dict[str, dict[str, str]]:
+    """Two declared inverters, each fed by its own circuit; and, unless `stale_state` is None,
+    the old inverter's retained topics, which the panel no longer declares."""
+    tree = {device_id: dict(topics) for device_id, topics in parent_child_tree().items()}
+    pv = tree.pop("pv")
+    declared = [child for child in json.loads(tree[PANEL]["$description"])["children"] if child != "pv"]
+    _with_children(tree, [*declared, SECOND_SOLAR_CIRCUIT, FIRST_PV, SECOND_PV])
+    tree[FIRST_PV] = dict(pv)
+    tree[SECOND_PV] = {**pv, "info/model": "SE7600H-B"}
+    tree[SOLAR_CIRCUIT]["connection/feeds-device-id"] = FIRST_PV
+    tree[SECOND_SOLAR_CIRCUIT] = {
+        **tree[SOLAR_CIRCUIT],
+        "connection/feeds-device-id": SECOND_PV,
+        "info/name": "Garage Solar",
+        "info/spaces": "5,7",
+    }
+    if stale_state is not None:
+        tree[STALE_PV] = {**pv, "$state": stale_state, "info/model": STALE_MODEL}
+    return tree
+
+
+def _replay(adapter: SchemaOneAdapter, tree: RetainedTopicTree, order: list[str]) -> None:
+    """Deliver each device's retained topics as the broker would, in `order`."""
+    for device_id in order:
+        topics = tree[device_id]
+        prefix = f"ebus/5/{device_id}"
+        adapter.handle_message(f"{prefix}/$description", topics["$description"])
+        adapter.handle_message(f"{prefix}/$state", topics["$state"])
+        for topic, value in topics.items():
+            if not topic.startswith("$"):
+                adapter.handle_message(f"{prefix}/{topic}", value)
+
+
+def _without_stale() -> SchemaOneAdapter:
+    tree = _upgraded_tree(None)
+    adapter = SchemaOneAdapter(PANEL, _schema())
+    _replay(adapter, tree, [PANEL, *[device_id for device_id in tree if device_id != PANEL]])
+    return adapter
+
+
+def _assert_stale_pv_is_absent(adapter: SchemaOneAdapter) -> None:
+    """Nothing the adapter reports differs from a broker that never held the stale device."""
+    reference = _without_stale()
+    snapshot = adapter.build_snapshot()
+
+    assert adapter.is_ready()
+    assert snapshot == reference.build_snapshot()
+    assert adapter.build_field_metadata() == reference.build_field_metadata()
+    # Spelled out as well, so a failure names what leaked.
+    assert {key: inverter.device_id for key, inverter in snapshot.pv_inverters.items()} == {
+        SOLAR_CIRCUIT: FIRST_PV,
+        SECOND_SOLAR_CIRCUIT: SECOND_PV,
+    }
+    assert snapshot.pv.model is None
+    assert all(device.device_id != STALE_PV for device in snapshot.adopted_devices)
+
+
+@pytest.mark.parametrize("stale_state", ["ready", "init", "disconnected", "lost"])
+@pytest.mark.parametrize("stale_first", [True, False], ids=["stale-replayed-first", "stale-replayed-last"])
+def test_a_pv_device_the_panel_no_longer_declares_never_reaches_the_snapshot(stale_state: str, stale_first: bool) -> None:
+    """Whatever its retained `$state` -- `ready` included -- and whenever the broker replays it."""
+    tree = _upgraded_tree(stale_state)
+    others = [device_id for device_id in tree if device_id not in (PANEL, STALE_PV)]
+    adapter = SchemaOneAdapter(PANEL, _schema())
+
+    _replay(adapter, tree, [STALE_PV, PANEL, *others] if stale_first else [PANEL, *others, STALE_PV])
+
+    _assert_stale_pv_is_absent(adapter)
+
+
+def _before_the_upgrade() -> dict[str, dict[str, str]]:
+    """The panel before r202639: one inverter, declared, under the id the upgrade retires."""
+    tree = {device_id: dict(topics) for device_id, topics in parent_child_tree().items()}
+    tree[STALE_PV] = {**tree.pop("pv"), "info/model": STALE_MODEL}
+    declared = json.loads(tree[PANEL]["$description"])["children"]
+    _with_children(tree, [STALE_PV if child == "pv" else child for child in declared])
+    tree[SOLAR_CIRCUIT]["connection/feeds-device-id"] = STALE_PV
+    return tree
+
+
+def test_a_declared_pv_device_does_reach_the_snapshot() -> None:
+    """The control: the same device, declared, is read -- so the tests above can see a leak."""
+    tree = _before_the_upgrade()
+    adapter = SchemaOneAdapter(PANEL, _schema())
+
+    _replay(adapter, tree, [PANEL, *[device_id for device_id in tree if device_id != PANEL]])
+
+    snapshot = adapter.build_snapshot()
+    assert {key: inverter.device_id for key, inverter in snapshot.pv_inverters.items()} == {SOLAR_CIRCUIT: STALE_PV}
+    assert snapshot.pv.model == STALE_MODEL
+
+
+@pytest.mark.parametrize("republished", ["through-init", "while-ready"])
+def test_a_pv_device_the_panel_stops_declaring_mid_session_leaves_the_snapshot(republished: str) -> None:
+    """An adapter running across the upgrade drops the inverter the new `$description` no longer names.
+
+    The panel either passes through `init` before announcing its new tree, or
+    republishes its `$description` while staying `ready`; both must drop it.
+    """
+    before = _before_the_upgrade()
+    adapter = SchemaOneAdapter(PANEL, _schema())
+    _replay(adapter, before, [PANEL, *[device_id for device_id in before if device_id != PANEL]])
+    after = _upgraded_tree("ready")
+
+    if republished == "through-init":
+        adapter.handle_message(f"ebus/5/{PANEL}/$state", "init")
+    adapter.handle_message(f"ebus/5/{PANEL}/$description", after[PANEL]["$description"])
+    if republished == "through-init":
+        adapter.handle_message(f"ebus/5/{PANEL}/$state", "ready")
+    # Then everything else retained, the stale inverter included.
+    _replay(adapter, after, [device_id for device_id in after if device_id != PANEL])
+
+    _assert_stale_pv_is_absent(adapter)