Merge pull request #117 from SpanPanel/2_3_0

2 3 0 extract simulation, add diagnostics for schema drift

Author: cayossarian

docs/simulation.md

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

pyproject.toml

@@ -7,7 +7,6 @@
 from .auth import download_ca_cert, get_homie_schema, regenerate_passphrase, register_v2
 from .detection import DetectionResult, detect_api_version
 from .exceptions import (
-    SimulationConfigurationError,
     SpanPanelAPIError,
     SpanPanelAuthError,
     SpanPanelConnectionError,
@@ -18,6 +17,7 @@
 )
 from .factory import create_span_client
 from .models import (
+    FieldMetadata,
     SpanBatterySnapshot,
     SpanCircuitSnapshot,
     SpanEvseSnapshot,
@@ -43,9 +43,8 @@
     SpanPanelClientProtocol,
     StreamingCapableProtocol,
 )
-from .simulation import DynamicSimulationEngine
 
-__version__ = "2.2.1"
+__version__ = "2.3.0"
 # fmt: off
 __all__ = [  # noqa: RUF022
     # Protocols
@@ -54,6 +53,8 @@
     "PanelControlProtocol",
     "SpanPanelClientProtocol",
     "StreamingCapableProtocol",
+    # Metadata
+    "FieldMetadata",
     # Snapshots
     "SpanBatterySnapshot",
     "SpanCircuitSnapshot",
@@ -84,15 +85,12 @@
     "suggest_balanced_pairing",
     "validate_solar_tabs",
     # Exceptions
-    "SimulationConfigurationError",
     "SpanPanelAPIError",
     "SpanPanelAuthError",
     "SpanPanelConnectionError",
     "SpanPanelError",
     "SpanPanelServerError",
     "SpanPanelTimeoutError",
     "SpanPanelValidationError",
-    # Simulation
-    "DynamicSimulationEngine",
 ]
 # fmt: on

src/span_panel_api/__init__.py

@@ -18,6 +18,13 @@
 from .models import V2AuthResponse, V2HomieSchema, V2StatusInfo
 
 
+def _build_url(host: str, port: int, path: str) -> str:
+    """Build an HTTP URL, omitting the port when it is the default (80)."""
+    if port == 80:
+        return f"http://{host}{path}"
+    return f"http://{host}:{port}{path}"
+
+
 def _str(val: object) -> str:
     """Extract a string from a JSON-decoded value."""
     return str(val) if val is not None else ""
@@ -37,6 +44,7 @@ async def register_v2(
     name: str,
     passphrase: str | None = None,
     timeout: float = 10.0,
+    port: int = 80,
 ) -> V2AuthResponse:
     """Register with the SPAN Panel v2 API and obtain access + MQTT credentials.
 
@@ -49,6 +57,7 @@ async def register_v2(
         name: Client display name base (e.g., "home-assistant"); a UUID suffix is appended
         passphrase: Panel passphrase (printed on label or set by owner). None for door bypass.
         timeout: Request timeout in seconds
+        port: HTTP port of the panel bootstrap API
 
     Returns:
         V2AuthResponse with access token and MQTT broker credentials
@@ -59,7 +68,7 @@ async def register_v2(
         SpanPanelTimeoutError: Request timed out
         SpanPanelAPIError: Unexpected response
     """
-    url = f"http://{host}/api/v2/auth/register"
+    url = _build_url(host, port, "/api/v2/auth/register")
     # The panel requires unique client names — append a random suffix.
     # The passphrase field must be "hopPassphrase" per the SPAN v2 API spec.
     suffix = uuid.uuid4().hex[:8]
@@ -99,12 +108,13 @@ async def register_v2(
     )
 
 
-async def download_ca_cert(host: str, timeout: float = 10.0) -> str:
+async def download_ca_cert(host: str, timeout: float = 10.0, port: int = 80) -> str:
     """Download the PEM CA certificate from the SPAN Panel.
 
     Args:
         host: IP address or hostname of the SPAN Panel
         timeout: Request timeout in seconds
+        port: HTTP port of the panel bootstrap API
 
     Returns:
         PEM-encoded CA certificate as a string
@@ -114,7 +124,7 @@ async def download_ca_cert(host: str, timeout: float = 10.0) -> str:
         SpanPanelTimeoutError: Request timed out
         SpanPanelAPIError: Unexpected response or invalid PEM
     """
