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

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

@@ -9,6 +9,39 @@ 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]
+
+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**.
+
+### 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.
+- **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
+
+- **`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.
+
+## [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
+[#178](https://github.com/SpanPanel/span-panel-api/issues/178).
+
+### Fixed
+
+- **An islanding assertion in force is now the reported islanding state even while the MID is ready.** `resolve_islanding_state` returned the MID's sensed value whenever the MID was ready and read `shed/asserted-islanding-state` only when it was not, so
+  `dsm_state` could disagree with the state the panel was acting on. `ON_GRID` or `OFF_GRID` asserted now wins; otherwise the ready MID's value, then the existing fallback.
+- **`set_dominant_power_source_target` returns None unless the panel declares `shed/asserted-islanding-state` settable**, the same refusal `set_circuit_relay_target` makes.
+- **`dominant_power_source_payload` refuses `NONE` and `UNKNOWN`** instead of publishing `NONE`, which the panel ignores. An assertion clears itself once the panel's link to the battery recovers.
+
 ## [1.1.3]
 
 `spec_lock.json` ships inside this wheel, so its shape changing is a release here even though the parser did not change.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: span-panel-api-schema-1
-Version: 1.1.3
+Version: 1.2.0
 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.0
 Description-Content-Type: text/markdown
 
 # span-panel-api-schema-1

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

@@ -1,6 +1,6 @@
 [project]
 name = "span-panel-api-schema-1"
-version = "1.1.3"
+version = "1.2.0"
 description = "Parent/child schema (data-model-version 1.x) parser for span-panel-api"
 authors = [
     {name = "SpanPanel"}
@@ -21,7 +21,11 @@ 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.
+    "span-panel-api>=3.6.0,<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.3 → span_panel_api_schema_1-1.2.0}/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,
@@ -40,9 +45,10 @@ from span_panel_api_schema_1.const import (
     STATE_READY,
     TYPE_CIRCUIT,
 )
-from span_panel_api_schema_1.description import device_type
+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`.
 
@@ -275,9 +374,23 @@ class SchemaOneAdapter:
         the BESS stops discharging. Returning None here, as this did until the
         successor was decided, left that recovery unavailable during an outage.
 
+        **The panel decides whether a write takes effect, by its own link to the
+        battery.** It accepts `ON_GRID` or `OFF_GRID` only while the battery's
+        `status/communication-state` is not `OK`; otherwise it ignores the write
+        and the published value does not change. A lost MID alone does not make
+        the write eligible. `NONE` is always ignored.
+
+        **None unless the panel declares the assertion `$settable`**, the same
+        refusal `set_circuit_relay_target` makes. Absence of the declaration,
+        or of the property, authorizes nothing (see
+        `description.declared_settable`).
+
         Payload translation is not optional: the flat enum this protocol speaks
         is not the one the panel accepts. See `dominant_power_source_payload`.
         """
+        root = self._controller.get_root(self._serial_number)
+        if not declared_settable(node_properties(root, NODE_SHED).get(PROP_ASSERTED_ISLANDING_STATE)):
+            return None
         return self._target(self._serial_number, NODE_SHED, PROP_ASSERTED_ISLANDING_STATE)
 
     def dominant_power_source_payload(self, value: str) -> str | None:
@@ -291,17 +404,19 @@ class SchemaOneAdapter:
 
         The narrowing loses nothing, because the six values were a *source
         class* pressed into service as a manual override and the job only ever
-        needed on-grid, off-grid, or no assertion. Anything not recognised
-        returns None rather than guessing, so the transport refuses the command
-        instead of asserting something the user did not ask for.
+        needed on-grid or off-grid. Anything not recognized returns None rather
+        than guessing, so the transport refuses the command instead of
+        asserting something the user did not ask for.
+
+        **`NONE` and `UNKNOWN` are refused too.** The panel ignores a written
+        `NONE`, so publishing one would report a clear that never happened. An
+        assertion clears itself once the panel's link to the battery recovers.
         """
         return {
             "GRID": "ON_GRID",
             "BATTERY": "OFF_GRID",
             "PV": "OFF_GRID",
             "GENERATOR": "OFF_GRID",
-            "NONE": "NONE",
-            "UNKNOWN": "NONE",
         }.get(value.strip().upper())
 
     def set_evse_charge_limit_target(self, node_id: str) -> ControlTarget | None:

{span_panel_api_schema_1-1.1.3 → span_panel_api_schema_1-1.2.0}/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 _tabs(device: DiscoveredDevice) -> list[int]:
+def circuit_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=_tabs(device),
+        tabs=circuit_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.1.3 → span_panel_api_schema_1-1.2.0}/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.3 → span_panel_api_schema_1-1.2.0}/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.
 
