span-panel-api-schema-1 1.3.0b1__tar.gz → 1.4.0b2__tar.gz

{span_panel_api_schema_1-1.3.0b1 → span_panel_api_schema_1-1.4.0b2}/CHANGELOG.md

@@ -11,10 +11,15 @@ Pre-releases are not listed separately. A beta is a step towards the next public
 
 ## [Unreleased]
 
-Requires `span-panel-api` **3.7.0 or newer**, whose snapshot fields accept the unknown values this parser now reports.
+Requires `span-panel-api` **3.8.0 or newer**, whose snapshot fields accept the unknown values this parser now reports and carry the fields it now fills.
+
+### Added
+
+- **spanos3/r202639/03 batch 2: reads more of the data this firmware publishes.**
 
 ### Changed
 
+- The shipped reference tree is recaptured with every circuit inside the panel's breaker positions.
 - **`proximity_proven` is `None`**, where it was a hard-coded `True`, because the tree publishes no proximity property.
 - **`uptime_s` is `None`**, where it was always `0`, because no device publishes an uptime and this parser keeps no readiness clock to measure one.
 
@@ -28,6 +33,8 @@ Requires `span-panel-api` **3.7.0 or newer**, whose snapshot fields accept the u
 
 - **A circuit whose shed priority is `UNKNOWN` is no longer reported as sheddable.**
 - **The grid-forming device name falls back to vendor and model instead of showing a device id.**
