span-panel-api-schema-0 1.0.0b1__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,67 @@
+"""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, HomieSchemaTypes, SpanPanelSnapshot
+
+
+class SchemaZeroAdapter:
+    """Parser for the flat single-device schema (firmware r202603-r202627)."""
+
+    schema_major = "schema_0"
+    SUPPORTS_DATA_MODEL_VERSIONS: tuple[str, str] = (">=0", "<1.0")
+
+    def __init__(self, serial_number: str, panel_size: int) -> None:
+        self._serial_number = serial_number
+        self._accumulator = HomiePropertyAccumulator(serial_number)
+        self._consumer = HomieDeviceConsumer(self._accumulator, 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, schema_types: HomieSchemaTypes) -> dict[str, FieldMetadata]:
+        return build_field_metadata(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 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

span_panel_api_schema_0/consumer.py

@@ -0,0 +1,641 @@
+"""Homie v5 device consumer for SPAN Panel.
+
+Builds transport-agnostic SpanPanelSnapshot from the accumulated
+Homie property state stored in a HomiePropertyAccumulator.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+import dataclasses
+import logging
+import time
+from typing import ClassVar
+
+from span_panel_api.models import (
+    SpanBatterySnapshot,
+    SpanCircuitSnapshot,
+    SpanEvseSnapshot,
+    SpanPanelSnapshot,
+    SpanPVSnapshot,
+)
+from span_panel_api_schema_0.accumulator import HomiePropertyAccumulator
+from span_panel_api_schema_0.const import (
+    LUGS_DOWNSTREAM,
+    LUGS_UPSTREAM,
+    TYPE_BESS,
+    TYPE_CIRCUIT,
+    TYPE_CORE,
+    TYPE_EVSE,
+    TYPE_LUGS,
+    TYPE_LUGS_DOWNSTREAM,
+    TYPE_LUGS_UPSTREAM,
+    TYPE_POWER_FLOWS,
+    TYPE_PV,
+    normalize_circuit_id,
+)
+
+_LOGGER = logging.getLogger(__name__)
+
+# Threshold below which grid power is considered "not exchanging" when no
+# authoritative bess/grid-state is available. Real lugs readings never land
+# exactly on 0.0; 1 W is well below sensor noise.
+_GRID_POWER_EPSILON_W = 1.0
+
+
+def _parse_bool(value: str) -> bool:
+    """Parse a Homie boolean string."""
+    return value.lower() == "true"
+
+
+def _parse_float(value: str, default: float = 0.0) -> float:
+    """Parse a float string, returning default on failure."""
+    try:
+        return float(value)
+    except (ValueError, TypeError):
+        return default
+
+
+def _parse_int(value: str, default: int = 0) -> int:
+    """Parse an integer string, returning default on failure."""
+    try:
+        return int(value)
+    except (ValueError, TypeError):
+        return default
+
+
+class HomieDeviceConsumer:
+    """Build SPAN-specific snapshots from accumulated Homie property state.
+
+    All methods must be called from the asyncio event loop thread
+    (guaranteed by AsyncMqttBridge's call_soon_threadsafe dispatch).
+    """
+
+    def __init__(self, accumulator: HomiePropertyAccumulator, panel_size: int) -> None:
+        self._acc = accumulator
+        self._panel_size = panel_size
+        self._cached_snapshot: SpanPanelSnapshot | None = None
+
+    # -- Delegation to accumulator -------------------------------------------
+    # These thin wrappers allow SpanMqttClient (and legacy test code) to
+    # continue calling is_ready / handle_message / find_node_by_type /
+    # register_property_callback on the consumer directly, without requiring
+    # callers to hold a separate reference to the accumulator.
+
+    def is_ready(self) -> bool:
+        """Delegate to accumulator.is_ready()."""
+        return self._acc.is_ready()
+
+    def handle_message(self, topic: str, payload: str) -> None:
+        """Delegate to accumulator.handle_message()."""
+        self._acc.handle_message(topic, payload)
+
+    def find_node_by_type(self, type_str: str) -> str | None:
+        """Delegate to accumulator.find_node_by_type()."""
+        return self._acc.find_node_by_type(type_str)
+
+    def register_property_callback(
+        self,
+        callback: Callable[[str, str, str, str | None], None],
+    ) -> Callable[[], None]:
+        """Delegate to accumulator.register_property_callback()."""
+        return self._acc.register_property_callback(callback)
+
+    def circuit_nodes_missing_names(self) -> list[str]:
+        """Return circuit-like node IDs that have no ``name`` property yet."""
+        missing: list[str] = []
+        for node_id in self._acc.nodes_by_type(TYPE_CIRCUIT):
+            if not self._acc.get_prop(node_id, "name"):
+                missing.append(node_id)
+        return missing
+
+    # Node types that affect panel-level snapshot fields.
+    # Any dirty node of these types triggers a full rebuild.
+    _PANEL_LEVEL_TYPES: ClassVar[frozenset[str]] = frozenset(
+        {
+            TYPE_CORE,
+            TYPE_LUGS,
+            TYPE_LUGS_UPSTREAM,
+            TYPE_LUGS_DOWNSTREAM,
+            TYPE_BESS,
+            TYPE_PV,
+            TYPE_EVSE,
+            TYPE_POWER_FLOWS,
+        }
+    )
+
+    def build_snapshot(self) -> SpanPanelSnapshot:
+        """Build a point-in-time snapshot, using cache when possible.
+
+        Must be called after accumulator is_ready() returns True.
+        """
+        dirty = self._acc.dirty_node_ids()
+
+        if not dirty and self._cached_snapshot is not None:
+            self._acc.mark_clean()
+            return self._cached_snapshot
+
+        node_types = self._acc.all_node_types()
+        needs_full = self._cached_snapshot is None or any(
+            node_types.get(nid, "") in self._PANEL_LEVEL_TYPES or nid not in node_types for nid in dirty
+        )
+
+        snapshot = self._build_snapshot() if needs_full else self._rebuild_dirty_circuits(dirty)
+        self._cached_snapshot = snapshot
+        self._acc.mark_clean()
+        return snapshot
+
+    def _rebuild_dirty_circuits(self, dirty: frozenset[str]) -> SpanPanelSnapshot:
+        """Partial rebuild — only rebuild circuits whose nodes are dirty."""
+        if self._cached_snapshot is None:
+            raise RuntimeError("_rebuild_dirty_circuits called without a cached snapshot")
+        cached = self._cached_snapshot
+
+        feed_metadata = self._build_feed_metadata()
+        updated_circuits: dict[str, SpanCircuitSnapshot] = {}
+        # Keep only non-unmapped circuits from cache, rebuild dirty ones
+        for cid, circ in cached.circuits.items():
+            if cid.startswith("unmapped_tab_"):
+                continue  # drop old unmapped entries; will recompute below
+            updated_circuits[cid] = circ
+        for node_id in dirty:
+            if self._is_circuit_node(node_id):
+                meta = feed_metadata.get(node_id, {})
+                device_type = meta.get("device_type", "circuit")
+                relative_position = meta.get("relative_position", "")
+                circuit = self._build_circuit(node_id, device_type, relative_position)
+                updated_circuits[circuit.circuit_id] = circuit
+
+        # Recompute unmapped tabs based on current circuit set
+        unmapped = self._build_unmapped_tabs(updated_circuits)
+        updated_circuits.update(unmapped)
+
+        return dataclasses.replace(cached, circuits=updated_circuits)
+
+    def _find_lugs_node(self, direction: str) -> str | None:
+        """Find the lugs node with a specific direction.
+
+        Handles two firmware conventions:
+        - Typed: node type is ``energy.ebus.device.lugs.upstream`` / ``.downstream``
+        - Generic: node type is ``energy.ebus.device.lugs`` with a ``direction`` property
+        """
+        # Typed variant (direction embedded in the type string)
+        typed_map = {
+            LUGS_UPSTREAM: TYPE_LUGS_UPSTREAM,
+            LUGS_DOWNSTREAM: TYPE_LUGS_DOWNSTREAM,
+        }
+        target_type = typed_map.get(direction)
+        if target_type:
+            node_types = self._acc.all_node_types()
+            for node_id, node_type in node_types.items():
+                if node_type == target_type:
+                    return node_id
+
+        # Generic variant (single TYPE_LUGS with direction property)
+        node_types = self._acc.all_node_types()
+        for node_id, node_type in node_types.items():
+            if node_type == TYPE_LUGS:
+                prop_dir = self._acc.get_prop(node_id, "direction")
+                if prop_dir.upper() == direction:
+                    return node_id
+        return None
+
+    # Only TYPE_CIRCUIT nodes have the full MQTT property schema (power,
+    # energy, relay, space, etc.).  PV and EVSE nodes are metadata-only
+    # (feed, nameplate-capacity, vendor-name) and reference the physical
+    # circuit via their ``feed`` property.
+    _CIRCUIT_LIKE_TYPES: frozenset[str] = frozenset({TYPE_CIRCUIT})
+
+    # Metadata node types whose ``feed`` property points to a circuit,
+    # annotating it with a device_type.
+    _FEED_TYPE_MAP: ClassVar[dict[str, str]] = {
+        TYPE_PV: "pv",
+        TYPE_EVSE: "evse",
+    }
+
+    def _is_circuit_node(self, node_id: str) -> bool:
+        """Check if node is a circuit device."""
+        return self._acc.get_node_type(node_id) in self._CIRCUIT_LIKE_TYPES
+
+    def _build_feed_metadata(self) -> dict[str, dict[str, str]]:
+        """Build mapping of circuit node_id → metadata from PV/EVSE feed references.
+
+        Returns dict keyed by circuit node_id with values containing:
+          - device_type: "pv" | "evse"
+          - relative_position: "IN_PANEL" | "UPSTREAM" | "DOWNSTREAM" | ""
+        """
+        feed_meta: dict[str, dict[str, str]] = {}
+        for node_id, node_type in self._acc.all_node_types().items():
+            device_type = self._FEED_TYPE_MAP.get(node_type)
+            if device_type:
+                feed_circuit = self._acc.get_prop(node_id, "feed")
+                if feed_circuit:
+                    rel_pos = self._acc.get_prop(node_id, "relative-position")
+                    feed_meta[feed_circuit] = {
+                        "device_type": device_type,
+                        "relative_position": rel_pos.upper() if rel_pos else "",
+                    }
+        return feed_meta
+
+    def _build_circuit(self, node_id: str, device_type: str = "circuit", relative_position: str = "") -> SpanCircuitSnapshot:
+        """Build a circuit snapshot from accumulated properties."""
+        circuit_id = normalize_circuit_id(node_id)
+
+        # active-power is in watts; negate so positive = consumption.
+        # Guard against -0.0 creeping in when raw_power_w is 0.0.
+        raw_power_w = _parse_float(self._acc.get_prop(node_id, "active-power"))
+        instant_power_w = 0.0 if raw_power_w == 0.0 else -raw_power_w
+
+        # Energy: exported-energy = consumption (panel exports TO circuit)
+        consumed_wh = _parse_float(self._acc.get_prop(node_id, "exported-energy"))
+        # imported-energy = production (panel imports FROM circuit)
+        produced_wh = _parse_float(self._acc.get_prop(node_id, "imported-energy"))
+
+        # Tabs: derived from space + dipole
+        # Dipole circuits occupy two consecutive spaces on the same bus bar
+        # side: [space, space + 2] (odd+odd or even+even)
+        space_val = self._acc.get_prop(node_id, "space")
+        is_dipole = _parse_bool(self._acc.get_prop(node_id, "dipole"))
+        tabs: list[int] = []
+        if space_val:
+            space = _parse_int(space_val)
+            tabs = [space, space + 2] if is_dipole else [space]
+
+        always_on = _parse_bool(self._acc.get_prop(node_id, "always-on"))
+
+        # Timestamps from MQTT arrival time
+        energy_ts = max(
+            self._acc.get_timestamp(node_id, "exported-energy"),
+            self._acc.get_timestamp(node_id, "imported-energy"),
+        )
+        power_ts = self._acc.get_timestamp(node_id, "active-power")
+
+        return SpanCircuitSnapshot(
+            circuit_id=circuit_id,
+            name=self._acc.get_prop(node_id, "name"),
+            relay_state=self._acc.get_prop(node_id, "relay", "UNKNOWN"),
+            instant_power_w=instant_power_w,
+            produced_energy_wh=produced_wh,
+            consumed_energy_wh=consumed_wh,
+            tabs=tabs,
+            priority=self._acc.get_prop(node_id, "shed-priority", "UNKNOWN"),
+            is_user_controllable=not always_on,
+            is_sheddable=_parse_bool(self._acc.get_prop(node_id, "sheddable")),
+            is_never_backup=_parse_bool(self._acc.get_prop(node_id, "never-backup")),
+            device_type=device_type,
+            relative_position=relative_position,
+            is_240v=_parse_bool(self._acc.get_prop(node_id, "dipole")),
+            current_a=(
+                _parse_float(self._acc.get_prop(node_id, "current")) if self._acc.get_prop(node_id, "current") else None
+            ),
+            breaker_rating_a=(
+                _parse_float(self._acc.get_prop(node_id, "breaker-rating"))
+                if self._acc.get_prop(node_id, "breaker-rating")
+                else None
+            ),
+            always_on=always_on,
+            relay_requester=self._acc.get_prop(node_id, "relay-requester", "UNKNOWN"),
+            energy_accum_update_time_s=energy_ts,
+            instant_power_update_time_s=power_ts,
+            relay_state_target=self._acc.get_target(node_id, "relay"),
+            priority_target=self._acc.get_target(node_id, "shed-priority"),
+        )
+
+    def _build_battery(self) -> SpanBatterySnapshot:
+        """Build battery snapshot from BESS node."""
+        bess_node = self._acc.find_node_by_type(TYPE_BESS)
+        if bess_node is None:
+            return SpanBatterySnapshot()
+
+        soc_str = self._acc.get_prop(bess_node, "soc")
+        soe_str = self._acc.get_prop(bess_node, "soe")
+
+        vn = self._acc.get_prop(bess_node, "vendor-name")
+        pn = self._acc.get_prop(bess_node, "product-name")
+        mdl = self._acc.get_prop(bess_node, "model")
+        sn = self._acc.get_prop(bess_node, "serial-number")
+        sw = self._acc.get_prop(bess_node, "software-version")
+        nc = self._acc.get_prop(bess_node, "nameplate-capacity")
+        conn = self._acc.get_prop(bess_node, "connected")
+
+        return SpanBatterySnapshot(
+            soe_percentage=_parse_float(soc_str) if soc_str else None,
+            soe_kwh=_parse_float(soe_str) if soe_str else None,
+            vendor_name=vn if vn else None,
+            product_name=pn if pn else None,
+            model=mdl if mdl else None,
+            serial_number=sn if sn else None,
+            software_version=sw if sw else None,
+            nameplate_capacity_kwh=_parse_float(nc) if nc else None,
+            connected=conn.lower() == "true" if conn else None,
+        )
+
+    def _build_pv(self) -> SpanPVSnapshot:
+        """Build PV snapshot from the first PV metadata node."""
+        pv_node = self._acc.find_node_by_type(TYPE_PV)
+        if pv_node is None:
+            return SpanPVSnapshot()
+
+        vn = self._acc.get_prop(pv_node, "vendor-name")
+        pn = self._acc.get_prop(pv_node, "product-name")
+        nc = self._acc.get_prop(pv_node, "nameplate-capacity")
+        feed = self._acc.get_prop(pv_node, "feed")
+        rel_pos = self._acc.get_prop(pv_node, "relative-position")
+
+        return SpanPVSnapshot(
+            vendor_name=vn if vn else None,
+            product_name=pn if pn else None,
+            nameplate_capacity_w=_parse_float(nc) if nc else None,
+            feed_circuit_id=normalize_circuit_id(feed) if feed else None,
+            relative_position=rel_pos.upper() if rel_pos else None,
+        )
+
+    def _build_evse_devices(self) -> dict[str, SpanEvseSnapshot]:
+        """Build EVSE snapshots from all EVSE metadata nodes."""
+        result: dict[str, SpanEvseSnapshot] = {}
+        for node_id, node_type in self._acc.all_node_types().items():
+            if node_type != TYPE_EVSE:
+                continue
+            feed = self._acc.get_prop(node_id, "feed")
+            if not feed:
+                continue
+            adv = self._acc.get_prop(node_id, "advertised-current")
+            result[node_id] = SpanEvseSnapshot(
+                node_id=node_id,
+                feed_circuit_id=normalize_circuit_id(feed),
+                status=self._acc.get_prop(node_id, "status") or "UNKNOWN",
+                lock_state=self._acc.get_prop(node_id, "lock-state") or "UNKNOWN",
+                advertised_current_a=_parse_float(adv) if adv else None,
+                vendor_name=self._acc.get_prop(node_id, "vendor-name") or None,
+                product_name=self._acc.get_prop(node_id, "product-name") or None,
+                part_number=self._acc.get_prop(node_id, "part-number") or None,
+                serial_number=self._acc.get_prop(node_id, "serial-number") or None,
+                software_version=self._acc.get_prop(node_id, "software-version") or None,
+            )
+        return result
+
+    def _derive_dsm_state(self, core_node: str | None, grid_power: float, power_flow_grid: float | None) -> str:
+        """Derive dsm_state from multiple signals.
+
+        Priority:
+        1. bess/grid-state — authoritative when BESS is commissioned
+        2. dominant-power-source == GRID — grid is the primary source
+        3. grid_power or power_flow_grid non-zero — grid exchanging power
+        4. both grid signals zero AND DPS != GRID — islanded
+        """
+        # 1. BESS grid-state is authoritative when available
+        bess_node = self._acc.find_node_by_type(TYPE_BESS)
+        if bess_node is not None:
+            gs = self._acc.get_prop(bess_node, "grid-state")
+            if gs == "ON_GRID":
+                return "DSM_ON_GRID"
+            if gs == "OFF_GRID":
+                return "DSM_OFF_GRID"
+
+        # 2-4. Fallback heuristic using DPS and grid power signals
+        if core_node is not None:
+            dps = self._acc.get_prop(core_node, "dominant-power-source")
+            if dps == "GRID":
+                return "DSM_ON_GRID"
+
+            if dps in ("BATTERY", "PV", "GENERATOR"):
+                grid_exchanging = abs(grid_power) > _GRID_POWER_EPSILON_W or (
+                    power_flow_grid is not None and abs(power_flow_grid) > _GRID_POWER_EPSILON_W
+                )
+                return "DSM_ON_GRID" if grid_exchanging else "DSM_OFF_GRID"
+
+        return "UNKNOWN"
+
+    def _derive_run_config(self, dsm_state: str, grid_islandable: bool | None, dps: str | None) -> str:
+        """Derive current_run_config from grid state, islandability, and power source.
+
+        Decision table:
+        - DSM_ON_GRID → PANEL_ON_GRID (regardless of islandable)
+        - DSM_OFF_GRID + islandable + BATTERY → PANEL_BACKUP
+        - DSM_OFF_GRID + islandable + PV/GENERATOR → PANEL_OFF_GRID
+        - DSM_OFF_GRID + islandable + other → UNKNOWN
+        - DSM_OFF_GRID + not islandable → UNKNOWN (shouldn't happen)
+        """
+        if dsm_state == "DSM_ON_GRID":
+            return "PANEL_ON_GRID"
+
+        if dsm_state == "DSM_OFF_GRID":
+            if not grid_islandable:
+                return "UNKNOWN"
+            if dps == "BATTERY":
+                return "PANEL_BACKUP"
+            if dps in ("PV", "GENERATOR"):
+                return "PANEL_OFF_GRID"
+            return "UNKNOWN"
+
+        return "UNKNOWN"
+
+    def _build_unmapped_tabs(
+        self,
+        circuits: dict[str, SpanCircuitSnapshot],
+    ) -> dict[str, SpanCircuitSnapshot]:
+        """Synthesize unmapped tab entries for breaker positions with no circuit.
+
+        Creates zero-power SpanCircuitSnapshot entries for unoccupied positions
+        up to ``self._panel_size``.
+        """
+        occupied_tabs: set[int] = set()
+        for circuit in circuits.values():
+            occupied_tabs.update(circuit.tabs)
+
+        unmapped: dict[str, SpanCircuitSnapshot] = {}
+        for tab in range(1, self._panel_size + 1):
+            if tab not in occupied_tabs:
+                circuit_id = f"unmapped_tab_{tab}"
+                unmapped[circuit_id] = SpanCircuitSnapshot(
+                    circuit_id=circuit_id,
+                    name=f"Unmapped Tab {tab}",
+                    relay_state="CLOSED",
+                    instant_power_w=0.0,
+                    produced_energy_wh=0.0,
+                    consumed_energy_wh=0.0,
+                    tabs=[tab],
+                    priority="UNKNOWN",
+                    is_user_controllable=False,
+                    is_sheddable=False,
+                    is_never_backup=False,
+                )
+
+        return unmapped
+
+    def _build_snapshot(self) -> SpanPanelSnapshot:
+        """Build full snapshot from accumulated property values."""
+        core_node = self._acc.find_node_by_type(TYPE_CORE)
+        upstream_lugs = self._find_lugs_node(LUGS_UPSTREAM)
+        downstream_lugs = self._find_lugs_node(LUGS_DOWNSTREAM)
+
+        # Core properties
+        firmware = ""
+        door_state = "UNKNOWN"
+        main_relay = "UNKNOWN"
+        eth0 = False
+        wlan = False
+        wwan_connected = False
+        dominant_power_source: str | None = None
+        grid_islandable: bool | None = None
+        l1_voltage: float | None = None
+        l2_voltage: float | None = None
+        main_breaker: int | None = None
+        wifi_ssid: str | None = None
+        vendor_cloud: str | None = None
+
+        if core_node is not None:
+            firmware = self._acc.get_prop(core_node, "software-version")
+            door_state = self._acc.get_prop(core_node, "door", "UNKNOWN")
+            main_relay = self._acc.get_prop(core_node, "relay", "UNKNOWN")
+            eth0 = _parse_bool(self._acc.get_prop(core_node, "ethernet"))
+            wlan = _parse_bool(self._acc.get_prop(core_node, "wifi"))
+
+            vc = self._acc.get_prop(core_node, "vendor-cloud")
+            wwan_connected = vc == "CONNECTED"
+            vendor_cloud = vc if vc else None
+
+            dps = self._acc.get_prop(core_node, "dominant-power-source")
+            dominant_power_source = dps if dps else None
+
+            gi = self._acc.get_prop(core_node, "grid-islandable")
+            grid_islandable = _parse_bool(gi) if gi else None
+
+            l1v = self._acc.get_prop(core_node, "l1-voltage")
+            l1_voltage = _parse_float(l1v) if l1v else None
+
+            l2v = self._acc.get_prop(core_node, "l2-voltage")
+            l2_voltage = _parse_float(l2v) if l2v else None
+
+            br = self._acc.get_prop(core_node, "breaker-rating")
+            main_breaker = _parse_int(br) if br else None
+
+            ws = self._acc.get_prop(core_node, "wifi-ssid")
+            wifi_ssid = ws if ws else None
+
+        # Upstream lugs → main meter (grid connection)
+        # imported-energy = energy imported from the grid = consumed by the house
+        # exported-energy = energy exported to the grid = produced (solar)
+        grid_power = 0.0
+        main_consumed = 0.0
+        main_produced = 0.0
+        upstream_l1_current: float | None = None
+        upstream_l2_current: float | None = None
+        if upstream_lugs is not None:
+            grid_power = _parse_float(self._acc.get_prop(upstream_lugs, "active-power"))
+            main_consumed = _parse_float(self._acc.get_prop(upstream_lugs, "imported-energy"))
+            main_produced = _parse_float(self._acc.get_prop(upstream_lugs, "exported-energy"))
+
+            l1_i = self._acc.get_prop(upstream_lugs, "l1-current")
+            upstream_l1_current = _parse_float(l1_i) if l1_i else None
+            l2_i = self._acc.get_prop(upstream_lugs, "l2-current")
+            upstream_l2_current = _parse_float(l2_i) if l2_i else None
+
+        # Downstream lugs → feedthrough
+        feedthrough_power = 0.0
+        feedthrough_consumed = 0.0
+        feedthrough_produced = 0.0
+        downstream_l1_current: float | None = None
+        downstream_l2_current: float | None = None
+        if downstream_lugs is not None:
+            feedthrough_power = _parse_float(self._acc.get_prop(downstream_lugs, "active-power"))
+            feedthrough_consumed = _parse_float(self._acc.get_prop(downstream_lugs, "imported-energy"))
+            feedthrough_produced = _parse_float(self._acc.get_prop(downstream_lugs, "exported-energy"))
+
+            dl1_i = self._acc.get_prop(downstream_lugs, "l1-current")
+            downstream_l1_current = _parse_float(dl1_i) if dl1_i else None
+            dl2_i = self._acc.get_prop(downstream_lugs, "l2-current")
+            downstream_l2_current = _parse_float(dl2_i) if dl2_i else None
+
+        # Power flows
+        pf_node = self._acc.find_node_by_type(TYPE_POWER_FLOWS)
+        power_flow_pv: float | None = None
+        power_flow_battery: float | None = None
+        power_flow_grid: float | None = None
+        power_flow_site: float | None = None
+        if pf_node is not None:
+            pf_pv = self._acc.get_prop(pf_node, "pv")
+            power_flow_pv = _parse_float(pf_pv) if pf_pv else None
+            pf_bat = self._acc.get_prop(pf_node, "battery")
+            power_flow_battery = _parse_float(pf_bat) if pf_bat else None
+            pf_grid = self._acc.get_prop(pf_node, "grid")
+            power_flow_grid = _parse_float(pf_grid) if pf_grid else None
+            pf_site = self._acc.get_prop(pf_node, "site")
+            power_flow_site = _parse_float(pf_site) if pf_site else None
+
+        # Build metadata annotations from PV/EVSE metadata nodes
+        feed_metadata = self._build_feed_metadata()
+
+        # Circuits
+        circuits: dict[str, SpanCircuitSnapshot] = {}
+        for node_id in self._acc.all_node_types():
+            if self._is_circuit_node(node_id):
+                meta = feed_metadata.get(node_id, {})
+                device_type = meta.get("device_type", "circuit")
+                relative_position = meta.get("relative_position", "")
+                circuit = self._build_circuit(node_id, device_type, relative_position)
+                circuits[circuit.circuit_id] = circuit
+
+        # Synthesize unmapped tab entries
+        unmapped = self._build_unmapped_tabs(circuits)
+        circuits.update(unmapped)
+
+        # Battery, PV, and EVSE metadata
+        battery = self._build_battery()
+        pv = self._build_pv()
+        evse = self._build_evse_devices()
+
+        # BESS grid state for v2-native field
+        bess_node = self._acc.find_node_by_type(TYPE_BESS)
+        grid_state: str | None = None
+        if bess_node is not None:
+            gs = self._acc.get_prop(bess_node, "grid-state")
+            grid_state = gs if gs else None
+
+        # Derived state values
+        dsm_state = self._derive_dsm_state(core_node, grid_power, power_flow_grid)
+        current_run_config = self._derive_run_config(dsm_state, grid_islandable, dominant_power_source)
+
+        # Connection uptime since $state==ready
+        uptime = int(time.monotonic() - self._acc.ready_since) if self._acc.ready_since > 0.0 else 0
+
+        return SpanPanelSnapshot(
+            serial_number=self._acc.serial_number,
+            firmware_version=firmware,
+            main_relay_state=main_relay,
+            instant_grid_power_w=grid_power,
+            feedthrough_power_w=feedthrough_power,
+            main_meter_energy_consumed_wh=main_consumed,
+            main_meter_energy_produced_wh=main_produced,
+            feedthrough_energy_consumed_wh=feedthrough_consumed,
+            feedthrough_energy_produced_wh=feedthrough_produced,
+            dsm_state=dsm_state,
+            current_run_config=current_run_config,
+            door_state=door_state,
+            proximity_proven=self._acc.is_ready(),
+            uptime_s=uptime,
+            eth0_link=eth0,
+            wlan_link=wlan,
+            wwan_link=wwan_connected,
+            panel_size=self._panel_size,
+            dominant_power_source=dominant_power_source,
+            grid_state=grid_state,
+            grid_islandable=grid_islandable,
+            l1_voltage=l1_voltage,
+            l2_voltage=l2_voltage,
+            main_breaker_rating_a=main_breaker,
+            wifi_ssid=wifi_ssid,
+            vendor_cloud=vendor_cloud,
+            power_flow_pv=power_flow_pv,
+            power_flow_battery=power_flow_battery,
+            power_flow_grid=power_flow_grid,
+            power_flow_site=power_flow_site,
+            upstream_l1_current_a=upstream_l1_current,
+            upstream_l2_current_a=upstream_l2_current,
+            downstream_l1_current_a=downstream_l1_current,
+            downstream_l2_current_a=downstream_l2_current,
+            circuits=circuits,
+            battery=battery,
+            pv=pv,
+            evse=evse,
+        )

