span-panel-api-schema-0 1.0.0__py3-none-any.whl

span_panel_api_schema_0/__init__.py

@@ -0,0 +1,11 @@
+"""Flat-schema adapter package (data-model-version absent)."""
+
+from span_panel_api_schema_0.adapter import SchemaZeroAdapter
+
+# Re-exported from the adapter rather than restated. The protocol requires the
+# range as a class attribute, so the class is the source of truth; a second
+# literal here would be free to drift, and nothing would notice until a panel
+# reported a version this adapter claims — falsely — to support.
+SUPPORTS_DATA_MODEL_VERSIONS: tuple[str, str] = SchemaZeroAdapter.SUPPORTS_DATA_MODEL_VERSIONS
+
+__all__ = ["SUPPORTS_DATA_MODEL_VERSIONS", "SchemaZeroAdapter"]

span_panel_api_schema_0/accumulator.py

@@ -0,0 +1,274 @@
+"""Homie v5 property accumulator with lifecycle state machine.
+
+Generic Homie protocol layer that knows nothing about SPAN-specific
+concepts. Stores property values, tracks lifecycle, and exposes a
+query API for higher-level consumers.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+import enum
+import json
+import logging
+import time
+
+from span_panel_api.mqtt.const import HOMIE_STATE_DISCONNECTED, HOMIE_STATE_LOST, HOMIE_STATE_READY
+from span_panel_api_schema_0.const import TOPIC_PREFIX
+
+_LOGGER = logging.getLogger(__name__)
+
+# Callback signature: (node_id, prop_id, value, old_value)
+PropertyCallback = Callable[[str, str, str, str | None], None]
+
+
+class HomieLifecycle(enum.Enum):
+    """Homie device lifecycle states."""
+
+    DISCONNECTED = "disconnected"
+    CONNECTED = "connected"
+    DESCRIPTION_RECEIVED = "description_received"
+    READY = "ready"
+
+
+class HomiePropertyAccumulator:
+    """Accumulate Homie v5 property values and track device lifecycle.
+
+    Topic prefix: ``ebus/5/{serial_number}``
+
+    All methods must be called from the asyncio event loop thread.
+    """
+
+    def __init__(self, serial_number: str) -> None:
+        self._serial_number = serial_number
+        self._topic_prefix = f"{TOPIC_PREFIX}/{serial_number}"
+
+        # Lifecycle
+        self._lifecycle = HomieLifecycle.DISCONNECTED
+        self._received_state_ready = False
+        self._received_description = False
+        self._ready_since: float = 0.0
+
+        # Property storage
+        self._property_values: dict[str, dict[str, str]] = {}
+        self._property_timestamps: dict[str, dict[str, int]] = {}
+        self._target_values: dict[str, dict[str, str]] = {}
+
+        # Node type mapping from $description
+        self._node_types: dict[str, str] = {}
+
+        # Dirty tracking
+        self._dirty_nodes: set[str] = set()
+
+        # Callbacks
+        self._property_callbacks: list[PropertyCallback] = []
+
+    # -- Public properties ---------------------------------------------------
+
+    @property
+    def serial_number(self) -> str:
+        """Serial number this accumulator tracks."""
+        return self._serial_number
+
+    @property
+    def lifecycle(self) -> HomieLifecycle:
+        """Current lifecycle state."""
+        return self._lifecycle
+
+    @property
+    def ready_since(self) -> float:
+        """Monotonic timestamp of the last READY transition, 0.0 if never ready."""
+        return self._ready_since
+
+    def is_ready(self) -> bool:
+        """True when lifecycle is READY."""
+        return self._lifecycle == HomieLifecycle.READY
+
+    # -- Message routing -----------------------------------------------------
+
+    def handle_message(self, topic: str, payload: str) -> None:
+        """Route an MQTT message to the appropriate handler."""
+        prefix_with_sep = f"{self._topic_prefix}/"
+        if not topic.startswith(prefix_with_sep):
+            return
+
+        suffix = topic[len(prefix_with_sep) :]
+
+        if suffix == "$state":
+            self._handle_state(payload)
+        elif suffix == "$description":
+            self._handle_description(payload)
+        elif suffix.endswith("/set"):
+            return  # ignore /set topics
+        elif "/" in suffix:
+            parts = suffix.split("/", 1)
+            node_id = parts[0]
+            prop_part = parts[1]
+            if prop_part.endswith("/$target"):
+                # Target value: {node_id}/{prop_id}/$target
+                prop_id = prop_part[: -len("/$target")]
+                self._handle_target(node_id, prop_id, payload)
+            else:
+                # Reported value: {node_id}/{prop_id}
+                self._handle_property(node_id, prop_part, payload)
+
+    # -- Query API -----------------------------------------------------------
+
+    def get_prop(self, node_id: str, prop_id: str, default: str = "") -> str:
+        """Get a property's reported value."""
+        return self._property_values.get(node_id, {}).get(prop_id, default)
+
+    def get_timestamp(self, node_id: str, prop_id: str) -> int:
+        """Get the epoch timestamp of a property's last update."""
+        return self._property_timestamps.get(node_id, {}).get(prop_id, 0)
+
+    def get_target(self, node_id: str, prop_id: str) -> str | None:
+        """Get a property's target value, or None if no target set."""
+        return self._target_values.get(node_id, {}).get(prop_id)
+
+    def has_target(self, node_id: str, prop_id: str) -> bool:
+        """True if a target value exists for the given property."""
+        return prop_id in self._target_values.get(node_id, {})
+
+    def find_node_by_type(self, type_str: str) -> str | None:
+        """Find the first node ID matching a given type string."""
+        for node_id, node_type in self._node_types.items():
+            if node_type == type_str:
+                return node_id
+        return None
+
+    def nodes_by_type(self, type_str: str) -> list[str]:
+        """Return all node IDs matching a given type string."""
+        return [nid for nid, ntype in self._node_types.items() if ntype == type_str]
+
+    def get_node_type(self, node_id: str) -> str:
+        """Get the type string for a node, or empty string if unknown."""
+        return self._node_types.get(node_id, "")
+
+    def all_node_types(self) -> dict[str, str]:
+        """Return a copy of the node_id → type mapping."""
+        return dict(self._node_types)
+
+    def dirty_node_ids(self) -> frozenset[str]:
+        """Return the set of node IDs with changed properties since last mark_clean."""
+        return frozenset(self._dirty_nodes)
+
+    def mark_clean(self) -> None:
+        """Clear the dirty set."""
+        self._dirty_nodes.clear()
+
+    def register_property_callback(self, callback: PropertyCallback) -> Callable[[], None]:
+        """Register a callback fired on property value changes.
+
+        Callback signature: (node_id, prop_id, new_value, old_value).
+        Only fires when the value actually changes, not on every message.
+
+        Returns an unregister function.
+        """
+        self._property_callbacks.append(callback)
+
+        def unregister() -> None:
+            try:
+                self._property_callbacks.remove(callback)
+            except ValueError:
+                _LOGGER.debug("Callback already unregistered")
+
+        return unregister
+
+    # -- Internal handlers ---------------------------------------------------
+
+    def _handle_state(self, payload: str) -> None:
+        """Handle $state topic and drive lifecycle transitions."""
+        if payload == HOMIE_STATE_READY:
+            self._received_state_ready = True
+            if self._received_description:
+                self._transition_to_ready()
+            else:
+                # State ready but no description yet
+                if self._lifecycle == HomieLifecycle.DISCONNECTED:
+                    self._lifecycle = HomieLifecycle.CONNECTED
+        elif payload in (HOMIE_STATE_DISCONNECTED, HOMIE_STATE_LOST):
+            self._lifecycle = HomieLifecycle.DISCONNECTED
+            self._received_state_ready = False
+            self._received_description = False
+        else:
+            # init, sleeping, alert, etc. — connected but not ready
+            if self._lifecycle == HomieLifecycle.DISCONNECTED:
+                self._lifecycle = HomieLifecycle.CONNECTED
+            self._received_state_ready = False
+
+        _LOGGER.debug("Homie $state: %s → lifecycle=%s", payload, self._lifecycle.value)
+
+    def _handle_description(self, payload: str) -> None:
+        """Parse $description JSON and extract node type mappings."""
+        try:
+            desc = json.loads(payload)
+        except json.JSONDecodeError:
+            _LOGGER.warning("Invalid $description JSON")
+            return
+
+        self._received_description = True
+        self._node_types.clear()
+
+        nodes = desc.get("nodes", {})
+        if isinstance(nodes, dict):
+            for node_id, node_def in nodes.items():
+                if isinstance(node_def, dict):
+                    node_type = node_def.get("type", "")
+                    if isinstance(node_type, str):
+                        self._node_types[str(node_id)] = node_type
+
+        # Mark all known nodes dirty
+        self._dirty_nodes.update(self._node_types.keys())
+
+        _LOGGER.debug("Parsed $description with %d nodes", len(self._node_types))
+
+        # Lifecycle transition
+        if self._received_state_ready:
+            self._transition_to_ready()
+        elif self._lifecycle in (HomieLifecycle.DISCONNECTED, HomieLifecycle.CONNECTED):
+            self._lifecycle = HomieLifecycle.DESCRIPTION_RECEIVED
+
+    def _handle_property(self, node_id: str, prop_id: str, value: str) -> None:
+        """Handle a reported property value update."""
+        now_s = int(time.time())
+
+        if node_id not in self._property_values:
+            self._property_values[node_id] = {}
+            self._property_timestamps[node_id] = {}
+
+        old_value = self._property_values[node_id].get(prop_id)
+
+        if old_value == value:
+            return  # no change — no dirty, no callbacks, no timestamp bump
+
+        self._property_values[node_id][prop_id] = value
+        self._property_timestamps[node_id][prop_id] = now_s
+        self._dirty_nodes.add(node_id)
+
+        self._fire_callbacks(node_id, prop_id, value, old_value)
+
+    def _handle_target(self, node_id: str, prop_id: str, value: str) -> None:
+        """Handle a $target property value."""
+        if node_id not in self._target_values:
+            self._target_values[node_id] = {}
+
+        old_target = self._target_values[node_id].get(prop_id)
+        if old_target == value:
+            return  # no change
+
+        self._target_values[node_id][prop_id] = value
+        self._dirty_nodes.add(node_id)
+
+    def _transition_to_ready(self) -> None:
+        """Transition lifecycle to READY."""
+        self._lifecycle = HomieLifecycle.READY
+        self._ready_since = time.monotonic()
+
+    def _fire_callbacks(self, node_id: str, prop_id: str, value: str, old_value: str | None) -> None:
+        """Fire all registered property callbacks, catching exceptions."""
+        for cb in self._property_callbacks:
+            try:
+                cb(node_id, prop_id, value, old_value)
+            except Exception:  # pylint: disable=broad-exception-caught
+                _LOGGER.debug("Property callback error for %s/%s", node_id, prop_id, exc_info=True)