+- **A panel with no MID reports `dsm_state` `DSM_ON_GRID` and `current_run_config` `PANEL_ON_GRID` whenever it is publishing**, where both dropped to `UNKNOWN` each time `power-flows/grid` read within 1 W of zero
+  ([#215](https://github.com/SpanPanel/span-panel-api/issues/215)).
 
 ## [1.2.2]
 

{span_panel_api_schema_1-1.3.0b1 → span_panel_api_schema_1-1.4.0b2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: span-panel-api-schema-1
-Version: 1.3.0b1
+Version: 1.4.0b2
 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.7.0b1
+Requires-Dist: span-panel-api<4.0,>=3.8.0b1
 Description-Content-Type: text/markdown
 
 # span-panel-api-schema-1

{span_panel_api_schema_1-1.3.0b1 → span_panel_api_schema_1-1.4.0b2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "span-panel-api-schema-1"
-version = "1.3.0b1"
+version = "1.4.0b2"
 description = "Parent/child schema (data-model-version 1.x) parser for span-panel-api"
 authors = [
     {name = "SpanPanel"}
@@ -31,7 +31,9 @@ dependencies = [
     # Raised to 3.7.0b1, whose snapshot fields accept the unknown values this
     # parser now reports: against an earlier one, the update times it leaves
     # unset read as a constant 0.
-    "span-panel-api>=3.7.0b1,<4.0",
+    # Raised to 3.8.0b1: this parser fills snapshot fields new in it and imports
+    # `device_id_order` from its models.
+    "span-panel-api>=3.8.0b1,<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.3.0b1 → span_panel_api_schema_1-1.4.0b2}/src/span_panel_api_schema_1/adapter.py

@@ -48,9 +48,9 @@ from span_panel_api_schema_1.const import (
 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, text
+from span_panel_api_schema_1.panel import integer, positions_outside_model, text
 from span_panel_api_schema_1.snapshot import TreeRoles, build_snapshot, harmonised_evse_keys
-from span_panel_api_schema_1.transport import ControllerRoutes
+from span_panel_api_schema_1.transport import ControllerRoutes, control_target
 
 if TYPE_CHECKING:
     from collections.abc import Callable
@@ -62,11 +62,12 @@ 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.
+"""How long an inverter's feed or a DER's model may stay unvalued once every name 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.
+A retained `connection/feeds-device-id` or `info/model` lands in the same burst
+as the rest of the tree's labels. One still missing this long after every name
+and firmware version is taken as absent: a DER may be published with no
+connection record at all, and a declared model may never be valued.
 """
 
 
@@ -110,8 +111,9 @@ class SchemaOneAdapter:
         self._serial_number = serial_number
         self._schema = schema
         self._clock = clock
-        self._feed_wait_since: float | None = None
-        self._feed_wait_reported = False
+        self._grace_since: dict[str, float] = {}
+        self._grace_reported: set[str] = set()
+        self._positions_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]] = []
@@ -186,7 +188,34 @@ class SchemaOneAdapter:
 
     def build_snapshot(self) -> SpanPanelSnapshot:
         root = self._require_root()
-        return build_snapshot(root, self._children())
+        snapshot = build_snapshot(root, self._children())
+        self._report_positions_outside_model(snapshot)
+        return snapshot
+
+    def _report_positions_outside_model(self, snapshot: SpanPanelSnapshot) -> None:
+        """Warn once per panel when its circuits occupy spaces outside its model's range.
+
+        The snapshot keeps reporting the model's range, so such a circuit lies
+        outside the positions a consumer lays out until the table is corrected.
+        """
+        if self._positions_reported:
+            return
+        outside = positions_outside_model(
+            snapshot.model, (tab for circuit in snapshot.circuits.values() for tab in circuit.tabs)
+        )
+        if outside is None:
+            return
+        (first, last), (lowest, highest) = outside
+        _LOGGER.warning(
+            "Panel model %s has breaker positions %d-%d, but its circuits occupy spaces %d-%d; "
+            "the snapshot reports the model's positions",
+            snapshot.model,
+            first,
+            last,
+            lowest,
+            highest,
+        )
+        self._positions_reported = True
 
     def build_field_metadata(self) -> dict[str, FieldMetadata]:
         root = self._controller.get_root(self._serial_number)
@@ -212,6 +241,12 @@ class SchemaOneAdapter:
         the same exposure, so a DER missing the model it declared is reported
         alongside a circuit missing its name.
 
+        Only a declared label is waited for. A circuit-typed device whose
+        description declares no `info/name` -- a meter outside the panel
+        declares no `info` node at all -- has no name coming, and waiting for
+        one would hold every connect and every tree rebuild to the full
+        timeout.
+
         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
@@ -223,52 +258,66 @@ class SchemaOneAdapter:
         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, and once every inverter is placed, so
-        an inverter that appears after another's feed has arrived, within the
-        same wait, gets a whole grace of its own.
+        The feed and model waits are bounded by `FEED_GRACE_S`. A DER may be
+        published with no connection record pointing at it, and a declared
+        model may never be valued; then no value is coming. Both land in the
+        same burst as the circuits' names, so once every name and firmware
+        version has arrived, a feed or model still unvalued after the grace is
+        taken as absent and reported once per device at INFO, rather than the
+        transport warning after the full name timeout. An inverter whose feed
+        was taken as absent is keyed by its device id; a model fills device
+        metadata only, so one that lands later moves nothing. Each device's
+        grace starts when it is first waited on alone and restarts whenever a
+        name or firmware version is missing again, so a device that appears
+        after another's grace has run gets a whole grace of its own.
         """
         roles = TreeRoles(self._children())
-        missing = [circuit.device_id for circuit in roles.circuits if not circuit.get_property(NODE_INFO, PROP_NAME)]
+        missing = [
+            circuit.device_id
+            for circuit in roles.circuits
+            if PROP_NAME in circuit.get_node_properties(NODE_INFO) and not circuit.get_property(NODE_INFO, PROP_NAME)
+        ]
+        missing.extend(self._firmware_version_pending(roles))
         ders = (roles.bess, *roles.pvs, *roles.evse)
-        missing.extend(
-            device.device_id
+        graced = {
+            device.device_id: f"{NODE_INFO}/{PROP_MODEL}"
             for device in ders
             if device is not None
             and PROP_MODEL in device.get_node_properties(NODE_INFO)
             and device.get_property(NODE_INFO, PROP_MODEL) is None
+        }
+        graced.update(
+            (circuit_id, f"{NODE_CONNECTION}/{PROP_FEEDS_DEVICE_ID}")
+            for circuit_id in _unvalued_feeds_for_unplaced_pvs(roles)
         )
-        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 = []
-        else:
-            # No feed is being waited out on its own: something else is still
-            # missing, or every inverter is placed. Either way a later feed wait
-            # is a new one and gets the whole grace.
-            self._feed_wait_since = None
-            if not feeds:
-                self._feed_wait_reported = False
-        missing.extend(feeds)
+        missing.extend(self._within_grace(graced, held=bool(missing)))
         return missing
 
+    def _within_grace(self, pending: dict[str, str], *, held: bool) -> list[str]:
+        """The devices of `pending` whose grace has not run out.
+
+        `pending` maps each device to the declared `node/property` it has not
+        valued. While `held`, something without a grace is still missing, so
+        every device is waited on and no grace runs. A device whose grace runs
+        out is reported once, and stops being waited on until its value arrives
+        or a hold starts its grace again.
+        """
+        for device_id in self._grace_since.keys() - pending.keys():
+            del self._grace_since[device_id]
+        self._grace_reported &= pending.keys()
+        if held:
+            self._grace_since.clear()
+            return list(pending)
+        now = self._clock()
+        waiting: list[str] = []
+        for device_id, path in pending.items():
+            if now - self._grace_since.setdefault(device_id, now) < FEED_GRACE_S:
+                waiting.append(device_id)
+            elif device_id not in self._grace_reported:
+                _LOGGER.info("%s declares %s and has not published it; taking it as absent", device_id, path)
+                self._grace_reported.add(device_id)
+        return waiting
+
     def _firmware_version_pending(self, roles: TreeRoles) -> list[str]:
         """The panel itself, while a declared BESS waits on the panel's firmware version.
 
@@ -308,7 +357,7 @@ class SchemaOneAdapter:
         """Where this circuit's relay is commanded, or None if it may not be.
 
         **None where the panel declares the relay non-commandable**, by either of
-        the two signals `relay_is_settable` reads. `_target` is pure string
+        the two signals `relay_is_settable` reads. `control_target` is pure string
         formatting from a device id, so building the topic unconditionally aimed
         a write at a circuit the panel commissioned as always-on — every part of
         the refusal was already in the tree, and nothing consulted it.
@@ -325,7 +374,7 @@ class SchemaOneAdapter:
         device = self._child(circuit_id)
         if device is None or not relay_is_settable(device):
             return None
-        return self._target(circuit_id, NODE_SWITCH, PROP_RELAY)
+        return control_target(circuit_id, NODE_SWITCH, PROP_RELAY)
 
     def set_circuit_priority_target(self, circuit_id: str) -> ControlTarget | None:
         """Where this circuit's shed priority is written, or None if it may not be.
@@ -342,7 +391,7 @@ class SchemaOneAdapter:
         device = self._child(circuit_id)
         if device is None or not priority_is_settable(device):
             return None
-        return self._target(circuit_id, NODE_LOAD_SHED, PROP_PRIORITY)
+        return control_target(circuit_id, NODE_LOAD_SHED, PROP_PRIORITY)
 
     def has_circuit(self, circuit_id: str) -> bool:
         """Whether the tree carries a circuit under this id.
@@ -398,7 +447,7 @@ class SchemaOneAdapter:
         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)
+        return control_target(self._serial_number, NODE_SHED, PROP_ASSERTED_ISLANDING_STATE)
 
     def dominant_power_source_payload(self, value: str) -> str | None:
         """Translate a flat `dominant-power-source` value into an assertion.
@@ -447,7 +496,7 @@ class SchemaOneAdapter:
         if writable is None:
             return None
         device, surface, limit = writable
-        return self._target(device.device_id, surface.node, limit.property_id)
+        return control_target(device.device_id, surface.node, limit.property_id)
 
     def evse_charge_limit_payload(self, node_id: str, amps: int) -> str | None:
         """The payload to publish for `amps`, or None if it may not be published.
@@ -514,25 +563,6 @@ class SchemaOneAdapter:
             return device, surface, surface.limit
         return None
 
-    def _target(self, device_id: str, node: str, prop: str) -> ControlTarget:
-        """One device/node/property address as both a set topic and an observation key.
-
-        The triple is returned alongside the topic rather than left for the
-        transport to parse back out of it: the transport is the one component
-        that is supposed to know nothing about this schema's topic grammar, and
-        under parent/child the device is a peer of the panel rather than a node
-        beneath it, so the grammar is not even the flat one.
-
-        The spelling here is the spelling `_on_property_changed` reports under,
-        because a write is verified by matching one against the other.
-        """
-        return ControlTarget(
-            topic=f"{HOMIE_DOMAIN}/{HOMIE_VERSION}/{device_id}/{node}/{prop}/set",
-            device_id=device_id,
-            node_id=node,
-            property_id=prop,
-        )
-
     def _require_root(self) -> DiscoveredDevice:
         """The root, or a clear error if discovery has not finished.
 

{span_panel_api_schema_1-1.3.0b1 → span_panel_api_schema_1-1.4.0b2}/src/span_panel_api_schema_1/adoption.py

@@ -25,6 +25,7 @@ from span_panel_api.models import ADOPTION_IDENTITY_NODE, ADOPTION_TOPOLOGY_NODE
 from span_panel_api_schema_1.const import (
     HOMIE_DOMAIN,
     HOMIE_VERSION,
+    SITE_PROPERTIES,
     TYPE_BESS,
     TYPE_CIRCUIT,
     TYPE_EVSE,
@@ -132,7 +133,7 @@ def _adopt(device: DiscoveredDevice, declared: str) -> AdoptedDevice:
 
 
 def _readings(device: DiscoveredDevice, declared_nodes: dict[str, dict[str, object]]) -> tuple[AdoptedProperty, ...]:
-    """Every declared property outside the identity and topology nodes.
+    """Every declared property outside the identity and topology nodes, and no site property.
 
     Those two are excluded by *node*, which is what the eBus vocabulary defines,
     rather than by property name. The catalogs carry no marker for "this string
@@ -146,6 +147,8 @@ def _readings(device: DiscoveredDevice, declared_nodes: dict[str, dict[str, obje
         if node_id in (ADOPTION_IDENTITY_NODE, ADOPTION_TOPOLOGY_NODE):
             continue
         for property_id, definition in properties(node).items():
+            if property_id in SITE_PROPERTIES:
+                continue
             raw = device.get_property(node_id, property_id)
             # The same reading the curated controls get: this one gates a set
             # topic on an uncurated device, so a declaration that has not said

{span_panel_api_schema_1-1.3.0b1 → span_panel_api_schema_1-1.4.0b2}/src/span_panel_api_schema_1/circuits.py

@@ -8,7 +8,7 @@ derivations are defined by the migration guide, not invented here:
 ======================  ===========================================================
 Flat property           v1.0 source
 ======================  ===========================================================
-``always-on``           ``switch/relay-controllable``, inverted
+``always-on``           ``switch/relay-controllable``, inverted, where a relay is declared
 ``never-backup``        ``$settable`` on ``load-shed/priority``, inverted
 ``sheddable``           computed: a shed priority and ``relay-controllable``
 ======================  ===========================================================
@@ -24,15 +24,31 @@ frame: a normal load reads **negative** ``active-power`` and accumulates
 ``exported-energy`` (the panel exported it *to* the circuit). The snapshot
 reports consumption as positive, so power is negated and the two energy
 accumulators are swapped.
+
+**A circuit-typed device that declares no breaker space is a meter outside the
+panel**, and none of that applies to it. Its ``active-power`` is already
+import-positive (positive = flowing into the panel), so it is reported as
+published, with ``imported-energy`` as consumed and ``exported-energy`` as
+produced: consumed minus produced is net import. The classification reads the
+declaration, never a value, so a meter that has not reported is already outside
+the panel and a hosted circuit that has not reported is still hosted.
 """
 
 from __future__ import annotations
 
 from typing import TYPE_CHECKING, Final
 
-from span_panel_api.models import SpanCircuitSnapshot
+from span_panel_api.models import (
+    FEEDS_ROLES,
+    PROTECTION_FUNCTIONS,
+    FeedsRole,
+    ProtectionFunction,
+    SpanCircuitSnapshot,
+    device_id_order,
+)
 from span_panel_api_schema_1.const import (
     NODE_BREAKER,
+    NODE_CONNECTION,
     NODE_INFO,
     NODE_LOAD_SHED,
     NODE_METER,
@@ -43,21 +59,28 @@ from span_panel_api_schema_1.const import (
     PROP_ACTIVE_POWER,
     PROP_CURRENT,
     PROP_EXPORTED_ENERGY,
+    PROP_FEEDS_ROLE,
     PROP_IMPORTED_ENERGY,
     PROP_MANAGED,
     PROP_NAME,
+    PROP_NOMINAL_VOLTAGE,
     PROP_POLES,
     PROP_PRIORITY,
+    PROP_PROTECTION_FUNCTIONS,
     PROP_RATING,
     PROP_RELAY,
     PROP_RELAY_CONTROLLABLE,
     PROP_RELAY_REQUESTER,
+    PROP_SHARED_WITH_DEVICE_IDS,
     PROP_SPACES,
     UNKNOWN,
 )
 from span_panel_api_schema_1.description import declared_settable, node_properties
+from span_panel_api_schema_1.panel import declares_node
 
 if TYPE_CHECKING:
+    from collections.abc import Collection
+
     from ebus_sdk.homie import DiscoveredDevice
 
 _SHED_PRIORITIES: Final = frozenset({PRIORITY_OFF_GRID, PRIORITY_SOC_THRESHOLD})
@@ -88,10 +111,11 @@ def _number(device: DiscoveredDevice, node: str, prop: str) -> float | None:
 def _flag(device: DiscoveredDevice, node: str, prop: str, *, default: bool) -> bool:
     """Read a Homie boolean. Absent means `default`, which is not always False.
 
-    `relay-controllable` absent has to mean *controllable*, because the
-    property exists to mark the exception (an always-on circuit). Defaulting it
-    to False would silently make every circuit uncontrollable on a panel that
-    omits it.
+    `relay-controllable` absent has to mean *controllable* on a device that
+    declares a relay, because the property exists to mark the exception (an
+    always-on circuit). Defaulting it to False would silently make every circuit
+    uncontrollable on a panel that omits it. See `_relay_controllable` for a
+    device that declares no relay.
     """
     raw = device.get_property(node, prop)
     if raw is None or raw == "":
@@ -125,6 +149,28 @@ def _optional_integer(device: DiscoveredDevice, node: str, prop: str) -> int | N
     return None if raw is None else int(raw)
 
 
+def declares_spaces(device: DiscoveredDevice) -> bool:
+    """Whether the device's `$description` declares ``info/spaces``.
+
+    The hosted-or-outside question, asked of the declaration because a value
+    cannot answer it: a hosted circuit whose spaces have not arrived yet and a
+    meter that has none read the same until the values land, and a consumer
+    that keyed the sign of a reading on that gap would book the first readings
+    of every hosted circuit backwards.
+    """
+    return PROP_SPACES in node_properties(device, NODE_INFO)
+
+
+def _relay_controllable(device: DiscoveredDevice) -> bool:
+    """``switch/relay-controllable``, defaulting to whether a relay is declared at all.
+
+    A device that declares no ``switch`` node has no relay to command, so it is
+    not controllable whatever it leaves unpublished; one that declares the node
+    and leaves the property unvalued is, for the reason `_flag` gives.
+    """
+    return _flag(device, NODE_SWITCH, PROP_RELAY_CONTROLLABLE, default=declares_node(device, NODE_SWITCH))
+
+
 def _tabs(device: DiscoveredDevice) -> list[int]:
     """Breaker spaces from ``info/spaces``.
 
@@ -235,21 +281,68 @@ def relay_is_settable(device: DiscoveredDevice) -> bool:
     specification's rule showing up in hardware. The vendored capture carries
     the same pattern on its five.
     """
-    return _settable(device, NODE_SWITCH, PROP_RELAY) and _flag(device, NODE_SWITCH, PROP_RELAY_CONTROLLABLE, default=True)
+    return _settable(device, NODE_SWITCH, PROP_RELAY) and _relay_controllable(device)
+
+
+def _feeds_role(device: DiscoveredDevice) -> FeedsRole | None:
+    """The declared `connection/feeds-role`, or None when unpublished or outside the role set."""
+    published = _text(device, NODE_CONNECTION, PROP_FEEDS_ROLE)
+    return next((role for role in FEEDS_ROLES if role == published), None)
+
+
+def _protection_functions(device: DiscoveredDevice) -> tuple[ProtectionFunction, ...] | None:
+    """The published `breaker/protection-functions`, in order, or None when unpublished.
+
+    A comma-separated list of the enum's members; a value outside
+    `PROTECTION_FUNCTIONS` is dropped rather than passed on.
+    """
+    published = device.get_property(NODE_BREAKER, PROP_PROTECTION_FUNCTIONS)
+    if published is None:
+        return None
+    listed = [part.strip() for part in str(published).split(",")]
+    return tuple(function for part in listed for function in PROTECTION_FUNCTIONS if function == part)
+
+
+def _shared_with(device: DiscoveredDevice, node: str, circuit_ids: Collection[str]) -> tuple[str, ...] | None:
+    """One node's `shared-with-device-ids`, resolved to the other circuits of the snapshot.
+
+    A circuit's snapshot key is its device id, so resolving keeps the listed ids
+    that name another circuit, in `device_id_order`. `None` while the list is
+    undeclared or unpublished; an empty tuple where it names no known circuit.
+    """
+    published = device.get_property(node, PROP_SHARED_WITH_DEVICE_IDS)
+    if published is None:
+        return None
+    listed = {part.strip() for part in str(published).split(",")}
+    return tuple(sorted((listed & set(circuit_ids)) - {device.device_id}, key=device_id_order))
 
 
 def build_circuit(
-    device: DiscoveredDevice, device_type: str = "circuit", relative_position: str = ""
+    device: DiscoveredDevice,
+    device_type: str = "circuit",
+    relative_position: str = "",
+    circuit_ids: Collection[str] = frozenset(),
 ) -> SpanCircuitSnapshot:
-    """Build one circuit snapshot from its v1.0 device."""
-    raw_power = _number(device, NODE_METER, PROP_ACTIVE_POWER)
-    # Negate so positive means consumption. The guard keeps -0.0 out of the
-    # snapshot, where it would compare equal to 0.0 but format as "-0.0".
-    # A meter that has not reported stays `None` rather than becoming 0.0 W —
-    # see `SpanCircuitSnapshot` for why absent and zero must not collapse.
-    instant_power_w = None if raw_power is None else (0.0 if raw_power == 0.0 else -raw_power)
+    """Build one circuit snapshot from its v1.0 device.
 
-    relay_controllable = _flag(device, NODE_SWITCH, PROP_RELAY_CONTROLLABLE, default=True)
+    `circuit_ids` is every circuit device id in the tree, against which the
+    circuit's shared-with lists are resolved.
+    """
+    outside = not declares_spaces(device)
+    raw_power = _number(device, NODE_METER, PROP_ACTIVE_POWER)
+    # A hosted circuit is negated so positive means consumption; a meter outside
+    # the panel is already import-positive and is reported as published. The
+    # guard keeps -0.0 out of the snapshot, where it would compare equal to 0.0
+    # but format as "-0.0". A meter that has not reported stays `None` rather
+    # than becoming 0.0 W — see `SpanCircuitSnapshot` for why absent and zero
+    # must not collapse.
+    frame = 1.0 if outside else -1.0
+    instant_power_w = None if raw_power is None else (0.0 if raw_power == 0.0 else frame * raw_power)
+    imported_wh = _number(device, NODE_METER, PROP_IMPORTED_ENERGY)
+    exported_wh = _number(device, NODE_METER, PROP_EXPORTED_ENERGY)
+    poles = _number(device, NODE_BREAKER, PROP_POLES)
+
+    relay_controllable = _relay_controllable(device)
     priority = _text(device, NODE_LOAD_SHED, PROP_PRIORITY, UNKNOWN)
     priority_settable = priority_is_settable(device)
 
@@ -258,11 +351,12 @@ def build_circuit(
         name=_text(device, NODE_INFO, PROP_NAME),
         relay_state=_text(device, NODE_SWITCH, PROP_RELAY, UNKNOWN),
         instant_power_w=instant_power_w,
-        # The panel *imported* this energy from the circuit, so the circuit
-        # produced it. Named from the panel's perspective, reported from the
-        # circuit's.
-        produced_energy_wh=_number(device, NODE_METER, PROP_IMPORTED_ENERGY),
-        consumed_energy_wh=_number(device, NODE_METER, PROP_EXPORTED_ENERGY),
+        # On a hosted circuit the panel *imported* this energy from the
+        # circuit, so the circuit produced it: named from the panel's
+        # perspective, reported from the circuit's. A meter outside the panel
+        # measures the panel's own import, so its imported energy is consumed.
+        produced_energy_wh=exported_wh if outside else imported_wh,
+        consumed_energy_wh=imported_wh if outside else exported_wh,
         tabs=_tabs(device),
         priority=priority,
         # `always-on` is `not relay-controllable`, and the flat schema derived
@@ -273,10 +367,18 @@ def build_circuit(
         is_never_backup=not priority_settable,
         device_type=device_type,
         relative_position=relative_position,
-        is_240v=(_number(device, NODE_BREAKER, PROP_POLES) or 1) >= 2,
+        nominal_voltage_v=_number(device, NODE_INFO, PROP_NOMINAL_VOLTAGE),
+        protection_functions=_protection_functions(device),
+        feeds_role=_feeds_role(device),
+        meter_shared_with=_shared_with(device, NODE_METER, circuit_ids),
+        relay_shared_with=_shared_with(device, NODE_SWITCH, circuit_ids),
+        # Unknown without a pole count: a meter outside the panel has no
+        # breaker, and a breaker whose count has not arrived has not said.
+        is_240v=None if poles is None else poles >= 2,
         current_a=_number(device, NODE_METER, PROP_CURRENT),
         breaker_rating_a=_number(device, NODE_BREAKER, PROP_RATING),
-        always_on=not relay_controllable,
+        # A relay locked closed. A device with no relay is not "on" at all.
+        always_on=declares_node(device, NODE_SWITCH) and not relay_controllable,
         relay_requester=_text(device, NODE_SWITCH, PROP_RELAY_REQUESTER, UNKNOWN),
         relay_state_target=device.get_property_target(NODE_SWITCH, PROP_RELAY),
         priority_target=device.get_property_target(NODE_LOAD_SHED, PROP_PRIORITY),
@@ -291,4 +393,5 @@ def build_circuit(
         # policy, both, or neither, so they are read separately and named apart.
         pcs_managed=_optional_flag(device, NODE_PCS, PROP_MANAGED),
         pcs_priority=_optional_integer(device, NODE_PCS, PROP_PRIORITY),
+        measures_outside_panel=outside,
     )

{span_panel_api_schema_1-1.3.0b1 → span_panel_api_schema_1-1.4.0b2}/src/span_panel_api_schema_1/const.py

@@ -8,6 +8,9 @@ look unchanged are addressed differently.
 
 from __future__ import annotations
 
+from collections.abc import Mapping
+from typing import Final
+
 # -- Device classes ---------------------------------------------------------
 
 DEVICE_TYPE_PREFIX = "energy.ebus.device."
@@ -41,6 +44,32 @@ NODE_CONNECTION = "connection"
 # imports `panel` -- so the constant has to live below both of them.
 PROP_FEEDS_DEVICE_ID = "feeds-device-id"
 PROP_FEEDS_DEVICE_STATUS = "feeds-device-status"
+PROP_FEEDS_ROLE = "feeds-role"
+PROP_SHARED_WITH_DEVICE_IDS = "shared-with-device-ids"
+PROP_OVERCURRENT_PROTECTION = "overcurrent-protection"
+PROP_BUSBAR_CURRENT = "busbar-current"
+PROP_FREQUENCY = "frequency"
+PROP_NOMINAL_VOLTAGE = "nominal-voltage"
+PROP_PROTECTION_FUNCTIONS = "protection-functions"
+
+SITE_PROPERTIES: Final[frozenset[str]] = frozenset(
+    {
+        "address-lines",
+        "locality",
+        "region",
+        "country-code",
+        "latitude",
+        "longitude",
+        "utility-meter-serial-number",
+    }
+)
+"""Property ids that say where a panel is installed, which never become a reading.
+
+Skipped by `extension` and `adoption` on whatever node a device declares them.
+Where the panel declares them, under `info` beside the site's `info/name`, the
+identity node is skipped as a whole already; this holds if a device declares
+them anywhere else. They stay discovery rows, which carry no values.
+"""
 PROP_FED_BY_DEVICE_ID = "fed-by-device-id"
 PROP_FED_BY_DEVICE_STATUS = "fed-by-device-status"
 NODE_DOOR = "door"
@@ -194,6 +223,17 @@ PANEL_SIZE_BY_MODEL: dict[str, int] = {
     "MLO_48": 48,
 }
 
+# The first and last breaker position for each model. Keyed like
+# `PANEL_SIZE_BY_MODEL`, and like it the numbers are ours: the panel publishes
+# only which positions are occupied.
+PANEL_POSITIONS_BY_MODEL: Final[Mapping[str, tuple[int, int]]] = {
+    "MAIN_16": (9, 24),
+    "MLO_24": (1, 24),
+    "MAIN_32": (1, 32),
+    "MAIN_40": (9, 48),
+    "MLO_48": (1, 48),
+}
+
 # The Homie attribute that carries what the flat schema published as the
 # `never-backup` boolean. v1.0 retires the property and expresses it as
 # mutability: a circuit commissioned never-backup has its priority locked, and