span_panel_api_schema_0/field_metadata.py

@@ -0,0 +1,176 @@
+"""Build transport-agnostic field metadata from the Homie schema.
+
+Maps every Homie property that ``HomieDeviceConsumer._build_snapshot()``
+reads to a snapshot field path, then looks up the schema-declared unit
+and datatype for each. The result is a dict the integration can consume
+without any Homie knowledge.
+
+Field path convention: ``{snapshot_type}.{field_name}``
+  - ``panel`` — SpanPanelSnapshot
+  - ``circuit`` — SpanCircuitSnapshot
+  - ``battery`` — SpanBatterySnapshot
+  - ``pv`` — SpanPVSnapshot
+  - ``evse`` — SpanEvseSnapshot
+"""
+
+from __future__ import annotations
+
+from span_panel_api.models import FieldMetadata, HomieSchemaTypes
+from span_panel_api_schema_0.const import (
+    TYPE_BESS,
+    TYPE_CIRCUIT,
+    TYPE_CORE,
+    TYPE_EVSE,
+    TYPE_LUGS,
+    TYPE_LUGS_DOWNSTREAM,
+    TYPE_LUGS_UPSTREAM,
+    TYPE_POWER_FLOWS,
+    TYPE_PV,
+)
+
+# ---------------------------------------------------------------------------
+# Static mapping: (node_type, property_id) → snapshot field path
+#
+# This encodes the library's internal knowledge of how _build_snapshot()
+# maps Homie properties to snapshot dataclass fields. The mapping must be
+# kept in sync with consumer.py (which held this class as homie.py before
+# the Phase 0 relocation).
+# ---------------------------------------------------------------------------
+
+_PROPERTY_FIELD_MAP: tuple[tuple[str, str, str], ...] = (
+    # --- Core node → panel.* -------------------------------------------------
+    (TYPE_CORE, "software-version", "panel.firmware_version"),
+    (TYPE_CORE, "door", "panel.door_state"),
+    (TYPE_CORE, "relay", "panel.main_relay_state"),
+    (TYPE_CORE, "ethernet", "panel.eth0_link"),
+    (TYPE_CORE, "wifi", "panel.wlan_link"),
+    (TYPE_CORE, "vendor-cloud", "panel.vendor_cloud"),
+    (TYPE_CORE, "dominant-power-source", "panel.dominant_power_source"),
+    (TYPE_CORE, "grid-islandable", "panel.grid_islandable"),
+    (TYPE_CORE, "l1-voltage", "panel.l1_voltage"),
+    (TYPE_CORE, "l2-voltage", "panel.l2_voltage"),
+    (TYPE_CORE, "breaker-rating", "panel.main_breaker_rating_a"),
+    (TYPE_CORE, "wifi-ssid", "panel.wifi_ssid"),
+    # --- Upstream lugs → panel.* (main meter) --------------------------------
+    (TYPE_LUGS_UPSTREAM, "active-power", "panel.instant_grid_power_w"),
+    (TYPE_LUGS_UPSTREAM, "imported-energy", "panel.main_meter_energy_consumed_wh"),
+    (TYPE_LUGS_UPSTREAM, "exported-energy", "panel.main_meter_energy_produced_wh"),
+    (TYPE_LUGS_UPSTREAM, "l1-current", "panel.upstream_l1_current_a"),
+    (TYPE_LUGS_UPSTREAM, "l2-current", "panel.upstream_l2_current_a"),
+    # --- Downstream lugs → panel.* (feedthrough) -----------------------------
+    (TYPE_LUGS_DOWNSTREAM, "active-power", "panel.feedthrough_power_w"),
+    (TYPE_LUGS_DOWNSTREAM, "imported-energy", "panel.feedthrough_energy_consumed_wh"),
+    (TYPE_LUGS_DOWNSTREAM, "exported-energy", "panel.feedthrough_energy_produced_wh"),
+    (TYPE_LUGS_DOWNSTREAM, "l1-current", "panel.downstream_l1_current_a"),
+    (TYPE_LUGS_DOWNSTREAM, "l2-current", "panel.downstream_l2_current_a"),
+    # --- Circuit → circuit.* -------------------------------------------------
+    (TYPE_CIRCUIT, "active-power", "circuit.instant_power_w"),
+    (TYPE_CIRCUIT, "exported-energy", "circuit.consumed_energy_wh"),
+    (TYPE_CIRCUIT, "imported-energy", "circuit.produced_energy_wh"),
+    (TYPE_CIRCUIT, "name", "circuit.name"),
+    (TYPE_CIRCUIT, "relay", "circuit.relay_state"),
+    (TYPE_CIRCUIT, "shed-priority", "circuit.priority"),
+    (TYPE_CIRCUIT, "current", "circuit.current_a"),
+    (TYPE_CIRCUIT, "breaker-rating", "circuit.breaker_rating_a"),
+    (TYPE_CIRCUIT, "space", "circuit.tabs"),
+    (TYPE_CIRCUIT, "sheddable", "circuit.is_sheddable"),
+    (TYPE_CIRCUIT, "never-backup", "circuit.is_never_backup"),
+    (TYPE_CIRCUIT, "always-on", "circuit.always_on"),
+    (TYPE_CIRCUIT, "dipole", "circuit.is_240v"),
+    (TYPE_CIRCUIT, "relay-requester", "circuit.relay_requester"),
+    # --- BESS → battery.* ----------------------------------------------------
+    (TYPE_BESS, "soc", "battery.soe_percentage"),
+    (TYPE_BESS, "soe", "battery.soe_kwh"),
+    (TYPE_BESS, "vendor-name", "battery.vendor_name"),
+    (TYPE_BESS, "product-name", "battery.product_name"),
+    (TYPE_BESS, "model", "battery.model"),
+    (TYPE_BESS, "serial-number", "battery.serial_number"),
+    (TYPE_BESS, "software-version", "battery.software_version"),
+    (TYPE_BESS, "nameplate-capacity", "battery.nameplate_capacity_kwh"),
+    (TYPE_BESS, "connected", "battery.connected"),
+    (TYPE_BESS, "grid-state", "panel.grid_state"),
+    # --- PV → pv.* -----------------------------------------------------------
+    (TYPE_PV, "vendor-name", "pv.vendor_name"),
+    (TYPE_PV, "product-name", "pv.product_name"),
+    (TYPE_PV, "nameplate-capacity", "pv.nameplate_capacity_w"),
+    (TYPE_PV, "feed", "pv.feed_circuit_id"),
+    (TYPE_PV, "relative-position", "pv.relative_position"),  # IN_PANEL | UPSTREAM | DOWNSTREAM
+    # --- EVSE → evse.* -------------------------------------------------------
+    (TYPE_EVSE, "status", "evse.status"),
+    (TYPE_EVSE, "lock-state", "evse.lock_state"),
+    (TYPE_EVSE, "advertised-current", "evse.advertised_current_a"),
+    (TYPE_EVSE, "vendor-name", "evse.vendor_name"),
+    (TYPE_EVSE, "product-name", "evse.product_name"),
+    (TYPE_EVSE, "part-number", "evse.part_number"),
+    (TYPE_EVSE, "serial-number", "evse.serial_number"),
+    (TYPE_EVSE, "software-version", "evse.software_version"),
+    (TYPE_EVSE, "feed", "evse.feed_circuit_id"),
+    # --- Power flows → panel.* -----------------------------------------------
+    (TYPE_POWER_FLOWS, "pv", "panel.power_flow_pv"),
+    (TYPE_POWER_FLOWS, "battery", "panel.power_flow_battery"),
+    (TYPE_POWER_FLOWS, "grid", "panel.power_flow_grid"),
+    (TYPE_POWER_FLOWS, "site", "panel.power_flow_site"),
+)
+
+# Generic lugs type used by some firmware versions instead of typed variants.
+# Properties are identical; only the node type differs.
+_LUGS_FALLBACK: dict[str, str] = {
+    TYPE_LUGS_UPSTREAM: TYPE_LUGS,
+    TYPE_LUGS_DOWNSTREAM: TYPE_LUGS,
+}
+
+
+def _lookup_property(
+    schema_types: HomieSchemaTypes,
+    node_type: str,
+    property_id: str,
+) -> dict[str, object] | None:
+    """Look up a property definition in the schema, with lugs fallback."""
+    node_props = schema_types.get(node_type)
+    if isinstance(node_props, dict):
+        prop_def = node_props.get(property_id)
+        if isinstance(prop_def, dict):
+            return prop_def
+
+    # Try generic lugs fallback
+    fallback_type = _LUGS_FALLBACK.get(node_type)
+    if fallback_type is not None:
+        fb_props = schema_types.get(fallback_type)
+        if isinstance(fb_props, dict):
+            prop_def = fb_props.get(property_id)
+            if isinstance(prop_def, dict):
+                return prop_def
+
+    return None
+
+
+def build_field_metadata(
+    schema_types: HomieSchemaTypes,
+) -> dict[str, FieldMetadata]:
+    """Build field metadata from the Homie schema.
+
+    Iterates the static property-to-field mapping, looks up each property
+    in the schema to get its declared unit and datatype, and returns a dict
+    keyed by snapshot field path.
+
+    Args:
+        schema_types: The ``V2HomieSchema.types`` dict.
+
+    Returns:
+        Dict mapping field paths to ``FieldMetadata``.
+    """
+    result: dict[str, FieldMetadata] = {}
+
+    for node_type, property_id, field_path in _PROPERTY_FIELD_MAP:
+        prop_def = _lookup_property(schema_types, node_type, property_id)
+        if prop_def is None:
+            continue
+
+        raw_unit = prop_def.get("unit")
+        unit = str(raw_unit) if raw_unit is not None else None
+        raw_datatype = prop_def.get("datatype")
+        datatype = str(raw_datatype) if raw_datatype is not None else "string"
+
+        result[field_path] = FieldMetadata(unit=unit, datatype=datatype)
+
+    return result