-    url = f"http://{host}/api/v2/certificate/ca"
+    url = _build_url(host, port, "/api/v2/certificate/ca")
 
     try:
         async with httpx.AsyncClient(timeout=timeout, verify=False) as client:  # nosec B501
@@ -134,14 +144,15 @@ async def download_ca_cert(host: str, timeout: float = 10.0) -> str:
     return pem
 
 
-async def get_homie_schema(host: str, timeout: float = 10.0) -> V2HomieSchema:
+async def get_homie_schema(host: str, timeout: float = 10.0, port: int = 80) -> V2HomieSchema:
     """Fetch the Homie property schema from the SPAN Panel.
 
     This endpoint is unauthenticated.
 
     Args:
         host: IP address or hostname of the SPAN Panel
         timeout: Request timeout in seconds
+        port: HTTP port of the panel bootstrap API
 
     Returns:
         V2HomieSchema with firmware version, schema hash, and type definitions
@@ -151,7 +162,7 @@ async def get_homie_schema(host: str, timeout: float = 10.0) -> V2HomieSchema:
         SpanPanelTimeoutError: Request timed out
         SpanPanelAPIError: Unexpected response
     """
-    url = f"http://{host}/api/v2/homie/schema"
+    url = _build_url(host, port, "/api/v2/homie/schema")
 
     try:
         async with httpx.AsyncClient(timeout=timeout, verify=False) as client:  # nosec B501
@@ -187,7 +198,7 @@ async def get_homie_schema(host: str, timeout: float = 10.0) -> V2HomieSchema:
     )
 
 
-async def regenerate_passphrase(host: str, token: str, timeout: float = 10.0) -> str:
+async def regenerate_passphrase(host: str, token: str, timeout: float = 10.0, port: int = 80) -> str:
     """Rotate the MQTT broker password on the SPAN Panel.
 
     After this call, the previous broker password is invalidated.
@@ -198,6 +209,7 @@ async def regenerate_passphrase(host: str, token: str, timeout: float = 10.0) ->
         host: IP address or hostname of the SPAN Panel
         token: Valid JWT access token
         timeout: Request timeout in seconds
+        port: HTTP port of the panel bootstrap API
 
     Returns:
         New MQTT broker password
@@ -208,7 +220,7 @@ async def regenerate_passphrase(host: str, token: str, timeout: float = 10.0) ->
         SpanPanelTimeoutError: Request timed out
         SpanPanelAPIError: Unexpected response
     """
-    url = f"http://{host}/api/v2/auth/passphrase"
+    url = _build_url(host, port, "/api/v2/auth/passphrase")
     headers = {"Authorization": f"Bearer {token}"}
 
     try:
@@ -229,12 +241,13 @@ async def regenerate_passphrase(host: str, token: str, timeout: float = 10.0) ->
     return _str(data["ebusBrokerPassword"])
 
 
-async def get_v2_status(host: str, timeout: float = 5.0) -> V2StatusInfo:
+async def get_v2_status(host: str, timeout: float = 5.0, port: int = 80) -> V2StatusInfo:
     """Lightweight v2 status probe (unauthenticated).
 
     Args:
         host: IP address or hostname of the SPAN Panel
         timeout: Request timeout in seconds
+        port: HTTP port of the panel bootstrap API
 
     Returns:
         V2StatusInfo with serial number and firmware version
@@ -244,7 +257,7 @@ async def get_v2_status(host: str, timeout: float = 5.0) -> V2StatusInfo:
         SpanPanelTimeoutError: Request timed out
         SpanPanelAPIError: Unexpected response or non-v2 panel
     """
-    url = f"http://{host}/api/v2/status"
+    url = _build_url(host, port, "/api/v2/status")
 
     try:
         async with httpx.AsyncClient(timeout=timeout, verify=False) as client:  # nosec B501

