span-panel-api 3.5.0__tar.gz → 3.6.1b1__tar.gz

{span_panel_api-3.5.0 → span_panel_api-3.6.1b1}/CHANGELOG.md

@@ -7,6 +7,33 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 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. What one
 beta corrected in an earlier beta does not appear at all: from the point of view of somebody upgrading between released versions, it never happened.
 
+## [3.6.1b1]
+
+3.6.0 was withdrawn from PyPI; this release carries its changes, listed under 3.6.0 below, except how `pv` is chosen, which this release replaces.
+
+### Changed
+
+- **`SpanPanelSnapshot.pv` is documented as the lone inverter or the inverters together**, and the `schema-1` extra requires `span-panel-api-schema-1` 1.2.1 or newer.
+
+## [3.6.0] [YANKED]
+
+The snapshot carries every PV inverter a panel commissions, and registration copes with a panel that cannot read its own passphrase.
+
+### Added
+
+- **`SpanPanelSnapshot.pv_inverters`** carries every commissioned PV inverter, keyed by its feeding circuit's id, which stays put when firmware r202639 renames a panel's inverters, or by its device id where no circuit feeds it.
+- **`SpanPVSnapshot.serial_number`, `device_id` and `node_id`** give an inverter's serial number when one is published, its id on the wire, and its key in `pv_inverters`.
+- **`SpanEvseSnapshot.effective_charge_current_limit_a`** is the charge-current limit a charger is applying, its user limit when one is published and its ceiling otherwise, since from firmware r202639 a SPAN Drive publishes a user limit only once someone
+  sets one.
+- **`SpanPanelPassphraseUnavailableError`**, raised by `register_v2` and `create_span_client` for a panel that cannot read its own passphrase, is a `SpanPanelAPIError` rather than a `SpanPanelAuthError` because the passphrase the user gave may be correct.
+
+### Changed
+
+- **`V2AuthResponse.ebus_broker_password` and `hop_passphrase` are `str | None`**, `None` when a panel on firmware r202639 or later cannot read its passphrase yet still issues a valid access token.
+- **`register_v2` raises `SpanPanelServerError` with `status_code` for any 5xx**, including the 503 a panel on firmware r202639 answers until it knows its serial number, where it raised a plain `SpanPanelAPIError`.
+- **`SpanPanelSnapshot.pv` is the inverter on the lowest breaker space when more than one is commissioned**, rather than whichever one the adapter met first.
+- **`SpanPVSnapshot.nameplate_capacity_w` is documented as the array's DC size recorded at installation**, an informational figure and never a ceiling on PV power.
+
 ## [3.5.0]
 
 A rotation replaces the panel passphrase as well as the broker password, and the library now hands back both, so a caller no longer loses the only copy of the user's new passphrase. A broker that refuses the credentials is now reported as an authentication

