span-panel-api-schema-1 1.4.0b2__tar.gz → 1.4.0b4__tar.gz

{span_panel_api_schema_1-1.4.0b2 → span_panel_api_schema_1-1.4.0b4}/.gitignore

@@ -16,6 +16,7 @@ xnotes/*
 .env
 .envrc
 .venv
+.deps-installed
 .vscode/settings.json
 
 # mypy

{span_panel_api_schema_1-1.4.0b2 → span_panel_api_schema_1-1.4.0b4}/CHANGELOG.md

@@ -16,17 +16,18 @@ Requires `span-panel-api` **3.8.0 or newer**, whose snapshot fields accept the u
 ### Added
 
 - **spanos3/r202639/03 batch 2: reads more of the data this firmware publishes.**
+- **`SchemaOneAdapter` exports the tree it holds, masked**, for `SpanMqttClient.masked_tree()`.
+- **Each SPAN Drive's declared charge-current limit range is reported.**
 
 ### Changed
 
-- The shipped reference tree is recaptured with every circuit inside the panel's breaker positions.
+- The shipped reference tree is recaptured with `ebus-panel-sim` 0.9.0: every circuit inside the panel's breaker positions, firmware r202639's discharge-positive battery meter, and no user charge limit until one is set.
 - **`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
@@ -35,6 +36,11 @@ Requires `span-panel-api` **3.8.0 or newer**, whose snapshot fields accept the u
 - **The grid-forming device name falls back to vendor and model instead of showing a device id.**
 - **A panel with no MID reports `dsm_state` `DSM_ON_GRID` and `current_run_config` `PANEL_ON_GRID` whenever it is publishing**, where both dropped to `UNKNOWN` each time `power-flows/grid` read within 1 W of zero
   ([#215](https://github.com/SpanPanel/span-panel-api/issues/215)).
+- **Each MQTT message costs the same few microseconds however many devices the panel declares**, where routing it tested every recorded subscription in turn and every readiness check walked the device tree. On a 30-device tree the work per message falls
+  from 90–250 µs to about 2 µs, measured on a desktop machine ([#223](https://github.com/SpanPanel/span-panel-api/issues/223)).
+- **A property the panel clears reads as unpublished**, where it read as an empty value until the panel published it again.
+- **A charge-current limit outside the range a SPAN Drive declares is refused** instead of published.
+- **A device typed as a subtype of a class (`energy.ebus.device.bess.<x>`) is read as that class**, where it was dropped from the snapshot, adoption and discovery ([#228](https://github.com/SpanPanel/span-panel-api/issues/228)).
 
 ## [1.2.2]
 

{span_panel_api_schema_1-1.4.0b2 → span_panel_api_schema_1-1.4.0b4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: span-panel-api-schema-1
-Version: 1.4.0b2
+Version: 1.4.0b4
 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.8.0b1
+Requires-Dist: span-panel-api<4.0,>=3.8.0b2
 Description-Content-Type: text/markdown
 
 # span-panel-api-schema-1

{span_panel_api_schema_1-1.4.0b2 → span_panel_api_schema_1-1.4.0b4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "span-panel-api-schema-1"
-version = "1.4.0b2"
+version = "1.4.0b4"
 description = "Parent/child schema (data-model-version 1.x) parser for span-panel-api"
 authors = [
     {name = "SpanPanel"}
@@ -33,7 +33,9 @@ dependencies = [
     # unset read as a constant 0.
     # Raised to 3.8.0b1: this parser fills snapshot fields new in it and imports
     # `device_id_order` from its models.
-    "span-panel-api>=3.8.0b1,<4.0",
+    # Raised to 3.8.0b2: this parser implements the masked-tree protocol and types
+    # new in it, and relies on its client reading a cleared value as unpublished.
+    "span-panel-api>=3.8.0b2,<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.4.0b2 → span_panel_api_schema_1-1.4.0b4}/src/span_panel_api_schema_1/adapter.py

@@ -17,9 +17,10 @@ tree, and the SDK repopulates — so there is no resync hook to wire or forget.
 
 from __future__ import annotations
 
+from importlib.metadata import PackageNotFoundError, version
 import logging
 import time
-from typing import TYPE_CHECKING, Final
+from typing import TYPE_CHECKING, Final, NamedTuple
 
 from ebus_sdk import Controller
 
@@ -45,22 +46,38 @@ from span_panel_api_schema_1.const import (
     STATE_READY,
     TYPE_CIRCUIT,
 )
-from span_panel_api_schema_1.description import declared_settable, device_type, node_properties
+from span_panel_api_schema_1.description import declared_settable, declares_class, device_type, node_properties
 from span_panel_api_schema_1.devices import feed_circuit_ids
 from span_panel_api_schema_1.field_metadata import build_field_metadata
 from span_panel_api_schema_1.panel import integer, positions_outside_model, text
 from span_panel_api_schema_1.snapshot import TreeRoles, build_snapshot, harmonised_evse_keys
 from span_panel_api_schema_1.transport import ControllerRoutes, control_target
+from span_panel_api_schema_1.tree_export import export_masked_tree
 
 if TYPE_CHECKING:
     from collections.abc import Callable
 
     from ebus_sdk.homie import DiscoveredDevice
 
-    from span_panel_api.models import FieldMetadata, SpanPanelSnapshot, V2HomieSchema
+    from span_panel_api.models import FieldMetadata, MaskedTree, SpanPanelSnapshot, V2HomieSchema
 
 _LOGGER = logging.getLogger(__name__)
 
+_DISTRIBUTION: Final = "span-panel-api-schema-1"
+
+
+def _producer() -> str:
+    """The distribution and version that wrote an export, or ``unknown`` where this code runs without its dist-info.
+
+    A checkout put on ``sys.path`` has no installed metadata, and an export must
+    not fail for the lack of a version string.
+    """
+    try:
+        return f"{_DISTRIBUTION} {version(_DISTRIBUTION)}"
+    except PackageNotFoundError:
+        return f"{_DISTRIBUTION} unknown"
+
+
 FEED_GRACE_S: Final = 2.0
 """How long an inverter's feed or a DER's model may stay unvalued once every name has arrived.
 
@@ -71,6 +88,50 @@ connection record at all, and a declared model may never be valued.
 """
 
 
+class _ValueTopic(NamedTuple):
+    """One device's `node/property`, and whether the topic carries its value or its `$target`."""
+
+    device_id: str
+    node_id: str
+    property_id: str
+    target: bool
+
+
+def _value_topic(topic: str) -> _ValueTopic | None:
+    """The value or `$target` a topic addresses, or None for any other topic.
+
+    The two shapes `Controller` stores a payload under, read as it reads them:
+    `<domain>/5/<device>/<node>/<property>` is a value unless the property id
+    starts with `$`, and `<domain>/5/<device>/<node>/<property>/$target` is a
+    target. `$state`, `$description` and every other shape are not values.
+    """
+    parts = topic.split("/")
+    if parts[:2] != [HOMIE_DOMAIN, HOMIE_VERSION]:
+        return None
+    if len(parts) == 5 and not parts[4].startswith("$"):
+        return _ValueTopic(parts[2], parts[3], parts[4], target=False)
+    if len(parts) == 6 and parts[5] == "$target":
+        return _ValueTopic(parts[2], parts[3], parts[4], target=True)
+    return None
+
+
+def _forget(by_node: object, node_id: str, property_id: str) -> bool:
+    """Remove one value from an SDK `{node: {property: value}}` map; whether there was one.
+
+    A node left with no values is removed with its last one, so the map holds
+    what the broker retains and nothing more.
+    """
+    if not isinstance(by_node, dict):
+        return False
+    by_property: object = by_node.get(node_id)
+    if not isinstance(by_property, dict) or property_id not in by_property:
+        return False
+    del by_property[property_id]
+    if not by_property:
+        del by_node[node_id]
+    return True
+
+
 def _unvalued_feeds_for_unplaced_pvs(roles: TreeRoles) -> list[str]:
     """Circuits whose feed has not arrived, while an inverter has no known source.
 
@@ -118,7 +179,14 @@ class SchemaOneAdapter:
         self._controller = Controller(root_device_id=serial_number, mqttc=self._routes)
         self._property_callbacks: list[Callable[[str, str, str, str | None], None]] = []
         self._awaiting: tuple[str, ...] = ()
+        # Readiness as last computed, or None once the tree has changed since.
+        self._ready: bool | None = None
         self._controller.set_on_property_changed_callback(self._on_property_changed)
+        # Every event that can change what `is_ready()` answers; see there.
+        self._controller.set_on_device_discovered_callback(self._tree_changed)
+        self._controller.set_on_device_state_changed_callback(self._tree_changed)
+        self._controller.set_on_device_removed_callback(self._tree_changed)
+        self._controller.set_on_description_received_callback(self._tree_changed)
         # Records the subscriptions the tree walk needs; nothing reaches the
         # wire, because this object has no connection to reach it with.
         self._controller.start_discovery()
@@ -138,8 +206,48 @@ class SchemaOneAdapter:
         return [f"{HOMIE_DOMAIN}/{HOMIE_VERSION}/#"]
 
     def handle_message(self, topic: str, payload: str) -> None:
+        """Route one message to the SDK callback that asked for it, keeping a clear a clear.
+
+        A zero-length payload deletes a retained message, and Homie 5 spells an
+        empty string differently, as one `0x00` byte, so that the two stay
+        apart. The SDK decodes both to `""` and stores it, which would leave a
+        property the panel cleared reading as one it published empty. So a
+        clear of a value or `$target` the tree holds is applied here: the
+        stored value goes, exactly as an unpublished one is absent, and
+        property observers hear `None`. A clear of `$state` (the SDK's device
+        removal) or `$description` still goes to the SDK, as does anything
+        else. A `$description` cleared on its own makes the SDK log
+        `descriptionParseError` at ERROR and keep the stale description; that
+        is normally silent only because Homie clears `$state` first, after
+        which the SDK no longer holds the device and ignores the rest.
+        """
+        if not payload and self._clear(topic):
+            return
         self._routes.dispatch(topic, payload)
 
+    def _clear(self, topic: str) -> bool:
+        """Apply a clear of a value or target; False where the topic addresses none the tree holds.
+
+        Only a device the controller holds is touched, the same test the SDK
+        applies before storing a value. Any other clear goes on to dispatch,
+        where a route the SDK still records for a device it dropped ignores it,
+        and an unrouted one takes back what is held for its topic.
+
+        A clear of a value that was never published changes nothing and is not
+        reported. A cleared value is reported as a change, so it forgets the
+        remembered readiness where a new value would; a cleared target is not,
+        as no target change is.
+        """
+        address = _value_topic(topic)
+        device = None if address is None else self._controller.get_device(address.device_id)
+        if address is None or device is None:
+            return False
+        if address.target:
+            _forget(device.property_targets, address.node_id, address.property_id)
+        elif _forget(device.properties, address.node_id, address.property_id):
+            self._notify(address.device_id, address.node_id, address.property_id, None)
+        return True
+
     def is_ready(self) -> bool:
         """Ready when the whole declared tree has described itself.
 
@@ -173,7 +281,22 @@ class SchemaOneAdapter:
         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`.
+
+        **The answer is remembered until the tree changes.** The transport asks
+        before and after every message, and walking the tree each time cost
+        more than routing the message did (#223). Only the Controller's own
+        events can move it: a device's first `$state`, a change of state, a
+        removal, a `$description`, and the root's `info/model` value. Each
+        forgets the answer and the next call works it out again. The events
+        never work it out themselves, because a description is announced before
+        the SDK has reconciled the children it declares.
         """
+        if self._ready is None:
+            self._ready = self._tree_ready()
+        return self._ready
+
+    def _tree_ready(self) -> bool:
+        """What `is_ready()` answers, worked out from the tree as it stands."""
         root = self._controller.get_root(self._serial_number)
         if root is None or root.state != STATE_READY or not root.description:
             return False
@@ -338,13 +461,15 @@ class SchemaOneAdapter:
         return []
 
     def find_node_by_type(self, type_str: str) -> str | None:
-        """Return the id of the first device declaring `type_str`.
+        """Return the id of the first device declaring `type_str` or a subtype of it.
 
         Named for the flat schema's nodes; under parent/child the same question
-        is asked of devices, and the answer is a device id.
+        is asked of devices, and the answer is a device id. A device typed
+        ``…device.bess.hybrid`` is a ``…device.bess`` (`declares_class`), the
+        same device the snapshot reads as the battery.
         """
         for device in self._children():
-            if device_type(device) == type_str:
+            if declares_class(device_type(device), type_str):
                 return device.device_id
         return None
 
@@ -400,7 +525,9 @@ class SchemaOneAdapter:
         is addressable by id — the BESS, the MID, the lugs, a charger — and none
         of them is a circuit, so answering on membership alone would report a
         BESS as a circuit whose relay the panel declares non-commandable. It
-        declares no relay at all.
+        declares no relay at all. The class is the answer rather than the exact
+        type, so a subtyped circuit the snapshot reads into `circuits` is a
+        circuit here too.
 
         A child that has not described itself yet reads as absent, because it
         has declared nothing: type, nodes and properties all arrive together in
@@ -413,7 +540,7 @@ class SchemaOneAdapter:
         would put a second, weaker rule where the authorisation lives.
         """
         device = self._child(circuit_id)
-        return device is not None and device_type(device) == TYPE_CIRCUIT
+        return device is not None and declares_class(device_type(device), TYPE_CIRCUIT)
 
     def set_dominant_power_source_target(self) -> ControlTarget | None:
         """The settable successor: `shed/asserted-islanding-state` on the panel.
@@ -512,22 +639,39 @@ class SchemaOneAdapter:
         charge-only EVSE cannot be told to export by lowering a ceiling, so a
         negative value is not a smaller limit but a malformed one.
 
+        **Refuses outside the range the limit declares.** Firmware r202639
+        publishes `<min>:<commissioned maximum>` as the limit's `$format`
+        (`6:32`), so a value under the minimum is refused here instead of being
+        published for the panel to reject or misapply. A declared maximum
+        tighter than the ceiling applies too. A format that is absent, or that
+        cannot be read as an integer range, bounds nothing extra and the
+        ceiling rule above still holds.
+
         A charger that declares no ceiling is not second-guessed — the catalog
-        makes `installer-max` a SHOULD, and the value that bounds the write is
-        the one the panel published, not one this library invents.
+        makes `installer-max` a SHOULD, and the values that bound the write are
+        the ones the panel published, not ones this library invents. With no
+        ceiling, a maximum declared in the limit's `$format` still bounds the
+        write; with neither, nothing does.
         """
         writable = self._writable_charge_limit(node_id)
         if writable is None or amps < 0:
             return None
-        device, surface, _limit = writable
+        device, surface, limit = writable
         ceiling = surface.ceiling
         commissioned = None if ceiling is None else integer(device, surface.node, ceiling.property_id)
         if commissioned is not None and amps > commissioned:
             return None
+        if limit.bounds is not None:
+            minimum, maximum = limit.bounds
+            if (minimum is not None and amps < minimum) or (maximum is not None and amps > maximum):
+                return None
         return str(amps)
 
     def register_property_callback(self, callback: Callable[[str, str, str, str | None], None]) -> Callable[[], None]:
-        """Subscribe to per-property updates: `(device_id, node_id, property_id, value)`."""
+        """Subscribe to per-property updates: `(device_id, node_id, property_id, value)`.
+
+        `value` is `None` when the panel clears a value it had published.
+        """
         self._property_callbacks.append(callback)
 
         def _unregister() -> None:
@@ -563,6 +707,23 @@ class SchemaOneAdapter:
             return device, surface, surface.limit
         return None
 
+    def export_masked_tree(self) -> MaskedTree | None:
+        """The device tree the adapter holds, masked, or None before the root has described itself.
+
+        Computed at call time and not gated on `is_ready()`: a tree that has not
+        finished arriving is exactly when a diagnostic is wanted, and
+        `metadata["tree_complete"]` says whether this one is whole.
+        """
+        root = self._controller.get_root(self._serial_number)
+        if root is None or root.description is None:
+            return None
+        return export_masked_tree(
+            root,
+            self._children(),
+            producer=_producer(),
+            tree_complete=self._controller.is_tree_complete(self._serial_number),
+        )
+
     def _require_root(self) -> DiscoveredDevice:
         """The root, or a clear error if discovery has not finished.
 
@@ -626,5 +787,16 @@ class SchemaOneAdapter:
         protocol has no place for the previous value, and consumers that need
         one keep it themselves.
         """
+        self._notify(device_id, node_id, property_id, value)
+
+    def _notify(self, device_id: str, node_id: str, property_id: str, value: str | None) -> None:
+        """Report one property's new value, `None` once cleared, after forgetting what it invalidates."""
+        # The one value readiness waits on.
+        if (device_id, node_id, property_id) == (self._serial_number, NODE_INFO, PROP_MODEL):
+            self._ready = None
         for callback in list(self._property_callbacks):
             callback(device_id, node_id, property_id, value)
+
+    def _tree_changed(self, *_event: object) -> None:
+        """Forget the remembered readiness. Accepts any of the Controller's tree events."""
+        self._ready = None

{span_panel_api_schema_1-1.4.0b2 → span_panel_api_schema_1-1.4.0b4}/src/span_panel_api_schema_1/adoption.py

@@ -35,7 +35,14 @@ from span_panel_api_schema_1.const import (
     TYPE_PANEL,
     TYPE_PV,
 )
-from span_panel_api_schema_1.description import declared_settable, device_type, nodes, optional_str, properties
+from span_panel_api_schema_1.description import (
+    declared_settable,
+    declares_class,
+    device_type,
+    nodes,
+    optional_str,
+    properties,
+)
 
 if TYPE_CHECKING:
     from ebus_sdk.homie import DiscoveredDevice
@@ -72,10 +79,11 @@ def is_modelled(declared: str) -> bool:
     Subtype-aware, because firmware may declare either a base type or a subtype
     of it -- ``…device.lugs`` with a ``direction`` property, or
     ``…device.lugs.upstream``. A subtype of something modelled is modelled: the
-    snapshot builder matches lugs by prefix for exactly this reason, and a
-    subtype arriving must not be adopted behind the builder's back.
+    snapshot builder sorts each class with the same `declares_class`, so the
+    two agree about which devices a class covers, and a subtype the builder
+    reads is never adopted behind its back.
     """
-    return any(declared == known or declared.startswith(f"{known}.") for known in MODELLED_TYPES)
+    return any(declares_class(declared, known) for known in MODELLED_TYPES)
 
 
 def build_adopted_devices(children: list[DiscoveredDevice]) -> tuple[AdoptedDevice, ...]:

{span_panel_api_schema_1-1.4.0b2 → span_panel_api_schema_1-1.4.0b4}/src/span_panel_api_schema_1/charge_limit.py

@@ -39,6 +39,7 @@ Homie 5's default rather than a rule this module chose, and it is the same one
 from __future__ import annotations
 
 from dataclasses import dataclass
+import re
 from typing import TYPE_CHECKING
 
 from span_panel_api_schema_1.description import declared_settable, nodes, optional_str, properties
@@ -81,6 +82,42 @@ mappings.
 """
 
 
+_PLAIN_INTEGER = re.compile(r"-?[0-9]+", re.ASCII)
+
+IntegerBounds = tuple[int | None, int | None]
+"""A declared integer range, `(minimum, maximum)`; None on a side the format leaves open."""
+
+
+def declared_integer_bounds(datatype: str, declared: object) -> IntegerBounds | None:
+    """The range an `integer` property's `$format` declares, or None.
+
+    Homie 5 spells it `<min>:<max>` and allows either side to be empty. Anything
+    else is not interpreted: a format that is not a string, a datatype that is
+    not `integer`, a missing colon, extra segments, or a bound that is not a
+    plain integer (an optional minus sign and ASCII digits, so `1_0`, `+6` and
+    non-ASCII digits are refused) or a minimum above the maximum all yield None,
+    which bounds nothing. Guessing a range from a format we cannot read would
+    refuse a write the panel might accept, and the commissioned ceiling still
+    applies either way.
+
+    A property declared `float` is not bounded by its range: only `integer`
+    ranges are read.
+    """
+    if datatype != "integer" or not isinstance(declared, str):
+        return None
+    parts = declared.split(":")
+    if len(parts) != 2:
+        return None
+    low, high = parts[0].strip(), parts[1].strip()
+    if any(text and _PLAIN_INTEGER.fullmatch(text) is None for text in (low, high)):
+        return None
+    minimum = int(low) if low else None
+    maximum = int(high) if high else None
+    if minimum is not None and maximum is not None and minimum > maximum:
+        return None
+    return minimum, maximum
+
+
 @dataclass(frozen=True, slots=True)
 class ChargeLimitProperty:
     """One declared property of the resolved surface.
@@ -95,6 +132,8 @@ class ChargeLimitProperty:
     unit: str | None
     datatype: str
     settable: bool
+    bounds: IntegerBounds | None = None
+    """The `<min>:<max>` range the declaration's `$format` states, or None where it states none we can read."""
 
 
 @dataclass(frozen=True, slots=True)
@@ -144,9 +183,11 @@ def resolve_charge_limit(device: DiscoveredDevice | None) -> ChargeLimitSurface
 def _property(property_id: str, definition: dict[str, object] | None) -> ChargeLimitProperty | None:
     if definition is None:
         return None
+    datatype = str(definition.get("datatype") or "string")
     return ChargeLimitProperty(
         property_id=property_id,
         unit=optional_str(definition.get("unit")),
-        datatype=str(definition.get("datatype") or "string"),
+        datatype=datatype,
         settable=declared_settable(definition),
+        bounds=declared_integer_bounds(datatype, definition.get("format")),
     )

{span_panel_api_schema_1-1.4.0b2 → span_panel_api_schema_1-1.4.0b4}/src/span_panel_api_schema_1/description.py

@@ -36,6 +36,21 @@ def device_type(device: DiscoveredDevice) -> str:
     return str(declared) if declared else ""
 
 
+def declares_class(declared: str, known: str) -> bool:
+    """Whether a declared device type is the class `known` or a subtype of it.
+
+    eBus device types are hierarchical and a subtype carries its parent's
+    class, so a device typed ``…device.bess.hybrid`` is a ``…device.bess``.
+    The boundary is the dot: ``…device.lugsfoo`` merely begins with
+    ``…device.lugs`` and names a different class.
+
+    The one answer to the question for every reader of a type -- the snapshot
+    roles, adoption, field metadata and discovery -- so that no two of them can
+    disagree about which class a device belongs to.
+    """
+    return declared == known or declared.startswith(f"{known}.")
+
+
 def nodes(description: dict[str, object]) -> dict[str, dict[str, object]]:
     """The capability nodes a description declares, by node id."""
     declared = description.get("nodes")

{span_panel_api_schema_1-1.4.0b2 → span_panel_api_schema_1-1.4.0b4}/src/span_panel_api_schema_1/devices.py

@@ -36,12 +36,13 @@ From r202639 the BESS meter is published discharge-positive, the negation of
 The frame is chosen from the enclosure's release build number
 (``firmware.release_build``), never from the respin suffix after it. Where the
 version does not parse, the two wire properties decide instead: one nonzero sign
-on both is the old frame, opposite signs the new one. Where either is zero or
+on both is the old frame, opposite signs the new one. The reference capture
+(``ebus-panel-sim`` 0.9.0) publishes no SPAN version string and is read this way:
+it carries r202639's frame, told by its opposite signs. Where either is zero or
 absent the old frame is assumed, because that is what every earlier release of
-this package applied and what the reference capture (``ebus-panel-sim`` 0.8.0,
-which publishes no SPAN version string) carries. A battery at rest reads zero in
-both frames, so the assumption only decides a nonzero BESS meter beside a missing
-or zero flow figure.
+this package applied. A battery at rest reads zero in both frames, so the
+assumption only decides a nonzero BESS meter beside a missing or zero flow
+figure.
 
 On either firmware ``panel.power_flow_battery`` (passed through untouched, and
 charge-positive) and ``battery.power_w`` end up as each other's mirror, so a
@@ -53,7 +54,7 @@ from __future__ import annotations
 from typing import TYPE_CHECKING
 
 from span_panel_api.models import SpanBatterySnapshot, SpanEvseSnapshot, SpanMidSnapshot, SpanPVSnapshot
-from span_panel_api_schema_1.charge_limit import ChargeLimitProperty, ChargeLimitSurface, resolve_charge_limit
+from span_panel_api_schema_1.charge_limit import ChargeLimitProperty, ChargeLimitSurface, IntegerBounds, resolve_charge_limit
 from span_panel_api_schema_1.const import (
     NODE_CONNECTION,
     NODE_GRID,
@@ -368,9 +369,12 @@ def build_evse(
     The charge-current pair is read through `resolve_charge_limit` rather than
     from named constants, because which node and properties carry it is a
     question only this charger's `$description` can answer. See
-    `span_panel_api_schema_1.charge_limit`.
+    `span_panel_api_schema_1.charge_limit`. The limit's declared range comes from
+    the same resolution, so the range a control offers and the range
+    `SchemaOneAdapter.evse_charge_limit_payload` enforces cannot disagree.
     """
     limit = resolve_charge_limit(evse)
+    minimum, maximum = _limit_bounds(limit)
     return SpanEvseSnapshot(
         node_id=node_id,
         feed_circuit_id=feeds.get(evse.device_id, ""),
@@ -393,9 +397,23 @@ def build_evse(
         charge_current_ceiling_a=_limit_value(evse, limit, limit.ceiling) if limit else None,
         charge_current_limit_target_a=_limit_target(evse, limit),
         charge_current_limit_settable=limit is not None and limit.limit is not None and limit.limit.settable,
+        charge_current_limit_minimum_a=minimum,
+        charge_current_limit_maximum_a=maximum,
     )
 
 
+def _limit_bounds(surface: ChargeLimitSurface | None) -> IntegerBounds:
+    """The range the resolved limit declares, `None` on a side it leaves open or cannot be read.
+
+    `ChargeLimitProperty.bounds` is already None for a format
+    `declared_integer_bounds` will not interpret, so a declaration that bounds
+    nothing on the write path reports no range here either.
+    """
+    if surface is None or surface.limit is None or surface.limit.bounds is None:
+        return None, None
+    return surface.limit.bounds
+
+
 def _limit_value(evse: DiscoveredDevice, surface: ChargeLimitSurface, declaration: ChargeLimitProperty | None) -> int | None:
     """One half of the resolved charge-limit pair, or None where it is not declared."""
     if declaration is None: