span-panel-api-schema-0 1.1.2__tar.gz → 1.3.0b1__tar.gz

{span_panel_api_schema_0-1.1.2 → span_panel_api_schema_0-1.3.0b1}/CHANGELOG.md

@@ -9,6 +9,34 @@ rather than by this version number. A release here means this parser changed, ne
 
 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 `True` on every snapshot because it read readiness rather than any proximity property.
+- **`uptime_s` is `None` before the panel first reports ready**, where it was `0`.
+- **A circuit's `instant_power_update_time_s` and `energy_accum_update_time_s` are `None` until the reading arrives**, where they were `0`.
+- **BREAKING FOR CONSUMERS: `HomiePropertyAccumulator.get_timestamp()` returns `int | None`, and `None` for a property never received**, where it returned `0`.
+
+### Removed
+
+- **BREAKING: snapshots no longer include synthesised `unmapped_tab_N` entries for unoccupied breaker positions, which carried no measured data.**
+
+### Fixed
+
+- **`uptime_s` keeps advancing while only circuits change**, where a snapshot rebuilt for changed circuits alone carried the previous snapshot's uptime forward until something panel-level changed.
+
+## [1.2.0]
+
+The panel's one inverter is reported through `pv_inverters` as well as `pv`. Requires `span-panel-api` **3.6.0 or newer**.
+
+### Added
+
+- **`pv_inverters` holds the panel's one inverter** under the key `span-panel-api-schema-1` gives it, so a consumer can read every panel through that field.
+- **`pv.device_id` and `pv.node_id`** give the inverter's flat node id and its `pv_inverters` key.
+
 ## [1.1.2]
 
 The reference schema document this parser is tested against now ships in the wheel.

{span_panel_api_schema_0-1.1.2 → span_panel_api_schema_0-1.3.0b1}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.5
 Name: span-panel-api-schema-0
-Version: 1.1.2
+Version: 1.3.0b1
 Summary: Flat-schema (data-model-version absent) 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
 Author: SpanPanel
 License-Expression: MIT
 Requires-Python: <4.0,>=3.14
-Requires-Dist: span-panel-api<4.0,>=3.1.0
+Requires-Dist: span-panel-api<4.0,>=3.7.0b1
 Description-Content-Type: text/markdown
 
 # span-panel-api-schema-0

{span_panel_api_schema_0-1.1.2 → span_panel_api_schema_0-1.3.0b1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "span-panel-api-schema-0"
-version = "1.1.2"
+version = "1.3.0b1"
 description = "Flat-schema (data-model-version absent) parser for span-panel-api"
 authors = [
     {name = "SpanPanel"}
@@ -16,7 +16,12 @@ dependencies = [
     # for `set_*_target` instead of `set_*_topic`. Against 3.0.x this wheel is
     # rejected at discovery for carrying names that bootstrap does not require —
     # so the floor moves with the rename rather than trailing it.
-    "span-panel-api>=3.1.0,<4.0",
+    # Raised to 3.6.0, the first bootstrap whose snapshot carries `pv_inverters`
+    # and the inverter's `device_id` and `node_id`, which this parser fills.
+    # Against an earlier one, building a snapshot fails on those arguments.
+    # Raised to 3.7.0b1, whose snapshot fields accept the unknown values this
+    # parser now reports, where an earlier one types them as never unknown.
+    "span-panel-api>=3.7.0b1,<4.0",
 ]
 
 [project.urls]

{span_panel_api_schema_0-1.1.2 → span_panel_api_schema_0-1.3.0b1}/src/span_panel_api_schema_0/accumulator.py

@@ -118,9 +118,9 @@ class HomiePropertyAccumulator:
         """Get a property's reported value."""
         return self._property_values.get(node_id, {}).get(prop_id, default)
 
-    def get_timestamp(self, node_id: str, prop_id: str) -> int:
-        """Get the epoch timestamp of a property's last update."""
-        return self._property_timestamps.get(node_id, {}).get(prop_id, 0)
+    def get_timestamp(self, node_id: str, prop_id: str) -> int | None:
+        """Get the epoch timestamp of a property's last update, or None if it never arrived."""
+        return self._property_timestamps.get(node_id, {}).get(prop_id)
 
     def get_target(self, node_id: str, prop_id: str) -> str | None:
         """Get a property's target value, or None if no target set."""

{span_panel_api_schema_0-1.1.2 → span_panel_api_schema_0-1.3.0b1}/src/span_panel_api_schema_0/consumer.py

@@ -85,6 +85,16 @@ def _parse_int(value: str, default: int = 0) -> int:
         return default
 
 
+def _latest(*timestamps: int | None) -> int | None:
+    """The most recent of the timestamps that exist, or `None` when none do.
+
+    A property that has not arrived has no receipt time, so it takes no part
+    rather than standing in as `0`.
+    """
+    arrived = [timestamp for timestamp in timestamps if timestamp is not None]
+    return max(arrived) if arrived else None
+
+
 class HomieDeviceConsumer:
     """Build SPAN-specific snapshots from accumulated Homie property state.
 
@@ -220,12 +230,8 @@ class HomieDeviceConsumer:
         cached = self._cached_snapshot
 
         feed_metadata = self._build_feed_metadata()
-        updated_circuits: dict[str, SpanCircuitSnapshot] = {}
-        # Keep only non-unmapped circuits from cache, rebuild dirty ones
-        for cid, circ in cached.circuits.items():
-            if cid.startswith("unmapped_tab_"):
-                continue  # drop old unmapped entries; will recompute below
-            updated_circuits[cid] = circ
+        # Keep cached circuits, rebuild dirty ones
+        updated_circuits = dict(cached.circuits)
         for node_id in dirty:
             if self.is_circuit_node(node_id):
                 meta = feed_metadata.get(node_id, {})
@@ -234,11 +240,14 @@ class HomieDeviceConsumer:
                 circuit = self._build_circuit(node_id, device_type, relative_position)
                 updated_circuits[circuit.circuit_id] = circuit
 
-        # Recompute unmapped tabs based on current circuit set
-        unmapped = self._build_unmapped_tabs(updated_circuits)
-        updated_circuits.update(unmapped)
+        # Uptime is a clock, not a property, so no dirty node announces that it
+        # moved; carrying the cached value would freeze it between full builds.
+        return dataclasses.replace(cached, circuits=updated_circuits, uptime_s=self._uptime_s())
 
-        return dataclasses.replace(cached, circuits=updated_circuits)
+    def _uptime_s(self) -> int | None:
+        """Connection uptime since $state==ready, measured here; none before the first ready."""
+        ready_since = self._acc.ready_since
+        return int(time.monotonic() - ready_since) if ready_since > 0.0 else None
 
     def _find_lugs_node(self, direction: str) -> str | None:
         """Find the lugs node with a specific direction.
@@ -339,8 +348,8 @@ class HomieDeviceConsumer:
 
         always_on = _parse_bool(self._acc.get_prop(node_id, "always-on"))
 
-        # Timestamps from MQTT arrival time
-        energy_ts = max(
+        # Timestamps from MQTT receipt time, `None` until the reading arrives
+        energy_ts = _latest(
             self._acc.get_timestamp(node_id, "exported-energy"),
             self._acc.get_timestamp(node_id, "imported-energy"),
         )
@@ -423,13 +432,18 @@ class HomieDeviceConsumer:
         feed = self._acc.get_prop(pv_node, "feed")
         rel_pos = self._acc.get_prop(pv_node, "relative-position")
 
+        feed_circuit_id = normalize_circuit_id(feed) if feed else None
         return SpanPVSnapshot(
             vendor_name=vn if vn else None,
             model=pn if pn else None,
             software_version=sw if sw else None,
             nameplate_capacity_w=_parse_float(nc) if nc else None,
-            feed_circuit_id=normalize_circuit_id(feed) if feed else None,
+            feed_circuit_id=feed_circuit_id,
             relative_position=rel_pos.upper() if rel_pos else None,
+            device_id=pv_node,
+            # The same key schema_1 gives this inverter, so a consumer's handle
+            # for it survives the panel's upgrade to the parent/child schema.
+            node_id=feed_circuit_id or pv_node,
         )
 
     def _build_evse_devices(self) -> dict[str, SpanEvseSnapshot]:
@@ -519,39 +533,6 @@ class HomieDeviceConsumer:
 
         return "UNKNOWN"
 
-    def _build_unmapped_tabs(
-        self,
-        circuits: dict[str, SpanCircuitSnapshot],
-    ) -> dict[str, SpanCircuitSnapshot]:
-        """Synthesize unmapped tab entries for breaker positions with no circuit.
-
-        Creates zero-power SpanCircuitSnapshot entries for unoccupied positions
-        up to ``self._panel_size``.
-        """
-        occupied_tabs: set[int] = set()
-        for circuit in circuits.values():
-            occupied_tabs.update(circuit.tabs)
-
-        unmapped: dict[str, SpanCircuitSnapshot] = {}
-        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(
-                    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 _build_snapshot(self) -> SpanPanelSnapshot:
         """Build full snapshot from accumulated property values."""
         core_node = self._acc.find_node_by_type(TYPE_CORE)
@@ -665,10 +646,6 @@ class HomieDeviceConsumer:
                 circuit = self._build_circuit(node_id, device_type, relative_position)
                 circuits[circuit.circuit_id] = circuit
 
-        # Synthesize unmapped tab entries
-        unmapped = self._build_unmapped_tabs(circuits)
-        circuits.update(unmapped)
-
         # Battery, PV, and EVSE metadata
         battery = self._build_battery()
         pv = self._build_pv()
@@ -685,9 +662,6 @@ class HomieDeviceConsumer:
         dsm_state = self._derive_dsm_state(core_node, grid_power, power_flow_grid)
         current_run_config = self._derive_run_config(dsm_state, grid_islandable, dominant_power_source)
 
-        # Connection uptime since $state==ready
-        uptime = int(time.monotonic() - self._acc.ready_since) if self._acc.ready_since > 0.0 else 0
-
         return SpanPanelSnapshot(
             serial_number=self._acc.serial_number,
             firmware_version=firmware,
@@ -701,8 +675,10 @@ class HomieDeviceConsumer:
             dsm_state=dsm_state,
             current_run_config=current_run_config,
             door_state=door_state,
-            proximity_proven=self._acc.is_ready(),
-            uptime_s=uptime,
+            # No flat property reports proximity. Readiness is not a stand-in:
+            # a snapshot is only built once ready, so it would always say True.
+            proximity_proven=None,
+            uptime_s=self._uptime_s(),
             eth0_link=eth0,
             wlan_link=wlan,
             wwan_link=wwan_connected,
@@ -726,5 +702,8 @@ class HomieDeviceConsumer:
             circuits=circuits,
             battery=battery,
             pv=pv,
+            # Flat publishes one inverter at most, so this is `pv` again, keyed
+            # as schema_1 keys each of its inverters.
+            pv_inverters={pv.node_id: pv} if pv.node_id is not None else {},
             evse=evse,
         )