{span_panel_api-3.5.0 → span_panel_api-3.6.1b1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: span-panel-api
-Version: 3.5.0
+Version: 3.6.1b1
 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
@@ -20,9 +20,9 @@ Requires-Dist: httpx<1.0,>=0.28.1
 Requires-Dist: paho-mqtt<3.0.0,>=2.0.0
 Requires-Dist: pyyaml>=6.0.0
 Provides-Extra: schema-0
-Requires-Dist: span-panel-api-schema-0>=1.1.0; extra == 'schema-0'
+Requires-Dist: span-panel-api-schema-0>=1.2.0; extra == 'schema-0'
 Provides-Extra: schema-1
-Requires-Dist: span-panel-api-schema-1>=1.1.0; extra == 'schema-1'
+Requires-Dist: span-panel-api-schema-1>=1.2.1b1; extra == 'schema-1'
 Description-Content-Type: text/markdown
 
 # SPAN Panel API
@@ -175,21 +175,25 @@ transport-specific classes.
 
 All panel state is represented as immutable, frozen dataclasses:
 
-| Dataclass             | Content                                                                                                                                                            |
-| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `SpanPanelSnapshot`   | Complete panel state: power, energy, grid/DSM state, hardware status, per-leg voltages, power flows, lugs current, shed forecast, circuits, battery, PV, EVSE, MID |
-| `SpanCircuitSnapshot` | Per-circuit: power, energy, relay state, priority, tabs, device type, breaker rating, current, `$target` pending state                                             |
-| `SpanBatterySnapshot` | BESS: SoC percentage, SoE kWh, own meter reading, communication state, link health, `model` / `part_number`, nameplate capacity                                    |
-| `SpanPVSnapshot`      | PV inverter: link health, `model` / `part_number`, nameplate capacity                                                                                              |
-| `SpanEvseSnapshot`    | EVSE (EV charger): status, lock state, advertised current, link health, `model` / `part_number` / serial / version metadata                                        |
-| `SpanMidSnapshot`     | Microgrid Interconnect Device: islanding state, grid state, grid-forming entity                                                                                    |
-| `AdoptedDevice`       | A device type this library models nothing for, carried whole: identity, readings, proxy link                                                                       |
-| `ExtensionProperty`   | A vendor property on a device this library _does_ model, with its value and the subject it hangs off                                                               |
-
-Identity is normalised across every DER class: **`model` is the human designation and `part_number` is the SKU**, on `battery`, `evse` and `pv` alike. `product_name` was retired in 3.0.0 — see the changelog, because `battery.model` changes value for
-existing flat users at that upgrade.
-
-`mid`, `adopted_devices`, `extension_properties` and the per-DER link-health fields exist only under the parent/child schema. They are `None` or empty on a flat panel rather than absent, so a consumer reads the same snapshot type either way.
+- **`SpanPanelSnapshot`**: complete panel state. Identity (serial, firmware, vendor, model, hardware version), panel size, main breaker rating, main relay, door and proximity state, uptime, network links with the Wi-Fi SSID and vendor cloud, grid and
+  feedthrough power and energy, grid/DSM state, run configuration, dominant power source, grid islandability, per-leg voltages, power flows, lugs current and whether the lugs are the service entrance, shed policy and forecast. It holds `circuits`,
+  `battery`, `pv`, `pv_inverters`, `evse`, `mid`, `pcs`, `adopted_devices` and `extension_properties`.
+- **`SpanCircuitSnapshot`**: one circuit. Id, name, relay state and requester, power, energy and their update times, tabs, 240 V, breaker rating, current, priority, user controllability, sheddable / never-backup / always-on flags, device type, relative
+  position, PCS management and priority, and the `$target` pending state for relay and priority.
+- **`SpanBatterySnapshot`**: the BESS. SoE percentage and kWh, its own meter reading, communication state, link health, vendor / `model` / `part_number` / serial / version, nameplate capacity.
+- **`SpanPVSnapshot`**: one PV inverter. Link health, vendor / `model` / serial / version, nameplate capacity (the array's DC size), feeding circuit, relative position, its wire `device_id` and its `node_id`, which is its key in `pv_inverters`.
+  `SpanPanelSnapshot.pv` is the lone inverter, or describes several together.
+- **`SpanEvseSnapshot`**: one EV charger. `node_id`, feeding circuit, status, lock state, advertised current, link health, vendor / `model` / `part_number` / serial / version, charge-current limit, ceiling, pending target and settability, and the effective
+  limit it applies.
+- **`SpanMidSnapshot`**: the Microgrid Interconnect Device. `node_id`, islanding state, grid state, grid-forming entity and its device name, vendor / `model` / serial / software and hardware version.
+- **`SpanPcsSnapshot`**: the Power Control System. Enabled and active, the enforced import limit and its binding constraint, and each import constraint's limit, enablement and active state (feed, operator, off-grid, requested).
+- **`AdoptedDevice`**: a device type this library models nothing for, carried whole. Identity (id, type, name, vendor, model, serial, versions), its declared parent, whether a peer proxies it, and its readings.
+- **`ExtensionProperty`**: a vendor property on a device this library _does_ model. The subject it hangs off, its node and property ids and its `path`, datatype / unit / format, settability, value, and whether its node has curated siblings.
+
+Identity is normalised across every DER class: **`model` is the human designation**, on `battery`, `evse` and `pv` alike, and **`part_number` is the SKU**, on `battery` and `evse`; `SpanPVSnapshot` has no SKU field. `product_name` was retired in 3.0.0 —
+see the changelog, because `battery.model` changes value for existing flat users at that upgrade.
+
+`mid`, `pcs`, `adopted_devices`, `extension_properties` and the per-DER link-health fields exist only under the parent/child schema. They are `None` or empty on a flat panel rather than absent, so a consumer reads the same snapshot type either way.
 
 ## Usage
 
@@ -611,7 +615,7 @@ src/span_panel_api/          # distribution: span-panel-api (no parser)
 ├── dispatch.py              # select_adapter_key() — what does this panel need?
 ├── exceptions.py            # Exception hierarchy
 ├── factory.py               # create_span_client() → SpanMqttClient
-├── models.py                # Snapshot dataclasses (panel, circuit, battery, PV, EVSE, MID, adopted)
+├── models.py                # Snapshot dataclasses (panel, circuit, battery, PV, EVSE, MID, PCS, adopted, extension)
 ├── phase_validation.py      # Electrical phase utilities
 ├── protocol.py              # PEP 544 protocols, SchemaAdapter, PanelCapability flags
 ├── schema_drift.py          # Reporting a panel that outruns what we can read

{span_panel_api-3.5.0 → span_panel_api-3.6.1b1}/README.md

@@ -148,21 +148,25 @@ transport-specific classes.
 
 All panel state is represented as immutable, frozen dataclasses:
 
-| Dataclass             | Content                                                                                                                                                            |
-| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `SpanPanelSnapshot`   | Complete panel state: power, energy, grid/DSM state, hardware status, per-leg voltages, power flows, lugs current, shed forecast, circuits, battery, PV, EVSE, MID |
-| `SpanCircuitSnapshot` | Per-circuit: power, energy, relay state, priority, tabs, device type, breaker rating, current, `$target` pending state                                             |
-| `SpanBatterySnapshot` | BESS: SoC percentage, SoE kWh, own meter reading, communication state, link health, `model` / `part_number`, nameplate capacity                                    |
-| `SpanPVSnapshot`      | PV inverter: link health, `model` / `part_number`, nameplate capacity                                                                                              |
-| `SpanEvseSnapshot`    | EVSE (EV charger): status, lock state, advertised current, link health, `model` / `part_number` / serial / version metadata                                        |
-| `SpanMidSnapshot`     | Microgrid Interconnect Device: islanding state, grid state, grid-forming entity                                                                                    |
-| `AdoptedDevice`       | A device type this library models nothing for, carried whole: identity, readings, proxy link                                                                       |
-| `ExtensionProperty`   | A vendor property on a device this library _does_ model, with its value and the subject it hangs off                                                               |
-
-Identity is normalised across every DER class: **`model` is the human designation and `part_number` is the SKU**, on `battery`, `evse` and `pv` alike. `product_name` was retired in 3.0.0 — see the changelog, because `battery.model` changes value for
-existing flat users at that upgrade.
-
-`mid`, `adopted_devices`, `extension_properties` and the per-DER link-health fields exist only under the parent/child schema. They are `None` or empty on a flat panel rather than absent, so a consumer reads the same snapshot type either way.
+- **`SpanPanelSnapshot`**: complete panel state. Identity (serial, firmware, vendor, model, hardware version), panel size, main breaker rating, main relay, door and proximity state, uptime, network links with the Wi-Fi SSID and vendor cloud, grid and
+  feedthrough power and energy, grid/DSM state, run configuration, dominant power source, grid islandability, per-leg voltages, power flows, lugs current and whether the lugs are the service entrance, shed policy and forecast. It holds `circuits`,
+  `battery`, `pv`, `pv_inverters`, `evse`, `mid`, `pcs`, `adopted_devices` and `extension_properties`.
+- **`SpanCircuitSnapshot`**: one circuit. Id, name, relay state and requester, power, energy and their update times, tabs, 240 V, breaker rating, current, priority, user controllability, sheddable / never-backup / always-on flags, device type, relative
+  position, PCS management and priority, and the `$target` pending state for relay and priority.
+- **`SpanBatterySnapshot`**: the BESS. SoE percentage and kWh, its own meter reading, communication state, link health, vendor / `model` / `part_number` / serial / version, nameplate capacity.
+- **`SpanPVSnapshot`**: one PV inverter. Link health, vendor / `model` / serial / version, nameplate capacity (the array's DC size), feeding circuit, relative position, its wire `device_id` and its `node_id`, which is its key in `pv_inverters`.
+  `SpanPanelSnapshot.pv` is the lone inverter, or describes several together.
+- **`SpanEvseSnapshot`**: one EV charger. `node_id`, feeding circuit, status, lock state, advertised current, link health, vendor / `model` / `part_number` / serial / version, charge-current limit, ceiling, pending target and settability, and the effective
+  limit it applies.
+- **`SpanMidSnapshot`**: the Microgrid Interconnect Device. `node_id`, islanding state, grid state, grid-forming entity and its device name, vendor / `model` / serial / software and hardware version.
+- **`SpanPcsSnapshot`**: the Power Control System. Enabled and active, the enforced import limit and its binding constraint, and each import constraint's limit, enablement and active state (feed, operator, off-grid, requested).
+- **`AdoptedDevice`**: a device type this library models nothing for, carried whole. Identity (id, type, name, vendor, model, serial, versions), its declared parent, whether a peer proxies it, and its readings.
+- **`ExtensionProperty`**: a vendor property on a device this library _does_ model. The subject it hangs off, its node and property ids and its `path`, datatype / unit / format, settability, value, and whether its node has curated siblings.
+
+Identity is normalised across every DER class: **`model` is the human designation**, on `battery`, `evse` and `pv` alike, and **`part_number` is the SKU**, on `battery` and `evse`; `SpanPVSnapshot` has no SKU field. `product_name` was retired in 3.0.0 —
+see the changelog, because `battery.model` changes value for existing flat users at that upgrade.
+
+`mid`, `pcs`, `adopted_devices`, `extension_properties` and the per-DER link-health fields exist only under the parent/child schema. They are `None` or empty on a flat panel rather than absent, so a consumer reads the same snapshot type either way.
 
 ## Usage
 
@@ -584,7 +588,7 @@ src/span_panel_api/          # distribution: span-panel-api (no parser)
 ├── dispatch.py              # select_adapter_key() — what does this panel need?
 ├── exceptions.py            # Exception hierarchy
 ├── factory.py               # create_span_client() → SpanMqttClient
-├── models.py                # Snapshot dataclasses (panel, circuit, battery, PV, EVSE, MID, adopted)
+├── models.py                # Snapshot dataclasses (panel, circuit, battery, PV, EVSE, MID, PCS, adopted, extension)
 ├── phase_validation.py      # Electrical phase utilities
 ├── protocol.py              # PEP 544 protocols, SchemaAdapter, PanelCapability flags
 ├── schema_drift.py          # Reporting a panel that outruns what we can read

{span_panel_api-3.5.0 → span_panel_api-3.6.1b1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "span-panel-api"
-version = "3.5.0"
+version = "3.6.1b1"
 description = "A client library for SPAN Panel API"
 authors = [
     {name = "SpanPanel"}
@@ -58,8 +58,13 @@ dependencies = [
 # makes every public protocol member mandatory of every adapter wheel — so a 1.0.0
 # adapter installed against this bootstrap is rejected at discovery rather than
 # working in a degraded way. The two must move together.
-schema-0 = ["span-panel-api-schema-0>=1.1.0"]
-schema-1 = ["span-panel-api-schema-1>=1.1.0"]
+# Raised to 1.2.0 for 3.6.0 for a different reason: no protocol member changed,
+# so a 1.1.x adapter is still accepted, but it fills neither `pv_inverters` nor
+# the inverter identity fields 3.6.0 adds. Upgrading through the extra is what
+# brings the adapters that do.
+schema-0 = ["span-panel-api-schema-0>=1.2.0"]
+# Raised to 1.2.1b1 for 3.6.1b1: that adapter stops ranking one inverter as pv.
+schema-1 = ["span-panel-api-schema-1>=1.2.1b1"]
 
 [project.urls]
 Homepage = "https://github.com/SpanPanel/span-panel-api"

{span_panel_api-3.5.0 → span_panel_api-3.6.1b1}/src/span_panel_api/__init__.py

@@ -28,6 +28,7 @@ from .exceptions import (
     SpanPanelConnectionError,
     SpanPanelError,
     SpanPanelInsufficientPrivilegeError,
+    SpanPanelPassphraseUnavailableError,
     SpanPanelSchemaVersionError,
     SpanPanelServerError,
     SpanPanelStaleDataError,
@@ -210,6 +211,11 @@ __all__ = [  # noqa: RUF022
     # Added 2026-10-02 (3.5.0): a 403 from a reduced-privilege token. A subclass
     # of SpanPanelAuthError, so every existing except clause keeps its meaning.
     "SpanPanelInsufficientPrivilegeError",
+    # Added 2026-10-06 (3.6.0): registration reached a panel that cannot read its own
+    # passphrase. A subclass of SpanPanelAPIError, so existing except clauses
+    # keep their meaning; deliberately not a SpanPanelAuthError, because the
+    # passphrase the user supplied may be correct.
+    "SpanPanelPassphraseUnavailableError",
     "SpanPanelServerError",
     "SpanPanelStaleDataError",
     # Added 2026-08-31 (3.4.0): a bootstrap REST call that failed verification

{span_panel_api-3.5.0 → span_panel_api-3.6.1b1}/src/span_panel_api/auth.py

@@ -19,7 +19,13 @@ import uuid
 import httpx
 
 from ._http import CA_CERT_PATH, V2_STATUS_PATH, _Reply, _request
-from .exceptions import SpanPanelAPIError, SpanPanelAuthError, SpanPanelInsufficientPrivilegeError, SpanPanelServerError
+from .exceptions import (
+    SpanPanelAPIError,
+    SpanPanelAuthError,
+    SpanPanelInsufficientPrivilegeError,
+    SpanPanelPassphraseUnavailableError,
+    SpanPanelServerError,
+)
 from .models import HomieSchemaTypes, PassphraseRotation, V2AuthResponse, V2HomieSchema, V2StatusInfo
 
 _LOGGER = logging.getLogger(__name__)
@@ -171,6 +177,11 @@ def _str(val: object) -> str:
     return str(val) if val is not None else ""
 
 
+def _optional_str(val: object) -> str | None:
+    """Extract a string from a JSON-decoded value that the panel may send as null or omit."""
+    return None if val is None else str(val)
+
+
 def _int(val: object) -> int:
     """Extract an int from a JSON-decoded value."""
     if isinstance(val, int):
@@ -182,6 +193,24 @@ def _int(val: object) -> int:
 
 HTTP_TOO_MANY_REQUESTS = 429
 
+#: The ``detail`` a registration 422 carries when the panel cannot read its own
+#: passphrase. Compared whole and quoted in the exception message, which is safe
+#: only because it is this fixed string and never anything the panel echoed.
+REGISTRATION_UNAVAILABLE_DETAIL = "Dashboard password is not available"
+
+
+def _error_detail(response: httpx.Response) -> str | None:
+    """The ``detail`` string of an error body, or None when there is no such string."""
+    try:
+        parsed = response.json()
+    except ValueError:
+        return None
+    if not isinstance(parsed, dict):
+        return None
+    detail = parsed.get("detail")
+    return detail if isinstance(detail, str) else None
+
+
 #: Default attempts and base backoff used when the panel rate-limits a request.
 CA_CERT_MAX_ATTEMPTS = 5
 CA_CERT_BACKOFF_S = 1.5
@@ -240,10 +269,15 @@ async def register_v2(
             this call to ``https://``; ``None`` is byte-identical to 3.0.1.
 
     Returns:
-        V2AuthResponse with access token and MQTT broker credentials
+        V2AuthResponse with access token and MQTT broker credentials. From firmware
+        r202639 the broker password and passphrase are ``None`` when the panel
+        cannot read its passphrase; the access token is still valid.
 
     Raises:
         SpanPanelAuthError: Invalid passphrase or auth failure
+        SpanPanelPassphraseUnavailableError: The panel cannot read its own passphrase
+        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
         SpanPanelTimeoutError: Request timed out
         SpanPanelAPIError: Unexpected response
@@ -267,6 +301,29 @@ async def register_v2(
         json=payload,
     )
 
+    sent = () if passphrase is None else (passphrase,)
+
+    if reply.status_code >= 500:
+        # From r202639 the panel answers 503 until it knows its own serial
+        # number, which is a panel still starting rather than a refusal. The
+        # same class `get_homie_schema` raises for a booting panel, so one retry
+        # clause covers both.
+        _log_auth_failure(reply.endpoint, reply.response, sent)
+        raise SpanPanelServerError(
+            f"Panel not ready: HTTP {reply.status_code} from /api/v2/auth/register",
+            status_code=reply.status_code,
+        )
+
+    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,
+        # and telling a user theirs is wrong would be false.
+        _log_auth_failure(reply.endpoint, reply.response, sent)
+        raise SpanPanelPassphraseUnavailableError(
+            f"Panel cannot register clients: {REGISTRATION_UNAVAILABLE_DETAIL} (HTTP 422)",
+            status_code=reply.status_code,
+        )
+
     if reply.status_code in (401, 403, 422):
         # Status only, matching the shape the branch below already uses. The body
         # is logged at DEBUG instead: a 422 from the panel's validation layer
@@ -276,39 +333,40 @@ async def register_v2(
         # passphrase goes with it because this is the one place in the library
         # that knows what was sent, and the panel is under no obligation to
         # quote it back under a key that names it.
-        _log_auth_failure(reply.endpoint, reply.response, () if passphrase is None else (passphrase,))
+        _log_auth_failure(reply.endpoint, reply.response, sent)
         raise SpanPanelAuthError(f"Authentication failed (HTTP {reply.status_code})")
 
     if reply.status_code != 200:
         raise SpanPanelAPIError(f"Unexpected response from /api/v2/auth/register: HTTP {reply.status_code}")
 
+    # The two credentials are not required: from r202639 the panel sends them
+    # as null, or may omit them, when it cannot read its passphrase, and the
+    # access token beside them is still good. Both read as None either way.
     data = reply.json_object(
         "accessToken",
         "tokenType",
         "iatMs",
         "ebusBrokerUsername",
-        "ebusBrokerPassword",
         "ebusBrokerHost",
         "ebusBrokerMqttsPort",
         "ebusBrokerWsPort",
         "ebusBrokerWssPort",
         "hostname",
         "serialNumber",
-        "hopPassphrase",
     )
     return V2AuthResponse(
         access_token=_str(data["accessToken"]),
         token_type=_str(data["tokenType"]),
         iat_ms=_int(data["iatMs"]),
         ebus_broker_username=_str(data["ebusBrokerUsername"]),
-        ebus_broker_password=_str(data["ebusBrokerPassword"]),
+        ebus_broker_password=_optional_str(data.get("ebusBrokerPassword")),
         ebus_broker_host=_str(data["ebusBrokerHost"]),
         ebus_broker_mqtts_port=_int(data["ebusBrokerMqttsPort"]),
         ebus_broker_ws_port=_int(data["ebusBrokerWsPort"]),
         ebus_broker_wss_port=_int(data["ebusBrokerWssPort"]),
         hostname=_str(data["hostname"]),
         serial_number=_str(data["serialNumber"]),
-        hop_passphrase=_str(data["hopPassphrase"]),
+        hop_passphrase=_optional_str(data.get("hopPassphrase")),
     )
 
 

{span_panel_api-3.5.0 → span_panel_api-3.6.1b1}/src/span_panel_api/exceptions.py

@@ -68,6 +68,22 @@ class SpanPanelServerError(SpanPanelAPIError):
     """
 
 
+class SpanPanelPassphraseUnavailableError(SpanPanelAPIError):
+    """The panel cannot read its own passphrase, so it cannot issue broker credentials.
+
+    A fault on the panel, not a rejected credential, which is why this is not a
+    `SpanPanelAuthError`: a caller that maps that class to "wrong passphrase"
+    would send the user back to retype one that may well be correct.
+
+    Raised in two places. ``register_v2`` raises it for the 422 a panel answers
+    when registration needs the passphrase and the panel cannot read it.
+    ``create_span_client`` raises it when registration succeeded but returned no
+    broker password, which from firmware r202639 is how a panel in the same
+    state answers a registration it can otherwise complete; connecting to the
+    broker without a password could only fail later and less clearly.
+    """
+
+
 class SpanPanelCAChangedError(SpanPanelError):
     """The panel is presenting a certificate chain from a different CA than the pin.
 

{span_panel_api-3.5.0 → span_panel_api-3.6.1b1}/src/span_panel_api/factory.py

@@ -15,7 +15,7 @@ from .adapters import resolve_adapter
 from .auth import get_homie_schema, register_v2
 from .detection import detect_api_version
 from .dispatch import select_adapter_key
-from .exceptions import SpanPanelAuthError
+from .exceptions import SpanPanelAuthError, SpanPanelPassphraseUnavailableError
 from .mqtt.client import SpanMqttClient
 from .mqtt.models import MqttClientConfig
 
@@ -77,6 +77,10 @@ async def create_span_client(
     Raises:
         SpanPanelAuthError: Neither mqtt_config nor passphrase provided,
             or serial_number could not be determined.
+        SpanPanelPassphraseUnavailableError: Registration was attempted and the panel
+            cannot read its own passphrase, so it issued no broker password.
+        SpanPanelServerError: Registration was attempted and the panel is not ready
+            to register clients yet; retryable.
         SpanPanelConnectionError: Cannot reach panel during detection or registration.
         SpanPanelTimeoutError: Timeout during detection or registration.
         SpanPanelSchemaVersionError: The panel reports a data-model-version whose
@@ -90,6 +94,11 @@ async def create_span_client(
         auth_response = await register_v2(
             host, _V2_CLIENT_NAME, passphrase, port=port, httpx_client=httpx_client, ssl_context=ssl_context
         )
+        if auth_response.ebus_broker_password is None:
+            raise SpanPanelPassphraseUnavailableError(
+                "Panel registration returned no MQTT broker password because the panel cannot read "
+                "its passphrase; the broker cannot be reached until that is resolved"
+            )
         mqtt_config = MqttClientConfig(
             broker_host=auth_response.ebus_broker_host,
             username=auth_response.ebus_broker_username,

{span_panel_api-3.5.0 → span_panel_api-3.6.1b1}/src/span_panel_api/models.py

@@ -74,11 +74,25 @@ class SpanCircuitSnapshot:
 
 @dataclass(frozen=True, slots=True)
 class SpanPVSnapshot:
-    """PV inverter metadata — populated only when a PV node is commissioned."""
+    """One PV inverter's metadata, populated only when a PV device is commissioned.
+
+    A panel may commission more than one inverter, and from firmware r202639 each
+    is published as its own device. `SpanPanelSnapshot.pv_inverters` carries all
+    of them; `SpanPanelSnapshot.pv` is the lone inverter, or describes several
+    together, as that field documents.
+    """
 
     vendor_name: str | None = None  # pv/vendor-name
     model: str | None = None  # human designation (v1.0 info/model; flat pv/product-name)
-    nameplate_capacity_w: float | None = None  # pv/nameplate-capacity (W)
+    nameplate_capacity_w: float | None = None
+    """The PV array's DC size as recorded at installation, in watts. Informational.
+
+    v1.0 `info/nominal-power`; flat `pv/nameplate-capacity`. A figure entered at
+    commissioning, never a measured or enforced limit: the inverter can produce
+    more or less than this, so a consumer must not treat it as a ceiling on PV
+    power or clamp a reading to it.
+    """
+
     feed_circuit_id: str | None = None  # pv/feed (normalized circuit ID)
     relative_position: str | None = None  # pv/relative-position (IN_PANEL | UPSTREAM | DOWNSTREAM)
     software_version: str | None = None
@@ -104,6 +118,36 @@ class SpanPVSnapshot:
     it does not know) and is deliberately distinct from `False`. The enum has
     three members, `OK,LOST,DEGRADED`, and no UNKNOWN, so absence is the only
     way to say it.
+
+    On a `pv` that describes several inverters together, `None` also means no
+    link is reported down and not every one is reported up, so it is never
+    `True` while any inverter's link is unreported; see `SpanPanelSnapshot.pv`.
+    """
+
+    serial_number: str | None = None
+    """`info/serial-number`, v1.0 only. Frequently unpublished, and that is normal.
+
+    An inverter's serial is often not recorded at commissioning, so `None` is
+    the ordinary case rather than a fault. Shown on a device card, never used as
+    an identity: see `node_id`.
+    """
+
+    device_id: str | None = None
+    """The inverter's id on the wire: the v1.0 device id, or the flat node id.
+
+    For addressing and diagnostics, never for identity. On a panel with more
+    than one inverter every PV device id changes at firmware r202639, the one
+    published before included.
+    """
+
+    node_id: str | None = None
+    """This inverter's key in `SpanPanelSnapshot.pv_inverters`; `None` on the empty snapshot.
+
+    Named after `SpanEvseSnapshot.node_id`, which plays the same role for
+    chargers. It is the feeding circuit's id when a circuit feeds the inverter,
+    because that id stays put when the inverter's own device id changes, and
+    `device_id` otherwise. `None` also on a `pv` that describes several
+    inverters together.
     """
 
 
@@ -310,7 +354,13 @@ class SpanEvseSnapshot:
 
     `None` means the charger declares no such property — `charge-limit.md` reads
     that as "no adjustable charge-current ceiling; it charges at a fixed rate" —
-    or that it has not published a value yet.
+    or that it has not published a value yet, or, from firmware r202639, that
+    no user has set a limit. That release publishes a value only once a user
+    sets one, leaving `charge_current_ceiling_a` as the limit in force; earlier
+    releases filled it with the ceiling on their own, and that retained value
+    can outlive the upgrade. A value equal to the ceiling therefore means the
+    same as `None`. Read `effective_charge_current_limit_a` for the limit the
+    charger is actually applying.
 
     **Not `advertised_current_a`.** That is the current actually being offered
     to the vehicle, which the capability defines as the `min()` of this, the
@@ -360,6 +410,20 @@ class SpanEvseSnapshot:
     cases.
     """
 
+    @property
+    def effective_charge_current_limit_a(self) -> int | None:
+        """The charge-current limit in force, in amps: the user's, else the ceiling.
+
+        `charge_current_limit_a` when one is published, otherwise
+        `charge_current_ceiling_a`, which is the limit from r202639 whenever no
+        user has set one. A stale retained limit equal to the ceiling resolves
+        to the same number either way, so no special case is needed for it.
+        `None` only when neither half is published.
+        """
+        if self.charge_current_limit_a is not None:
+            return self.charge_current_limit_a
+        return self.charge_current_ceiling_a
+
 
 @dataclass(frozen=True, slots=True)
 class SpanBatterySnapshot:
@@ -379,23 +443,24 @@ class SpanBatterySnapshot:
     nameplate_capacity_kwh: float | None = None  # bess/nameplate-capacity (kWh)
     connected: bool | None = None  # bess/connected
 
-    # The BESS's own `meter/active-power`, v1.0 only. **Charge-positive**, which
-    # is a sign flip away from the wire: the enclosure meters the BESS the way it
-    # meters a circuit, so a charging battery reads negative there and positive
-    # here, exactly as `SpanCircuitSnapshot.instant_power_w` reports a load's
-    # consumption positive. The snapshot's rule across every power field is that
+    # The BESS's own `meter/active-power`, v1.0 only. **Discharge-positive**:
     # positive means power flowing *out of* the battery, which is discharging.
     # That is the frame the eBus specification asks of a device's own meter, and
-    # it is deliberately NOT the into-the-device rule the circuit fields follow:
-    # the wire input is in the opposite frame, so one negation lands here rather
-    # than there. Measured against a producer in self-consumption with the grid
-    # at zero, where the direction cannot be argued.
+    # it is deliberately NOT the into-the-device rule
+    # `SpanCircuitSnapshot.instant_power_w` follows. Measured against a producer
+    # in self-consumption with the grid at zero, where the direction cannot be
+    # argued.
+    #
+    # The wire frame changed under this field at firmware r202639: earlier
+    # releases publish the BESS meter charge-positive and the adapter negates it;
+    # r202639 and later publish it discharge-positive and it passes through. The
+    # field's own convention is the same on both.
     #
     # Distinct from `SpanPanelSnapshot.power_flow_battery`, which is the
     # enclosure's own arbitrated flow figure, passed through untouched and
     # charge-positive. The two describe the same physical power in opposite
     # frames, so a consumer rendering both must negate one of them; this one is
-    # already negated.
+    # already in the discharge-positive frame.
     power_w: float | None = None  # v2: bess meter/active-power (W), discharge-positive
 
     # `status/communication-state`, v1.0 only: the BESS publisher's report of its
@@ -513,20 +578,27 @@ class DiscoveredMetadata(FieldMetadata):
 
 @dataclass(frozen=True, slots=True)
 class V2AuthResponse:
-    """Response from POST /api/v2/auth/register."""
+    """Response from POST /api/v2/auth/register.
+
+    ``ebus_broker_password`` and ``hop_passphrase`` are ``None`` when the panel
+    could not read its passphrase. From firmware r202639 that no longer fails
+    the registration: the access token is still issued and REST calls work, but
+    there is no broker password to connect with. Earlier firmware always
+    supplied both.
+    """
 
     access_token: str
     token_type: str
     iat_ms: int
     ebus_broker_username: str
-    ebus_broker_password: str  # Use this for MQTT, NOT hop_passphrase
+    ebus_broker_password: str | None  # Use this for MQTT, NOT hop_passphrase
     ebus_broker_host: str
     ebus_broker_mqtts_port: int
     ebus_broker_ws_port: int
     ebus_broker_wss_port: int
     hostname: str
     serial_number: str
-    hop_passphrase: str  # For REST auth; currently the same value as ebus_broker_password
+    hop_passphrase: str | None  # For REST auth; currently the same value as ebus_broker_password
 
 
 @dataclass(frozen=True, slots=True)
@@ -893,6 +965,10 @@ class ExtensionSubject:
     The EVSE's `node_id` and the circuit's `circuit_id` -- the same keys
     `snapshot.evse` and `snapshot.circuits` use, so a consumer holding the
     snapshot resolves the subject with a lookup it already performs.
+
+    `pv` is a singleton while the panel publishes one inverter. With more than
+    one, each inverter's subject carries its `SpanPVSnapshot.node_id`, the key
+    `snapshot.pv_inverters` uses.
     """
 
 
@@ -1112,6 +1188,26 @@ class SpanPanelSnapshot:
     circuits: dict[str, SpanCircuitSnapshot] = field(default_factory=dict)
     battery: SpanBatterySnapshot = field(default_factory=SpanBatterySnapshot)
     pv: SpanPVSnapshot = field(default_factory=SpanPVSnapshot)
+    """The lone PV inverter, or the inverters together; the empty snapshot when none is commissioned.
+
+    With one inverter it is that inverter, identical to its `pv_inverters` entry. With several it describes them together
+    and identifies none of them: vendor and model where every inverter shares one, the sum of their installed DC sizes where
+    every inverter publishes one, and their link down if any is reported down, up if every one is reported up, unknown
+    otherwise. It never carries an inverter's device id, key, serial, firmware, feeding circuit or position. A consumer that
+    needs one inverter reads `pv_inverters`.
+    """
+    pv_inverters: dict[str, SpanPVSnapshot] = field(default_factory=dict)
+    """Every commissioned PV inverter, keyed by `SpanPVSnapshot.node_id`.
+
+    The key is the feeding circuit's id where a circuit feeds the inverter, and
+    the inverter's own device id otherwise. Preferring the circuit keeps the key
+    still across firmware r202639, which changes every PV device id on a panel
+    with more than one inverter but leaves circuit ids alone.
+
+    Empty when no inverter is commissioned, and from an adapter that predates
+    the field; a consumer falls back to `pv` in that case. A defaulted snapshot
+    field for the reason `adopted_devices` gives.
+    """
     evse: dict[str, SpanEvseSnapshot] = field(default_factory=dict)  # keyed by serial (see SpanEvseSnapshot.node_id)
     mid: SpanMidSnapshot | None = None
     """The islanding authority, when the panel publishes one. v1.0 only.