span-panel-api 2.4.1__tar.gz → 2.5.0__tar.gz

{span_panel_api-2.4.1 → span_panel_api-2.5.0}/.github/workflows/ci.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.13", "3.14"]
+        python-version: ["3.14"]
 
     steps:
     - name: Checkout code
@@ -21,10 +21,9 @@ jobs:
       uses: actions/setup-python@v6
       with:
         python-version: ${{ matrix.python-version }}
-        allow-prereleases: true
 
     - name: Install uv
-      uses: astral-sh/setup-uv@v5
+      uses: astral-sh/setup-uv@v7
       with:
         enable-cache: true
 
@@ -50,10 +49,10 @@ jobs:
     - name: Set up Python
       uses: actions/setup-python@v6
       with:
-        python-version: "3.13"
+        python-version: "3.14"
 
     - name: Install uv
-      uses: astral-sh/setup-uv@v5
+      uses: astral-sh/setup-uv@v7
       with:
         enable-cache: true
 
@@ -79,10 +78,10 @@ jobs:
     - name: Set up Python
       uses: actions/setup-python@v6
       with:
-        python-version: "3.13"
+        python-version: "3.14"
 
     - name: Install uv
-      uses: astral-sh/setup-uv@v5
+      uses: astral-sh/setup-uv@v7
       with:
         enable-cache: true
 

{span_panel_api-2.4.1 → span_panel_api-2.5.0}/.github/workflows/dependabot-auto-approve.yml

@@ -15,7 +15,7 @@ jobs:
     steps:
       - name: Dependabot metadata
         id: metadata
-        uses: dependabot/fetch-metadata@v2.5.0
+        uses: dependabot/fetch-metadata@v3.0.0
         with:
           github-token: "${{ secrets.GITHUB_TOKEN }}"
 

{span_panel_api-2.4.1 → span_panel_api-2.5.0}/.github/workflows/dependabot-auto-merge.yml

@@ -15,7 +15,7 @@ jobs:
     steps:
       - name: Dependabot metadata
         id: metadata
-        uses: dependabot/fetch-metadata@v2.5.0
+        uses: dependabot/fetch-metadata@v3.0.0
         with:
           github-token: "${{ secrets.GITHUB_TOKEN }}"
 

{span_panel_api-2.4.1 → span_panel_api-2.5.0}/.github/workflows/release.yml

@@ -18,10 +18,10 @@ jobs:
     - name: Set up Python
       uses: actions/setup-python@v6
       with:
-        python-version: "3.13"
+        python-version: "3.14"
 
     - name: Install uv
-      uses: astral-sh/setup-uv@v5
+      uses: astral-sh/setup-uv@v7
       with:
         enable-cache: true
 

{span_panel_api-2.4.1 → span_panel_api-2.5.0}/CHANGELOG.md

@@ -4,6 +4,29 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.5.0] - 03/2026
+
+### Added
+
+- **`HomiePropertyAccumulator`** — new layer that handles generic Homie v5 protocol parsing (message routing, property/target storage, dirty-node tracking) with an explicit lifecycle state machine (`HomieLifecycle`), cleanly separated from SPAN-specific
+  snapshot construction.
+- **`$target` property support** — `SpanCircuitSnapshot` gains `relay_state_target` and `priority_target` fields, surfacing the desired-vs-actual state for relay and shed-priority commands.
+- **Dirty-node snapshot caching** — `HomieDeviceConsumer.build_snapshot()` tracks which nodes changed since the last build and returns a cached snapshot when nothing is dirty, reducing per-scan CPU cost on constrained hardware.
+
+### Changed
+
+- **Layered Homie consumer architecture** — `HomieDeviceConsumer` no longer handles protocol plumbing. It reads from `HomiePropertyAccumulator` via a query API (`get_prop`, `get_target`, `nodes_by_type`, etc.) and focuses solely on SPAN domain
+  interpretation: power sign normalization, DSM derivation, unmapped tab synthesis, and snapshot assembly.
+- **`SpanMqttClient` composes both layers** — `connect()` creates an accumulator and wires it into the consumer. The public client API is unchanged.
+- **Property callbacks fire only on value change** — retained messages replaying already-known values no longer trigger callback storms on MQTT reconnect.
+
+## [2.4.2] - 03/2026
+
+### Fixed
+
+- **Moved SSL context creation to executor** — `httpx.AsyncClient()` eagerly calls `ssl.SSLContext.load_verify_locations()` with the system CA bundle, which is a blocking file I/O operation that triggers Home Assistant's event loop protection. The SSL
+  context is now created in an executor thread and passed to httpx via `verify=ctx`.
+
 ## [2.4.1] - 03/2026
 
 ### Fixed

{span_panel_api-2.4.1 → span_panel_api-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: span-panel-api
-Version: 2.4.1
+Version: 2.5.0
 Summary: A client library 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
@@ -22,7 +22,6 @@ Description-Content-Type: text/markdown
 [![CI Status](https://img.shields.io/github/actions/workflow/status/SpanPanel/span-panel-api/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/SpanPanel/span-panel-api/actions/workflows/ci.yml)
 
 [![Code Quality](https://img.shields.io/codefactor/grade/github/SpanPanel/span-panel-api?style=flat-square)](https://www.codefactor.io/repository/github/spanpanel/span-panel-api)
-[![Security](https://img.shields.io/snyk/vulnerabilities/github/SpanPanel/span-panel-api?style=flat-square)](https://snyk.io/test/github/SpanPanel/span-panel-api)
 
 [![Pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&style=flat-square)](https://github.com/pre-commit/pre-commit)
 [![Linting: Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json&style=flat-square)](https://github.com/astral-sh/ruff)
@@ -47,16 +46,18 @@ pip install span-panel-api
 
 - `httpx` — v2 authentication and detection endpoints
 - `paho-mqtt` — MQTT/Homie transport (real-time push)
-- `pyyaml` — simulation configuration
+- `pyyaml` — YAML parsing for configuration and API payloads
 
 ## Architecture
 
-v2.0.0 is a ground-up rewrite. The package connects to the SPAN Panel's on-device MQTT broker using the [Homie v5](https://homieiot.github.io/) convention. All panel and circuit state is delivered via retained MQTT messages — no polling required.
-
 ### Transport
 
-The `SpanMqttClient` connects to the panel's MQTT broker (MQTTS or WebSocket) and subscribes to the Homie device tree. A `HomieDeviceConsumer` state machine parses incoming topic updates into typed `SpanPanelSnapshot` dataclasses. Changes are pushed to
-consumers via callbacks.
+The `SpanMqttClient` connects to the panel's MQTT broker (MQTTS or WebSocket) and subscribes to the Homie device tree. A two-layer architecture separates generic Homie v5 protocol handling from SPAN-specific interpretation:
+
+- **`HomiePropertyAccumulator`** — handles message routing, property and `$target` storage, dirty-node tracking, and an explicit lifecycle state machine (`HomieLifecycle`). Protocol-only; no SPAN domain knowledge.
+- **`HomieDeviceConsumer`** — reads from the accumulator via a query API and builds typed `SpanPanelSnapshot` dataclasses. Handles power sign normalization, DSM derivation, unmapped tab synthesis, and dirty-node-aware snapshot caching.
+
+Changes are pushed to consumers via callbacks. Dirty-node tracking allows the snapshot builder to skip unchanged nodes, reducing per-scan CPU cost on constrained hardware.
 
 ### Event-Loop-Driven I/O (Home Assistant Compatible)
 
@@ -89,6 +90,7 @@ The library defines three structural subtyping protocols (PEP 544) that both the
 | -------------------------- | ------------------------------------------------------------------------------------- |
 | `SpanPanelClientProtocol`  | Core lifecycle: `connect`, `close`, `ping`, `get_snapshot`                            |
 | `CircuitControlProtocol`   | Relay and shed-priority control: `set_circuit_relay`, `set_circuit_priority`          |
+| `PanelControlProtocol`     | Panel-level control: `set_dominant_power_source`                                      |
 | `StreamingCapableProtocol` | Push-based updates: `register_snapshot_callback`, `start_streaming`, `stop_streaming` |
 
 Integration code programs against these protocols, not transport-specific classes.
@@ -100,7 +102,7 @@ All panel state is represented as immutable, frozen dataclasses:
 | Dataclass             | Content                                                                                                                                        |
 | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
 | `SpanPanelSnapshot`   | Complete panel state: power, energy, grid/DSM state, hardware status, per-leg voltages, power flows, lugs current, circuits, battery, PV, EVSE |
-| `SpanCircuitSnapshot` | Per-circuit: power, energy, relay state, priority, tabs, device type, breaker rating, current                                                  |
+| `SpanCircuitSnapshot` | Per-circuit: power, energy, relay state, priority, tabs, device type, breaker rating, current, `$target` pending state                         |
 | `SpanBatterySnapshot` | BESS: SoC percentage, SoE kWh, vendor/product metadata, nameplate capacity                                                                     |
 | `SpanPVSnapshot`      | PV inverter: vendor/product metadata, nameplate capacity                                                                                       |
 | `SpanEvseSnapshot`    | EVSE (EV charger): status, lock state, advertised current, vendor/product/serial/version metadata                                              |
@@ -196,6 +198,40 @@ client = await create_span_client(
 )
 ```
 
+### Direct Client Construction
+
+Consumers that manage their own registration and broker configuration can instantiate `SpanMqttClient` directly:
+
+```python
+from span_panel_api import SpanMqttClient, MqttClientConfig
+
+config = MqttClientConfig(
+    broker_host="192.168.1.100",
+    username="stored-username",
+    password="stored-password",
+    mqtts_port=8883,
+    ws_port=9001,
+    wss_port=443,
+)
+
+client = SpanMqttClient(
+    host="192.168.1.100",
+    serial_number="nj-2316-XXXX",
+    broker_config=config,
+    snapshot_interval=1.0,
+)
+await client.connect()
+```
+
+### Scan Frequency
+
+`set_snapshot_interval()` controls how often push-mode snapshot callbacks fire. Lower values mean lower latency; higher values reduce CPU usage on constrained hardware. Dirty-node caching (v2.5.0) further reduces per-scan cost by skipping unchanged nodes.
+
+```python
+# Reduce snapshot frequency to every 2 seconds
+client.set_snapshot_interval(2.0)
+```
+
 ### Circuit Control
 
 ```python
@@ -207,6 +243,18 @@ await client.set_circuit_relay("circuit-uuid", "CLOSED")
 await client.set_circuit_priority("circuit-uuid", "NEVER")
 ```
 
+### Pending-State Detection
+
+When the panel publishes Homie `$target` properties, `SpanCircuitSnapshot` exposes the desired state alongside the actual state:
+
+```python
+for cid, circuit in snapshot.circuits.items():
+    if circuit.relay_state_target and circuit.relay_state_target != circuit.relay_state:
+        print(f"  {circuit.name}: relay transitioning {circuit.relay_state} → {circuit.relay_state_target}")
+    if circuit.priority_target and circuit.priority_target != circuit.priority:
+        print(f"  {circuit.name}: priority pending {circuit.priority} → {circuit.priority_target}")
+```
+
 ### API Version Detection
 
 Detect whether a panel supports v2 (unauthenticated probe):
@@ -226,7 +274,11 @@ if result.status_info:
 Standalone async functions for v2-specific HTTP operations:
 
 ```python
-from span_panel_api import register_v2, download_ca_cert, get_homie_schema, regenerate_passphrase
+from span_panel_api import (
+    register_v2, download_ca_cert, get_homie_schema,
+    regenerate_passphrase, get_v2_status,
+    register_fqdn, get_fqdn, delete_fqdn,
+)
 
 # Register and obtain MQTT broker credentials
 auth = await register_v2("192.168.1.100", "my-app", passphrase="panel-passphrase")
@@ -243,21 +295,29 @@ print(f"Schema hash: {schema.types_schema_hash}")
 
 # Rotate MQTT broker password (invalidates previous password)
 new_password = await regenerate_passphrase("192.168.1.100", token=auth.access_token)
+
+# Get panel status (unauthenticated)
+status = await get_v2_status("192.168.1.100")
+print(f"Serial: {status.serial_number}, Firmware: {status.firmware_version}")
+
+# FQDN management (for panel TLS certificate SAN)
+await register_fqdn("192.168.1.100", "panel.local", token=auth.access_token)
+fqdn = await get_fqdn("192.168.1.100", token=auth.access_token)
+await delete_fqdn("192.168.1.100", token=auth.access_token)
 ```
 
 ## Error Handling
 
 All exceptions inherit from `SpanPanelError`:
 
-| Exception                      | Cause                                                     |
-| ------------------------------ | --------------------------------------------------------- |
-| `SpanPanelAuthError`           | Invalid passphrase, expired token, or missing credentials |
-| `SpanPanelConnectionError`     | Cannot reach the panel (network/DNS)                      |
-| `SpanPanelTimeoutError`        | Request or connection timed out                           |
-| `SpanPanelValidationError`     | Data validation failure                                   |
-| `SpanPanelAPIError`            | Unexpected HTTP response from v2 endpoints                |
-| `SpanPanelServerError`         | Panel returned HTTP 500                                   |
-| `SimulationConfigurationError` | Invalid simulation YAML configuration                     |
+| Exception                  | Cause                                                     |
+| -------------------------- | --------------------------------------------------------- |
+| `SpanPanelAuthError`       | Invalid passphrase, expired token, or missing credentials |
+| `SpanPanelConnectionError` | Cannot reach the panel (network/DNS)                      |
+| `SpanPanelTimeoutError`    | Request or connection timed out                           |
+| `SpanPanelValidationError` | Data validation failure                                   |
+| `SpanPanelAPIError`        | Unexpected HTTP response from v2 endpoints                |
+| `SpanPanelServerError`     | Panel returned HTTP 500                                   |
 
 ```python
 from span_panel_api import SpanPanelAuthError, SpanPanelConnectionError
@@ -294,14 +354,14 @@ src/span_panel_api/
 ├── models.py            # Snapshot dataclasses (panel, circuit, battery, PV)
 ├── phase_validation.py  # Electrical phase utilities
 ├── protocol.py          # PEP 544 protocols + PanelCapability flags
-├── simulation.py        # Simulation engine (YAML-driven, snapshot-producing)
 └── mqtt/
     ├── __init__.py
+    ├── accumulator.py   # HomiePropertyAccumulator (Homie v5 protocol layer)
     ├── async_client.py  # NullLock + AsyncMQTTClient (HA core pattern)
     ├── client.py        # SpanMqttClient (all three protocols)
     ├── connection.py    # AsyncMqttBridge (event-loop-driven, no threads)
     ├── const.py         # MQTT/Homie constants + UUID helpers
-    ├── homie.py         # HomieDeviceConsumer (Homie v5 state machine)
+    ├── homie.py         # HomieDeviceConsumer (SPAN snapshot builder)
     └── models.py        # MqttClientConfig, MqttTransport
 ```
 

{span_panel_api-2.4.1 → span_panel_api-2.5.0}/README.md

@@ -7,7 +7,6 @@
 [![CI Status](https://img.shields.io/github/actions/workflow/status/SpanPanel/span-panel-api/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/SpanPanel/span-panel-api/actions/workflows/ci.yml)
 
 [![Code Quality](https://img.shields.io/codefactor/grade/github/SpanPanel/span-panel-api?style=flat-square)](https://www.codefactor.io/repository/github/spanpanel/span-panel-api)
-[![Security](https://img.shields.io/snyk/vulnerabilities/github/SpanPanel/span-panel-api?style=flat-square)](https://snyk.io/test/github/SpanPanel/span-panel-api)
 
 [![Pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&style=flat-square)](https://github.com/pre-commit/pre-commit)
 [![Linting: Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json&style=flat-square)](https://github.com/astral-sh/ruff)
@@ -32,16 +31,18 @@ pip install span-panel-api
 
 - `httpx` — v2 authentication and detection endpoints
 - `paho-mqtt` — MQTT/Homie transport (real-time push)
-- `pyyaml` — simulation configuration
+- `pyyaml` — YAML parsing for configuration and API payloads
 
 ## Architecture
 
-v2.0.0 is a ground-up rewrite. The package connects to the SPAN Panel's on-device MQTT broker using the [Homie v5](https://homieiot.github.io/) convention. All panel and circuit state is delivered via retained MQTT messages — no polling required.
-
 ### Transport
 
-The `SpanMqttClient` connects to the panel's MQTT broker (MQTTS or WebSocket) and subscribes to the Homie device tree. A `HomieDeviceConsumer` state machine parses incoming topic updates into typed `SpanPanelSnapshot` dataclasses. Changes are pushed to
-consumers via callbacks.
+The `SpanMqttClient` connects to the panel's MQTT broker (MQTTS or WebSocket) and subscribes to the Homie device tree. A two-layer architecture separates generic Homie v5 protocol handling from SPAN-specific interpretation:
+
+- **`HomiePropertyAccumulator`** — handles message routing, property and `$target` storage, dirty-node tracking, and an explicit lifecycle state machine (`HomieLifecycle`). Protocol-only; no SPAN domain knowledge.
+- **`HomieDeviceConsumer`** — reads from the accumulator via a query API and builds typed `SpanPanelSnapshot` dataclasses. Handles power sign normalization, DSM derivation, unmapped tab synthesis, and dirty-node-aware snapshot caching.
+
+Changes are pushed to consumers via callbacks. Dirty-node tracking allows the snapshot builder to skip unchanged nodes, reducing per-scan CPU cost on constrained hardware.
 
 ### Event-Loop-Driven I/O (Home Assistant Compatible)
 
@@ -74,6 +75,7 @@ The library defines three structural subtyping protocols (PEP 544) that both the
 | -------------------------- | ------------------------------------------------------------------------------------- |
 | `SpanPanelClientProtocol`  | Core lifecycle: `connect`, `close`, `ping`, `get_snapshot`                            |
 | `CircuitControlProtocol`   | Relay and shed-priority control: `set_circuit_relay`, `set_circuit_priority`          |
+| `PanelControlProtocol`     | Panel-level control: `set_dominant_power_source`                                      |
 | `StreamingCapableProtocol` | Push-based updates: `register_snapshot_callback`, `start_streaming`, `stop_streaming` |
 
 Integration code programs against these protocols, not transport-specific classes.
@@ -85,7 +87,7 @@ All panel state is represented as immutable, frozen dataclasses:
 | Dataclass             | Content                                                                                                                                        |
 | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
 | `SpanPanelSnapshot`   | Complete panel state: power, energy, grid/DSM state, hardware status, per-leg voltages, power flows, lugs current, circuits, battery, PV, EVSE |
-| `SpanCircuitSnapshot` | Per-circuit: power, energy, relay state, priority, tabs, device type, breaker rating, current                                                  |
+| `SpanCircuitSnapshot` | Per-circuit: power, energy, relay state, priority, tabs, device type, breaker rating, current, `$target` pending state                         |
 | `SpanBatterySnapshot` | BESS: SoC percentage, SoE kWh, vendor/product metadata, nameplate capacity                                                                     |
 | `SpanPVSnapshot`      | PV inverter: vendor/product metadata, nameplate capacity                                                                                       |
 | `SpanEvseSnapshot`    | EVSE (EV charger): status, lock state, advertised current, vendor/product/serial/version metadata                                              |
@@ -181,6 +183,40 @@ client = await create_span_client(
 )
 ```
 
+### Direct Client Construction
+
+Consumers that manage their own registration and broker configuration can instantiate `SpanMqttClient` directly:
+
+```python
+from span_panel_api import SpanMqttClient, MqttClientConfig
+
+config = MqttClientConfig(
+    broker_host="192.168.1.100",
+    username="stored-username",
+    password="stored-password",
+    mqtts_port=8883,
+    ws_port=9001,
+    wss_port=443,
+)
+
+client = SpanMqttClient(
+    host="192.168.1.100",
+    serial_number="nj-2316-XXXX",
+    broker_config=config,
+    snapshot_interval=1.0,
+)
+await client.connect()
+```
+
+### Scan Frequency
+
+`set_snapshot_interval()` controls how often push-mode snapshot callbacks fire. Lower values mean lower latency; higher values reduce CPU usage on constrained hardware. Dirty-node caching (v2.5.0) further reduces per-scan cost by skipping unchanged nodes.
+
+```python
+# Reduce snapshot frequency to every 2 seconds
+client.set_snapshot_interval(2.0)
+```
+
 ### Circuit Control
 
 ```python
@@ -192,6 +228,18 @@ await client.set_circuit_relay("circuit-uuid", "CLOSED")
 await client.set_circuit_priority("circuit-uuid", "NEVER")
 ```
 
+### Pending-State Detection
+
+When the panel publishes Homie `$target` properties, `SpanCircuitSnapshot` exposes the desired state alongside the actual state:
+
+```python
+for cid, circuit in snapshot.circuits.items():
+    if circuit.relay_state_target and circuit.relay_state_target != circuit.relay_state:
+        print(f"  {circuit.name}: relay transitioning {circuit.relay_state} → {circuit.relay_state_target}")
+    if circuit.priority_target and circuit.priority_target != circuit.priority:
+        print(f"  {circuit.name}: priority pending {circuit.priority} → {circuit.priority_target}")
+```
+
 ### API Version Detection
 
 Detect whether a panel supports v2 (unauthenticated probe):
@@ -211,7 +259,11 @@ if result.status_info:
 Standalone async functions for v2-specific HTTP operations:
 
 ```python
-from span_panel_api import register_v2, download_ca_cert, get_homie_schema, regenerate_passphrase
+from span_panel_api import (
+    register_v2, download_ca_cert, get_homie_schema,
+    regenerate_passphrase, get_v2_status,
+    register_fqdn, get_fqdn, delete_fqdn,
+)
 
 # Register and obtain MQTT broker credentials
 auth = await register_v2("192.168.1.100", "my-app", passphrase="panel-passphrase")
@@ -228,21 +280,29 @@ print(f"Schema hash: {schema.types_schema_hash}")
 
 # Rotate MQTT broker password (invalidates previous password)
 new_password = await regenerate_passphrase("192.168.1.100", token=auth.access_token)
+
+# Get panel status (unauthenticated)
+status = await get_v2_status("192.168.1.100")
+print(f"Serial: {status.serial_number}, Firmware: {status.firmware_version}")
+
+# FQDN management (for panel TLS certificate SAN)
+await register_fqdn("192.168.1.100", "panel.local", token=auth.access_token)
+fqdn = await get_fqdn("192.168.1.100", token=auth.access_token)
+await delete_fqdn("192.168.1.100", token=auth.access_token)
 ```
 
 ## Error Handling
 
 All exceptions inherit from `SpanPanelError`:
 
-| Exception                      | Cause                                                     |
-| ------------------------------ | --------------------------------------------------------- |
-| `SpanPanelAuthError`           | Invalid passphrase, expired token, or missing credentials |
-| `SpanPanelConnectionError`     | Cannot reach the panel (network/DNS)                      |
-| `SpanPanelTimeoutError`        | Request or connection timed out                           |
-| `SpanPanelValidationError`     | Data validation failure                                   |
-| `SpanPanelAPIError`            | Unexpected HTTP response from v2 endpoints                |
-| `SpanPanelServerError`         | Panel returned HTTP 500                                   |
-| `SimulationConfigurationError` | Invalid simulation YAML configuration                     |
+| Exception                  | Cause                                                     |
+| -------------------------- | --------------------------------------------------------- |
+| `SpanPanelAuthError`       | Invalid passphrase, expired token, or missing credentials |
+| `SpanPanelConnectionError` | Cannot reach the panel (network/DNS)                      |
+| `SpanPanelTimeoutError`    | Request or connection timed out                           |
+| `SpanPanelValidationError` | Data validation failure                                   |
+| `SpanPanelAPIError`        | Unexpected HTTP response from v2 endpoints                |
+| `SpanPanelServerError`     | Panel returned HTTP 500                                   |
 
 ```python
 from span_panel_api import SpanPanelAuthError, SpanPanelConnectionError
@@ -279,14 +339,14 @@ src/span_panel_api/
 ├── models.py            # Snapshot dataclasses (panel, circuit, battery, PV)
 ├── phase_validation.py  # Electrical phase utilities
 ├── protocol.py          # PEP 544 protocols + PanelCapability flags
-├── simulation.py        # Simulation engine (YAML-driven, snapshot-producing)
 └── mqtt/
     ├── __init__.py
+    ├── accumulator.py   # HomiePropertyAccumulator (Homie v5 protocol layer)
     ├── async_client.py  # NullLock + AsyncMQTTClient (HA core pattern)
     ├── client.py        # SpanMqttClient (all three protocols)
     ├── connection.py    # AsyncMqttBridge (event-loop-driven, no threads)
     ├── const.py         # MQTT/Homie constants + UUID helpers
-    ├── homie.py         # HomieDeviceConsumer (Homie v5 state machine)
+    ├── homie.py         # HomieDeviceConsumer (SPAN snapshot builder)
     └── models.py        # MqttClientConfig, MqttTransport
 ```
 

{span_panel_api-2.4.1 → span_panel_api-2.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "span-panel-api"
-version = "2.4.1"
+version = "2.5.0"
 description = "A client library for SPAN Panel API"
 authors = [
     {name = "SpanPanel"}
@@ -45,7 +45,7 @@ requires = ["hatchling"]
 build-backend = "hatchling.build"
 
 [tool.hatch.build.targets.wheel]
-packages = ["src/span_panel_api"]
+packages = ["src/span_panel_api", "scripts"]
 
 [tool.ruff]
 line-length = 125

{span_panel_api-2.4.1 → span_panel_api-2.5.0}/src/span_panel_api/__init__.py

@@ -37,7 +37,7 @@ from .models import (
     V2HomieSchema,
     V2StatusInfo,
 )
-from .mqtt import MqttClientConfig, SpanMqttClient
+from .mqtt import HomieLifecycle, HomiePropertyAccumulator, MqttClientConfig, SpanMqttClient
 from .phase_validation import (
     PhaseDistribution,
     are_tabs_opposite_phase,
@@ -54,7 +54,7 @@ from .protocol import (
     StreamingCapableProtocol,
 )
 
-__version__ = "2.4.0"
+__version__ = "2.5.0"
 # fmt: off
 __all__ = [  # noqa: RUF022
     # Protocols
@@ -90,6 +90,8 @@ __all__ = [  # noqa: RUF022
     "regenerate_passphrase",
     "register_v2",
     # Transport
+    "HomieLifecycle",
+    "HomiePropertyAccumulator",
     "MqttClientConfig",
     "SpanMqttClient",
     # Phase validation

span_panel_api-2.5.0/src/span_panel_api/_http.py

@@ -0,0 +1,66 @@
+"""Shared HTTP helpers for SPAN Panel bootstrap REST calls."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from dataclasses import dataclass, field
+import ssl
+
+import httpx
+
+
+@dataclass
+class _SSLCache:
+    """Mutable container for the cached SSLContext and its async lock."""
+
+    context: ssl.SSLContext | None = None
+    lock: asyncio.Lock | None = field(default=None, repr=False)
+
+    def get_lock(self) -> asyncio.Lock:
+        """Return the async lock, creating it lazily."""
+        if self.lock is None:
+            self.lock = asyncio.Lock()
+        return self.lock
+
+
+_ssl_cache = _SSLCache()
+
+
+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}"
+
+
+async def _create_ssl_context() -> ssl.SSLContext:
+    """Return a cached default SSL context, creating it in an executor on first call.
+
+    ``ssl.create_default_context()`` calls ``load_verify_locations`` which
+    performs blocking file I/O on the system CA bundle.  The resulting context
+    is thread-safe and reusable, so we cache it for the lifetime of the process.
+    """
+    if _ssl_cache.context is not None:
+        return _ssl_cache.context
+    async with _ssl_cache.get_lock():
+        # Double-check after acquiring the lock.
+        if _ssl_cache.context is not None:
+            return _ssl_cache.context
+        loop = asyncio.get_running_loop()
+        _ssl_cache.context = await loop.run_in_executor(None, ssl.create_default_context)
+        return _ssl_cache.context
+
+
+@asynccontextmanager
+async def _get_client(
+    httpx_client: httpx.AsyncClient | None,
+    timeout: float,
+) -> AsyncIterator[httpx.AsyncClient]:
+    if httpx_client is not None:
+        yield httpx_client
+        return
+    ctx = await _create_ssl_context()
+    async with httpx.AsyncClient(timeout=timeout, verify=ctx) as client:
+        yield client

{span_panel_api-2.4.1 → span_panel_api-2.5.0}/src/span_panel_api/models.py

@@ -42,6 +42,8 @@ class SpanCircuitSnapshot:
     relay_requester: str = "UNKNOWN"  # v2 new: circuit/relay-requester
     energy_accum_update_time_s: int = 0  # v1: poll timestamp | v2: MQTT arrival time
     instant_power_update_time_s: int = 0  # v1: poll timestamp | v2: MQTT arrival time
+    relay_state_target: str | None = None  # v2: $target for relay (desired state)
+    priority_target: str | None = None  # v2: $target for shed-priority (desired state)
 
 
 @dataclass(frozen=True, slots=True)

{span_panel_api-2.4.1 → span_panel_api-2.5.0}/src/span_panel_api/mqtt/__init__.py

@@ -1,5 +1,6 @@
 """SPAN Panel MQTT/Homie transport."""
 
+from .accumulator import HomieLifecycle, HomiePropertyAccumulator
 from .async_client import AsyncMQTTClient
 from .client import SpanMqttClient
 from .connection import AsyncMqttBridge
@@ -10,6 +11,8 @@ __all__ = [
     "AsyncMQTTClient",
     "AsyncMqttBridge",
     "HomieDeviceConsumer",
+    "HomieLifecycle",
+    "HomiePropertyAccumulator",
     "MqttClientConfig",
     "SpanMqttClient",
 ]