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

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

@@ -9,6 +9,38 @@ 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.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.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
+
+- **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.
+
+## [1.2.0] [YANKED]
+
+Withdrawn from PyPI; 1.2.1 replaces it.
+
 ## [1.1.4]
 
 The parser reports the islanding state the panel is acting on, and refuses islanding writes the panel would ignore. Reported and fixed by [@dcj](https://github.com/dcj) in [#179](https://github.com/SpanPanel/span-panel-api/pull/179), from issue

{span_panel_api_schema_1-1.1.4 → 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.1.4
+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.1.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.1.4 → span_panel_api_schema_1-1.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "span-panel-api-schema-1"
-version = "1.1.4"
+version = "1.2.1"
 description = "Parent/child schema (data-model-version 1.x) parser for span-panel-api"
 authors = [
     {name = "SpanPanel"}
@@ -21,7 +21,12 @@ dependencies = [
     # bootstrap defining everything this parser imports. 3.1.0 adds `ControlTarget`
     # and replaces the `set_*_topic` members with `set_*_target`, so this wheel is
     # rejected at discovery by any 3.0.x.
-    "span-panel-api>=3.1.0,<4.0",
+    # Raised to 3.6.0, the first bootstrap whose snapshot carries `pv_inverters`
+    # 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.
+    # 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.1.4 → span_panel_api_schema_1-1.2.1}/src/span_panel_api_schema_1/adapter.py

@@ -18,7 +18,8 @@ tree, and the SDK repopulates — so there is no resync hook to wire or forget.
 from __future__ import annotations
 
 import logging
-from typing import TYPE_CHECKING
+import time
+from typing import TYPE_CHECKING, Final
 
 from ebus_sdk import Controller
 
@@ -28,11 +29,15 @@ from span_panel_api_schema_1.circuits import priority_is_settable, relay_is_sett
 from span_panel_api_schema_1.const import (
     HOMIE_DOMAIN,
     HOMIE_VERSION,
+    NODE_CONNECTION,
     NODE_INFO,
     NODE_LOAD_SHED,
     NODE_SHED,
     NODE_SWITCH,
     PROP_ASSERTED_ISLANDING_STATE,
+    PROP_FED_BY_DEVICE_ID,
+    PROP_FEEDS_DEVICE_ID,
+    PROP_FIRMWARE_VERSION,
     PROP_MODEL,
     PROP_NAME,
     PROP_PRIORITY,
@@ -41,8 +46,9 @@ from span_panel_api_schema_1.const import (
     TYPE_CIRCUIT,
 )
 from span_panel_api_schema_1.description import declared_settable, device_type, node_properties
+from span_panel_api_schema_1.devices import feed_circuit_ids
 from span_panel_api_schema_1.field_metadata import build_field_metadata
-from span_panel_api_schema_1.panel import integer
+from span_panel_api_schema_1.panel import integer, text
 from span_panel_api_schema_1.snapshot import TreeRoles, build_snapshot, harmonised_evse_keys
 from span_panel_api_schema_1.transport import ControllerRoutes
 
@@ -55,6 +61,33 @@ if TYPE_CHECKING:
 
 _LOGGER = logging.getLogger(__name__)
 
+FEED_GRACE_S: Final = 2.0
+"""How long an inverter's feed may stay unvalued once everything else has arrived.
+
+A retained `connection/feeds-device-id` lands in the same burst as its circuit's
+name. One still missing this long after the rest of the tree's labels is taken
+as absent: a DER may be published with no connection record at all.
+"""
+
+
+def _unvalued_feeds_for_unplaced_pvs(roles: TreeRoles) -> list[str]:
+    """Circuits whose feed has not arrived, while an inverter has no known source.
+
+    Empty when every inverter is placed, by a circuit's
+    `connection/feeds-device-id` or a lugs device's `connection/fed-by-device-id`:
+    no value still to arrive can then change any inverter's key.
+    """
+    placed = set(feed_circuit_ids(roles.circuits))
+    placed.update(text(lugs, NODE_CONNECTION, PROP_FED_BY_DEVICE_ID) for lugs in roles.lugs)
+    if all(pv.device_id in placed for pv in roles.pvs):
+        return []
+    return [
+        circuit.device_id
+        for circuit in roles.circuits
+        if PROP_FEEDS_DEVICE_ID in circuit.get_node_properties(NODE_CONNECTION)
+        and circuit.get_property(NODE_CONNECTION, PROP_FEEDS_DEVICE_ID) is None
+    ]
+
 
 class SchemaOneAdapter:
     """Parser for the parent/child schema (data-model-version 1.x)."""
@@ -67,9 +100,18 @@ class SchemaOneAdapter:
     schema_major = "schema_1"
     SUPPORTS_DATA_MODEL_VERSIONS: tuple[str, str] = (">=1.0", "<2.0")
 
-    def __init__(self, serial_number: str, schema: V2HomieSchema) -> None:
+    def __init__(
+        self,
+        serial_number: str,
+        schema: V2HomieSchema,
+        *,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
         self._serial_number = serial_number
         self._schema = schema
+        self._clock = clock
+        self._feed_wait_since: float | None = None
+        self._feed_wait_reported = False
         self._routes = ControllerRoutes()
         self._controller = Controller(root_device_id=serial_number, mqttc=self._routes)
         self._property_callbacks: list[Callable[[str, str, str, str | None], None]] = []
@@ -169,10 +211,30 @@ class SchemaOneAdapter:
         way to get a placeholder. Under parent/child every mapped device has
         the same exposure, so a DER missing the model it declared is reported
         alongside a circuit missing its name.
+
+        An inverter's feeding circuit is waited on too, because it decides the
+        inverter's `pv_inverters` key, and a key that moved after the first
+        snapshot would move every entity built on it. A circuit feeding nothing
+        publishes no `connection/feeds-device-id` value at all, so an unvalued
+        one is ambiguous; it is reported only while some inverter is still
+        unplaced (no circuit feeds it and no lugs device names it as its
+        source), which is the one case its value could still change a key.
+
+        The panel itself is reported while a declared BESS waits on the
+        panel's declared firmware version, which decides the BESS meter's frame.
+
+        The feed wait is bounded by `FEED_GRACE_S`. A DER may be published with
+        no connection record pointing at it, and then no value is coming; a
+        retained feed lands in the same burst as its circuit's name, so once
+        every name, model and firmware version has arrived, a feed still
+        unvalued after the grace is taken as absent. The inverter is then keyed
+        by its device id, reported once at INFO rather than the transport
+        warning after the full name timeout. The grace restarts whenever
+        anything else is missing again.
         """
         roles = TreeRoles(self._children())
         missing = [circuit.device_id for circuit in roles.circuits if not circuit.get_property(NODE_INFO, PROP_NAME)]
-        ders = (roles.bess, roles.pv, *roles.evse)
+        ders = (roles.bess, *roles.pvs, *roles.evse)
         missing.extend(
             device.device_id
             for device in ders
@@ -180,8 +242,45 @@ class SchemaOneAdapter:
             and PROP_MODEL in device.get_node_properties(NODE_INFO)
             and device.get_property(NODE_INFO, PROP_MODEL) is None
         )
+        missing.extend(self._firmware_version_pending(roles))
+        feeds = _unvalued_feeds_for_unplaced_pvs(roles)
+        if feeds and not missing:
+            now = self._clock()
+            if self._feed_wait_since is None:
+                self._feed_wait_since = now
+            if now - self._feed_wait_since >= FEED_GRACE_S:
+                if not self._feed_wait_reported:
+                    _LOGGER.info(
+                        "No connection record names %d circuit(s) as an inverter's feed; "
+                        "inverters without one are keyed by device id",
+                        len(feeds),
+                    )
+                    self._feed_wait_reported = True
+                feeds = []
+        elif missing:
+            self._feed_wait_since = None
+        missing.extend(feeds)
         return missing
 
+    def _firmware_version_pending(self, roles: TreeRoles) -> list[str]:
+        """The panel itself, while a declared BESS waits on the panel's firmware version.
+
+        The release build in the panel's `info/firmware-version` decides which
+        frame the BESS meter is read in. A first snapshot built before it lands
+        falls back to comparing signs with `power-flows/battery`, and a later one
+        may read the other way, so the battery's power would flip once after
+        connect. Only a declared property is waited on: a panel that does not
+        promise one is never held for it.
+        """
+        root = self._controller.get_root(self._serial_number)
+        if roles.bess is None or root is None:
+            return []
+        if PROP_FIRMWARE_VERSION not in root.get_node_properties(NODE_INFO):
+            return []
+        if root.get_property(NODE_INFO, PROP_FIRMWARE_VERSION) is None:
+            return [root.device_id]
+        return []
+
     def find_node_by_type(self, type_str: str) -> str | None:
         """Return the id of the first device declaring `type_str`.
 

{span_panel_api_schema_1-1.1.4 → span_panel_api_schema_1-1.2.1}/src/span_panel_api_schema_1/devices.py

@@ -19,36 +19,33 @@ against conflating them. Both are now carried, in separate fields
 (``connected`` and ``communication_state``), because they answer different
 questions: the panel's view of the link, and the publisher's view of its own.
 
-**Battery power is discharge-positive, and that is not the rule circuits follow.**
-``build_circuit`` negates so that positive means power flowing *into* the metered
-device, which is the convention the rest of this module states. ``build_battery``
-negates too, but its wire input is in the opposite frame, so it lands on the
-opposite result: ``battery.power_w`` is positive while the battery *discharges*.
-
-Measured rather than reasoned. Driving the producer into self-consumption with
-the grid at zero forces the direction: PV 4181 W plus battery 1917 W meeting a
-6099 W load leaves nothing ambiguous, and the battery is discharging. The wire
+**Battery power is discharge-positive, and the wire's frame for it changed at r202639.**
+``battery.power_w`` is positive while the battery *discharges*: the frame the eBus
+specification asks for from a device's own meter, and deliberately not the
+into-the-device rule ``build_circuit`` follows.
+
+Through r202633 the BESS ``meter/active-power`` is charge-positive, carrying the
+same sign as the enclosure's ``power-flows/battery``, so ``build_battery`` negates
+it. Measured rather than reasoned: driving the producer into self-consumption
+with the grid at zero forces the direction. PV 4181 W plus battery 1917 W meeting
+a 6099 W load leaves nothing ambiguous: the battery is discharging. The wire
 publishes ``-1917.49`` and this module reports ``+1917.49``.
 
-That value is *correct* -- it is the frame the eBus specification asks for from a
-device's own meter, "positive while discharging, that is, power flowing out of
-the device". What was wrong was the name: this used to be ``_charge_positive``,
-and the sentence above used to claim the into-the-device rule held everywhere.
-It does not hold for the battery, and saying so was the defect.
-
-Both wire properties behind it carry the *same* sign as each other -- a live
-panel capture and ``ebus-panel-sim`` 0.6.0 both publish the pair identically --
-so ``panel.power_flow_battery`` (passed through untouched) and
-``battery.power_w`` (negated here) end up as each other's mirror, and a consumer
-showing both sees one convention after applying one negation to either.
-
-Note that the alignment of those two wire properties is the specification's
-*violation* rather than its rule: the spec defines ``power-flows/battery`` as the
-negation of the BESS meter, and this firmware publishes them equal. Comparing the
-two therefore tells a consumer which firmware it is on -- equal means today's,
-opposite means a conformant future one -- which is what would let this conversion
-stay correct across that change. Undecidable while the battery is idle and both
-read zero.
+From r202639 the BESS meter is published discharge-positive, the negation of
+``power-flows/battery`` (whose own sign did not change), so it passes through.
+The frame is chosen from the enclosure's release build number
+(``firmware.release_build``), never from the respin suffix after it. Where the
+version does not parse, the two wire properties decide instead: one nonzero sign
+on both is the old frame, opposite signs the new one. Where either is zero or
+absent the old frame is assumed, because that is what every earlier release of
+this package applied and what the reference capture (``ebus-panel-sim`` 0.8.0,
+which publishes no SPAN version string) carries. A battery at rest reads zero in
+both frames, so the assumption only decides a nonzero BESS meter beside a missing
+or zero flow figure.
+
+On either firmware ``panel.power_flow_battery`` (passed through untouched, and
+charge-positive) and ``battery.power_w`` end up as each other's mirror, so a
+consumer showing both sees one convention after negating either one.
 """
 
 from __future__ import annotations
@@ -78,6 +75,7 @@ from span_panel_api_schema_1.const import (
     PROP_VENDOR_NAME,
     UNKNOWN,
 )
+from span_panel_api_schema_1.firmware import release_build
 from span_panel_api_schema_1.panel import integer, number, resolve_grid_forming_device_name, text
 
 if TYPE_CHECKING:
@@ -114,12 +112,14 @@ def feed_circuit_ids(circuits: list[DiscoveredDevice]) -> dict[str, str]:
 
     v1.0 states the relationship on the *circuit* (``connection/feeds-device-id``)
     rather than on the DER, so it is read once here and handed to whichever
-    device needs it.
+    device needs it. A device fed by more than one circuit (the specification
+    allows it) maps to the circuit with the lowest device id, so the answer, and
+    every key built on it, does not depend on discovery order.
     """
     feeds: dict[str, str] = {}
-    for circuit in circuits:
+    for circuit in sorted(circuits, key=lambda device: device.device_id):
         fed = text(circuit, NODE_CONNECTION, PROP_FEEDS_DEVICE_ID)
-        if fed:
+        if fed and fed not in feeds:
             feeds[fed] = circuit.device_id
     return feeds
 
@@ -157,12 +157,18 @@ def feed_connection_statuses(circuits: list[DiscoveredDevice]) -> dict[str, str]
     Most circuits publish neither. A mixed-load or unsurveyed circuit feeds no
     commissioned DER, so it has no connection record to publish — the spec calls
     that normal, which is why nothing here treats a missing record as an error.
+
+    A device fed by more than one circuit takes the status of the circuit
+    ``feed_circuit_ids`` chose for it, so its link health and its feed come from
+    one record whatever the discovery order. That circuit's silence is not
+    filled from the other feed: it leaves the device absent here, as any
+    circuit publishing only one half does.
     """
+    by_id = {circuit.device_id: circuit for circuit in circuits}
     statuses: dict[str, str] = {}
-    for circuit in circuits:
-        fed = text(circuit, NODE_CONNECTION, PROP_FEEDS_DEVICE_ID)
-        status = text(circuit, NODE_CONNECTION, PROP_FEEDS_DEVICE_STATUS)
-        if fed and status:
+    for fed, circuit_id in feed_circuit_ids(circuits).items():
+        status = text(by_id[circuit_id], NODE_CONNECTION, PROP_FEEDS_DEVICE_STATUS)
+        if status:
             statuses[fed] = status
     return statuses
 
@@ -185,32 +191,71 @@ def _connected(status: str | None) -> bool | None:
     return None if status is None else status == STATUS_OK
 
 
-def _discharge_positive(raw_power_w: float | None) -> float | None:
-    """Flip the enclosure's meter frame to the BESS device's own.
+BESS_METER_DISCHARGE_POSITIVE_FROM_BUILD = 202639
+"""The first release build whose BESS ``meter/active-power`` is discharge-positive."""
+
+
+def _bess_meter_is_charge_positive(
+    firmware_version: str | None,
+    raw_power_w: float | None,
+    power_flow_battery: float | None,
+) -> bool:
+    """Whether the BESS meter on the wire is in the pre-r202639 frame.
+
+    The enclosure's release build decides when it parses. Otherwise the BESS
+    meter is compared with ``power-flows/battery``, which kept its sign across
+    the change: equal signs mean the old frame, opposite signs the new one. With
+    either one zero or absent the comparison says nothing, and the old frame is
+    assumed (see the module docstring for why).
+    """
+    build = release_build(firmware_version)
+    if build is not None:
+        return build < BESS_METER_DISCHARGE_POSITIVE_FROM_BUILD
+    if raw_power_w is None or power_flow_battery is None or raw_power_w == 0.0 or power_flow_battery == 0.0:
+        return True
+    return (raw_power_w > 0.0) == (power_flow_battery > 0.0)
+
+
+def _discharge_positive(raw_power_w: float | None, *, charge_positive_on_wire: bool) -> float | None:
+    """Bring the BESS meter into the device's own frame, discharge-positive.
 
     Positive means power flowing *out of the battery*, which is discharging, and
-    which is what the eBus specification asks of a device's own meter. Named for
-    what it produces after being called `_charge_positive` for as long as it
-    produced the opposite -- measured against a producer driven into
-    self-consumption, where the grid sits at zero and the direction cannot be
-    argued.
+    which is what the eBus specification asks of a device's own meter. A wire
+    value already in that frame passes through; one in the older charge-positive
+    frame is negated.
 
     `None` stays `None`: a BESS that publishes no `meter` node has no power
     reading, which is not the same as zero. The `0.0` guard is `build_circuit`'s,
-    for the same reason — negating `0.0` yields `-0.0`, which compares equal to
-    `0.0` and formats as `"-0.0"`.
+    for the same reason: negating `0.0` yields `-0.0`, which compares equal to
+    `0.0` and formats as `"-0.0"`. A wire `-0.0` is normalized on the
+    pass-through path too.
     """
     if raw_power_w is None:
         return None
-    return 0.0 if raw_power_w == 0.0 else -raw_power_w
+    if raw_power_w == 0.0:
+        return 0.0
+    return -raw_power_w if charge_positive_on_wire else raw_power_w
 
 
-def build_battery(bess: DiscoveredDevice | None, owners: list[DiscoveredDevice]) -> SpanBatterySnapshot:
-    """Build the battery snapshot. An uncommissioned panel yields the empty one."""
+def build_battery(
+    bess: DiscoveredDevice | None,
+    owners: list[DiscoveredDevice],
+    *,
+    firmware_version: str | None = None,
+    power_flow_battery: float | None = None,
+) -> SpanBatterySnapshot:
+    """Build the battery snapshot. An uncommissioned panel yields the empty one.
+
+    `firmware_version` is the enclosure's ``info/firmware-version`` and
+    `power_flow_battery` its ``power-flows/battery``; together they pick the
+    BESS meter's wire frame. Omitted, they leave the old frame assumed.
+    """
     if bess is None:
         return SpanBatterySnapshot()
 
     status = connection_status_for(bess.device_id, owners)
+    raw_power_w = number(bess, NODE_METER, PROP_ACTIVE_POWER)
+    charge_positive_on_wire = _bess_meter_is_charge_positive(firmware_version, raw_power_w, power_flow_battery)
 
     return SpanBatterySnapshot(
         # Historically misnamed in the snapshot and kept that way: `soe_percentage`
@@ -229,7 +274,7 @@ def build_battery(bess: DiscoveredDevice | None, owners: list[DiscoveredDevice])
         nameplate_capacity_kwh=number(bess, NODE_INFO, PROP_NAMEPLATE_CAPACITY),
         # None when unclaimed, so "nobody has said" stays distinct from "not OK".
         connected=_connected(status),
-        power_w=_discharge_positive(number(bess, NODE_METER, PROP_ACTIVE_POWER)),
+        power_w=_discharge_positive(raw_power_w, charge_positive_on_wire=charge_positive_on_wire),
         # The BESS's own link health, kept as the published enum string rather
         # than collapsed to a bool: DEGRADED is neither OK nor LOST, and a bool
         # would have to pick one.
@@ -237,6 +282,17 @@ def build_battery(bess: DiscoveredDevice | None, owners: list[DiscoveredDevice])
     )
 
 
+def pv_inverter_key(pv: DiscoveredDevice, feeds: Mapping[str, str]) -> str:
+    """The inverter's `pv_inverters` key: its feeding circuit's id, else its device id.
+
+    The circuit first because its id survives firmware r202639, which renumbers
+    every PV device on a panel with more than one inverter. A circuit feeds at
+    most one device, so two circuit-fed inverters cannot share a key. An
+    inverter no circuit feeds keeps its device id, the only handle it has.
+    """
+    return feeds.get(pv.device_id) or pv.device_id
+
+
 def build_pv(
     pv: DiscoveredDevice | None,
     feeds: dict[str, str],
@@ -245,7 +301,11 @@ def build_pv(
     *,
     feed_statuses: dict[str, str],
 ) -> SpanPVSnapshot:
-    """Build the PV snapshot. An uncommissioned panel yields the empty one."""
+    """Build one inverter's PV snapshot. An uncommissioned panel yields the empty one.
+
+    `info/nominal-power` is the array's DC size as recorded at installation,
+    carried for display and never a limit on what the inverter produces.
+    """
     if pv is None:
         return SpanPVSnapshot()
 
@@ -253,9 +313,12 @@ def build_pv(
         connected=_connected(feed_statuses.get(pv.device_id)),
         vendor_name=_optional(text(pv, NODE_INFO, PROP_VENDOR_NAME)),
         model=_optional(text(pv, NODE_INFO, PROP_MODEL)),
+        serial_number=_optional(text(pv, NODE_INFO, PROP_SERIAL_NUMBER)),
         software_version=_optional(text(pv, NODE_INFO, PROP_FIRMWARE_VERSION)),
         nameplate_capacity_w=number(pv, NODE_INFO, PROP_NOMINAL_POWER),
         feed_circuit_id=feeds.get(pv.device_id),
+        device_id=pv.device_id,
+        node_id=pv_inverter_key(pv, feeds),
         # Retired as a property in v1.0 and derived instead, per the enclosure model's
         # own replacement rule. `None` where no owner references the DER, because the
         # integration gates whether a control entity exists on this value.

{span_panel_api_schema_1-1.1.4 → span_panel_api_schema_1-1.2.1}/src/span_panel_api_schema_1/field_metadata.py

@@ -157,11 +157,11 @@ _PROPERTY_FIELD_MAP: tuple[tuple[str, str, str, str], ...] = (
     (TYPE_BESS, NODE_INFO, "serial-number", "battery.serial_number"),
     (TYPE_BESS, NODE_INFO, "firmware-version", "battery.software_version"),
     (TYPE_BESS, NODE_INFO, "nameplate-capacity", "battery.nameplate_capacity_kwh"),
-    # The BESS's own meter and its own link health. `battery.power_w` carries a
-    # sign flip (`build_battery` reports discharge-positive, the wire carries the
-    # enclosure's frame), which does not affect the unit or the datatype this row
-    # describes — a row states what the property *is*, not what the mapper does
-    # with it.
+    # The BESS's own meter and its own link health. `battery.power_w` may carry a
+    # sign flip (`build_battery` reports discharge-positive, and the wire is
+    # charge-positive before r202639), which does not affect the unit or the
+    # datatype this row describes: a row states what the property *is*, not what
+    # the mapper does with it.
     (TYPE_BESS, NODE_METER, "active-power", "battery.power_w"),
     (TYPE_BESS, NODE_STATUS, "communication-state", "battery.communication_state"),
     # --- PV ------------------------------------------------------------------
@@ -457,6 +457,7 @@ _CONSUMED_WITHOUT_A_ROW: tuple[tuple[str, str, str], ...] = (
     (TYPE_EVSE, NODE_INFO, "serial-number"),
     (TYPE_EVSE, NODE_INFO, "vendor-name"),
     (TYPE_PV, NODE_INFO, "firmware-version"),
+    (TYPE_PV, NODE_INFO, "serial-number"),
 )
 """Declarations the mapper reads into the snapshot without a metadata row.
 

span_panel_api_schema_1-1.2.1/src/span_panel_api_schema_1/firmware.py

@@ -0,0 +1,34 @@
+"""Read the release build number out of the enclosure's firmware version string.
+
+SPAN firmware publishes ``info/firmware-version`` as slash-separated segments,
+for example ``spanos2/r202639/03``. The ``rNNNNNN`` segment names the release and
+is the only part a behavior gate may compare: the trailing ``/03`` is a respin of
+that release, and two respins of one release publish the same wire conventions.
+
+Kept to one function so every gate in this package parses the string the same
+way, and so a string this package does not recognize yields `None` rather than a
+guess. A caller decides what `None` means for its own question.
+"""
+
+from __future__ import annotations
+
+import re
+
+_RELEASE_SEGMENT = re.compile(r"r(\d{6})")
+
+
+def release_build(firmware_version: str | None) -> int | None:
+    """The six-digit release build number, or `None` when there is none to read.
+
+    ``"spanos2/r202639/03"`` gives ``202639``. Only a whole path segment of the
+    form ``r`` plus exactly six digits counts, so ``"r2026390"``, ``"rc1"`` and a
+    simulator's ``"example/v0.1.0"`` all give `None`. The first such segment wins;
+    the respin suffix after it is never read.
+    """
+    if firmware_version is None:
+        return None
+    for segment in firmware_version.strip().split("/"):
+        match = _RELEASE_SEGMENT.fullmatch(segment)
+        if match is not None:
+            return int(match.group(1))
+    return None

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

@@ -11,11 +11,13 @@ from __future__ import annotations
 import time
 from typing import TYPE_CHECKING
 
-from span_panel_api.models import ExtensionSubject, SpanPanelSnapshot
+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
 from span_panel_api_schema_1.const import (
+    NODE_CONNECTION,
     NODE_INFO,
+    PROP_FEEDS_DEVICE_ID,
     PROP_MODEL,
     PROP_SERIAL_NUMBER,
     TYPE_BESS,
@@ -34,6 +36,7 @@ from span_panel_api_schema_1.devices import (
     build_pv,
     feed_circuit_ids,
     feed_connection_statuses,
+    pv_inverter_key,
 )
 from span_panel_api_schema_1.extension import build_extension_properties
 from span_panel_api_schema_1.field_metadata import addressed_rows
@@ -71,7 +74,10 @@ class TreeRoles:
         self.lugs: list[DiscoveredDevice] = []
         self.evse: list[DiscoveredDevice] = []
         self.bess: DiscoveredDevice | None = None
-        self.pv: DiscoveredDevice | None = None
+        # Every inverter, in tree order. From r202639 each commissioned inverter
+        # is its own device; earlier firmware published one. None of them is
+        # primary.
+        self.pvs: list[DiscoveredDevice] = []
         self.mid: DiscoveredDevice | None = None
 
         for device in devices:
@@ -84,12 +90,44 @@ class TreeRoles:
                 self.evse.append(device)
             elif declared == TYPE_BESS and self.bess is None:
                 self.bess = device
-            elif declared == TYPE_PV and self.pv is None:
-                self.pv = device
+            elif declared == TYPE_PV:
+                self.pvs.append(device)
             elif declared == TYPE_MID and self.mid is None:
                 self.mid = device
 
 
+def _pv_for(inverters: Sequence[SpanPVSnapshot]) -> SpanPVSnapshot:
+    """`SpanPanelSnapshot.pv`: the lone inverter, or the inverters together.
+
+    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 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:
     """Build a full snapshot from the panel and its descendants."""
     roles = TreeRoles(children)
@@ -104,11 +142,16 @@ def build_snapshot(panel: DiscoveredDevice, children: list[DiscoveredDevice], re
     feed_statuses = feed_connection_statuses(roles.circuits)
     # 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".
+    # reports device_type "pv" rather than "circuit". Every inverter's circuit,
+    # 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_id: kind
-        for kind, device in (("pv", roles.pv), *(("evse", e) for e in roles.evse))
-        if device is not None and (circuit_id := feeds.get(device.device_id))
+        circuit.device_id: kind
+        for circuit in roles.circuits
+        if (kind := kind_by_der.get(text(circuit, NODE_CONNECTION, PROP_FEEDS_DEVICE_ID)))
     }
 
     circuits = {}
@@ -176,12 +219,25 @@ def build_snapshot(panel: DiscoveredDevice, children: list[DiscoveredDevice], re
             ("panel", panel),
             ("battery", roles.bess),
             ("mid", roles.mid),
-            ("pv", roles.pv),
+            *((("pv", roles.pvs[0]),) if len(roles.pvs) == 1 else ()),
         )
         if device is not None
     ]
+    # One inverter keeps the singleton `pv` subject it always had. With more
+    # than one, each inverter is its own subject keyed like `pv_inverters`, so
+    # no inverter's vendor properties are filed under another's.
+    pv_subjects = (
+        [(device, ExtensionSubject(kind="pv", instance_key=pv_inverter_key(device, feeds))) for device in roles.pvs]
+        if len(roles.pvs) > 1
+        else []
+    )
+    pv_inverters = {
+        pv_inverter_key(device, feeds): build_pv(device, feeds, upstream, downstream, feed_statuses=feed_statuses)
+        for device in roles.pvs
+    }
+
     extension_properties = build_extension_properties(
-        [*singleton_subjects, *lugs_subjects, *evse_subjects, *circuit_subjects],
+        [*singleton_subjects, *pv_subjects, *lugs_subjects, *evse_subjects, *circuit_subjects],
         addressed_rows(children),
     )
 
@@ -240,8 +296,14 @@ def build_snapshot(panel: DiscoveredDevice, children: list[DiscoveredDevice], re
         downstream_l1_current_a=fields.downstream_l1_current_a,
         downstream_l2_current_a=fields.downstream_l2_current_a,
         circuits=circuits,
-        battery=build_battery(roles.bess, owners),
-        pv=build_pv(roles.pv, feeds, upstream, downstream, feed_statuses=feed_statuses),
+        battery=build_battery(
+            roles.bess,
+            owners,
+            firmware_version=fields.firmware_version,
+            power_flow_battery=fields.power_flow_battery,
+        ),
+        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
         # capability publishes is legally `0.0`, so there is no reading that can