span-panel-api-schema-1 1.2.2__tar.gz → 1.4.0b1__tar.gz

{span_panel_api_schema_1-1.2.2 → span_panel_api_schema_1-1.4.0b1}/CHANGELOG.md

@@ -9,6 +9,31 @@ 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.
 
+## [Unreleased]
+
+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.
+
+### Removed
+
+- **BREAKING FOR CONSUMERS: `snapshot.build_snapshot()` no longer takes the `ready_since` argument**, which no caller in this repository passed, so a call that passes it by keyword or position now raises `TypeError`.
+
+- **BREAKING: snapshots no longer include synthesised `unmapped_tab_N` entries for unoccupied breaker positions, which carried no measured data**, and `panel.build_unmapped_tabs` and `const.UNMAPPED_TAB_PREFIX` are gone with them.
+
+### Fixed
+
+- **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.**
+
 ## [1.2.2]
 
 Requires `span-panel-api` **3.6.2 or newer**, which waits on this parser's missing labels after a reconnect as well as on connect.

{span_panel_api_schema_1-1.2.2 → span_panel_api_schema_1-1.4.0b1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: span-panel-api-schema-1
-Version: 1.2.2
+Version: 1.4.0b1
 Summary: Parent/child schema (data-model-version 1.x) parser for span-panel-api
 Project-URL: Homepage, https://github.com/SpanPanel/span-panel-api
 Project-URL: Issues, https://github.com/SpanPanel/span-panel-api/issues
@@ -8,7 +8,7 @@ Author: SpanPanel
 License-Expression: MIT
 Requires-Python: <4.0,>=3.14
 Requires-Dist: ebus-sdk<0.24,>=0.19.0
-Requires-Dist: span-panel-api<4.0,>=3.6.2
+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.2.2 → span_panel_api_schema_1-1.4.0b1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "span-panel-api-schema-1"
-version = "1.2.2"
+version = "1.4.0b1"
 description = "Parent/child schema (data-model-version 1.x) parser for span-panel-api"
 authors = [
     {name = "SpanPanel"}
@@ -28,7 +28,12 @@ dependencies = [
     # Raised to 3.6.1, whose SpanPanelSnapshot.pv documents what this parser builds.
     # Raised to 3.6.2, which waits on this parser's missing labels after a bridge
     # rebuild as well as on connect; the fix spans both, so the pair moves together.
-    "span-panel-api>=3.6.2,<4.0",
+    # 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.
+    # 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.2.2 → span_panel_api_schema_1-1.4.0b1}/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]] = []
@@ -167,10 +169,10 @@ class SchemaOneAdapter:
 
         The model is required only when the root's description declares it: the
         panel's size comes from nowhere else, and a snapshot built a moment too
-        early reports zero spaces, which erases every unmapped position rather
-        than merely mis-stating a number. Asking only for what the panel itself
-        promised keeps a firmware that omits the property connectable — it
-        falls back to the drift warning in `panel_size_from_model`.
+        early reports zero spaces, which leaves a consumer laying out the
+        panel's positions with none to lay out. Asking only for what the panel
+        itself promised keeps a firmware that omits the property connectable —
+        it falls back to the drift warning in `panel_size_from_model`.
         """
         root = self._controller.get_root(self._serial_number)
         if root is None or root.state != STATE_READY or not root.description:
@@ -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.2.2 → span_panel_api_schema_1-1.4.0b1}/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.2.2 → span_panel_api_schema_1-1.4.0b1}/src/span_panel_api_schema_1/circuits.py

@@ -8,52 +8,84 @@ 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: ``priority != NEVER and relay-controllable``
+``sheddable``           computed: a shed priority and ``relay-controllable``
 ======================  ===========================================================
 
+A shed priority is ``OFF_GRID`` or ``SOC_THRESHOLD``. SPAN's r202633 changelog
+derives sheddable as ``priority != NEVER`` and asks consumers to treat ``UNKNOWN``
+as "not yet known" rather than as sheddable, so the rule names the priorities the
+panel sheds by instead of excluding the one it never sheds.
+
 Sign and direction are unchanged from the flat schema, and both are the reverse
 of what the property names suggest. Values are in the enclosure's reference
 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
+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,
     NODE_PCS,
     NODE_SWITCH,
-    PRIORITY_NEVER,
+    PRIORITY_OFF_GRID,
+    PRIORITY_SOC_THRESHOLD,
     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})
+"""The `load-shed/priority` values the panel sheds a circuit by; see the module docstring."""
+
 
 def _text(device: DiscoveredDevice, node: str, prop: str, default: str = "") -> str:
     value = device.get_property(node, prop)
@@ -79,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 == "":
@@ -116,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``.
 
@@ -226,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)
 
@@ -249,25 +351,34 @@ 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
         # user-controllability from `always-on` — so this is the same answer by
         # a shorter route.
         is_user_controllable=relay_controllable,
-        is_sheddable=priority != PRIORITY_NEVER and relay_controllable,
+        is_sheddable=priority in _SHED_PRIORITIES and relay_controllable,
         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),
@@ -282,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,
     )