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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: span-panel-api
-Version: 2.2.0
+Version: 2.2.2
 Summary: A client library for SPAN Panel API
 License-File: LICENSE
 Author: SpanPanel

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

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

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

@@ -35,15 +35,22 @@ from .phase_validation import (
     suggest_balanced_pairing,
     validate_solar_tabs,
 )
-from .protocol import CircuitControlProtocol, PanelCapability, SpanPanelClientProtocol, StreamingCapableProtocol
+from .protocol import (
+    CircuitControlProtocol,
+    PanelCapability,
+    PanelControlProtocol,
+    SpanPanelClientProtocol,
+    StreamingCapableProtocol,
+)
 from .simulation import DynamicSimulationEngine
 
-__version__ = "2.0.0"
+__version__ = "2.2.1"
 # fmt: off
 __all__ = [  # noqa: RUF022
     # Protocols
     "CircuitControlProtocol",
     "PanelCapability",
+    "PanelControlProtocol",
     "SpanPanelClientProtocol",
     "StreamingCapableProtocol",
     # Snapshots

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

@@ -1,8 +1,8 @@
 """SPAN Panel MQTT client.
 
 Composes AsyncMqttBridge and HomieDeviceConsumer to implement
-SpanPanelClientProtocol, CircuitControlProtocol, and
-StreamingCapableProtocol.
+SpanPanelClientProtocol, CircuitControlProtocol,
+PanelControlProtocol, and StreamingCapableProtocol.
 """
 
 from __future__ import annotations
@@ -11,11 +11,11 @@ import asyncio
 from collections.abc import Awaitable, Callable
 import logging
 
-from ..exceptions import SpanPanelConnectionError
+from ..exceptions import SpanPanelConnectionError, SpanPanelServerError
 from ..models import SpanPanelSnapshot
 from ..protocol import PanelCapability
 from .connection import AsyncMqttBridge
-from .const import MQTT_READY_TIMEOUT_S, PROPERTY_SET_TOPIC_FMT, WILDCARD_TOPIC_FMT
+from .const import MQTT_READY_TIMEOUT_S, PROPERTY_SET_TOPIC_FMT, TYPE_CORE, WILDCARD_TOPIC_FMT
 from .homie import HomieDeviceConsumer
 from .models import MqttClientConfig
 
@@ -180,6 +180,21 @@ class SpanMqttClient:
         if self._bridge is not None:
             self._bridge.publish(topic, priority, qos=1)
 
+    # -- PanelControlProtocol ----------------------------------------------
+
+    async def set_dominant_power_source(self, value: str) -> None:
+        """Publish dominant-power-source change to the core node.
+
+        Args:
+            value: DPS enum value (GRID, BATTERY, NONE, GENERATOR, PV)
+        """
+        core_node = self._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")
+        if self._bridge is not None:
+            self._bridge.publish(topic, value, qos=1)
+
     # -- StreamingCapableProtocol ------------------------------------------
 
     def register_snapshot_callback(

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

@@ -188,7 +188,7 @@ class HomieDeviceConsumer:
         """Get a property timestamp."""
         return self._property_timestamps.get(node_id, {}).get(prop_id, 0)
 
-    def _find_node_by_type(self, type_string: str) -> str | None:
+    def find_node_by_type(self, type_string: str) -> str | None:
         """Find the first node ID matching a given type."""
         for node_id, node_type in self._node_types.items():
             if node_type == type_string:
@@ -319,7 +319,7 @@ class HomieDeviceConsumer:
 
     def _build_battery(self) -> SpanBatterySnapshot:
         """Build battery snapshot from BESS node."""
-        bess_node = self._find_node_by_type(TYPE_BESS)
+        bess_node = self.find_node_by_type(TYPE_BESS)
         if bess_node is None:
             return SpanBatterySnapshot()
 
@@ -348,7 +348,7 @@ class HomieDeviceConsumer:
 
     def _build_pv(self) -> SpanPVSnapshot:
         """Build PV snapshot from the first PV metadata node."""
-        pv_node = self._find_node_by_type(TYPE_PV)
+        pv_node = self.find_node_by_type(TYPE_PV)
         if pv_node is None:
             return SpanPVSnapshot()
 
@@ -396,7 +396,7 @@ class HomieDeviceConsumer:
         4. both grid signals zero AND DPS != GRID — islanded
         """
         # 1. BESS grid-state is authoritative when available
-        bess_node = self._find_node_by_type(TYPE_BESS)
+        bess_node = self.find_node_by_type(TYPE_BESS)
         if bess_node is not None:
             gs = self._get_prop(bess_node, "grid-state")
             if gs == "ON_GRID":
@@ -482,7 +482,7 @@ class HomieDeviceConsumer:
 
     def _build_snapshot(self) -> SpanPanelSnapshot:
         """Build full snapshot from accumulated property values."""
-        core_node = self._find_node_by_type(TYPE_CORE)
+        core_node = self.find_node_by_type(TYPE_CORE)
         upstream_lugs = self._find_lugs_node(LUGS_UPSTREAM)
         downstream_lugs = self._find_lugs_node(LUGS_DOWNSTREAM)
 
@@ -569,7 +569,7 @@ class HomieDeviceConsumer:
             downstream_l2_current = _parse_float(dl2_i) if dl2_i else None
 
         # Power flows
-        pf_node = self._find_node_by_type(TYPE_POWER_FLOWS)
+        pf_node = self.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
@@ -607,7 +607,7 @@ class HomieDeviceConsumer:
         evse = self._build_evse_devices()
 
         # BESS grid state for v2-native field
-        bess_node = self._find_node_by_type(TYPE_BESS)
+        bess_node = self.find_node_by_type(TYPE_BESS)
         grid_state: str | None = None
         if bess_node is not None:
             gs = self._get_prop(bess_node, "grid-state")

{span_panel_api-2.2.0 → span_panel_api-2.2.2}/src/span_panel_api/protocol.py

@@ -53,6 +53,13 @@ class CircuitControlProtocol(Protocol):
     async def set_circuit_priority(self, circuit_id: str, priority: str) -> None: ...
 
 
+@runtime_checkable
+class PanelControlProtocol(Protocol):
+    """Control protocol for panel-level settable properties."""
+
+    async def set_dominant_power_source(self, value: str) -> None: ...
+
+
 @runtime_checkable
 class StreamingCapableProtocol(Protocol):
     """Push-based transport that delivers updates via callbacks."""

{span_panel_api-2.2.0 → span_panel_api-2.2.2}/src/span_panel_api/simulation.py

@@ -1168,7 +1168,18 @@ class DynamicSimulationEngine:
 
         # --- Battery ---
         soe_percentage = float(soe_data["soe"]["percentage"])
-        battery_snapshot = SpanBatterySnapshot(soe_percentage=soe_percentage)
+        nameplate_kwh = 13.5  # Simulated battery capacity
+        soe_kwh = nameplate_kwh * soe_percentage / 100.0
+        battery_snapshot = SpanBatterySnapshot(
+            soe_percentage=soe_percentage,
+            soe_kwh=soe_kwh,
+            vendor_name="Simulated BESS",
+            product_name="Battery Storage",
+            serial_number=f"SIM-BESS-{raw['status']['system']['serial']}",
+            software_version="1.0.0-sim",
+            nameplate_capacity_kwh=nameplate_kwh,
+            connected=True,
+        )
 
         # --- EVSE ---
         evse_devices: dict[str, SpanEvseSnapshot] = {}