span-panel-api-schema-1 1.2.2__tar.gz → 1.3.0b1__tar.gz

{span_panel_api_schema_1-1.2.2 → span_panel_api_schema_1-1.3.0b1}/CHANGELOG.md

@@ -9,6 +9,26 @@ number. A release here means this parser changed, never that the panel did.
 
 Pre-releases are not listed separately. A beta is a step towards the next public version, so its changes are folded into that version's entry as they land and are described against the last public release, never against the beta before it.
 
+## [Unreleased]
+
+Requires `span-panel-api` **3.7.0 or newer**, whose snapshot fields accept the unknown values this parser now reports.
+
+### Changed
+
+- **`proximity_proven` is `None`**, where it was a hard-coded `True`, because the tree publishes no proximity property.
+- **`uptime_s` is `None`**, where it was always `0`, because no device publishes an uptime and this parser keeps no readiness clock to measure one.
+
+### Removed
+
+- **BREAKING FOR CONSUMERS: `snapshot.build_snapshot()` no longer takes the `ready_since` argument**, which no caller in this repository passed, so a call that passes it by keyword or position now raises `TypeError`.
+
+- **BREAKING: snapshots no longer include synthesised `unmapped_tab_N` entries for unoccupied breaker positions, which carried no measured data**, and `panel.build_unmapped_tabs` and `const.UNMAPPED_TAB_PREFIX` are gone with them.
+
+### Fixed
+
+- **A circuit whose shed priority is `UNKNOWN` is no longer reported as sheddable.**
+- **The grid-forming device name falls back to vendor and model instead of showing a device id.**
+
 ## [1.2.2]
 
 Requires `span-panel-api` **3.6.2 or newer**, which waits on this parser's missing labels after a reconnect as well as on connect.

