span-panel-api-schema-1 1.2.0__tar.gz → 1.2.1__tar.gz

{span_panel_api_schema_1-1.2.0 → span_panel_api_schema_1-1.2.1}/CHANGELOG.md

@@ -9,26 +9,37 @@ number. A release here means this parser changed, never that the panel did.
 
 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.
 
-## [1.2.0]
+## [1.2.1]
 
-Every PV inverter a panel commissions is read, and the battery's power keeps its sign on firmware r202639. Requires `span-panel-api` **3.6.0 or newer**.
+Every PV inverter a panel commissions is read, and the battery's power keeps its sign on firmware r202639. Requires `span-panel-api` **3.6.1 or newer**.
+
+### Added
+
+- **Every PV inverter is read, not only the first**, each landing in `pv_inverters` with its serial number when published, its device id and its key.
+- **`pv.serial_number` is read from `info/serial-number`**, so that property no longer appears as a discovery row.
+- **`TreeRoles.pvs` and `devices.pv_inverter_key`** list every inverter and give an inverter's key.
+- **`span_panel_api_schema_1.firmware.release_build`** reads the six-digit release build number out of a firmware version string, or returns `None` when it has none.
+- **`build_battery` takes keyword-only `firmware_version` and `power_flow_battery`** to pick the BESS meter's wire frame, and `SchemaOneAdapter` a keyword-only `clock` for the wait on feeding circuits, and both behave as before without them.
+
+### Changed
+
+- **`pv` describes the inverters together when a panel commissions more than one**, with 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 came first in the device tree.
+
+### Removed
+
+- **`TreeRoles.pv`**, which held only the first inverter, replaced by `TreeRoles.pvs`.
 
 ### Fixed
 
-- **A second inverter's feeding circuit is labeled `device_type="pv"`**, so its power no longer reads as a load with the opposite sign.
-- **A PV inverter wired through two breakers now reports its power and link status consistently**, with both circuits labeled `pv` and its feed and link status read from the one with the lowest circuit id.
-- **`pv` is the inverter on the lowest breaker space when more than one is commissioned**, rather than whichever came first in the device tree.
+- **Every inverter's feeding circuit is labeled `device_type="pv"`**, so a second inverter's power no longer reads as a load with the opposite sign.
+- **A PV inverter or charger wired through two breakers reports its power and link status consistently**, with both circuits labeled for it and its feed and link status read from the one with the lowest circuit id.
 - **Each inverter's extension properties are filed under that inverter**, with its `pv_inverters` key as the `instance_key` when more than one is commissioned.
 - **The first snapshot waits briefly for the circuits that feed an inverter**, so an inverter's key and its circuit's label do not change just after connecting.
 - **`battery.power_w` is discharge-positive on firmware r202639 and later, from the first snapshot on**, where a charging battery read positive.
 
-### Added
+## [1.2.0] [YANKED]
 
-- **`span_panel_api_schema_1.firmware.release_build`** reads the six-digit release build number out of a firmware version string, or returns `None` when it has none.
-- **`build_battery` takes keyword-only `firmware_version` and `power_flow_battery`** to pick the BESS meter's wire frame, and behaves as before without them.
-- **Every PV inverter is read, not only the first**, each landing in `pv_inverters` with its serial number when published, its device id and its key.
-- **`TreeRoles.pvs` lists every inverter**, and `snapshot.primary_pv`, `devices.pv_inverter_key` and `circuits.circuit_tabs` choose the one `pv` describes, give an inverter's key, and read a circuit's breaker spaces.
-- **`pv.serial_number` is read from `info/serial-number`**, so that property no longer appears as a discovery row.
+Withdrawn from PyPI; 1.2.1 replaces it.
 
 ## [1.1.4]
 