src/span_panel_api/auth.py

@@ -14,6 +14,13 @@
 from .models import V2StatusInfo
 
 
+def _build_url(host: str, port: int, path: str) -> str:
+    """Build an HTTP URL, omitting the port when it is the default (80)."""
+    if port == 80:
+        return f"http://{host}{path}"
+    return f"http://{host}:{port}{path}"
+
+
 @dataclass(frozen=True, slots=True)
 class DetectionResult:
     """Result of probing a SPAN Panel for API version support."""
@@ -22,7 +29,7 @@ class DetectionResult:
     status_info: V2StatusInfo | None = None  # populated when v2 detected
 
 
-async def detect_api_version(host: str, timeout: float = 5.0) -> DetectionResult:
+async def detect_api_version(host: str, timeout: float = 5.0, port: int = 80) -> DetectionResult:
     """Detect SPAN Panel API version.
 
     Probes GET /api/v2/status (unauthenticated).
@@ -32,11 +39,12 @@ async def detect_api_version(host: str, timeout: float = 5.0) -> DetectionResult
     Args:
         host: IP address or hostname of the SPAN Panel
         timeout: Request timeout in seconds
+        port: HTTP port of the panel bootstrap API
 
     Returns:
         DetectionResult indicating which API version is available
     """
-    url = f"http://{host}/api/v2/status"
+    url = _build_url(host, port, "/api/v2/status")
     try:
         async with httpx.AsyncClient(timeout=timeout, verify=False) as client:  # nosec B501
             response = await client.get(url)

src/span_panel_api/detection.py

@@ -34,7 +34,3 @@ def __str__(self) -> str:
 
 class SpanPanelServerError(SpanPanelAPIError):
     """Server error (500)."""
-
-
-class SimulationConfigurationError(SpanPanelError):
-    """Simulation configuration is invalid or missing required data."""

src/span_panel_api/exceptions.py

@@ -45,7 +45,9 @@ class SpanPVSnapshot:
 
     vendor_name: str | None = None  # pv/vendor-name
     product_name: str | None = None  # pv/product-name
-    nameplate_capacity_kw: float | None = None  # pv/nameplate-capacity (kW)
+    nameplate_capacity_w: float | None = None  # pv/nameplate-capacity (W)
+    feed_circuit_id: str | None = None  # pv/feed (normalized circuit ID)
+    relative_position: str | None = None  # pv/relative-position (IN_PANEL | UPSTREAM | DOWNSTREAM)
 
 
 @dataclass(frozen=True, slots=True)
@@ -84,6 +86,19 @@ class SpanBatterySnapshot:
     connected: bool | None = None  # bess/connected
 
 
+@dataclass(frozen=True, slots=True)
+class FieldMetadata:
+    """Schema-derived metadata for a single snapshot field.
+
+    Exposed by the client in a dict keyed by snapshot field path
+    (e.g. ``"panel.instant_grid_power_w"``). The integration compares
+    these values against its sensor definitions for unit validation.
+    """
+
+    unit: str | None  # "W", "A", "V", "%", "kWh", None
+    datatype: str  # "float", "integer", "enum", "string", "boolean"
+
+
 @dataclass(frozen=True, slots=True)
 class V2AuthResponse:
     """Response from POST /api/v2/auth/register."""

src/span_panel_api/models.py

@@ -13,10 +13,11 @@
 
 from ..auth import get_homie_schema
 from ..exceptions import SpanPanelConnectionError, SpanPanelServerError
-from ..models import SpanPanelSnapshot
+from ..models import FieldMetadata, SpanPanelSnapshot
 from ..protocol import PanelCapability
 from .connection import AsyncMqttBridge
 from .const import MQTT_READY_TIMEOUT_S, PROPERTY_SET_TOPIC_FMT, TYPE_CORE, WILDCARD_TOPIC_FMT
+from .field_metadata import build_field_metadata, log_schema_drift
 from .homie import HomieDeviceConsumer
 from .models import MqttClientConfig
 
