span-panel-api 2.2.2__tar.gz → 2.2.3__tar.gz

{span_panel_api-2.2.2 → span_panel_api-2.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: span-panel-api
-Version: 2.2.2
+Version: 2.2.3
 Summary: A client library for SPAN Panel API
 License-File: LICENSE
 Author: SpanPanel
@@ -243,6 +243,7 @@ pem = await download_ca_cert("192.168.1.100")
 
 # Fetch the Homie property schema (unauthenticated)
 schema = await get_homie_schema("192.168.1.100")
+print(f"Panel size: {schema.panel_size} spaces")
 print(f"Schema hash: {schema.types_schema_hash}")
 
 # Rotate MQTT broker password (invalidates previous password)

{span_panel_api-2.2.2 → span_panel_api-2.2.3}/README.md

@@ -223,6 +223,7 @@ pem = await download_ca_cert("192.168.1.100")
 
 # Fetch the Homie property schema (unauthenticated)
 schema = await get_homie_schema("192.168.1.100")
+print(f"Panel size: {schema.panel_size} spaces")
 print(f"Schema hash: {schema.types_schema_hash}")
 
 # Rotate MQTT broker password (invalidates previous password)

{span_panel_api-2.2.2 → span_panel_api-2.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "span-panel-api"
-version = "2.2.2"
+version = "2.2.3"
 description = "A client library for SPAN Panel API"
 authors = [
     {name = "SpanPanel"}

{span_panel_api-2.2.2 → span_panel_api-2.2.3}/src/span_panel_api/__init__.py

@@ -24,6 +24,7 @@ from .models import (
     SpanPanelSnapshot,
     SpanPVSnapshot,
     V2AuthResponse,
+    V2HomieSchema,
     V2StatusInfo,
 )
 from .mqtt import MqttClientConfig, SpanMqttClient
@@ -66,6 +67,7 @@ __all__ = [  # noqa: RUF022
     "detect_api_version",
     # v2 auth
     "V2AuthResponse",
+    "V2HomieSchema",
     "V2StatusInfo",
     "download_ca_cert",
     "get_homie_schema",

{span_panel_api-2.2.2 → span_panel_api-2.2.3}/src/span_panel_api/models.py

@@ -110,6 +110,9 @@ class V2StatusInfo:
     firmware_version: str
 
 
+_CIRCUIT_TYPE_KEY = "energy.ebus.device.circuit"
+
+
 @dataclass(frozen=True, slots=True)
 class V2HomieSchema:
     """Response from GET /api/v2/homie/schema."""
@@ -118,6 +121,32 @@ class V2HomieSchema:
     types_schema_hash: str  # SHA-256, first 16 hex chars
     types: dict[str, dict[str, object]]  # {type_name: {prop_name: {attr: value}}}
 
+    @property
+    def panel_size(self) -> int:
+        """Extract panel size from the circuit ``space`` property format.
+
+        The Homie schema defines ``space`` with ``"format": "min:max:step"``
+        (e.g. ``"1:32:1"``). The *max* value is the number of breaker spaces
+        in the panel.
+
+        Raises:
+            ValueError: If the space format is missing or unparseable.
+        """
+        circuit_type = self.types.get(_CIRCUIT_TYPE_KEY, {})
+        space_prop = circuit_type.get("space")
+        if not isinstance(space_prop, dict):
+            raise ValueError(f"Schema missing '{_CIRCUIT_TYPE_KEY}/space' property")
+        fmt = space_prop.get("format")
+        if not isinstance(fmt, str):
+            raise ValueError(f"Schema '{_CIRCUIT_TYPE_KEY}/space' has no format string")
+        parts = fmt.split(":")
+        if len(parts) != 3:
+            raise ValueError(f"Unexpected space format '{fmt}', expected 'min:max:step'")
+        try:
+            return int(parts[1])
+        except ValueError as exc:
+            raise ValueError(f"Cannot parse max from space format '{fmt}'") from exc
+
 
 @dataclass(frozen=True, slots=True)
 class SpanPanelSnapshot:
@@ -146,6 +175,7 @@ class SpanPanelSnapshot:
     eth0_link: bool  # v1: direct | v2: core/ethernet
     wlan_link: bool  # v1: direct | v2: core/wifi
     wwan_link: bool  # v1: direct | v2: vendor-cloud == "CONNECTED"
+    panel_size: int  # Total breaker spaces (from Homie schema space format)
 
     # v2-native fields — None for REST transport
     dominant_power_source: str | None = None  # v2: core/dominant-power-source (settable)
@@ -156,7 +186,6 @@ class SpanPanelSnapshot:
     main_breaker_rating_a: int | None = None  # v2: core/breaker-rating (A)
     wifi_ssid: str | None = None  # v2: core/wifi-ssid
     vendor_cloud: str | None = None  # v2: core/vendor-cloud
-    panel_size: int | None = None  # v2: core/panel-size (total breaker spaces)
 
     # Power flows (None when node not present)
     power_flow_pv: float | None = None  # v2: power-flows/pv (W)

{span_panel_api-2.2.2 → span_panel_api-2.2.3}/src/span_panel_api/mqtt/client.py

@@ -11,6 +11,7 @@ import asyncio
 from collections.abc import Awaitable, Callable
 import logging
 
+from ..auth import get_homie_schema
 from ..exceptions import SpanPanelConnectionError, SpanPanelServerError
 from ..models import SpanPanelSnapshot
 from ..protocol import PanelCapability
@@ -43,7 +44,7 @@ class SpanMqttClient:
         self._snapshot_interval = snapshot_interval
 
         self._bridge: AsyncMqttBridge | None = None
-        self._homie = HomieDeviceConsumer(serial_number)
+        self._homie: HomieDeviceConsumer | None = None
         self._streaming = False
         self._snapshot_callbacks: list[Callable[[SpanPanelSnapshot], Awaitable[None]]] = []
         self._ready_event: asyncio.Event | None = None
@@ -51,6 +52,12 @@ class SpanMqttClient:
         self._background_tasks: set[asyncio.Task[None]] = set()
         self._snapshot_timer: asyncio.TimerHandle | None = None
 
+    def _require_homie(self) -> HomieDeviceConsumer:
+        """Return the HomieDeviceConsumer, raising if not yet connected."""
+        if self._homie is None:
+            raise SpanPanelConnectionError("Client not connected — call connect() first")
+        return self._homie
+
     # -- SpanPanelClientProtocol -------------------------------------------
 
     @property
@@ -72,10 +79,11 @@ class SpanMqttClient:
         """Connect to MQTT broker and wait for Homie device ready.
 
         Flow:
-        1. Create AsyncMqttBridge with broker credentials
-        2. Connect to MQTT broker
-        3. Subscribe to ebus/5/{serial}/#
-        4. Wait for $state==ready and $description parsed
+        1. Fetch Homie schema to determine panel size
+        2. Create AsyncMqttBridge with broker credentials
+        3. Connect to MQTT broker
+        4. Subscribe to ebus/5/{serial}/#
+        5. Wait for $state==ready and $description parsed
 
         Raises:
             SpanPanelConnectionError: Cannot connect or device not ready
@@ -84,6 +92,10 @@ class SpanMqttClient:
         self._loop = asyncio.get_running_loop()
         self._ready_event = asyncio.Event()
 
+        # Fetch schema to determine panel size before processing any messages
+        schema = await get_homie_schema(self._host)
+        self._homie = HomieDeviceConsumer(self._serial_number, schema.panel_size)
+
         _LOGGER.debug(
             "MQTT: Creating bridge to %s:%s (serial=%s)",
             self._broker_config.broker_host,
@@ -145,7 +157,7 @@ class SpanMqttClient:
 
     async def ping(self) -> bool:
         """Check if MQTT connection is alive and device is ready."""
-        if self._bridge is None:
+        if self._bridge is None or self._homie is None:
             return False
         return self._bridge.is_connected() and self._homie.is_ready()
 
@@ -154,7 +166,7 @@ class SpanMqttClient:
 
         No network call — snapshot is built from in-memory property values.
         """
-        return self._homie.build_snapshot()
+        return self._require_homie().build_snapshot()
 
     # -- CircuitControlProtocol --------------------------------------------
 
@@ -188,7 +200,7 @@ class SpanMqttClient:
         Args:
             value: DPS enum value (GRID, BATTERY, NONE, GENERATOR, PV)
         """
-        core_node = self._homie.find_node_by_type(TYPE_CORE)
+        core_node = self._require_homie().find_node_by_type(TYPE_CORE)
         if core_node is None:
             raise SpanPanelServerError("Core node not found in panel topology")
         topic = PROPERTY_SET_TOPIC_FMT.format(serial=self._serial_number, node=core_node, prop="dominant-power-source")
@@ -228,15 +240,18 @@ class SpanMqttClient:
 
     def _on_message(self, topic: str, payload: str) -> None:
         """Handle incoming MQTT message (called from asyncio loop)."""
-        was_ready = self._homie.is_ready()
-        self._homie.handle_message(topic, payload)
+        homie = self._homie
+        if homie is None:
+            return
+        was_ready = homie.is_ready()
+        homie.handle_message(topic, payload)
 
         # Check if device just became ready
-        if not was_ready and self._homie.is_ready() and self._ready_event is not None:
+        if not was_ready and homie.is_ready() and self._ready_event is not None:
             self._ready_event.set()
 
         # Dispatch snapshot callbacks if streaming
-        if self._streaming and self._homie.is_ready() and self._loop is not None:
+        if self._streaming and homie.is_ready() and self._loop is not None:
             if self._snapshot_interval <= 0:
                 # No debounce — dispatch immediately (backward compat)
                 self._create_dispatch_task()
@@ -263,15 +278,16 @@ class SpanMqttClient:
         returns as soon as all circuit names are populated, or when the
         timeout elapses (non-fatal — entities will use fallback names).
         """
+        homie = self._require_homie()
         deadline = asyncio.get_event_loop().time() + timeout
         while asyncio.get_event_loop().time() < deadline:
-            missing = self._homie.circuit_nodes_missing_names()
+            missing = homie.circuit_nodes_missing_names()
             if not missing:
                 _LOGGER.debug("All circuit names received")
                 return
             await asyncio.sleep(_CIRCUIT_NAMES_POLL_INTERVAL_S)
 
-        still_missing = self._homie.circuit_nodes_missing_names()
+        still_missing = homie.circuit_nodes_missing_names()
         if still_missing:
             _LOGGER.warning(
                 "Timed out waiting for circuit names (%d still missing): %s",
@@ -313,7 +329,7 @@ class SpanMqttClient:
 
     async def _dispatch_snapshot(self) -> None:
         """Build snapshot and send to all registered callbacks."""
-        snapshot = self._homie.build_snapshot()
+        snapshot = self._require_homie().build_snapshot()
         for cb in list(self._snapshot_callbacks):
             try:
                 await cb(snapshot)

{span_panel_api-2.2.2 → span_panel_api-2.2.3}/src/span_panel_api/mqtt/homie.py

@@ -65,8 +65,9 @@ class HomieDeviceConsumer:
     (guaranteed by AsyncMqttBridge's call_soon_threadsafe dispatch).
     """
 
-    def __init__(self, serial_number: str) -> None:
+    def __init__(self, serial_number: str, panel_size: int) -> None:
         self._serial_number = serial_number
+        self._panel_size = panel_size
         self._topic_prefix = f"{TOPIC_PREFIX}/{serial_number}"
 
         self._state: str = ""
@@ -440,28 +441,21 @@ class HomieDeviceConsumer:
 
         return "UNKNOWN"
 
-    def _build_unmapped_tabs(self, circuits: dict[str, SpanCircuitSnapshot]) -> dict[str, SpanCircuitSnapshot]:
+    def _build_unmapped_tabs(
+        self,
+        circuits: dict[str, SpanCircuitSnapshot],
+    ) -> dict[str, SpanCircuitSnapshot]:
         """Synthesize unmapped tab entries for breaker positions with no circuit.
 
-        Determines panel size from the highest occupied tab, then creates
-        zero-power SpanCircuitSnapshot entries for unoccupied positions.
+        Creates zero-power SpanCircuitSnapshot entries for unoccupied positions
+        up to ``self._panel_size``.
         """
-        # Collect all occupied tabs from commissioned circuits
         occupied_tabs: set[int] = set()
         for circuit in circuits.values():
             occupied_tabs.update(circuit.tabs)
 
-        if not occupied_tabs:
-            return {}
-
-        # Panel size is the highest occupied tab (rounded up to even
-        # to cover both bus bar sides)
-        max_tab = max(occupied_tabs)
-        panel_size = max_tab if max_tab % 2 == 0 else max_tab + 1
-
-        # Synthesize entries for unoccupied positions
         unmapped: dict[str, SpanCircuitSnapshot] = {}
-        for tab in range(1, panel_size + 1):
+        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(
@@ -500,7 +494,6 @@ class HomieDeviceConsumer:
         main_breaker: int | None = None
         wifi_ssid: str | None = None
         vendor_cloud: str | None = None
-        panel_size: int | None = None
 
         if core_node is not None:
             firmware = self._get_prop(core_node, "software-version")
@@ -531,9 +524,6 @@ class HomieDeviceConsumer:
             ws = self._get_prop(core_node, "wifi-ssid")
             wifi_ssid = ws if ws else None
 
-            ps = self._get_prop(core_node, "panel-size")
-            panel_size = _parse_int(ps) if ps 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)
@@ -638,6 +628,7 @@ class HomieDeviceConsumer:
             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,
@@ -646,7 +637,6 @@ class HomieDeviceConsumer:
             main_breaker_rating_a=main_breaker,
             wifi_ssid=wifi_ssid,
             vendor_cloud=vendor_cloud,
-            panel_size=panel_size,
             power_flow_pv=power_flow_pv,
             power_flow_battery=power_flow_battery,
             power_flow_grid=power_flow_grid,