{span_panel_api_schema_1-1.2.0 → span_panel_api_schema_1-1.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: span-panel-api-schema-1
-Version: 1.2.0
+Version: 1.2.1
 Summary: Parent/child schema (data-model-version 1.x) parser 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
@@ -8,7 +8,7 @@ Author: SpanPanel
 License-Expression: MIT
 Requires-Python: <4.0,>=3.14
 Requires-Dist: ebus-sdk<0.24,>=0.19.0
-Requires-Dist: span-panel-api<4.0,>=3.6.0
+Requires-Dist: span-panel-api<4.0,>=3.6.1
 Description-Content-Type: text/markdown
 
 # span-panel-api-schema-1

{span_panel_api_schema_1-1.2.0 → span_panel_api_schema_1-1.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "span-panel-api-schema-1"
-version = "1.2.0"
+version = "1.2.1"
 description = "Parent/child schema (data-model-version 1.x) parser for span-panel-api"
 authors = [
     {name = "SpanPanel"}
@@ -25,7 +25,8 @@ dependencies = [
     # and the inverter's `serial_number`, `device_id` and `node_id`, which this
     # parser fills. Against an earlier one, building a snapshot fails on those
     # arguments.
-    "span-panel-api>=3.6.0,<4.0",
+    # Raised to 3.6.1, whose SpanPanelSnapshot.pv documents what this parser builds.
+    "span-panel-api>=3.6.1,<4.0",
     # Only this distribution depends on the eBus SDK. The bootstrap and
     # schema-0 stay clean, so a flat-panel install never pulls it in — which is
     # what bounds the release coupling this dependency introduces to panels on

{span_panel_api_schema_1-1.2.0 → span_panel_api_schema_1-1.2.1}/src/span_panel_api_schema_1/circuits.py

@@ -116,7 +116,7 @@ def _optional_integer(device: DiscoveredDevice, node: str, prop: str) -> int | N
     return None if raw is None else int(raw)
 
 
-def circuit_tabs(device: DiscoveredDevice) -> list[int]:
+def _tabs(device: DiscoveredDevice) -> list[int]:
     """Breaker spaces from ``info/spaces``.
 
     v1.0 publishes the occupied spaces literally (``"36,38"``), where the flat
@@ -254,7 +254,7 @@ def build_circuit(
         # circuit's.
         produced_energy_wh=_number(device, NODE_METER, PROP_IMPORTED_ENERGY),
         consumed_energy_wh=_number(device, NODE_METER, PROP_EXPORTED_ENERGY),
-        tabs=circuit_tabs(device),
+        tabs=_tabs(device),
         priority=priority,
         # `always-on` is `not relay-controllable`, and the flat schema derived
         # user-controllability from `always-on` — so this is the same answer by

{span_panel_api_schema_1-1.2.0 → span_panel_api_schema_1-1.2.1}/src/span_panel_api_schema_1/snapshot.py

@@ -13,7 +13,7 @@ from typing import TYPE_CHECKING
 
 from span_panel_api.models import ExtensionSubject, SpanPanelSnapshot, SpanPVSnapshot
 from span_panel_api_schema_1.adoption import build_adopted_devices
-from span_panel_api_schema_1.circuits import build_circuit, circuit_tabs
+from span_panel_api_schema_1.circuits import build_circuit
 from span_panel_api_schema_1.const import (
     NODE_CONNECTION,
     NODE_INFO,
@@ -75,7 +75,8 @@ class TreeRoles:
         self.evse: list[DiscoveredDevice] = []
         self.bess: DiscoveredDevice | None = None
         # Every inverter, in tree order. From r202639 each commissioned inverter
-        # is its own device; earlier firmware published one.
+        # is its own device; earlier firmware published one. None of them is
+        # primary.
         self.pvs: list[DiscoveredDevice] = []
         self.mid: DiscoveredDevice | None = None
 
@@ -94,33 +95,37 @@ class TreeRoles:
             elif declared == TYPE_MID and self.mid is None:
                 self.mid = device
 
-        self.pv: DiscoveredDevice | None = primary_pv(self.pvs, self.circuits)
 
+def _pv_for(inverters: Sequence[SpanPVSnapshot]) -> SpanPVSnapshot:
+    """`SpanPanelSnapshot.pv`: the lone inverter, or the inverters together.
 
-def primary_pv(pvs: Sequence[DiscoveredDevice], circuits: Sequence[DiscoveredDevice]) -> DiscoveredDevice | None:
-    """The inverter ``snapshot.pv`` describes, chosen the same way on every build.
-
-    The order depends only on what the panel publishes, never on the order the
-    devices were discovered in:
-
-    1. an inverter whose feeding circuit publishes its breaker spaces, before
-       one with no feeding circuit (or a circuit that publishes none);
-    2. among those, the lowest breaker space the feeding circuit occupies;
-    3. then the lowest device id.
-
-    A single inverter is chosen whatever it publishes, so a panel with one
-    inverter reads exactly as it did before more than one could be published.
+    No inverter stands for the others. With several, `pv` identifies none of
+    them -- no device id, key, serial, firmware, feeding circuit or position --
+    and carries only what describes them together: the vendor and model where
+    every inverter shares one, the sum of their installed DC sizes where every
+    inverter publishes one, and their link as a three-valued AND (down if any
+    is reported down, up if every one is reported up, unknown otherwise).
+    Independent of order.
     """
-    if not pvs:
-        return None
-    feeds = feed_circuit_ids(list(circuits))
-    lowest_tab = {circuit.device_id: min(circuit_tabs(circuit), default=None) for circuit in circuits}
-
-    def rank(device: DiscoveredDevice) -> tuple[int, int, str]:
-        tab = lowest_tab.get(feeds.get(device.device_id, ""))
-        return (0, tab, device.device_id) if tab is not None else (1, 0, device.device_id)
-
-    return min(pvs, key=rank)
+    if not inverters:
+        return SpanPVSnapshot()
+    if len(inverters) == 1:
+        return inverters[0]
+    vendors = {inverter.vendor_name for inverter in inverters}
+    models = {inverter.model for inverter in inverters}
+    nameplates = [inverter.nameplate_capacity_w for inverter in inverters if inverter.nameplate_capacity_w is not None]
+    links = [inverter.connected for inverter in inverters]
+    connected: bool | None = None
+    if any(link is False for link in links):
+        connected = False
+    elif all(link is True for link in links):
+        connected = True
+    return SpanPVSnapshot(
+        vendor_name=vendors.pop() if len(vendors) == 1 else None,
+        model=models.pop() if len(models) == 1 else None,
+        nameplate_capacity_w=sum(nameplates) if len(nameplates) == len(inverters) else None,
+        connected=connected,
+    )
 
 
 def build_snapshot(panel: DiscoveredDevice, children: list[DiscoveredDevice], ready_since: float = 0.0) -> SpanPanelSnapshot:
@@ -138,10 +143,10 @@ def build_snapshot(panel: DiscoveredDevice, children: list[DiscoveredDevice], re
     # A DER's device type decides how its feeding circuit is labelled, so the
     # circuit inherits it — matching the flat adapter, where the same circuit
     # reports device_type "pv" rather than "circuit". Every inverter's circuit,
-    # not only the one `snapshot.pv` describes: a PV circuit left labeled
-    # "circuit" is read as a load, with its power in the opposite sign. Read
-    # from the circuit side rather than through `feeds`, which keeps one circuit
-    # per DER: every circuit of a DER fed by several carries its power.
+    # however many are commissioned: a PV circuit left labeled "circuit" is
+    # read as a load, with its power in the opposite sign. Read from the
+    # circuit side rather than through `feeds`, which keeps one circuit per
+    # DER: every circuit of a DER fed by several carries its power.
     kind_by_der = {device.device_id: "pv" for device in roles.pvs} | {device.device_id: "evse" for device in roles.evse}
     der_type_by_circuit = {
         circuit.device_id: kind
@@ -214,7 +219,7 @@ def build_snapshot(panel: DiscoveredDevice, children: list[DiscoveredDevice], re
             ("panel", panel),
             ("battery", roles.bess),
             ("mid", roles.mid),
-            *((("pv", roles.pv),) if len(roles.pvs) == 1 else ()),
+            *((("pv", roles.pvs[0]),) if len(roles.pvs) == 1 else ()),
         )
         if device is not None
     ]
@@ -297,7 +302,7 @@ def build_snapshot(panel: DiscoveredDevice, children: list[DiscoveredDevice], re
             firmware_version=fields.firmware_version,
             power_flow_battery=fields.power_flow_battery,
         ),
-        pv=pv_inverters[pv_inverter_key(roles.pv, feeds)] if roles.pv is not None else SpanPVSnapshot(),
+        pv=_pv_for(list(pv_inverters.values())),
         pv_inverters=pv_inverters,
         mid=build_mid(roles.mid, device_names),
         # Gated on the node being declared, not on any value: every limit this