@@ -37,11 +38,13 @@ def __init__(
         serial_number: str,
         broker_config: MqttClientConfig,
         snapshot_interval: float = 1.0,
+        panel_http_port: int = 80,
     ) -> None:
         self._host = host
         self._serial_number = serial_number
         self._broker_config = broker_config
         self._snapshot_interval = snapshot_interval
+        self._panel_http_port = panel_http_port
 
         self._bridge: AsyncMqttBridge | None = None
         self._homie: HomieDeviceConsumer | None = None
@@ -51,6 +54,9 @@ def __init__(
         self._loop: asyncio.AbstractEventLoop | None = None
         self._background_tasks: set[asyncio.Task[None]] = set()
         self._snapshot_timer: asyncio.TimerHandle | None = None
+        self._field_metadata: dict[str, FieldMetadata] | None = None
+        self._schema_hash: str | None = None
+        self._previous_schema_types: dict[str, dict[str, object]] | None = None
 
     def _require_homie(self) -> HomieDeviceConsumer:
         """Return the HomieDeviceConsumer, raising if not yet connected."""
@@ -75,6 +81,15 @@ def serial_number(self) -> str:
         """Return the panel serial number."""
         return self._serial_number
 
+    @property
+    def field_metadata(self) -> dict[str, FieldMetadata] | None:
+        """Schema-derived metadata for snapshot fields, or None before connect().
+
+        Keyed by snapshot field path (e.g. ``"panel.instant_grid_power_w"``).
+        Built once during ``connect()`` from the Homie schema.
+        """
+        return self._field_metadata
+
     async def connect(self) -> None:
         """Connect to MQTT broker and wait for Homie device ready.
 
@@ -92,10 +107,26 @@ async def connect(self) -> None:
         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)
+        # Fetch schema to determine panel size and build field metadata
+        schema = await get_homie_schema(self._host, port=self._panel_http_port)
         self._homie = HomieDeviceConsumer(self._serial_number, schema.panel_size)
 
+        # Detect schema drift from previous connection
+        new_hash = schema.types_schema_hash
+        if self._schema_hash is not None and new_hash != self._schema_hash:
+            _LOGGER.debug(
+                "Homie schema hash changed: %s → %s (firmware update may have modified the property schema)",
+                self._schema_hash,
+                new_hash,
+            )
+            if self._previous_schema_types is not None:
+                log_schema_drift(self._previous_schema_types, schema.types)
+        self._schema_hash = new_hash
+        self._previous_schema_types = schema.types
+
+        # Build transport-agnostic field metadata from schema
+        self._field_metadata = build_field_metadata(schema.types)
+
         _LOGGER.debug(
             "MQTT: Creating bridge to %s:%s (serial=%s)",
             self._broker_config.broker_host,
@@ -113,6 +144,7 @@ async def connect(self) -> None:
             transport=self._broker_config.transport,
             use_tls=self._broker_config.use_tls,
             loop=self._loop,
+            panel_http_port=self._panel_http_port,
         )
 
         # Wire message handler

src/span_panel_api/mqtt/client.py

@@ -61,6 +61,7 @@ def __init__(
         transport: MqttTransport = "tcp",
         use_tls: bool = True,
         loop: asyncio.AbstractEventLoop | None = None,
+        panel_http_port: int = 80,
     ) -> None:
         self._host = host
         self._port = port
@@ -71,6 +72,7 @@ def __init__(
         self._transport: MqttTransport = transport
         self._use_tls = use_tls
         self._loop = loop
+        self._panel_http_port = panel_http_port
 
         self._connected = False
         self._client: AsyncMQTTClient | None = None
@@ -118,7 +120,7 @@ async def connect(self) -> None:
         ca_cert_path: Path | None = None
         if self._use_tls:
             try:
-                pem = await download_ca_cert(self._panel_host)
+                pem = await download_ca_cert(self._panel_host, port=self._panel_http_port)
             except Exception as exc:
                 raise SpanPanelConnectionError(f"Failed to fetch CA certificate from {self._panel_host}") from exc