span_panel_api_schema_0-1.0.0b1.dist-info/METADATA

@@ -0,0 +1,44 @@
+Metadata-Version: 2.4
+Name: span-panel-api-schema-0
+Version: 1.0.0b1
+Summary: Flat-schema (data-model-version absent) 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
+Author: SpanPanel
+License-Expression: MIT
+Requires-Python: <4.0,>=3.10
+Requires-Dist: span-panel-api<4.0,>=3.0.0b1
+Description-Content-Type: text/markdown
+
+# span-panel-api-schema-0
+
+The **flat-schema** parser for [`span-panel-api`](https://github.com/SpanPanel/span-panel-api): the single-device Homie model published by SPAN firmware `r202603` through `r202627`, which carries no `data-model-version`.
+
+## Why this is a separate distribution
+
+`span-panel-api` is a transport and a dispatcher. It knows how to connect to a panel's MQTT broker, route messages, and choose a parser — but it contains no parsing code and no Homie type strings. Each wire format ships as its own distribution and
+registers itself under the `span_panel_api.schema_adapters` entry-point group.
+
+That split exists because the two halves break on different axes. The wire format changes when SPAN ships firmware; the library API changes when we do. Separate distributions let each carry its own version, so a consumer can pin them independently and add
+support for a new panel schema by installing a package rather than by upgrading the transport.
+
+## Installation
+
+```console
+pip install span-panel-api span-panel-api-schema-0
+```
+
+Installing this package is what makes flat-schema panels work. `span-panel-api` on its own will connect and then raise `SpanPanelAdapterMissingError` naming the adapter it could not find.
+
+A consumer that wants to support panels on either schema installs both adapters:
+
+```console
+pip install span-panel-api span-panel-api-schema-0 span-panel-api-schema-1
+```
+
+Dispatch happens at runtime, per panel, from the `data-model-version` the panel reports.
+
+## Retirement
+
+SPAN retires the flat schema in the same release that introduces the parent/child model (`r202633`, fleet rollout projected for early September 2026). When the fleet has moved, consumers drop this package from their requirements. Published versions stay on
+PyPI for anyone still running older firmware.

span_panel_api_schema_0-1.0.0b1.dist-info/RECORD

@@ -0,0 +1,11 @@
+span_panel_api_schema_0/__init__.py,sha256=FRN8R2YS8lUXXm2td4thxqb8OSTh-0_DNCw6XrRyZG0,589
+span_panel_api_schema_0/accumulator.py,sha256=KGkX68hfTMrN0Pv7m_wYEwb7CsxO3vAbG8drJkMk4ao,10424
+span_panel_api_schema_0/adapter.py,sha256=s8iydZsi_lbvrZtYq28nZnGDSUBNf5Oqpd3XnP1qumw,2886
+span_panel_api_schema_0/const.py,sha256=2zswfoyGYNnZy8vQcZ4XB_YRMc9bJlIQImVoiNYcdms,4030
+span_panel_api_schema_0/consumer.py,sha256=lcAxLNJorLVfVOSnR4fCi202RbGkf_tvrkXF7PamPbM,27369
+span_panel_api_schema_0/field_metadata.py,sha256=M4d3qbx9xYXwUUXPbQ61crJTuVAyB5vCPXsXLtCxeGI,7893
+span_panel_api_schema_0/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+span_panel_api_schema_0-1.0.0b1.dist-info/METADATA,sha256=hwMd9CuWqeGVHv1VrW11anSqPNNFmg-AngsogsvdQig,2264
+span_panel_api_schema_0-1.0.0b1.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+span_panel_api_schema_0-1.0.0b1.dist-info/entry_points.txt,sha256=cj7Udv-ohuTOC5dDFqBE17a3L6pF9Tfn_lYQ_MHHkj8,86
+span_panel_api_schema_0-1.0.0b1.dist-info/RECORD,,

span_panel_api_schema_0-1.0.0b1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

span_panel_api_schema_0-1.0.0b1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[span_panel_api.schema_adapters]
+schema_0 = span_panel_api_schema_0:SchemaZeroAdapter