{span_panel_api_schema_1-1.2.2 → span_panel_api_schema_1-1.3.0b1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: span-panel-api-schema-1
-Version: 1.2.2
+Version: 1.3.0b1
 Summary: Parent/child schema (data-model-version 1.x) 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
@@ -8,7 +8,7 @@ Author: SpanPanel
 License-Expression: MIT
 Requires-Python: <4.0,>=3.14
 Requires-Dist: ebus-sdk<0.24,>=0.19.0
-Requires-Dist: span-panel-api<4.0,>=3.6.2
+Requires-Dist: span-panel-api<4.0,>=3.7.0b1
 Description-Content-Type: text/markdown
 
 # span-panel-api-schema-1

{span_panel_api_schema_1-1.2.2 → span_panel_api_schema_1-1.3.0b1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "span-panel-api-schema-1"
-version = "1.2.2"
+version = "1.3.0b1"
 description = "Parent/child schema (data-model-version 1.x) parser for span-panel-api"
 authors = [
     {name = "SpanPanel"}
@@ -28,7 +28,10 @@ dependencies = [
     # Raised to 3.6.1, whose SpanPanelSnapshot.pv documents what this parser builds.
     # Raised to 3.6.2, which waits on this parser's missing labels after a bridge
     # rebuild as well as on connect; the fix spans both, so the pair moves together.
-    "span-panel-api>=3.6.2,<4.0",
+    # Raised to 3.7.0b1, whose snapshot fields accept the unknown values this
+    # parser now reports: against an earlier one, the update times it leaves
+    # unset read as a constant 0.
+    "span-panel-api>=3.7.0b1,<4.0",
     # Only this distribution depends on the eBus SDK. The bootstrap and
     # schema-0 stay clean, so a flat-panel install never pulls it in — which is
     # what bounds the release coupling this dependency introduces to panels on

{span_panel_api_schema_1-1.2.2 → span_panel_api_schema_1-1.3.0b1}/src/span_panel_api_schema_1/adapter.py

@@ -167,10 +167,10 @@ class SchemaOneAdapter:
 
         The model is required only when the root's description declares it: the
         panel's size comes from nowhere else, and a snapshot built a moment too
-        early reports zero spaces, which erases every unmapped position rather
-        than merely mis-stating a number. Asking only for what the panel itself
-        promised keeps a firmware that omits the property connectable — it
-        falls back to the drift warning in `panel_size_from_model`.
+        early reports zero spaces, which leaves a consumer laying out the
+        panel's positions with none to lay out. Asking only for what the panel
+        itself promised keeps a firmware that omits the property connectable —
+        it falls back to the drift warning in `panel_size_from_model`.
         """
         root = self._controller.get_root(self._serial_number)
         if root is None or root.state != STATE_READY or not root.description:

{span_panel_api_schema_1-1.2.2 → span_panel_api_schema_1-1.3.0b1}/src/span_panel_api_schema_1/circuits.py

@@ -10,9 +10,14 @@ Flat property           v1.0 source
 ======================  ===========================================================
 ``always-on``           ``switch/relay-controllable``, inverted
 ``never-backup``        ``$settable`` on ``load-shed/priority``, inverted
-``sheddable``           computed: ``priority != NEVER and relay-controllable``
+``sheddable``           computed: a shed priority and ``relay-controllable``
 ======================  ===========================================================
 
+A shed priority is ``OFF_GRID`` or ``SOC_THRESHOLD``. SPAN's r202633 changelog
+derives sheddable as ``priority != NEVER`` and asks consumers to treat ``UNKNOWN``
+as "not yet known" rather than as sheddable, so the rule names the priorities the
+panel sheds by instead of excluding the one it never sheds.
+
 Sign and direction are unchanged from the flat schema, and both are the reverse
 of what the property names suggest. Values are in the enclosure's reference
 frame: a normal load reads **negative** ``active-power`` and accumulates
@@ -23,7 +28,7 @@ accumulators are swapped.
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Final
 
 from span_panel_api.models import SpanCircuitSnapshot
 from span_panel_api_schema_1.const import (
@@ -33,7 +38,8 @@ from span_panel_api_schema_1.const import (
     NODE_METER,
     NODE_PCS,
     NODE_SWITCH,
-    PRIORITY_NEVER,
+    PRIORITY_OFF_GRID,
+    PRIORITY_SOC_THRESHOLD,
     PROP_ACTIVE_POWER,
     PROP_CURRENT,
     PROP_EXPORTED_ENERGY,
@@ -54,6 +60,9 @@ from span_panel_api_schema_1.description import declared_settable, node_properti
 if TYPE_CHECKING:
     from ebus_sdk.homie import DiscoveredDevice
 
+_SHED_PRIORITIES: Final = frozenset({PRIORITY_OFF_GRID, PRIORITY_SOC_THRESHOLD})
+"""The `load-shed/priority` values the panel sheds a circuit by; see the module docstring."""
+
 
 def _text(device: DiscoveredDevice, node: str, prop: str, default: str = "") -> str:
     value = device.get_property(node, prop)
@@ -260,7 +269,7 @@ def build_circuit(
         # user-controllability from `always-on` — so this is the same answer by
         # a shorter route.
         is_user_controllable=relay_controllable,
-        is_sheddable=priority != PRIORITY_NEVER and relay_controllable,
+        is_sheddable=priority in _SHED_PRIORITIES and relay_controllable,
         is_never_backup=not priority_settable,
         device_type=device_type,
         relative_position=relative_position,

{span_panel_api_schema_1-1.2.2 → span_panel_api_schema_1-1.3.0b1}/src/span_panel_api_schema_1/const.py

@@ -152,6 +152,8 @@ PROP_COMMUNICATION_STATE = "communication-state"
 # -- Values -----------------------------------------------------------------
 
 PRIORITY_NEVER = "NEVER"
+PRIORITY_OFF_GRID = "OFF_GRID"
+PRIORITY_SOC_THRESHOLD = "SOC_THRESHOLD"
 UNKNOWN = "UNKNOWN"
 CLOUD_CONNECTED = "CONNECTED"
 
@@ -181,9 +183,9 @@ STATE_READY = "ready"
 # exists because of that split — the panel can tell us a model we have no size
 # for, and we would rather say so than guess.
 #
-# Total size matters beyond a display field: unoccupied positions are only
-# knowable as `total - occupied`, and synthesising them is what gives the
-# integration its unmapped-circuit sensors.
+# Total size matters beyond a display field: the tree lists only occupied
+# positions, so the total is the only way a consumer knows how many positions
+# to lay out, empty ones included.
 PANEL_SIZE_BY_MODEL: dict[str, int] = {
     "MAIN_16": 16,
     "MLO_24": 24,
@@ -192,11 +194,6 @@ PANEL_SIZE_BY_MODEL: dict[str, int] = {
     "MLO_48": 48,
 }
 
-# Prefix for synthesised unoccupied-position entries. Must match the flat
-# adapter's, because the integration keys entities off it and a rename would
-# strand every existing unmapped-tab entity.
-UNMAPPED_TAB_PREFIX = "unmapped_tab_"
-
 # The Homie attribute that carries what the flat schema published as the
 # `never-backup` boolean. v1.0 retires the property and expresses it as
 # mutability: a circuit commissioned never-backup has its priority locked, and

{span_panel_api_schema_1-1.2.2 → span_panel_api_schema_1-1.3.0b1}/src/span_panel_api_schema_1/panel.py

@@ -35,7 +35,7 @@ import json
 import logging
 from typing import TYPE_CHECKING, NamedTuple
 
-from span_panel_api.models import SpanCircuitSnapshot, SpanPcsSnapshot
+from span_panel_api.models import SpanPcsSnapshot
 from span_panel_api_schema_1.const import (
     CLOUD_CONNECTED,
     NODE_BREAKER,
@@ -89,7 +89,6 @@ from span_panel_api_schema_1.const import (
     TYPE_BESS,
     TYPE_PV,
     UNKNOWN,
-    UNMAPPED_TAB_PREFIX,
 )
 
 if TYPE_CHECKING:
@@ -201,20 +200,19 @@ def panel_size_from_model(model: str) -> int:
     device publishes no size property.
 
     The highest *occupied* space is not a substitute: it is a lower bound, so a
-    40-space panel whose highest occupied slot is 36 would report 36 and every
-    position above it would silently cease to exist. Since unoccupied positions
-    are exactly `total - occupied`, that would delete the integration's
-    unmapped-circuit sensors rather than merely miscount a display value.
+    panel whose highest occupied slot is below its size would report that slot,
+    and a consumer laying out positions `1..panel_size` would silently lose
+    every position above it.
 
     Unknown models return 0 and log, because inventing a size is worse than
-    reporting none: a wrong total fabricates unmapped positions that are not
-    there, or hides real ones.
+    reporting none: a wrong total lays out positions that are not there, or
+    hides real ones.
     """
     size = PANEL_SIZE_BY_MODEL.get(model.strip().upper())
     if size is None:
         if model:
             _LOGGER.warning(
-                "Unknown panel model %r; panel size unavailable and unmapped positions cannot be derived. Known models: %s",
+                "Unknown panel model %r; panel size unavailable. Known models: %s",
                 model,
                 ", ".join(sorted(PANEL_SIZE_BY_MODEL)),
             )
@@ -248,47 +246,13 @@ def panel_model_drift(panel: DiscoveredDevice) -> tuple[str, ...]:
     ]
     if unknown:
         _LOGGER.warning(
-            "Panel advertises model(s) %s that this adapter cannot size; "
-            "unmapped positions would be wrong for such a panel. Known: %s",
+            "Panel advertises model(s) %s that this adapter cannot size; its panel size would be reported as 0. Known: %s",
             ", ".join(unknown),
             ", ".join(sorted(PANEL_SIZE_BY_MODEL)),
         )
     return tuple(unknown)
 
 
-def build_unmapped_tabs(panel_size: int, occupied: set[int]) -> dict[str, SpanCircuitSnapshot]:
-    """Synthesise a zero-power entry for every unoccupied breaker position.
-
-    The integration surfaces these as unmapped-circuit sensors, gated by its
-    own `enable_unmapped_circuit_sensors` option, and builds entity ids from
-    the circuit id — so the `unmapped_tab_<n>` naming is a compatibility
-    contract with entities that already exist, not an internal detail.
-
-    Reproducible under v1.0 only because the model gives a true total: the tree
-    itself lists occupied positions and says nothing about the rest. A panel
-    whose model is unrecognised yields nothing rather than a guess.
-    """
-    unmapped: dict[str, SpanCircuitSnapshot] = {}
-    for tab in range(1, panel_size + 1):
-        if tab in occupied:
-            continue
-        circuit_id = f"{UNMAPPED_TAB_PREFIX}{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 find_lugs(devices: list[DiscoveredDevice], upstream: bool) -> DiscoveredDevice | None:
     """Locate a lugs device by its declared direction.
 
@@ -795,6 +759,29 @@ def resolve_dominant_power_source(
     return _POWER_SOURCE_BY_TYPE.get(device_types.get(forming, ""), UNKNOWN)
 
 
+def device_display_name(device: DiscoveredDevice) -> str | None:
+    """A device's readable name, or `None` when nothing it publishes names it.
+
+    Homie's `$description.name` (`Battery`, `Solar`, `SPAN Drive - Garage`) where it
+    is set and is not the device's own id. Real r202639 panels publish each non-root
+    device's id there, and an id shown as a name is the outcome
+    `resolve_grid_forming_device_name` exists to avoid. Otherwise the name comes from
+    the device's `info`: vendor and model together (`Tesla Powerwall 2 AC`), or the
+    model alone. A vendor alone names a maker rather than a device, so it gives `None`.
+
+    An empty value names nothing, exactly as an unpublished one does.
+    """
+    description: dict[str, object] = device.description or {}
+    name = description.get("name")
+    if name and str(name) != device.device_id:
+        return str(name)
+    vendor = text(device, NODE_INFO, PROP_VENDOR_NAME)
+    model = text(device, NODE_INFO, PROP_MODEL)
+    if vendor and model:
+        return f"{vendor} {model}"
+    return model or None
+
+
 def resolve_grid_forming_device_name(
     mid: DiscoveredDevice | None,
     device_names: Mapping[str, str],
@@ -803,9 +790,9 @@ def resolve_grid_forming_device_name(
 
     The wire value is a Homie device id -- `sim-40t-001-SIM-BESS-40T-001`. That means
     nothing to someone reading a dashboard: it is not a Home Assistant device id, and an
-    opaque string is worse than no string. Homie's `$description.name` is the device's
-    own display name (`Battery`, `Solar`, `SPAN Drive - Garage`), which is what a person
-    would recognise, so that is what gets surfaced.
+    opaque string is worse than no string. `device_names` holds each device's
+    `device_display_name`, which is what a person would recognise, so that is what gets
+    surfaced.
 
     `None` when the grid is forming (there is no device to name), when no MID publishes
     an answer, or when the id resolves to nothing -- the raw id is still on

{span_panel_api_schema_1-1.2.2 → span_panel_api_schema_1-1.3.0b1}/src/span_panel_api_schema_1/snapshot.py

@@ -8,7 +8,6 @@ likes, and the type string is what the schema defines.
 
 from __future__ import annotations
 
-import time
 from typing import TYPE_CHECKING
 
 from span_panel_api.models import ExtensionSubject, SpanPanelSnapshot, SpanPVSnapshot
@@ -43,7 +42,7 @@ from span_panel_api_schema_1.field_metadata import addressed_rows
 from span_panel_api_schema_1.panel import (
     PanelFields,
     build_pcs,
-    build_unmapped_tabs,
+    device_display_name,
     find_lugs,
     panel_size_from_model,
     resolve_dominant_power_source,
@@ -128,7 +127,7 @@ def _pv_for(inverters: Sequence[SpanPVSnapshot]) -> SpanPVSnapshot:
     )
 
 
-def build_snapshot(panel: DiscoveredDevice, children: list[DiscoveredDevice], ready_since: float = 0.0) -> SpanPanelSnapshot:
+def build_snapshot(panel: DiscoveredDevice, children: list[DiscoveredDevice]) -> SpanPanelSnapshot:
     """Build a full snapshot from the panel and its descendants."""
     roles = TreeRoles(children)
     upstream = find_lugs(roles.lugs, upstream=True)
@@ -165,12 +164,8 @@ def build_snapshot(panel: DiscoveredDevice, children: list[DiscoveredDevice], re
         circuits[snapshot.circuit_id] = snapshot
         circuit_subjects.append((circuit, ExtensionSubject(kind="circuit", instance_key=snapshot.circuit_id)))
 
-    occupied = {tab for circuit in circuits.values() for tab in circuit.tabs}
-    # Unoccupied positions are `total - occupied`, so this is only meaningful
-    # when the model gave a real total. An unknown model yields size 0 and no
-    # unmapped entries rather than a fabricated set.
+    # An unknown model yields size 0 rather than a guessed total.
     panel_size = panel_size_from_model(text(panel, NODE_INFO, PROP_MODEL))
-    circuits.update(build_unmapped_tabs(panel_size, occupied))
 
     # Owners are every device that can claim a DER through a `connection` node.
     owners = [*roles.lugs, *roles.circuits, panel]
@@ -180,12 +175,7 @@ def build_snapshot(panel: DiscoveredDevice, children: list[DiscoveredDevice], re
     # is what makes PANEL_BACKUP distinguishable from PANEL_OFF_GRID authoritatively
     # instead of guessed from a power source the way flat had to.
     device_types = {device.device_id: device_type(device) for device in children}
-    device_names: dict[str, str] = {}
-    for device in children:
-        description: dict[str, object] = device.description or {}
-        name = description.get("name")
-        if name:
-            device_names[device.device_id] = str(name)
+    device_names = {device.device_id: name for device in children if (name := device_display_name(device)) is not None}
     inverters = [device for device in children if device_type(device) == TYPE_INVERTER]
     islanding = resolve_islanding_state(roles.mid, panel)
 
@@ -259,10 +249,12 @@ def build_snapshot(panel: DiscoveredDevice, children: list[DiscoveredDevice], re
         dsm_state=resolve_dsm_state(islanding),
         current_run_config=resolve_run_config(roles.mid, islanding, device_types),
         door_state=fields.door_state,
-        # The panel has no proximity sensor property; the flat adapter reports
-        # authenticated-and-ready, and the same holds here.
-        proximity_proven=True,
-        uptime_s=int(time.monotonic() - ready_since) if ready_since > 0.0 else 0,
+        # The panel publishes no proximity property, and being connected and
+        # ready is not one, so the snapshot does not know.
+        proximity_proven=None,
+        # No device publishes an uptime, and this adapter keeps no readiness
+        # clock of its own to measure one from.
+        uptime_s=None,
         eth0_link=fields.eth0_link,
         wlan_link=fields.wlan_link,
         wwan_link=fields.wwan_link,