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

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

@@ -7,7 +7,15 @@ 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.1b1]
+
+3.6.0 was withdrawn from PyPI; this release carries its changes, listed under 3.6.0 below, except how `pv` is chosen, which this release replaces.
+
+### Changed
+
+- **`SpanPanelSnapshot.pv` is documented as the lone inverter or the inverters together**, and the `schema-1` extra requires `span-panel-api-schema-1` 1.2.1 or newer.
+
+## [3.6.0] [YANKED]
 
 The snapshot carries every PV inverter a panel commissions, and registration copes with a panel that cannot read its own passphrase.
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: span-panel-api
-Version: 3.6.0
+Version: 3.6.1b1
 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.1b1; 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.1b1}/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.1b1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "span-panel-api"
-version = "3.6.0"
+version = "3.6.1b1"
 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.1b1 for 3.6.1b1: that adapter stops ranking one inverter as pv.
+schema-1 = ["span-panel-api-schema-1>=1.2.1b1"]
 
 [project.urls]
 Homepage = "https://github.com/SpanPanel/span-panel-api"

{span_panel_api-3.6.0 → span_panel_api-3.6.1b1}/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.1b1}/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: