span-panel-api-schema-1 1.1.3__tar.gz → 1.1.4__tar.gz

{span_panel_api_schema_1-1.1.3 → span_panel_api_schema_1-1.1.4}/CHANGELOG.md

@@ -9,6 +9,18 @@ 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.
 
+## [1.1.4]
+
+The parser reports the islanding state the panel is acting on, and refuses islanding writes the panel would ignore. Reported and fixed by [@dcj](https://github.com/dcj) in [#179](https://github.com/SpanPanel/span-panel-api/pull/179), from issue
+[#178](https://github.com/SpanPanel/span-panel-api/issues/178).
+
+### Fixed
+
+- **An islanding assertion in force is now the reported islanding state even while the MID is ready.** `resolve_islanding_state` returned the MID's sensed value whenever the MID was ready and read `shed/asserted-islanding-state` only when it was not, so
+  `dsm_state` could disagree with the state the panel was acting on. `ON_GRID` or `OFF_GRID` asserted now wins; otherwise the ready MID's value, then the existing fallback.
+- **`set_dominant_power_source_target` returns None unless the panel declares `shed/asserted-islanding-state` settable**, the same refusal `set_circuit_relay_target` makes.
+- **`dominant_power_source_payload` refuses `NONE` and `UNKNOWN`** instead of publishing `NONE`, which the panel ignores. An assertion clears itself once the panel's link to the battery recovers.
+
 ## [1.1.3]
 
 `spec_lock.json` ships inside this wheel, so its shape changing is a release here even though the parser did not change.

{span_panel_api_schema_1-1.1.3 → span_panel_api_schema_1-1.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: span-panel-api-schema-1
-Version: 1.1.3
+Version: 1.1.4
 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

{span_panel_api_schema_1-1.1.3 → span_panel_api_schema_1-1.1.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "span-panel-api-schema-1"
-version = "1.1.3"
+version = "1.1.4"
 description = "Parent/child schema (data-model-version 1.x) parser for span-panel-api"
 authors = [
     {name = "SpanPanel"}

{span_panel_api_schema_1-1.1.3 → span_panel_api_schema_1-1.1.4}/src/span_panel_api_schema_1/adapter.py

@@ -40,7 +40,7 @@ from span_panel_api_schema_1.const import (
     STATE_READY,
     TYPE_CIRCUIT,
 )
-from span_panel_api_schema_1.description import device_type
+from span_panel_api_schema_1.description import declared_settable, device_type, node_properties
 from span_panel_api_schema_1.field_metadata import build_field_metadata
 from span_panel_api_schema_1.panel import integer
 from span_panel_api_schema_1.snapshot import TreeRoles, build_snapshot, harmonised_evse_keys
@@ -275,9 +275,23 @@ class SchemaOneAdapter:
         the BESS stops discharging. Returning None here, as this did until the
         successor was decided, left that recovery unavailable during an outage.
 
+        **The panel decides whether a write takes effect, by its own link to the
+        battery.** It accepts `ON_GRID` or `OFF_GRID` only while the battery's
+        `status/communication-state` is not `OK`; otherwise it ignores the write
+        and the published value does not change. A lost MID alone does not make
+        the write eligible. `NONE` is always ignored.
+
+        **None unless the panel declares the assertion `$settable`**, the same
+        refusal `set_circuit_relay_target` makes. Absence of the declaration,
+        or of the property, authorizes nothing (see
+        `description.declared_settable`).
+
         Payload translation is not optional: the flat enum this protocol speaks
         is not the one the panel accepts. See `dominant_power_source_payload`.
         """
+        root = self._controller.get_root(self._serial_number)
+        if not declared_settable(node_properties(root, NODE_SHED).get(PROP_ASSERTED_ISLANDING_STATE)):
+            return None
         return self._target(self._serial_number, NODE_SHED, PROP_ASSERTED_ISLANDING_STATE)
 
     def dominant_power_source_payload(self, value: str) -> str | None:
@@ -291,17 +305,19 @@ class SchemaOneAdapter:
 
         The narrowing loses nothing, because the six values were a *source
         class* pressed into service as a manual override and the job only ever
-        needed on-grid, off-grid, or no assertion. Anything not recognised
-        returns None rather than guessing, so the transport refuses the command
-        instead of asserting something the user did not ask for.
+        needed on-grid or off-grid. Anything not recognized returns None rather
+        than guessing, so the transport refuses the command instead of
+        asserting something the user did not ask for.
+
+        **`NONE` and `UNKNOWN` are refused too.** The panel ignores a written
+        `NONE`, so publishing one would report a clear that never happened. An
+        assertion clears itself once the panel's link to the battery recovers.
         """
         return {
             "GRID": "ON_GRID",
             "BATTERY": "OFF_GRID",
             "PV": "OFF_GRID",
             "GENERATOR": "OFF_GRID",
-            "NONE": "NONE",
-            "UNKNOWN": "NONE",
         }.get(value.strip().upper())
 
     def set_evse_charge_limit_target(self, node_id: str) -> ControlTarget | None:

{span_panel_api_schema_1-1.1.3 → span_panel_api_schema_1-1.1.4}/src/span_panel_api_schema_1/field_metadata.py

@@ -472,8 +472,8 @@ _CONSUMED_OFF_SNAPSHOT: dict[tuple[str, str, str], str] = {
         "parses the tree, so it is consumed before any snapshot exists"
     ),
     (TYPE_PANEL, NODE_SHED, "asserted-islanding-state"): (
-        "tier 2 of resolve_islanding_state (panel.py), shadowed wherever a MID answers "
-        "at tier 1, and the write target of set_dominant_power_source_target"
+        "tier 1 of resolve_islanding_state (panel.py), which returns a non-NONE "
+        "assertion first, and the write target of set_dominant_power_source_target"
     ),
     (TYPE_LUGS, NODE_CONNECTION, "feeds-device-id"): (
         "the downstream-lugs feedthrough branch of resolve_relative_position "

{span_panel_api_schema_1-1.1.3 → span_panel_api_schema_1-1.1.4}/src/span_panel_api_schema_1/panel.py

@@ -600,7 +600,6 @@ _GRID_POWER_EPSILON_W = 1.0
 
 ISLANDING_ON_GRID = "ON_GRID"
 ISLANDING_OFF_GRID = "OFF_GRID"
-ASSERTION_NONE = "NONE"
 
 
 def resolve_islanding_state(mid: DiscoveredDevice | None, panel: DiscoveredDevice) -> str | None:
@@ -608,17 +607,19 @@ def resolve_islanding_state(mid: DiscoveredDevice | None, panel: DiscoveredDevic
 
     | tier | condition | source |
     | --- | --- | --- |
-    | 1 | MID `$state` is `ready` and `islanding-state` present | sensed |
-    | 2 | MID not `ready` | `shed/asserted-islanding-state`, when not `NONE` |
+    | 1 | `shed/asserted-islanding-state` is `ON_GRID` or `OFF_GRID` | asserted |
+    | 2 | MID `$state` is `ready` and `islanding-state` present | sensed |
     | 3 | no MID at all | `power-flows/grid` heuristic |
     | 4 | none of the above | unknown |
 
-    **Tier 2 is the reason the assertion control exists.** When comms to the BESS or MID
-    are lost and the grid returns, the user asserts the grid is up so the BESS stops
-    discharging. Declining to read it here would wire the control and then ignore it at
-    exactly the moment it matters. Nothing is hidden by doing so: the MID is a device, so
-    it goes *unavailable* in Home Assistant when it stops publishing, and the assertion is
-    itself visible as the control the user set.
+    **An assertion in force is the effective state, so it outranks the MID.** When the
+    panel's link to the battery is not healthy (the battery's `status/communication-state`
+    is not `OK`) and the grid returns, the user asserts the grid is up so the BESS stops
+    discharging, and the panel acts on that assertion until it clears. The panel ignores
+    the write while that link is healthy.
+    Reading the MID first would report the sensed value while the panel is acting on a
+    different one. The assertion clears itself back to `NONE` once the battery link
+    recovers, so the MID's answer returns without anything here having to expire it.
 
     **Tier 3 never answers `OFF_GRID`, and never asserts on-grid from a missing MID.** An
     earlier draft reasoned that no MID means no islanding authority means on-grid. That is
@@ -627,14 +628,15 @@ def resolve_islanding_state(mid: DiscoveredDevice | None, panel: DiscoveredDevic
     counterexample. Grid power flowing is positive evidence of being on-grid; its absence
     is not evidence of the opposite.
     """
+    asserted = text(panel, NODE_SHED, PROP_ASSERTED_ISLANDING_STATE)
+    if asserted in (ISLANDING_ON_GRID, ISLANDING_OFF_GRID):
+        return asserted
+
     if mid is not None:
         if mid.state == "ready":
             sensed = text(mid, NODE_GRID, PROP_ISLANDING_STATE)
             if sensed:
                 return sensed
-        asserted = text(panel, NODE_SHED, PROP_ASSERTED_ISLANDING_STATE)
-        if asserted and asserted != ASSERTION_NONE:
-            return asserted
         return None
 
     grid_power = number(panel, NODE_POWER_FLOWS, "grid")