span-panel-api-schema-1 0.1.0b1__py3-none-any.whl

span_panel_api_schema_1/__init__.py

@@ -0,0 +1,6 @@
+"""Parent/child schema (data-model-version 1.x) parser for span-panel-api."""
+
+from span_panel_api_schema_1.adapter import SchemaOneAdapter
+from span_panel_api_schema_1.transport import ControllerRoutes
+
+__all__ = ["ControllerRoutes", "SchemaOneAdapter"]

span_panel_api_schema_1/adapter.py

@@ -0,0 +1,255 @@
+"""Parent/child adapter: `ebus_sdk.Controller` behind the `SchemaAdapter` protocol.
+
+The SDK does the Homie work — walking `$description.children`, gating each
+child's subscription on its parent reaching `ready`, and cascading state down
+the tree. This adapter supplies the transport it parses over, sorts the result
+into a `SpanPanelSnapshot`, and builds the topics the transport publishes
+commands to.
+
+**It never touches the connection.** `SchemaAdapter` instances are built before
+one exists, so `Controller` is given a route table (`ControllerRoutes`) that
+records its subscriptions instead of making them, and this adapter asks for one
+broad subscription up front through `topics_to_subscribe()`. Every message then
+arrives via `handle_message` and is routed to whichever SDK callback wanted it.
+A reconnect re-subscribes that same static list, the broker replays the retained
+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
+
+from ebus_sdk import Controller
+
+from span_panel_api_schema_1.const import (
+    HOMIE_DOMAIN,
+    HOMIE_VERSION,
+    NODE_INFO,
+    NODE_LOAD_SHED,
+    NODE_SWITCH,
+    PROP_MODEL,
+    PROP_NAME,
+    PROP_PRIORITY,
+    PROP_RELAY,
+    STATE_READY,
+)
+from span_panel_api_schema_1.field_metadata import build_field_metadata
+from span_panel_api_schema_1.snapshot import TreeRoles, build_snapshot, device_type
+from span_panel_api_schema_1.transport import ControllerRoutes
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from ebus_sdk.homie import DiscoveredDevice
+
+    from span_panel_api.models import FieldMetadata, SpanPanelSnapshot, V2HomieSchema
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class SchemaOneAdapter:
+    """Parser for the parent/child schema (data-model-version 1.x)."""
+
+    schema_major = "schema_1"
+    SUPPORTS_DATA_MODEL_VERSIONS: tuple[str, str] = (">=1.0", "<2.0")
+
+    def __init__(self, serial_number: str, schema: V2HomieSchema) -> None:
+        self._serial_number = serial_number
+        self._schema = schema
+        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]] = []
+        self._awaiting: tuple[str, ...] = ()
+        self._controller.set_on_property_changed_callback(self._on_property_changed)
+        # Records the subscriptions the tree walk needs; nothing reaches the
+        # wire, because this object has no connection to reach it with.
+        self._controller.start_discovery()
+
+    # -- SchemaAdapter -----------------------------------------------------
+
+    def topics_to_subscribe(self) -> list[str]:
+        """One subscription covering the whole tree.
+
+        Deliberately broader than the SDK's own per-device subscriptions,
+        because the adapter is asked this once at connect and again after a
+        reconnect — it has no way to add one when a child announces later. The
+        flat adapter takes the same approach with `ebus/5/{serial}/#`; here the
+        wildcard spans devices, since children are peers of the panel in the
+        topic tree rather than nodes beneath it.
+        """
+        return [f"{HOMIE_DOMAIN}/{HOMIE_VERSION}/#"]
+
+    def handle_message(self, topic: str, payload: str) -> None:
+        self._routes.dispatch(topic, payload)
+
+    def is_ready(self) -> bool:
+        """Ready when the whole declared tree has described itself.
+
+        The flat schema gets its entire topology in one `$description`, so
+        "described" and "complete" are the same event. Under parent/child the
+        topology arrives as one description per device, and the root's says
+        ready as soon as *its own* arrives — while its children are still
+        landing. Treating that as ready hands the transport a panel with a
+        handful of circuits and no model, which it reports as a healthy
+        connection. So readiness waits for every device the tree declares.
+
+        Child *state* is deliberately not required. A commissioned DER that is
+        currently offline publishes `lost` but keeps its retained description,
+        and a panel should not fail to connect because a battery is unplugged.
+
+        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`.
+        """
+        root = self._controller.get_root(self._serial_number)
+        if root is None or root.state != STATE_READY or not root.description:
+            return False
+        if self._awaiting_descriptions(root):
+            return False
+        return self._model_arrived(root)
+
+    def build_snapshot(self) -> SpanPanelSnapshot:
+        root = self._require_root()
+        return build_snapshot(root, self._children())
+
+    def build_field_metadata(self) -> dict[str, FieldMetadata]:
+        root = self._controller.get_root(self._serial_number)
+        devices = [] if root is None else [root, *self._children()]
+        return build_field_metadata(devices)
+
+    def circuit_nodes_missing_names(self) -> list[str]:
+        """Devices whose retained identity has not arrived yet.
+
+        The transport polls this during connect so the first snapshot carries
+        real names rather than falling back to identifiers.
+
+        Readiness proves the tree's *shape* — every device the tree declares
+        has described itself. It cannot prove the tree's *labels*: a
+        description says which properties exist, and their retained values
+        arrive as separate messages that may land after the last description
+        does. That gap exists under the flat schema too; it just matters more
+        here, because a DER is its own device and the integration registers it
+        from this first snapshot.
+
+        Named for the flat schema's circuits, where a missing name was the only
+        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.
+        """
+        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)
+        missing.extend(
+            device.device_id
+            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
+        )
+        return missing
+
+    def find_node_by_type(self, type_str: str) -> str | None:
+        """Return the id of the first device declaring `type_str`.
+
+        Named for the flat schema's nodes; under parent/child the same question
+        is asked of devices, and the answer is a device id.
+        """
+        for device in self._children():
+            if device_type(device) == type_str:
+                return device.device_id
+        return None
+
+    # -- Command topics ----------------------------------------------------
+    #
+    # The adapter names the topic and the transport publishes it, so commanding
+    # a panel needs no connection here either.
+
+    def set_circuit_relay_topic(self, circuit_id: str) -> str:
+        return self._set_topic(circuit_id, NODE_SWITCH, PROP_RELAY)
+
+    def set_circuit_priority_topic(self, circuit_id: str) -> str:
+        return self._set_topic(circuit_id, NODE_LOAD_SHED, PROP_PRIORITY)
+
+    def set_dominant_power_source_topic(self) -> str | None:
+        """No v1.0 equivalent, so no topic.
+
+        `dominant-power-source` split into `grid-forming-entity` and
+        `asserted-islanding-state`, which are different controls on different
+        devices rather than a renamed one. Returning None makes the transport
+        reject the command instead of publishing to a topic nothing serves —
+        and which successor to expose is a product decision, tracked in the
+        entity and config deltas write-up.
+        """
+        return None
+
+    def register_property_callback(self, callback: Callable[[str, str, str, str | None], None]) -> Callable[[], None]:
+        """Subscribe to per-property updates; returns an unregister callable."""
+        self._property_callbacks.append(callback)
+
+        def _unregister() -> None:
+            if callback in self._property_callbacks:
+                self._property_callbacks.remove(callback)
+
+        return _unregister
+
+    # -- internals ---------------------------------------------------------
+
+    def _set_topic(self, device_id: str, node: str, prop: str) -> str:
+        return f"{HOMIE_DOMAIN}/{HOMIE_VERSION}/{device_id}/{node}/{prop}/set"
+
+    def _require_root(self) -> DiscoveredDevice:
+        """The root, or a clear error if discovery has not finished.
+
+        Checks readiness rather than existence: `start_discovery` pre-creates
+        the root entry so descendants have somewhere to attach, so the device
+        object exists from construction and proves nothing on its own.
+        """
+        root = self._controller.get_root(self._serial_number)
+        if root is None or not self.is_ready():
+            raise RuntimeError(f"Device tree for {self._serial_number!r} is not ready; build_snapshot called too early")
+        return root
+
+    def _children(self) -> list[DiscoveredDevice]:
+        return list(self._controller.get_descendants(self._serial_number))
+
+    def _awaiting_descriptions(self, root: DiscoveredDevice) -> tuple[str, ...]:
+        """Devices the tree declares that have not described themselves yet.
+
+        Walks declarations rather than discoveries, and at any depth: a child
+        may declare children of its own, and those count too. Logged when the
+        set changes, because the alternative diagnostic for a tree that never
+        completes is a bare 30-second connect timeout.
+        """
+        described = {device.device_id: device for device in self._children() if device.description is not None}
+        awaiting = {
+            child_id
+            for device in (root, *described.values())
+            for child_id in device.children_ids
+            if child_id not in described
+        }
+        pending = tuple(sorted(awaiting))
+        if pending != self._awaiting:
+            self._awaiting = pending
+            if pending:
+                _LOGGER.debug("Waiting on %d declared devices: %s", len(pending), ", ".join(pending))
+        return pending
+
+    def _model_arrived(self, root: DiscoveredDevice) -> bool:
+        """Whether the panel has published the model it said it would."""
+        if PROP_MODEL not in root.get_node_properties(NODE_INFO):
+            return True
+        return root.get_property(NODE_INFO, PROP_MODEL) is not None
+
+    def _on_property_changed(self, device_id: str, node_id: str, property_id: str, value: str, _old: str | None) -> None:
+        """Fan a Controller property change out to registered consumers.
+
+        Signature adapts the SDK's five arguments to the protocol's four: the
+        protocol has no place for the previous value, and consumers that need
+        one keep it themselves.
+        """
+        for callback in list(self._property_callbacks):
+            callback(device_id, node_id, property_id, value)

span_panel_api_schema_1/circuits.py

@@ -0,0 +1,177 @@
+"""Map a v1.0 circuit device onto ``SpanCircuitSnapshot``.
+
+The snapshot's field names come from the v1 REST API and are preserved so the
+integration's entities do not move. Three of them no longer have a property to
+read, because v1.0 consolidated four flat mechanisms into two. Their
+derivations are defined by the migration guide, not invented here:
+
+======================  ===========================================================
+Flat property           v1.0 source
+======================  ===========================================================
+``always-on``           ``switch/relay-controllable``, inverted
+``never-backup``        ``$settable`` on ``load-shed/priority``, inverted
+``sheddable``           computed: ``priority != NEVER and relay-controllable``
+======================  ===========================================================
+
+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.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from span_panel_api.models import SpanCircuitSnapshot
+from span_panel_api_schema_1.const import (
+    ATTR_SETTABLE,
+    NODE_BREAKER,
+    NODE_INFO,
+    NODE_LOAD_SHED,
+    NODE_METER,
+    NODE_SWITCH,
+    PRIORITY_NEVER,
+    PROP_ACTIVE_POWER,
+    PROP_CURRENT,
+    PROP_EXPORTED_ENERGY,
+    PROP_IMPORTED_ENERGY,
+    PROP_NAME,
+    PROP_POLES,
+    PROP_PRIORITY,
+    PROP_RATING,
+    PROP_RELAY,
+    PROP_RELAY_CONTROLLABLE,
+    PROP_RELAY_REQUESTER,
+    PROP_SPACES,
+    UNKNOWN,
+)
+
+if TYPE_CHECKING:
+    from ebus_sdk.homie import DiscoveredDevice
+
+
+def _text(device: DiscoveredDevice, node: str, prop: str, default: str = "") -> str:
+    value = device.get_property(node, prop)
+    return default if value is None else str(value)
+
+
+def _number(device: DiscoveredDevice, node: str, prop: str) -> float | None:
+    """Read a numeric property, or None when it is absent or unparseable.
+
+    Unparseable is treated as absent rather than as an error: a single
+    malformed value must not take down a whole snapshot, and the field it
+    feeds is optional.
+    """
+    raw = device.get_property(node, prop)
+    if raw is None or raw == "":
+        return None
+    try:
+        return float(raw)
+    except (TypeError, ValueError):
+        return 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.
+    """
+    raw = device.get_property(node, prop)
+    if raw is None or raw == "":
+        return default
+    return str(raw).strip().lower() == "true"
+
+
+def _tabs(device: DiscoveredDevice) -> list[int]:
+    """Breaker spaces from ``info/spaces``.
+
+    v1.0 publishes the occupied spaces literally (``"36,38"``), where the flat
+    schema published one space plus a `dipole` flag and left the consumer to
+    infer the second as ``space + 2``. Reading the list means a 3-pole breaker
+    reports three tabs instead of being silently truncated to two.
+    """
+    raw = _text(device, NODE_INFO, PROP_SPACES)
+    if not raw:
+        return []
+    tabs: list[int] = []
+    for part in raw.split(","):
+        part = part.strip()
+        if not part:
+            continue
+        try:
+            tabs.append(int(part))
+        except ValueError:
+            continue
+    return tabs
+
+
+def _priority_is_settable(device: DiscoveredDevice) -> bool:
+    """Whether ``load-shed/priority`` is user-settable on this circuit.
+
+    This is the successor to the flat ``never-backup`` boolean, and it is read
+    from the description rather than from a value topic — v1.0 expresses
+    never-backup as *mutability*, so the signal is the Homie ``$settable``
+    attribute on the property definition.
+
+    Absent means settable: locking is the exception a panel announces, so
+    treating an unannounced circuit as locked would mark every circuit
+    never-backup on a panel that does not publish the attribute.
+    """
+    definition = device.get_node_properties(NODE_LOAD_SHED).get(PROP_PRIORITY)
+    if not isinstance(definition, dict):
+        return True
+    settable = definition.get(ATTR_SETTABLE)
+    if settable is None:
+        return True
+    if isinstance(settable, bool):
+        return settable
+    return str(settable).strip().lower() != "false"
+
+
+def build_circuit(
+    device: DiscoveredDevice, device_type: str = "circuit", relative_position: str = ""
+) -> SpanCircuitSnapshot:
+    """Build one circuit snapshot from its v1.0 device."""
+    raw_power = _number(device, NODE_METER, PROP_ACTIVE_POWER) or 0.0
+    # 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".
+    instant_power_w = 0.0 if raw_power == 0.0 else -raw_power
+
+    relay_controllable = _flag(device, NODE_SWITCH, PROP_RELAY_CONTROLLABLE, default=True)
+    priority = _text(device, NODE_LOAD_SHED, PROP_PRIORITY, UNKNOWN)
+    priority_settable = _priority_is_settable(device)
+
+    return SpanCircuitSnapshot(
+        circuit_id=device.device_id,
+        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) or 0.0,
+        consumed_energy_wh=_number(device, NODE_METER, PROP_EXPORTED_ENERGY) or 0.0,
+        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_never_backup=not priority_settable,
+        device_type=device_type,
+        relative_position=relative_position,
+        is_240v=(_number(device, NODE_BREAKER, PROP_POLES) or 1) >= 2,
+        current_a=_number(device, NODE_METER, PROP_CURRENT),
+        breaker_rating_a=_number(device, NODE_BREAKER, PROP_RATING),
+        always_on=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),
+    )

span_panel_api_schema_1/const.py

@@ -0,0 +1,115 @@
+"""Wire vocabulary for the parent/child schema (data-model-version 1.x).
+
+Every name here is a v1.0 device class, capability node, or property id. Nothing
+in this module is shared with the flat schema: v1.0 moved each property from a
+node on one device to a capability node on its own device, so even names that
+look unchanged are addressed differently.
+"""
+
+from __future__ import annotations
+
+# -- Device classes ---------------------------------------------------------
+
+TYPE_PANEL = "energy.ebus.device.distribution-enclosure"
+TYPE_CIRCUIT = "energy.ebus.device.circuit"
+TYPE_BESS = "energy.ebus.device.bess"
+TYPE_PV = "energy.ebus.device.pv"
+TYPE_EVSE = "energy.ebus.device.evse"
+TYPE_MID = "energy.ebus.device.mid"
+TYPE_LUGS = "energy.ebus.device.lugs"
+
+# -- Capability nodes -------------------------------------------------------
+
+NODE_BREAKER = "breaker"
+NODE_CONNECTION = "connection"
+NODE_DOOR = "door"
+NODE_GRID = "grid"
+NODE_INFO = "info"
+NODE_LOAD_SHED = "load-shed"
+NODE_METER = "meter"
+NODE_PCS = "pcs"
+NODE_POWER_FLOWS = "power-flows"
+NODE_SHED = "shed"
+NODE_SOC = "soc"
+NODE_STATUS = "status"
+NODE_SWITCH = "switch"
+
+# -- Properties -------------------------------------------------------------
+
+PROP_ACTIVE_POWER = "active-power"
+PROP_CURRENT = "current"
+PROP_EXPORTED_ENERGY = "exported-energy"
+PROP_IMPORTED_ENERGY = "imported-energy"
+PROP_NAME = "name"
+PROP_POLES = "poles"
+PROP_PRIORITY = "priority"
+PROP_RATING = "rating"
+PROP_RELAY = "relay"
+PROP_RELAY_CONTROLLABLE = "relay-controllable"
+PROP_RELAY_REQUESTER = "relay-requester"
+PROP_SPACES = "spaces"
+
+# Panel-level
+PROP_DATA_MODEL_VERSION = "data-model-version"
+PROP_FIRMWARE_VERSION = "firmware-version"
+PROP_SERIAL_NUMBER = "serial-number"
+PROP_STATE = "state"
+PROP_VOLTAGE_A = "voltage-a"
+PROP_VOLTAGE_B = "voltage-b"
+
+# status node
+PROP_CLOUD_CONNECTION = "cloud-connection"
+PROP_ETHERNET = "ethernet"
+PROP_WIFI = "wifi"
+
+# -- Values -----------------------------------------------------------------
+
+PRIORITY_NEVER = "NEVER"
+UNKNOWN = "UNKNOWN"
+CLOUD_CONNECTED = "CONNECTED"
+
+PROP_MODEL = "model"
+
+# Topic root. Children are peers of the panel in the topic tree rather than
+# nodes beneath it, so a subscription covering the tree spans the domain.
+HOMIE_DOMAIN = "ebus"
+HOMIE_VERSION = "5"
+
+STATE_READY = "ready"
+
+# Breaker spaces per panel model.
+#
+# This is the only source of the panel's total size in v1.0. The flat schema
+# carried it in the Homie schema's `space` format (`"1:32:1"`, max = 32); its
+# successor `info/spaces` is a plain string with no format, and the panel device
+# publishes no size property. What v1.0 does publish is `info/model`, a **closed
+# enum** — the topic reference, the migration guide, and the panel's own Homie
+# `$format` all list exactly these five values — so this is a lookup over a
+# defined value set, not an inference from a vendor string.
+#
+# The *sizes* are ours: neither the SDK nor the published schema states how many
+# spaces a model has, only which model names are valid. `panel_model_drift`
+# exists because of that split — the panel can tell us a model we have no size
+# for, and we would rather say so than guess.
+#
+# Total size matters beyond a display field: unoccupied positions are only
+# knowable as `total - occupied`, and synthesising them is what gives the
+# integration its unmapped-circuit sensors.
+PANEL_SIZE_BY_MODEL: dict[str, int] = {
+    "MAIN_16": 16,
+    "MLO_24": 24,
+    "MAIN_32": 32,
+    "MAIN_40": 40,
+    "MLO_48": 48,
+}
+
+# Prefix for synthesised unoccupied-position entries. Must match the flat
+# adapter's, because the integration keys entities off it and a rename would
+# strand every existing unmapped-tab entity.
+UNMAPPED_TAB_PREFIX = "unmapped_tab_"
+
+# 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, so
+# the panel publishes `$settable = false` on `load-shed/priority`.
+ATTR_SETTABLE = "settable"