@@ -472,8 +473,8 @@ _CONSUMED_OFF_SNAPSHOT: dict[tuple[str, str, str], str] = {
         "parses the tree, so it is consumed before any snapshot exists"
     ),
     (TYPE_PANEL, NODE_SHED, "asserted-islanding-state"): (
-        "tier 2 of resolve_islanding_state (panel.py), shadowed wherever a MID answers "
-        "at tier 1, and the write target of set_dominant_power_source_target"
+        "tier 1 of resolve_islanding_state (panel.py), which returns a non-NONE "
+        "assertion first, and the write target of set_dominant_power_source_target"
     ),
     (TYPE_LUGS, NODE_CONNECTION, "feeds-device-id"): (
         "the downstream-lugs feedthrough branch of resolve_relative_position "

span_panel_api_schema_1-1.2.0/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.3 → span_panel_api_schema_1-1.2.0}/src/span_panel_api_schema_1/panel.py

@@ -600,7 +600,6 @@ _GRID_POWER_EPSILON_W = 1.0
 
 ISLANDING_ON_GRID = "ON_GRID"
 ISLANDING_OFF_GRID = "OFF_GRID"
-ASSERTION_NONE = "NONE"
 
 
 def resolve_islanding_state(mid: DiscoveredDevice | None, panel: DiscoveredDevice) -> str | None:
@@ -608,17 +607,19 @@ def resolve_islanding_state(mid: DiscoveredDevice | None, panel: DiscoveredDevic
 
     | tier | condition | source |
     | --- | --- | --- |
-    | 1 | MID `$state` is `ready` and `islanding-state` present | sensed |
-    | 2 | MID not `ready` | `shed/asserted-islanding-state`, when not `NONE` |
+    | 1 | `shed/asserted-islanding-state` is `ON_GRID` or `OFF_GRID` | asserted |
+    | 2 | MID `$state` is `ready` and `islanding-state` present | sensed |
     | 3 | no MID at all | `power-flows/grid` heuristic |
     | 4 | none of the above | unknown |
 
-    **Tier 2 is the reason the assertion control exists.** When comms to the BESS or MID
-    are lost and the grid returns, the user asserts the grid is up so the BESS stops
-    discharging. Declining to read it here would wire the control and then ignore it at
-    exactly the moment it matters. Nothing is hidden by doing so: the MID is a device, so
-    it goes *unavailable* in Home Assistant when it stops publishing, and the assertion is
-    itself visible as the control the user set.
+    **An assertion in force is the effective state, so it outranks the MID.** When the
+    panel's link to the battery is not healthy (the battery's `status/communication-state`
+    is not `OK`) and the grid returns, the user asserts the grid is up so the BESS stops
+    discharging, and the panel acts on that assertion until it clears. The panel ignores
+    the write while that link is healthy.
+    Reading the MID first would report the sensed value while the panel is acting on a
+    different one. The assertion clears itself back to `NONE` once the battery link
+    recovers, so the MID's answer returns without anything here having to expire it.
 
     **Tier 3 never answers `OFF_GRID`, and never asserts on-grid from a missing MID.** An
     earlier draft reasoned that no MID means no islanding authority means on-grid. That is
@@ -627,14 +628,15 @@ def resolve_islanding_state(mid: DiscoveredDevice | None, panel: DiscoveredDevic
     counterexample. Grid power flowing is positive evidence of being on-grid; its absence
     is not evidence of the opposite.
     """
+    asserted = text(panel, NODE_SHED, PROP_ASSERTED_ISLANDING_STATE)
+    if asserted in (ISLANDING_ON_GRID, ISLANDING_OFF_GRID):
+        return asserted
+
     if mid is not None:
         if mid.state == "ready":
             sensed = text(mid, NODE_GRID, PROP_ISLANDING_STATE)
             if sensed:
                 return sensed
-        asserted = text(panel, NODE_SHED, PROP_ASSERTED_ISLANDING_STATE)
-        if asserted and asserted != ASSERTION_NONE:
-            return asserted
         return None
 
     grid_power = number(panel, NODE_POWER_FLOWS, "grid")

{span_panel_api_schema_1-1.1.3 → span_panel_api_schema_1-1.2.0}/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.circuits import build_circuit, circuit_tabs
 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,9 @@ 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.
+        self.pvs: list[DiscoveredDevice] = []
         self.mid: DiscoveredDevice | None = None
 
         for device in devices:
@@ -84,11 +89,39 @@ 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
 
+        self.pv: DiscoveredDevice | None = primary_pv(self.pvs, self.circuits)
+
+
+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.
+    """
+    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)
+
 
 def build_snapshot(panel: DiscoveredDevice, children: list[DiscoveredDevice], ready_since: float = 0.0) -> SpanPanelSnapshot:
     """Build a full snapshot from the panel and its descendants."""
@@ -104,11 +137,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,
+    # 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.
+    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 +214,25 @@ def build_snapshot(panel: DiscoveredDevice, children: list[DiscoveredDevice], re
             ("panel", panel),
             ("battery", roles.bess),
             ("mid", roles.mid),
-            ("pv", roles.pv),
+            *((("pv", roles.pv),) 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 +291,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_inverters[pv_inverter_key(roles.pv, feeds)] if roles.pv is not None else SpanPVSnapshot(),
+        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