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

{span_panel_api-3.8.0b1 → span_panel_api-3.8.0b2}/.gitignore

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

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

@@ -14,7 +14,9 @@ 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.**
+- **`SpanMqttClient.masked_tree()` returns the panel's device tree with identifiers and site details masked**, for a consumer's diagnostics; `None` on a flat panel.
 - **`V2StatusInfo.hardware_version` reports the hardware version string from `GET /api/v2/status`.**
+- **`SpanEvseSnapshot.charge_current_limit_minimum_a` and `charge_current_limit_maximum_a` report the range a SPAN Drive declares for its charge-current limit**, `None` where undeclared.
 
 ### Changed
 
@@ -37,6 +39,7 @@ Snapshot fields that held a fabricated constant can now be unknown, and with `sp
 
 - **`V2HomieSchema.types_schema_hash` on data model 1.0 is the panel's published `deviceClassesSchemaHash`, or a hash of `deviceClasses` when none is published, where it was one constant for every such panel**; a flat panel's value is unchanged, and a
   value stored from 3.6.x differs once on a data model 1.0 panel.
+- **A property the panel clears reads as unpublished** on a parent/child panel, where it read as an empty value until the panel published it again.
 
 ## [3.6.2]
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: span-panel-api
-Version: 3.8.0b1
+Version: 3.8.0b2
 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.4.0b1; extra == 'schema-1'
+Requires-Dist: span-panel-api-schema-1>=1.4.0b4; extra == 'schema-1'
 Description-Content-Type: text/markdown
 
 # SPAN Panel API
@@ -171,6 +171,9 @@ because a transport could reasonably offer one and not the other.
 One further protocol, `SchemaAdapter`, is the bootstrap-to-parser contract rather than a consumer-facing one; it is what an adapter distribution implements and what discovery checks. Integration code programs against the protocols above, not against
 transport-specific classes.
 
+`TreeExportingAdapter` sits beside `SchemaAdapter` as an optional protocol, not one every adapter must implement: an adapter that offers `export_masked_tree()` lets `SpanMqttClient.masked_tree()` return the panel's device tree with serials, device ids and
+site details masked, and `None` otherwise.
+
 ### Snapshots
 
 All panel state is represented as immutable, frozen dataclasses:

{span_panel_api-3.8.0b1 → span_panel_api-3.8.0b2}/README.md

@@ -144,6 +144,9 @@ because a transport could reasonably offer one and not the other.
 One further protocol, `SchemaAdapter`, is the bootstrap-to-parser contract rather than a consumer-facing one; it is what an adapter distribution implements and what discovery checks. Integration code programs against the protocols above, not against
 transport-specific classes.
 
+`TreeExportingAdapter` sits beside `SchemaAdapter` as an optional protocol, not one every adapter must implement: an adapter that offers `export_masked_tree()` lets `SpanMqttClient.masked_tree()` return the panel's device tree with serials, device ids and
+site details masked, and `None` otherwise.
+
 ### Snapshots
 
 All panel state is represented as immutable, frozen dataclasses:

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

@@ -1,6 +1,6 @@
 [project]
 name = "span-panel-api"
-version = "3.8.0b1"
+version = "3.8.0b2"
 description = "A client library for SPAN Panel API"
 authors = [
     {name = "SpanPanel"}
@@ -71,7 +71,8 @@ schema-0 = ["span-panel-api-schema-0>=1.3.0b1"]
 # Raised to 1.3.0b1 for 3.7.0b1, for the same reason as schema-0's.
 # 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"]
+# Raised to 1.4.0b4 for 3.8.0b2: that adapter exports the masked device tree.
+schema-1 = ["span-panel-api-schema-1>=1.4.0b4"]
 
 [project.urls]
 Homepage = "https://github.com/SpanPanel/span-panel-api"
@@ -95,7 +96,7 @@ dev = [
     # known. Dependabot raises the bump on its own; the bump PR re-runs
     # `scripts/capture_parent_child_reference.py` and the suite then says whether
     # the wire moved.
-    "ebus-panel-sim==0.8.0",
+    "ebus-panel-sim==0.9.0",
     "pytest>=9.0.2",
     "pytest-asyncio>=1.3.0",
     "pytest-cov",
@@ -255,6 +256,12 @@ explicit_package_bases = true
 # `tests/` on `sys.path`; the support packages the mypy hook checks resolve the same
 # way here.
 mypy_path = "src:tests"
+# paho ships `py.typed` but leaves its topic matcher unannotated, so every call
+# into it would be an untyped call. The schema-1 route table resolves what the
+# matcher yields through a typed dict at once, which keeps its `Any` from going
+# further; `warn_return_any` does not police that for you (a union or a
+# `yield from` passes it), so keep it to that shape.
+untyped_calls_exclude = ["paho.mqtt.matcher"]
 # Excluded by name for the reason `[tool.ruff]` gives above: the capture script is
 # checked like the library, and the hand-run tools written before that was expected
 # are not.

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

@@ -53,6 +53,9 @@ from .models import (
     FeedsRole,
     FieldMetadata,
     HomieSchemaTypes,
+    MaskedTree,
+    MaskedTreeDevice,
+    MaskedTreeMetadata,
     PassphraseRotation,
     ProtectionFunction,
     SpanBatterySnapshot,
@@ -62,6 +65,7 @@ from .models import (
     SpanPanelSnapshot,
     SpanPcsSnapshot,
     SpanPVSnapshot,
+    UndescribedDevice,
     V2AuthResponse,
     V2HomieSchema,
     V2StatusInfo,
@@ -95,6 +99,7 @@ from .protocol import (
     PanelControlProtocol,
     SpanPanelClientProtocol,
     StreamingCapableProtocol,
+    TreeExportingAdapter,
 )
 
 __version__ = _pkg_version("span-panel-api")
@@ -147,6 +152,15 @@ __all__ = [  # noqa: RUF022
     "ControlTarget",
     "ExtensionProperty",
     "ExtensionSubject",
+    # Added 2026-10-31: the masked device tree a consumer forwards in diagnostics,
+    # and the optional protocol an adapter offers it through. Deliberately not a
+    # SchemaAdapter member: the protocol derives its required set from itself, so a
+    # member there would invalidate every built adapter wheel.
+    "MaskedTree",
+    "MaskedTreeDevice",
+    "MaskedTreeMetadata",
+    "UndescribedDevice",
+    "TreeExportingAdapter",
     # Snapshots
     "SpanBatterySnapshot",
     "SpanCircuitSnapshot",

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

@@ -12,7 +12,7 @@ from __future__ import annotations
 from collections.abc import Mapping
 from dataclasses import dataclass, field
 import re
-from typing import Final, Literal
+from typing import Final, Literal, NotRequired, TypedDict
 
 # Homie schema type: {type_name: {property_name: {attribute: value}}}
 # Values are heterogeneous JSON (str, int, bool, nested dicts).
@@ -465,6 +465,36 @@ class SpanEvseSnapshot:
     set topic when it is not.
     """
 
+    charge_current_limit_minimum_a: int | None = None
+    """The lowest charge-current limit the charger declares a user may set, in amps. v1.0 only.
+
+    The minimum of the `<min>:<max>` range the limit's declaration states in
+    `$format`, from the same resolution as `charge_current_limit_a`; firmware
+    r202639 declares `6:<commissioned maximum>`. A write below it is refused
+    rather than published, so a control offers nothing under it.
+
+    A declaration, not a reading: it is reported as soon as the charger
+    describes itself, and whether or not the limit is settable, which
+    `charge_current_limit_settable` answers. `None` where the charger declares
+    no limit, no `$format`, or the format leaves this side open, and where the
+    format cannot be read as an integer range (not `integer`, not `<min>:<max>`,
+    a bound that is not a plain integer, or a minimum above the maximum). `None`
+    on the flat schema, which declares no range.
+    """
+
+    charge_current_limit_maximum_a: int | None = None
+    """The highest charge-current limit the charger declares a user may set, in amps. v1.0 only.
+
+    The maximum of the same declared range, `None` on the same terms. A write
+    above it is refused rather than published.
+
+    **Not `charge_current_ceiling_a`.** That is the commissioned ceiling, a
+    published value; this is the declared range, part of the limit's
+    description. Every r202639 capture declares a maximum equal to the ceiling
+    it publishes, but they are separate facts, and a write must satisfy both: a
+    control's upper bound is the lower of the two where both are present.
+    """
+
     lock_control: ControlTarget | None = None
     """Where the charger's connector lock is commanded, and which property reports it. v1.0 only.
 
@@ -1506,3 +1536,65 @@ class SpanPanelSnapshot:
     the feeding device is another panel with its own tree, not a child of this
     one.
     """
+
+
+class MaskedTreeMetadata(TypedDict):
+    """What produced a `MaskedTree` and whether it can be trusted to be whole.
+
+    `masked` is always `True`: the tree never carries a serial, a credential or
+    an address, and the marker lets whoever reads a forwarded diagnostic see that
+    without inspecting the values. `tree_complete` is `False` when the panel had
+    not finished publishing its tree, so what follows is a partial reading.
+    """
+
+    schema: Literal["tree-v1"]
+    masked: Literal[True]
+    producer: str
+    tree_complete: bool
+
+
+class MaskedTreeDevice(TypedDict):
+    """One described device in a `MaskedTree`, as a consumer forwards it in diagnostics.
+
+    Values are keyed `"<node>/<property>"` and kept as the wire strings the
+    panel published, masked where they identify the device or the site.
+    `numeric_properties` holds the values of declared `integer` and `float`
+    properties, `properties` the values of every other declared property,
+    `undeclared_properties` values the panel published that its own description
+    does not declare, and `targets` its `$target` values. A declared property
+    with no value has no key: never `None`, and never a `""` the panel did not
+    send, because a placeholder would read as a reading. A `""` the panel did
+    publish is kept as `""`.
+    """
+
+    description: dict[str, object]
+    properties: dict[str, str]
+    numeric_properties: dict[str, str]
+    targets: dict[str, str]
+    undeclared_properties: dict[str, str]
+    state: NotRequired[str]
+
+
+class UndescribedDevice(TypedDict):
+    """A device the panel published values for but never described.
+
+    With no `$description` there is nothing to say which node a property belongs
+    to, so `values` keeps each as `"<node>/<property>"` -> wire string, unsplit.
+    """
+
+    values: dict[str, str]
+    targets: dict[str, str]
+    state: NotRequired[str]
+
+
+class MaskedTree(TypedDict):
+    """The masked device tree a consumer forwards in diagnostics.
+
+    Produced by an adapter that offers `TreeExportingAdapter`. Described devices
+    and undescribed ones are kept apart so a reader never mistakes one for the
+    other.
+    """
+
+    metadata: MaskedTreeMetadata
+    devices: dict[str, MaskedTreeDevice]
+    undescribed_devices: dict[str, UndescribedDevice]

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

@@ -36,8 +36,16 @@ from ..exceptions import (
     SpanPanelTLSVerificationError,
     SpanPanelValidationError,
 )
-from ..models import AdoptedProperty, ControlTarget, FieldMetadata, HomieSchemaTypes, SpanPanelSnapshot, V2HomieSchema
-from ..protocol import PanelCapability, SchemaAdapter
+from ..models import (
+    AdoptedProperty,
+    ControlTarget,
+    FieldMetadata,
+    HomieSchemaTypes,
+    MaskedTree,
+    SpanPanelSnapshot,
+    V2HomieSchema,
+)
+from ..protocol import PanelCapability, SchemaAdapter, TreeExportingAdapter
 from .connection import AsyncMqttBridge
 from .const import MQTT_READY_TIMEOUT_S
 from .control import ControlCommand, ControlDeadlines, ControlInterceptor, PublishOutcome, PublishState
@@ -420,6 +428,18 @@ class SpanMqttClient:
             return None
         return adapter.build_field_metadata()
 
+    def masked_tree(self) -> MaskedTree | None:
+        """The panel's device tree with serials, device ids and site details masked.
+
+        Computed from the adapter's current view at call time. None on a flat
+        panel, whose adapter does not export a tree, and before the root device
+        has described itself.
+        """
+        adapter = self._adapter
+        if isinstance(adapter, TreeExportingAdapter):
+            return adapter.export_masked_tree()
+        return None
+
     async def connect(self) -> None:
         """Connect to MQTT broker and wait for Homie device ready.
 
@@ -1079,10 +1099,16 @@ class SpanMqttClient:
         self._unregister_property_observer = adapter.register_property_callback(self._on_property_value)
 
     def _on_property_value(self, device_id: str, node_id: str, property_id: str, value: str | None) -> None:
-        """Record one property's value and resolve any write waiting for it."""
+        """Record one property's value and resolve any write waiting for it.
+
+        `None` is a property with no value, such as one the panel cleared. Its
+        last value is forgotten, so a write of that value is not taken for a
+        no-op, and no write is confirmed by it.
+        """
+        key = (device_id, node_id, property_id)
         if value is None:
+            self._observed_values.pop(key, None)
             return
-        key = (device_id, node_id, property_id)
         self._observed_values[key] = value
         for verification in list(self._verifications):
             if verification.key == key and verification.expected == value and not verification.observed.done():

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

@@ -14,7 +14,7 @@ from typing import TYPE_CHECKING, Protocol, runtime_checkable
 if TYPE_CHECKING:
     from ._ssl import LeafNameMismatch
     from .exceptions import SpanPanelError
-    from .models import ControlTarget, FieldMetadata, SpanPanelSnapshot, V2HomieSchema
+    from .models import ControlTarget, FieldMetadata, MaskedTree, SpanPanelSnapshot, V2HomieSchema
     from .mqtt.control import ControlInterceptor, PublishOutcome
 
 
@@ -386,3 +386,18 @@ class SchemaAdapter(Protocol):
         `device_id` is the panel serial rather than being omitted. Filling it in
         is what lets a consumer treat both schemas' streams as one shape.
         """
+
+
+@runtime_checkable
+class TreeExportingAdapter(Protocol):
+    """Adapter that can export the device tree it holds, masked for diagnostics.
+
+    A protocol of its own rather than a `SchemaAdapter` member: the required set
+    of that protocol is derived from itself, so a member added there would be
+    demanded of every built adapter and invalidate those already shipped. A
+    consumer asks `isinstance(adapter, TreeExportingAdapter)` and offers the
+    export only when it holds.
+    """
+
+    def export_masked_tree(self) -> MaskedTree | None:
+        """The masked tree, or None when the adapter holds no tree yet."""

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

@@ -44,7 +44,7 @@ from pathlib import Path
 import re
 from typing import Final
 
-from reference_payloads.schema_one import RetainedTopicTree, devices_from_tree
+from reference_payloads.schema_one import RetainedTopicTree, devices_from_tree, retained_payload
 from span_panel_api.models import (
     ADOPTION_IDENTITY_NODE,
     ADOPTION_TOPOLOGY_NODE,
@@ -344,7 +344,7 @@ def _frozen_clock() -> float:
 
 
 def _replay(capture: _Capture) -> SchemaOneAdapter:
-    """A fresh adapter fed the capture as retained messages."""
+    """A fresh adapter fed the capture as retained messages, an empty value as `0x00` (`retained_payload`)."""
     schema = V2HomieSchema(
         firmware_version=capture.firmware,
         types_schema_hash="sha256:capture",
@@ -358,7 +358,7 @@ def _replay(capture: _Capture) -> SchemaOneAdapter:
         adapter.handle_message(f"{prefix}/$description", json.dumps(device.description))
         adapter.handle_message(f"{prefix}/$state", "ready")
         for topic in sorted(device.values):
-            adapter.handle_message(f"{prefix}/{topic}", device.values[topic])
+            adapter.handle_message(f"{prefix}/{topic}", retained_payload(device.values[topic]))
     return adapter
 
 
@@ -609,13 +609,13 @@ def _measure(capture: _Capture, instances: list[_Instance], baseline: Mapping[st
         # as a later retained value does.
         target = session if instance.raw is not None else _replay(capture)
         for candidate in _candidates(instance.declaration, instance.raw, property_id, references):
-            target.handle_message(topic, candidate)
+            target.handle_message(topic, retained_payload(candidate))
             leaves = _flatten(target)
             moved = _moved(baseline, leaves)
             instance.effect |= moved
             instance.perturbed.append((candidate, {leaf: leaves[leaf] for leaf in moved if leaf in leaves}))
         if instance.raw is not None:
-            session.handle_message(topic, instance.raw)
+            session.handle_message(topic, retained_payload(instance.raw))
     unrestored = _moved(baseline, _flatten(session))
     if unrestored:
         raise AssertionError(f"republishing the captured values did not restore the session: {sorted(unrestored)[:5]}")

{span_panel_api-3.8.0b1 → span_panel_api-3.8.0b2}/tests/adapter_fidelity/rules.py

@@ -172,13 +172,6 @@ def _transforms() -> dict[RowKey, dict[str, Transform]]:
         _DERIVED,
         "devices.build_battery: compared in sign with the BESS meter where the firmware names no release build",
     )
-    add(
-        "panel",
-        "power-flows/grid",
-        ANY_LEAF,
-        _DERIVED,
-        "panel.resolve_islanding_state: grid power decides on-grid only where no MID is published",
-    )
     add("panel", "shed/policy", "panel.shed_policy", _LITERAL, panel_fields)
     for policy_field in ("shed_policy_algorithm", "shed_soc_threshold_shed_percent", "shed_soc_threshold_release_percent"):
         add("panel", "shed/policy", f"panel.{policy_field}", _DERIVED, "panel._shed_policy parses the policy document")

{span_panel_api-3.8.0b1 → span_panel_api-3.8.0b2}/tests/adapter_fidelity/rules_captured.py

@@ -50,6 +50,16 @@ _DERIVATIONS: Final = (
         "panel.resolve_dominant_power_source: with no MID, GRID is an elimination, since nothing else can form the grid",
         values=("GRID",),
     ),
+    Derivation(
+        "panel.dsm_state",
+        "panel.resolve_islanding_state: with no MID, on-grid is the same elimination, since nothing can island the panel",
+        values=("DSM_ON_GRID",),
+    ),
+    Derivation(
+        "panel.current_run_config",
+        "panel.resolve_islanding_state: with no MID, on-grid is the same elimination, since nothing can island the panel",
+        values=("PANEL_ON_GRID",),
+    ),
     Derivation(
         "circuit.relay_state",
         f"{_STR_SENTINEL}: circuits.build_circuit reads UNKNOWN where the device publishes no switch/relay",

{span_panel_api-3.8.0b1 → span_panel_api-3.8.0b2}/tests/adapter_fidelity/test_harness.py

@@ -22,6 +22,7 @@ from span_panel_api_schema_1 import adapter as adapter_module
 from span_panel_api_schema_1.const import TYPE_CIRCUIT, TYPE_PV
 from span_panel_api_schema_1.snapshot import build_snapshot
 
+from . import harness
 from .harness import FidelityReport, RowKey, run_cell
 from .rules import MAIN32_RULES
 
@@ -192,3 +193,49 @@ def test_a_deferred_row_is_reported_apart_from_the_silent_drops(small_capture: P
     report = run_cell(small_capture, replace(MAIN32_RULES, deferred={key: "planted for this test"}))
     assert report.silently_dropped == ()
     assert report.deferred == (key,)
+
+
+_FED_BY = "connection/fed-by-device-id"
+
+
+@pytest.fixture
+def valued_empty_capture(small_capture: Path) -> Path:
+    """The small capture with the upstream lugs publishing an empty `fed-by-device-id`.
+
+    In a `tree-v1` document an empty value is written decoded, as `""`, the way
+    the masked export writes one: a retained store never holds a zero-length
+    payload, so `""` there cannot be a clear.
+    """
+    tree = _mapping(json.loads(small_capture.read_text(encoding="utf-8")))
+    devices = _mapping(tree["devices"])
+    upstream = next(
+        device_id
+        for device_id, entry in devices.items()
+        if _mapping(_mapping(entry)["properties"]).get("info/direction") == "UPSTREAM"
+    )
+    record = _mapping(devices[upstream])
+    record["properties"] = {**_mapping(record["properties"]), _FED_BY: ""}
+    devices[upstream] = record
+    path = small_capture.with_name("valued-empty-tree-v1.json")
+    path.write_text(json.dumps({**tree, "devices": devices}), encoding="utf-8")
+    return path
+
+
+def test_an_empty_value_is_measured_as_published(valued_empty_capture: Path) -> None:
+    """Published empty, nothing feeds the lugs: they are the service entrance, not unknown.
+
+    Replayed as a zero-length payload, the value would be a clear and read as unpublished.
+    """
+    leaves = harness._flatten(harness._replay(harness._load(valued_empty_capture)))
+
+    assert leaves["panel.lugs_at_service_entrance"] is True
+
+
+def test_republishing_an_empty_value_restores_the_session(valued_empty_capture: Path) -> None:
+    """Each perturbed property is set back to its captured value; an empty one must go back as a value.
+
+    `run_cell` raises when the session does not end equal to the baseline.
+    """
+    report = run_cell(valued_empty_capture, MAIN32_RULES)
+
+    assert report.declared_property_instances > 0

{span_panel_api-3.8.0b1 → span_panel_api-3.8.0b2}/tests/fixtures/panelbench_unvalued_by_both.json

@@ -80,6 +80,8 @@
   "energy.ebus.device.circuit::kitchen Lights  connection/feeds-device-id",
   "energy.ebus.device.circuit::kitchen Lights  connection/feeds-device-status",
   "energy.ebus.device.circuit::kitchen Lights  connection/feeds-device-type",
+  "energy.ebus.device.evse::SPAN Drive - Driveway  config/user-max-charge-current",
+  "energy.ebus.device.evse::SPAN Drive - Garage  config/user-max-charge-current",
   "energy.ebus.device.lugs::Downstream lugs  connection/fed-by-device-id",
   "energy.ebus.device.lugs::Downstream lugs  connection/fed-by-device-status",
   "energy.ebus.device.lugs::Downstream lugs  connection/fed-by-device-type",

{span_panel_api-3.8.0b1 → span_panel_api-3.8.0b2}/tests/reference_payloads/captures.py

@@ -130,14 +130,18 @@ def capture_tree(stem: str) -> CaptureTree:
 
 def _parse(path: Path) -> CaptureTree:
     raw: object = json.loads(path.read_text(encoding="utf-8"))
-    document = _json_object(raw, path.name)
+    return capture_tree_from_document(_json_object(raw, path.name), path.name)
+
+
+def capture_tree_from_document(document: Mapping[str, object], where: str) -> CaptureTree:
+    """Parse a `tree-v1` document already read from JSON; `where` names it in errors."""
     devices = {
-        device_id: _device(device_id, body, f"{path.name}: {device_id}")
-        for device_id, body in _json_object(document["devices"], f"{path.name}: devices").items()
+        device_id: _device(device_id, body, f"{where}: {device_id}")
+        for device_id, body in _json_object(document["devices"], f"{where}: devices").items()
     }
     roots = [device_id for device_id, device in devices.items() if device.device_type == _TYPE_PANEL]
     if len(roots) != 1:
-        raise ValueError(f"{path.name} holds {len(roots)} panels, not one")
+        raise ValueError(f"{where} holds {len(roots)} panels, not one")
     return CaptureTree(devices=MappingProxyType(devices), root_id=roots[0])