span-panel-api 3.7.0b1__tar.gz → 3.8.0b1__tar.gz

{span_panel_api-3.7.0b1 → span_panel_api-3.8.0b1}/CHANGELOG.md

@@ -13,6 +13,7 @@ Snapshot fields that held a fabricated constant can now be unknown, and with `sp
 
 ### Added
 
+- **spanos3/r202639/03 batch 2: reads more of the data this firmware publishes.**
 - **`V2StatusInfo.hardware_version` reports the hardware version string from `GET /api/v2/status`.**
 
 ### Changed
@@ -22,7 +23,10 @@ Snapshot fields that held a fabricated constant can now be unknown, and with `sp
 - **BREAKING FOR CONSUMERS: `SpanPanelSnapshot.uptime_s` becomes `int | None`**, and with those parsers it is `None` on a parent/child panel and before a flat panel first reports ready, where it was a constant `0`.
 - **BREAKING FOR CONSUMERS: `SpanCircuitSnapshot.instant_power_update_time_s` and `energy_accum_update_time_s` become `int | None` and default to `None`**, and with those parsers they are `None` until the reading has arrived and always on a parent/child
   panel, where they were `0`.
-- **The `schema-0` and `schema-1` extras require `span-panel-api-schema-0` and `span-panel-api-schema-1` 1.3.0 or newer**, the adapters that report these values as unknown.
+- **BREAKING FOR CONSUMERS: `SpanCircuitSnapshot.is_240v` becomes `bool | None`**, and with `span-panel-api-schema-1` 1.4.0 or newer it is `None` where the pole count is unpublished.
+- **BREAKING FOR CONSUMERS: `SpanPanelSnapshot.lugs_at_service_entrance` becomes `bool | None`**, and with `span-panel-api-schema-1` 1.4.0 or newer it is `None` while the upstream lugs declare their feed but leave it unpublished.
+- **The `schema-0` extra requires `span-panel-api-schema-0` 1.3.0 or newer and the `schema-1` extra requires `span-panel-api-schema-1` 1.4.0 or newer**, the adapters that report these values as unknown; schema-1 1.4.0 also fills the snapshot fields this
+  release adds.
 
 ### Removed
 

{span_panel_api-3.7.0b1 → span_panel_api-3.8.0b1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: span-panel-api
-Version: 3.7.0b1
+Version: 3.8.0b1
 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,7 @@ Requires-Dist: pyyaml>=6.0.0
 Provides-Extra: schema-0
 Requires-Dist: span-panel-api-schema-0>=1.3.0b1; extra == 'schema-0'
 Provides-Extra: schema-1
-Requires-Dist: span-panel-api-schema-1>=1.3.0b1; extra == 'schema-1'
+Requires-Dist: span-panel-api-schema-1>=1.4.0b1; extra == 'schema-1'
 Description-Content-Type: text/markdown
 
 # SPAN Panel API

{span_panel_api-3.7.0b1 → span_panel_api-3.8.0b1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "span-panel-api"
-version = "3.7.0b1"
+version = "3.8.0b1"
 description = "A client library for SPAN Panel API"
 authors = [
     {name = "SpanPanel"}
@@ -69,7 +69,9 @@ schema-0 = ["span-panel-api-schema-0>=1.3.0b1"]
 # Raised to 1.2.2 for 3.6.2: the readiness gate every snapshot passes asks that
 # adapter what is still missing, and 1.2.2 restarts its feed grace correctly.
 # Raised to 1.3.0b1 for 3.7.0b1, for the same reason as schema-0's.
-schema-1 = ["span-panel-api-schema-1>=1.3.0b1"]
+# Raised to 1.4.0b1 for 3.8.0b1: that adapter fills the snapshot fields this
+# bootstrap adds.
+schema-1 = ["span-panel-api-schema-1>=1.4.0b1"]
 
 [project.urls]
 Homepage = "https://github.com/SpanPanel/span-panel-api"

{span_panel_api-3.7.0b1 → span_panel_api-3.8.0b1}/src/span_panel_api/__init__.py

@@ -29,6 +29,7 @@ from .exceptions import (
     SpanPanelError,
     SpanPanelInsufficientPrivilegeError,
     SpanPanelPassphraseUnavailableError,
+    SpanPanelRateLimitError,
     SpanPanelSchemaVersionError,
     SpanPanelServerError,
     SpanPanelStaleDataError,
@@ -41,15 +42,19 @@ from .models import (
     ADOPTION_IDENTITY_NODE,
     ADOPTION_TOPOLOGY_NODE,
     DISCOVERY_NAMESPACE,
+    FEEDS_ROLES,
+    PROTECTION_FUNCTIONS,
     AdoptedDevice,
     AdoptedProperty,
     ControlTarget,
     DiscoveredMetadata,
     ExtensionProperty,
     ExtensionSubject,
+    FeedsRole,
     FieldMetadata,
     HomieSchemaTypes,
     PassphraseRotation,
+    ProtectionFunction,
     SpanBatterySnapshot,
     SpanCircuitSnapshot,
     SpanEvseSnapshot,
@@ -61,6 +66,7 @@ from .models import (
     V2HomieSchema,
     V2StatusInfo,
     is_discovery_path,
+    shared_meter_groups,
 )
 from .mqtt import (
     ControlCommand,
@@ -84,6 +90,7 @@ from .protocol import (
     CircuitControlProtocol,
     ControlInterceptionProtocol,
     EvseControlProtocol,
+    EvseLockControlProtocol,
     PanelCapability,
     PanelControlProtocol,
     SpanPanelClientProtocol,
@@ -106,6 +113,9 @@ __all__ = [  # noqa: RUF022
     # snapshot rather than by its arguments -- a device the adapter models
     # produces no AdoptedDevice and so cannot be addressed through it.
     "AdoptedControlProtocol",
+    # A charger's connector lock, authorised by `SpanEvseSnapshot.lock_control`.
+    # A protocol of its own so `EvseControlProtocol`'s implementers are unchanged.
+    "EvseLockControlProtocol",
     # Added 2026-08-25 (3.1.0): one veto/observe point for every control
     # command. A protocol of its own rather than a member on the four control
     # protocols, which would break their implementers a second time in one
@@ -145,6 +155,16 @@ __all__ = [  # noqa: RUF022
     "SpanPVSnapshot",
     "SpanPanelSnapshot",
     "SpanPcsSnapshot",
+    # What a circuit's `connection/feeds-role` declares, read into
+    # `SpanCircuitSnapshot.feeds_role`.
+    "FEEDS_ROLES",
+    "FeedsRole",
+    # What a circuit's `breaker/protection-functions` lists, read into
+    # `SpanCircuitSnapshot.protection_functions`.
+    "PROTECTION_FUNCTIONS",
+    "ProtectionFunction",
+    # The circuits one meter measures, from `SpanCircuitSnapshot.meter_shared_with`.
+    "shared_meter_groups",
     # Factory
     "create_span_client",
     # Detection
@@ -216,6 +236,10 @@ __all__ = [  # noqa: RUF022
     # keep their meaning; deliberately not a SpanPanelAuthError, because the
     # passphrase the user supplied may be correct.
     "SpanPanelPassphraseUnavailableError",
+    # Registration refused with HTTP 429, carrying the panel's `Retry-After` in
+    # seconds. A subclass of SpanPanelAPIError, so existing except clauses keep
+    # their meaning; not a SpanPanelAuthError, because no credential was judged.
+    "SpanPanelRateLimitError",
     "SpanPanelServerError",
     "SpanPanelStaleDataError",
     # Added 2026-08-31 (3.4.0): a bootstrap REST call that failed verification

{span_panel_api-3.7.0b1 → span_panel_api-3.8.0b1}/src/span_panel_api/auth.py

@@ -10,9 +10,12 @@ from __future__ import annotations
 
 import asyncio
 from collections.abc import Collection, Mapping
+from datetime import UTC, datetime
+from email.utils import parsedate_to_datetime
 import hashlib
 import json
 import logging
+import math
 import ssl
 import uuid
 
@@ -24,6 +27,7 @@ from .exceptions import (
     SpanPanelAuthError,
     SpanPanelInsufficientPrivilegeError,
     SpanPanelPassphraseUnavailableError,
+    SpanPanelRateLimitError,
     SpanPanelServerError,
 )
 from .models import HomieSchemaTypes, PassphraseRotation, V2AuthResponse, V2HomieSchema, V2StatusInfo
@@ -216,21 +220,37 @@ CA_CERT_MAX_ATTEMPTS = 5
 CA_CERT_BACKOFF_S = 1.5
 
 
-def _retry_delay(retry_after: str | None, attempt: int, backoff_s: float) -> float:
-    """Return how long to wait before retrying a rate-limited request.
+def _retry_after_s(retry_after: str | None, now: datetime) -> float | None:
+    """The wait a ``Retry-After`` header asks for, in seconds, or None if it asks for none.
 
-    Prefers the panel's ``Retry-After`` header (delta-seconds form) and falls
-    back to exponential backoff. Malformed or negative values fall back too,
-    so a bad header can never stall or skip the retry.
+    Both forms RFC 9110 allows: delta-seconds, taken as given, and an HTTP-date,
+    taken as the seconds from `now` until then (0.0 once it has passed). A
+    negative, infinite or unparseable value is no answer, so a bad header can
+    never stall or skip a retry.
     """
-    fallback = backoff_s * (2.0 ** (attempt - 1))
     if retry_after is None:
-        return fallback
+        return None
     try:
-        parsed = float(retry_after)
-    except (TypeError, ValueError):
-        return fallback
-    return parsed if parsed >= 0 else fallback
+        seconds = float(retry_after)
+    except ValueError:
+        try:
+            until = parsedate_to_datetime(retry_after)
+        except (TypeError, ValueError):
+            return None
+        if until.tzinfo is None:
+            return None
+        return max((until - now).total_seconds(), 0.0)
+    return seconds if math.isfinite(seconds) and seconds >= 0 else None
+
+
+def _retry_delay(retry_after: str | None, attempt: int, backoff_s: float) -> float:
+    """Return how long to wait before retrying a rate-limited request.
+
+    Prefers the panel's ``Retry-After`` header and falls back to exponential
+    backoff where it gives no usable wait.
+    """
+    parsed = _retry_after_s(retry_after, datetime.now(UTC))
+    return backoff_s * (2.0 ** (attempt - 1)) if parsed is None else parsed
 
 
 async def register_v2(
@@ -276,6 +296,7 @@ async def register_v2(
     Raises:
         SpanPanelAuthError: Invalid passphrase or auth failure
         SpanPanelPassphraseUnavailableError: The panel cannot read its own passphrase
+        SpanPanelRateLimitError: HTTP 429; the panel is limiting registrations. Not retried
         SpanPanelServerError: The panel is not ready to register clients (any 5xx,
             including the 503 it answers before its serial number is known); retryable
         SpanPanelConnectionError: Cannot reach panel
@@ -314,6 +335,16 @@ async def register_v2(
             status_code=reply.status_code,
         )
 
+    if reply.status_code == HTTP_TOO_MANY_REQUESTS:
+        # Not retried: the panel limits registrations per client address, and a
+        # retry here would spend the caller's next attempt on its behalf.
+        _log_auth_failure(reply.endpoint, reply.response, sent)
+        raise SpanPanelRateLimitError(
+            f"Panel is rate-limiting registration (HTTP {reply.status_code})",
+            status_code=reply.status_code,
+            retry_after_s=_retry_after_s(reply.headers.get("retry-after"), datetime.now(UTC)),
+        )
+
     if reply.status_code == 422 and _error_detail(reply.response) == REGISTRATION_UNAVAILABLE_DETAIL:
         # Checked before the general 422 below, which means "credential not
         # accepted". This one is the panel failing to read its own passphrase,
@@ -613,8 +644,8 @@ async def rotate_passphrase(
     Raises:
         SpanPanelInsufficientPrivilegeError: HTTP 403; the token is reduced-privilege
         SpanPanelAuthError: HTTP 401 (token invalid or stale) or 412 (no bearer token)
-        SpanPanelServerError: HTTP 5xx. After a 500 the outcome is unknown: the
-            passphrase may or may not have changed.
+        SpanPanelServerError: HTTP 5xx. After a 500 or a 504 the outcome is unknown:
+            the passphrase may or may not have changed.
         SpanPanelConnectionError: Cannot reach panel
         SpanPanelTimeoutError: Request timed out
         SpanPanelAPIError: Unexpected response

{span_panel_api-3.7.0b1 → span_panel_api-3.8.0b1}/src/span_panel_api/exceptions.py

@@ -68,6 +68,25 @@ class SpanPanelServerError(SpanPanelAPIError):
     """
 
 
+class SpanPanelRateLimitError(SpanPanelAPIError):
+    """The panel is limiting the client's requests and refused this one (HTTP 429).
+
+    Raised by ``register_v2``, which does not retry: the caller decides when to
+    try again. ``retry_after_s`` is the wait the panel asked for, in seconds,
+    from its ``Retry-After`` header: a delta-seconds value as given, an HTTP-date
+    as the seconds until that time. ``None`` when the header is absent or holds
+    neither.
+
+    A `SpanPanelAPIError`, so an existing clause catching that class still
+    catches this, and not a `SpanPanelAuthError`: the credential was never
+    judged.
+    """
+
+    def __init__(self, message: str, status_code: int | None = None, retry_after_s: float | None = None) -> None:
+        super().__init__(message, status_code)
+        self.retry_after_s = retry_after_s
+
+
 class SpanPanelPassphraseUnavailableError(SpanPanelAPIError):
     """The panel cannot read its own passphrase, so it cannot issue broker credentials.
 

{span_panel_api-3.7.0b1 → span_panel_api-3.8.0b1}/src/span_panel_api/models.py

@@ -11,11 +11,25 @@ from __future__ import annotations
 
 from collections.abc import Mapping
 from dataclasses import dataclass, field
+import re
+from typing import Final, Literal
 
 # Homie schema type: {type_name: {property_name: {attribute: value}}}
 # Values are heterogeneous JSON (str, int, bool, nested dicts).
 type HomieSchemaTypes = dict[str, dict[str, object]]
 
+type FeedsRole = Literal["LOADS", "SUBPANEL", "SOLAR", "STORAGE", "GENERATOR", "MIXED", "UNUSED"]
+"""What a circuit feeds, as its `connection/feeds-role` declares it."""
+
+FEEDS_ROLES: Final[tuple[FeedsRole, ...]] = ("LOADS", "SUBPANEL", "SOLAR", "STORAGE", "GENERATOR", "MIXED", "UNUSED")
+"""Every `FeedsRole`, for reading a wire value into one."""
+
+type ProtectionFunction = Literal["OVERCURRENT", "SHORT_CIRCUIT", "GROUND_FAULT", "ARC_FAULT"]
+"""One protection a circuit's breaker provides, as `breaker/protection-functions` lists it."""
+
+PROTECTION_FUNCTIONS: Final[tuple[ProtectionFunction, ...]] = ("OVERCURRENT", "SHORT_CIRCUIT", "GROUND_FAULT", "ARC_FAULT")
+"""Every `ProtectionFunction`, for reading a wire value into one."""
+
 
 @dataclass(frozen=True, slots=True)
 class SpanCircuitSnapshot:
@@ -33,9 +47,9 @@ class SpanCircuitSnapshot:
     # fabricated zero as a reset and books the whole counter as an offset
     # (`SpanPanel/span#259`). A new circuit legitimately reads `0.0`, and the
     # two must stay tellable apart.
-    instant_power_w: float | None  # Positive = consumption
-    produced_energy_wh: float | None  # Generation/backfeed (Wh)
-    consumed_energy_wh: float | None  # Consumption (Wh)
+    instant_power_w: float | None  # Positive = consumption; import where `measures_outside_panel`
+    produced_energy_wh: float | None  # Generation/backfeed (Wh); export where `measures_outside_panel`
+    consumed_energy_wh: float | None  # Consumption (Wh); import where `measures_outside_panel`
     tabs: list[int]
     priority: str  # v1: MUST_HAVE | NICE_TO_HAVE | NON_ESSENTIAL | UNKNOWN
     #                 v2: NEVER | SOC_THRESHOLD | OFF_GRID | UNKNOWN
@@ -44,7 +58,10 @@ class SpanCircuitSnapshot:
     is_never_backup: bool  # v1: Circuit.isNeverBackup | v2: circuit/never-backup
     device_type: str = "circuit"  # "circuit" | "pv" | "evse"
     relative_position: str = ""  # PV/EVSE: "IN_PANEL" | "UPSTREAM" | "DOWNSTREAM"
-    is_240v: bool = False
+    # From the breaker's pole count. `None` where the circuit publishes no pole
+    # count: a meter outside the panel has no breaker, and a breaker whose count
+    # has not arrived has not said.
+    is_240v: bool | None = False
     current_a: float | None = None
     breaker_rating_a: float | None = None
     always_on: bool = False  # v2 new: circuit/always-on
@@ -75,6 +92,53 @@ class SpanCircuitSnapshot:
     pcs_managed: bool | None = None  # v2: circuit pcs/managed
     pcs_priority: int | None = None  # v2: circuit pcs/priority
 
+    measures_outside_panel: bool = False
+    """The device declares no breaker space: a meter outside the panel.
+
+    Power is import-positive (positive = flowing into the panel); consumed is
+    imported energy and produced is exported energy, so consumed minus produced
+    is net import. Read from the device's declaration, never from its values, so
+    a meter that has not reported yet is already outside the panel. Such a meter
+    has no relay, no breaker and no shed priority, and occupies no position.
+    """
+
+    meter_shared_with: tuple[str, ...] | None = None
+    """The other circuits this circuit's meter also measures, by circuit id.
+
+    From `meter/shared-with-device-ids`, without the circuit itself or an id
+    naming no circuit in the snapshot, ordered by `device_id_order`. `None`
+    where the circuit declares no such list or has not published it; `()` where
+    it lists no circuit the snapshot holds. The peers' readings are the same
+    meter's, so a consumer never adds them up; `shared_meter_groups` groups
+    them.
+    """
+    relay_shared_with: tuple[str, ...] | None = None
+    """The other circuits this circuit's relay also switches, by circuit id.
+
+    From `switch/shared-with-device-ids`, read as `meter_shared_with` is.
+    """
+
+    nominal_voltage_v: float | None = None
+    """The circuit's rated voltage, from `info/nominal-voltage`.
+
+    `None` where the circuit declares none or has not published it.
+    """
+    protection_functions: tuple[ProtectionFunction, ...] | None = None
+    """The protections the circuit's breaker provides, from `breaker/protection-functions`.
+
+    In published order, without any value outside `PROTECTION_FUNCTIONS`.
+    `None` where the breaker declares none or has not published them.
+    """
+
+    feeds_role: FeedsRole | None = None
+    """What the circuit feeds, from its `connection/feeds-role`.
+
+    `None` where the circuit declares no role, has not published it, or
+    publishes a value outside `FEEDS_ROLES`. Reported as declared and nothing
+    more: `device_type` stays as published, so a circuit whose role is solar is
+    still a circuit. The flat schema declares no roles.
+    """
+
 
 @dataclass(frozen=True, slots=True)
 class SpanPVSnapshot:
@@ -401,6 +465,22 @@ class SpanEvseSnapshot:
     set topic when it is not.
     """
 
+    lock_control: ControlTarget | None = None
+    """Where the charger's connector lock is commanded, and which property reports it. v1.0 only.
+
+    Addresses `switch/lock-state` on the charger's own device, and is present
+    only where that declaration carries `$settable`: absence is refusal, so a
+    lock the charger reports but does not accept writes to has no target. The
+    value written is one of `lock_state_options`. `None` on the flat schema.
+    """
+
+    lock_state_options: tuple[str, ...] | None = None
+    """The values the charger's `switch/lock-state` declares in its `$format`. v1.0 only.
+
+    What a lock command may write: a value outside them is refused rather than
+    published. `None` where the charger declares no lock or no `$format`.
+    """
+
     connected: bool | None = None
     """The enclosure's view of the link to this charger, v1.0 only.
 
@@ -476,6 +556,20 @@ class SpanBatterySnapshot:
     # it, and the migration guide warns against conflating them.
     communication_state: str | None = None  # v2: bess status/communication-state
 
+    # Whether the panel's device tree declares a battery, v1.0 only. True from the
+    # moment the battery describes itself, before any of its values arrive, so a
+    # battery whose state of charge is never published is still a battery. None
+    # on the flat schema, which has no battery device to declare and publishes
+    # its battery values whether or not one is installed.
+    present: bool | None = None
+
+    # The circuit whose `connection/feeds-device-id` names this battery, v1.0
+    # only. Where it is set and no device claims the battery through a
+    # `fed-by-*` record, `connected` is that circuit's `feeds-device-status`.
+    # None where no circuit feeds the battery, as when it sits ahead of the
+    # upstream lugs, and on the flat schema.
+    feed_circuit_id: str | None = None
+
 
 @dataclass(frozen=True, slots=True)
 class FieldMetadata:
@@ -540,6 +634,48 @@ reading a row can look it up without translating it.
 _DISCOVERY_PREFIX = f"{DISCOVERY_NAMESPACE}."
 
 
+def device_id_order(device_id: str) -> tuple[str | int, ...]:
+    """Sort key for device ids under which digit runs compare as numbers.
+
+    `circuit-9` sorts before `circuit-10`. Splitting on a captured digit run
+    leaves the runs at the odd positions and the text between them at the even
+    ones, so every position holds the same type in every key.
+    """
+    parts = re.split(r"(\d+)", device_id)
+    return tuple(int(part) if index % 2 else part for index, part in enumerate(parts))
+
+
+def shared_meter_groups(circuits: Mapping[str, SpanCircuitSnapshot]) -> dict[str, tuple[str, ...]]:
+    """The circuits one meter measures, grouped and keyed by their first member.
+
+    A group holds every circuit linked through `meter_shared_with`, in
+    `device_id_order`, and its key is the first of them. A circuit that names no
+    known peer and is named by none is in no group. Only membership: no reading
+    is combined, because every member already reports the one meter's values.
+    """
+    links: dict[str, set[str]] = {}
+    for circuit_id, circuit in circuits.items():
+        for peer in circuit.meter_shared_with or ():
+            if peer in circuits and peer != circuit_id:
+                links.setdefault(circuit_id, set()).add(peer)
+                links.setdefault(peer, set()).add(circuit_id)
+    groups: dict[str, tuple[str, ...]] = {}
+    seen: set[str] = set()
+    for start in sorted(links, key=device_id_order):
+        if start in seen:
+            continue
+        members = {start}
+        pending = [start]
+        while pending:
+            for peer in links[pending.pop()] - members:
+                members.add(peer)
+                pending.append(peer)
+        seen |= members
+        ordered = tuple(sorted(members, key=device_id_order))
+        groups[ordered[0]] = ordered
+    return groups
+
+
 def discovery_path(device_type: str, node_id: str, property_id: str) -> str:
     """The namespaced field path for one declared-but-unaddressed property.
 
@@ -1135,6 +1271,45 @@ class SpanPanelSnapshot:
     and `DeviceInfo(hw_version=...)` is the consumer's abbreviation, not ours.
     """
 
+    busbar_current_a: float | None = None
+    """The panel's busbar current, from its `meter/busbar-current`. v1.0 only.
+
+    `None` where the panel declares none or has not published it.
+    """
+    frequency_hz: float | None = None
+    """The line frequency, from the panel's `meter/frequency`. v1.0 only.
+
+    `None` where the panel declares none or has not published it.
+    """
+    upstream_protection_rating_a: int | None = None
+    """The rating of the protection ahead of the upstream lugs, in amperes. v1.0 only.
+
+    From the upstream lugs' `connection/overcurrent-protection`; `None` where
+    they declare none or have not published it.
+    """
+
+    first_position: int | None = None
+    """The panel's first breaker position. v1.0 only.
+
+    The reported model's range as the adapter's model table gives it, where
+    the table knows the model, otherwise the lowest occupied space. An occupied
+    space outside a known model's range does not move it: the adapter warns
+    once for that panel instead. `None` on the flat schema and where neither is
+    known. Together with `last_position` it says which positions exist,
+    occupied or not; no circuit is made up for an empty one.
+    """
+    last_position: int | None = None
+    """The panel's last breaker position. v1.0 only; see `first_position`."""
+
+    publishes_solar_roles: bool = False
+    """Whether any circuit declares `connection/feeds-role`.
+
+    The declaration decides, not the value: a circuit that declares the role
+    before publishing it, or declares a role other than solar, still marks the
+    panel as one that says where its solar is. `False` on the flat schema,
+    which declares no roles.
+    """
+
     # `shed/policy`, v1.0 only: how the panel decides what to shed, and the two
     # SoC thresholds that make its behaviour predictable. The wire carries one
     # `json` document; these are the parsed answer plus the document itself.
@@ -1285,7 +1460,7 @@ class SpanPanelSnapshot:
     apart — every limit in this capture is a legal `0.0`.
     """
 
-    lugs_at_service_entrance: bool = True
+    lugs_at_service_entrance: bool | None = True
     """Whether this enclosure's upstream lugs *are* the utility connection point.
 
     `False` means something sits between the utility and the main lugs, so the
@@ -1316,6 +1491,9 @@ class SpanPanelSnapshot:
     flat panel's lugs are its service entrance. schema_0 leaves it alone for that
     reason.
 
+    `None` while the lugs declare `connection/fed-by-device-id` and have not
+    published it: the feed may yet name a device, so neither answer is known.
+
     A defaulted snapshot field rather than a `SchemaAdapter` member, for the
     reason `adopted_devices` gives above: the protocol derives its required
     members from itself, so a new member would be required of every adapter

{span_panel_api-3.7.0b1 → span_panel_api-3.8.0b1}/src/span_panel_api/mqtt/client.py

@@ -48,6 +48,11 @@ if TYPE_CHECKING:
 
 _LOGGER = logging.getLogger(__name__)
 
+LOCK_STATE_LOCKED = "LOCKED"
+"""The `switch/lock-state` value that locks a charger's connector, as the panel declares it."""
+LOCK_STATE_UNLOCKED = "UNLOCKED"
+"""The `switch/lock-state` value that unlocks it."""
+
 # How long to wait for circuit name properties after device ready.
 # Retained messages typically arrive within 1-2s, but allow headroom.
 _CIRCUIT_NAMES_TIMEOUT_S = 10.0
@@ -949,6 +954,41 @@ class SpanMqttClient:
             )
         return await self._publish_control(target, payload, self._control_deadlines.evse_charge_limit)
 
+    # -- EvseLockControlProtocol -------------------------------------------
+
+    async def set_evse_lock(self, node_id: str, locked: bool) -> PublishOutcome:
+        """Lock or unlock one commissioned charger's connector.
+
+        Args:
+            node_id: the key this charger has in `SpanPanelSnapshot.evse`
+            locked: True to lock, False to unlock
+
+        **The snapshot is the authorisation**, as for an adopted property: the
+        charger's `lock_control` is the topic, and it is set only where the
+        charger declares `switch/lock-state` settable. The value must be one the
+        declaration's `$format` lists, so a charger that spells its states
+        differently is refused rather than sent a word it does not know.
+        """
+        value = LOCK_STATE_LOCKED if locked else LOCK_STATE_UNLOCKED
+        charger = self._require_adapter().build_snapshot().evse.get(node_id)
+        target = None if charger is None else charger.lock_control
+        if charger is None or target is None:
+            await self._refuse_control(
+                device_id=node_id,
+                value=value,
+                detail="no such control",
+                message=f"No settable lock on EVSE {node_id!r}",
+            )
+        if value not in (charger.lock_state_options or ()):
+            await self._refuse_control(
+                target=target,
+                device_id=target.device_id,
+                value=value,
+                detail="value not declared",
+                message=f"EVSE {node_id!r} does not declare the lock state {value}",
+            )
+        return await self._publish_control(target, value, self._control_deadlines.evse_lock)
+
     # -- AdoptedControlProtocol --------------------------------------------
 
     async def set_adopted_property(self, device_id: str, node_id: str, property_id: str, value: str) -> PublishOutcome:

{span_panel_api-3.7.0b1 → span_panel_api-3.8.0b1}/src/span_panel_api/mqtt/control.py

@@ -105,6 +105,7 @@ class ControlDeadlines:
     priority: float = 2.0
     dominant_power_source: float = 2.0
     evse_charge_limit: float = 2.0
+    evse_lock: float = 2.0
     adopted_property: float = 2.0
 
 

{span_panel_api-3.7.0b1 → span_panel_api-3.8.0b1}/src/span_panel_api/protocol.py

@@ -124,6 +124,19 @@ class EvseControlProtocol(Protocol):
     async def set_evse_charge_limit(self, node_id: str, amps: int) -> PublishOutcome: ...
 
 
+@runtime_checkable
+class EvseLockControlProtocol(Protocol):
+    """Control protocol for a commissioned EV charger's connector lock.
+
+    A protocol of its own rather than a member on `EvseControlProtocol`, which
+    would break that protocol's implementers. The write is authorised by the
+    snapshot: only a charger whose `SpanEvseSnapshot.lock_control` is set can be
+    addressed, and only with a value its `lock_state_options` lists.
+    """
+
+    async def set_evse_lock(self, node_id: str, locked: bool) -> PublishOutcome: ...
+
+
 @runtime_checkable
 class AdoptedControlProtocol(Protocol):
     """Control protocol for settable properties on a device nothing here models.

{span_panel_api-3.7.0b1 → span_panel_api-3.8.0b1}/tests/adapter_fidelity/harness.py

@@ -542,10 +542,21 @@ class _Instance:
     deferred: bool = False
 
 
+OUTSIDE_PANEL_ROLE: Final = "meter-outside-panel"
+"""The role of a circuit-typed device that declares no breaker space: a meter outside the panel.
+
+Its own role, because the library reads it in the opposite frame from a hosted
+circuit (`circuits.build_circuit` and `SpanCircuitSnapshot.measures_outside_panel`),
+so one row could not document both.
+"""
+
+
 def _role(capture: _Capture, device: _Device) -> str:
     if device.device_id == capture.root_id:
         return "panel"
     short = device.device_type.removeprefix(DEVICE_TYPE_PREFIX)
+    if device.device_type == TYPE_CIRCUIT and "info/spaces" not in device.declared:
+        return OUTSIDE_PANEL_ROLE
     if device.device_type.startswith(TYPE_LUGS):
         direction = device.values.get("info/direction", "").strip().lower()
         return f"lugs-{direction}" if direction else "lugs"