span_panel_api_schema_0/adapter.py

@@ -0,0 +1,115 @@
+"""Flat-schema (data-model-version absent) adapter.
+
+Composes the existing accumulator + consumer and owns the flat wire format:
+a single Homie device whose node ids are circuit UUIDs and capability names.
+Nothing outside this package constructs a flat-schema topic.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+from span_panel_api_schema_0.accumulator import HomiePropertyAccumulator
+from span_panel_api_schema_0.const import PROPERTY_SET_TOPIC_FMT, TYPE_CORE, WILDCARD_TOPIC_FMT
+from span_panel_api_schema_0.consumer import HomieDeviceConsumer
+from span_panel_api_schema_0.field_metadata import build_field_metadata
+
+if TYPE_CHECKING:
+    from span_panel_api.models import FieldMetadata, SpanPanelSnapshot, V2HomieSchema
+
+
+class SchemaZeroAdapter:
+    """Parser for the flat single-device schema (firmware r202603-r202627)."""
+
+    # A literal, deliberately not imported from span_panel_api.protocol: a value
+    # read from the installed bootstrap would agree with every bootstrap, which
+    # is the disagreement the check exists to find. Bump when this adapter is
+    # rebuilt against a new contract, never to match what happens to be installed.
+    ADAPTER_CONTRACT: int = 1
+    schema_major = "schema_0"
+    SUPPORTS_DATA_MODEL_VERSIONS: tuple[str, str] = (">=0", "<1.0")
+
+    def __init__(self, serial_number: str, schema: V2HomieSchema) -> None:
+        self._serial_number = serial_number
+        # `panel_size` is derived here rather than handed in, because deriving
+        # it means reading the flat schema's `types` block for the circuit
+        # `space` format — knowledge that belongs to this package. The
+        # transport used to do this on every adapter's behalf, which only
+        # worked while every adapter was this one.
+        self._schema = schema
+        self._accumulator = HomiePropertyAccumulator(serial_number)
+        self._consumer = HomieDeviceConsumer(self._accumulator, schema.panel_size)
+
+    def topics_to_subscribe(self) -> list[str]:
+        return [WILDCARD_TOPIC_FMT.format(serial=self._serial_number)]
+
+    def handle_message(self, topic: str, payload: str) -> None:
+        self._consumer.handle_message(topic, payload)
+
+    def is_ready(self) -> bool:
+        return self._consumer.is_ready()
+
+    def build_snapshot(self) -> SpanPanelSnapshot:
+        return self._consumer.build_snapshot()
+
+    def build_field_metadata(self) -> dict[str, FieldMetadata]:
+        return build_field_metadata(self._schema.types)
+
+    def circuit_nodes_missing_names(self) -> list[str]:
+        return self._consumer.circuit_nodes_missing_names()
+
+    def find_node_by_type(self, type_str: str) -> str | None:
+        return self._consumer.find_node_by_type(type_str)
+
+    def set_circuit_relay_topic(self, circuit_id: str) -> str:
+        return PROPERTY_SET_TOPIC_FMT.format(serial=self._serial_number, node=circuit_id, prop="relay")
+
+    def set_circuit_priority_topic(self, circuit_id: str) -> str:
+        return PROPERTY_SET_TOPIC_FMT.format(serial=self._serial_number, node=circuit_id, prop="shed-priority")
+
+    def set_dominant_power_source_topic(self) -> str | None:
+        core_node = self._consumer.find_node_by_type(TYPE_CORE)
+        if core_node is None:
+            return None
+        return PROPERTY_SET_TOPIC_FMT.format(serial=self._serial_number, node=core_node, prop="dominant-power-source")
+
+    def dominant_power_source_payload(self, value: str) -> str | None:
+        """Flat speaks this vocabulary already, so the caller's value passes through.
+
+        The method exists because `schema_1` has to translate — its successor
+        property accepts `NONE`/`ON_GRID`/`OFF_GRID`, not a source class — and a
+        caller should not have to know which schema it is talking to. Here the
+        translation is the identity.
+
+        Validated rather than passed blindly: an unrecognised value returns None
+        and the transport refuses the command, which matches `schema_1`'s
+        behaviour and is better than putting a string outside the enum on the
+        wire.
+        """
+        allowed = {"GRID", "BATTERY", "PV", "GENERATOR", "NONE", "UNKNOWN"}
+        candidate = value.strip().upper()
+        return candidate if candidate in allowed else None
+
+    def set_evse_charge_limit_topic(self, node_id: str) -> str | None:  # pylint: disable=unused-argument
+        """None: flat firmware publishes no charge-current ceiling to write.
+
+        The flat `energy.ebus.device.evse` type carries `advertised-current` —
+        what the charger is offering the vehicle, read-only — and nothing that
+        sets it. There is no property to aim a set topic at, so the transport
+        refuses the command rather than publishing to a topic no panel of this
+        generation subscribes to.
+
+        `node_id` is accepted and unused for the same reason
+        `set_dominant_power_source_topic` takes no arguments and still returns
+        None on a panel with no core node: the answer does not depend on which
+        charger is asked.
+        """
+        return None
+
+    def evse_charge_limit_payload(self, node_id: str, amps: int) -> str | None:  # pylint: disable=unused-argument
+        """None, for the same reason: no property, so no representable value."""
+        return None
+
+    def register_property_callback(self, callback: Callable[[str, str, str, str | None], None]) -> Callable[[], None]:
+        return self._consumer.register_property_callback(callback)

span_panel_api_schema_0/const.py

@@ -0,0 +1,83 @@
+"""Constants for the flat-schema (Homie v5) parsing implementation."""
+
+# ---------------------------------------------------------------------------
+# Provenance anchor — the schema revision every fact in this module was read
+# from. `tests/test_schema_provenance.py` fails when a captured schema reports a
+# different one, which is the only pre-release signal that this adapter has
+# drifted from the wire it claims to parse.
+#
+# The field name is per-adapter, not per-bootstrap: flat firmware publishes
+# `typesSchemaHash` over a `types` block, while parent/child renames it to
+# `deviceClassesSchemaHash` over `deviceClasses` — the hash is renamed with the
+# block it covers, so schema_1 declares its own.
+#
+# Content-derived, not build-derived: SPAN defines it as the SHA-256 of the
+# canonicalized schema object and states the schema "may remain unchanged across
+# multiple firmware releases". So it moves when the schema moves, not on every
+# release — which is what makes it usable as an anchor rather than noise.
+# ---------------------------------------------------------------------------
+SCHEMA_ANCHOR_FIELD = "typesSchemaHash"
+SCHEMA_ANCHOR = "sha256:d347556a07d98f40"
+SCHEMA_ANCHOR_FIRMWARE = "spanos2/r202603/05"
+
+# Homie v5 topic structure
+HOMIE_VERSION = 5
+HOMIE_DOMAIN = "ebus"
+TOPIC_PREFIX = f"{HOMIE_DOMAIN}/{HOMIE_VERSION}"
+
+# Topic patterns (serial_number substituted at runtime).
+# The adapter subscribes with the wildcard and publishes with the set pattern;
+# per-topic read formats are not needed because every message arrives through
+# the one wildcard subscription.
+PROPERTY_SET_TOPIC_FMT = f"{TOPIC_PREFIX}/{{serial}}/{{node}}/{{prop}}/set"
+WILDCARD_TOPIC_FMT = f"{TOPIC_PREFIX}/{{serial}}/#"
+
+# ---------------------------------------------------------------------------
+# Homie type strings.
+#
+# Two namespaces that are easy to conflate and are NOT the same set:
+#
+#   * the `types` block of GET /api/v2/homie/schema, which declares the
+#     properties, units and datatypes available to a type; and
+#   * the `type` string a node actually carries in its $description on the wire.
+#
+# Every constant below is a node type observed on the wire. The ones in the
+# first group are also declared in the schema, so metadata lookup finds them
+# directly. See tests/test_schema_provenance.py, which asserts that.
+# ---------------------------------------------------------------------------
+TYPE_CORE = "energy.ebus.device.distribution-enclosure.core"
+TYPE_LUGS = "energy.ebus.device.lugs"
+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_POWER_FLOWS = "energy.ebus.device.power-flows"
+
+# Wire-only subtypes: real node types published by real firmware (confirmed
+# against a live panel in 1eef0dc), but NOT declared in the schema's `types`
+# block, which carries only the base `energy.ebus.device.lugs`. Firmware uses
+# one convention or the other — typed nodes, or generic nodes plus a
+# `direction` property — and _find_lugs_node handles both.
+#
+# Because the schema does not declare them, every one of these needs an entry
+# in field_metadata._LUGS_FALLBACK mapping it to a declared type, or property
+# metadata silently comes back empty for those nodes. The provenance test
+# asserts that pairing rather than trusting it.
+TYPE_LUGS_UPSTREAM = "energy.ebus.device.lugs.upstream"
+TYPE_LUGS_DOWNSTREAM = "energy.ebus.device.lugs.downstream"
+
+# Lugs direction values
+LUGS_UPSTREAM = "UPSTREAM"
+LUGS_DOWNSTREAM = "DOWNSTREAM"
+
+
+def normalize_circuit_id(node_id: str) -> str:
+    """Strip dashes from Homie UUID for entity stability."""
+    return node_id.replace("-", "")
+
+
+def denormalize_circuit_id(circuit_id: str) -> str:
+    """Restore dashes to a 32-char dashless UUID (8-4-4-4-12 format)."""
+    if len(circuit_id) == 32 and "-" not in circuit_id:
+        return f"{circuit_id[:8]}-{circuit_id[8:12]}-{circuit_id[12:16]}-{circuit_id[16:20]}-{circuit_id[20:]}"
+    return circuit_id