Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

span-panel-api-schema-1

The parent/child schema parser for span-panel-api: the multi-device Homie tree published by SPAN firmware r202633+, which reports data-model-version 1.x.

Why this is a separate distribution

span-panel-api is a transport and a dispatcher. It knows how to connect to a panel's MQTT broker, route messages, and choose a parser — but it contains no parsing code. Each wire format ships as its own distribution and registers itself under the span_panel_api.schema_adapters entry-point group, so the bootstrap never imports this package until a panel asks for it by name.

The split matters more here than anywhere else in the workspace: this parser depends on the eBus SDK to turn the tree back into devices, and that dependency is this distribution's alone. A flat-panel install never pulls it in.

Installation

pip install "span-panel-api[schema-1]"

Installing this package is what makes parent/child panels work. span-panel-api on its own will connect and then raise SpanPanelAdapterMissingError naming the adapter it could not find.

A consumer that wants to support panels on either schema installs both adapters, and dispatch happens at runtime, per panel, from the data-model-version the panel reports:

pip install "span-panel-api[schema-0,schema-1]"

What it parses

SchemaOneAdapter maps the device tree onto the same SpanPanelSnapshot the flat adapter produces — circuits, both lugs devices, the BESS, PV and EVSE — plus the surface that only exists under the parent/child model:

  • The MID (SpanPanelSnapshot.mid). The enclosure model puts the grid capability on a Microgrid Interconnect Device rather than on the enclosure, so islanding state, grid state and the grid-forming entity live there.
  • Adopted devices (SpanPanelSnapshot.adopted_devices). A device type this parser models nothing for is reported whole — identity and readings — rather than dropped. The schema is explicitly vendor-extensible, so an unmodelled device is an expected arrival rather than a hypothetical one.
  • Extension properties (SpanPanelSnapshot.extension_properties). A vendor property on a device this parser does model, carried with its value and the snapshot subject it hangs off.
  • Meters outside the panel (SpanCircuitSnapshot.measures_outside_panel). A circuit device that declares no breaker space is reported as a meter with no relay, breaker or shed priority, its power import-positive.
  • The masked device tree (SchemaOneAdapter.export_masked_tree()). The tree the adapter holds with serials, device ids and site details masked, which SpanMqttClient.masked_tree() returns for a consumer's diagnostics.

Devices are sorted by declared device type, never by device id. Field metadata comes from each device's own $description rather than from a schema document, because the same capability exposes different properties on different device classes — meter is voltage on the panel, power and energy on a circuit, and both currents on the lugs.

ControllerRoutes is how the eBus SDK reaches the panel without opening its own connection: it is an ebus_sdk.MqttControllerTransport that records Controller's subscriptions instead of making them, so a single wildcard subscription owned by span-panel-api's transport covers the whole tree and each message is routed to whichever SDK callback asked for it.

Conformance

spec_lock.json ships with the package and is this parser's declaration as a consumer: the firmware range it reads, the eBus specification commit its vocabulary was read from, and the version of every capability, device and registry it implements. The capability catalogs it addresses are byte-copied into the repository under spec/, and the repository checks them against the copies the eBus emitter carries in its own wheel.

Those copies exist to be checked against, never parsed in production — units and datatypes come from each device's $description, since a catalog is the superset across all hardware rather than a statement about the panel in front of you. The suite asks the consumer's question rather than the publisher's: is every name this adapter reads one the specification defines? A consumer addressing a name that no longer exists does not fail loudly, it goes quiet — the property never arrives, metadata lookup returns None, and an entity disappears.

Reference payload

span_panel_api_schema_1/reference/parent_child_tree.json ships in this wheel: a retained-topic capture of a full 40-space parent/child panel — 14 devices, {device_id: {topic: payload}}, every value a string exactly as a broker retains it.

Test-support data, and no runtime path reads it. It ships so a downstream test suite pinned to a version of this adapter replays the bytes that version was built and tested against, out of its own site-packages:

from importlib.resources import files
import json

tree = json.loads((files("span_panel_api_schema_1") / "reference" / "parent_child_tree.json").read_text(encoding="utf-8"))

Vendoring a copy instead means also maintaining a guard to keep the copy honest, which is what this replaces. It was package data until 1.1.0, a fixture of the repository's test suite for 1.1.2, and package data again from 1.1.3 — for the cost, not for the principle: no runtime path has ever read it.

The bytes are produced by ebus-panel-sim, pinned in the repository's dev dependencies, and the repository's suite regenerates the capture in-process on every run and compares it, so a tree the pinned producer does not reproduce is a test failure rather than a claim in a document.

Metadata

Release files for span-panel-api-schema-1 1.5.0b1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for span-panel-api-schema-1 1.5.0b1
File Size Uploaded Provenance Actions
span_panel_api_schema_1-1.5.0b1.tar.gz 121.4 kB With provenance Details for span_panel_api_schema_1-1.5.0b1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for span-panel-api-schema-1 1.5.0b1
File Interpreter ABI Platform Actions
span_panel_api_schema_1-1.5.0b1-py3-none-any.whl Python 3 none any Details for span_panel_api_schema_1-1.5.0b1-py3-none-any.whl

Total release size: 231.9 kB

Release files / span_panel_api_schema_1-1.5.0b1.tar.gz

Download URL span_panel_api_schema_1-1.5.0b1.tar.gz
Size 121.4 kB
Tags Source
SHA-256 checksum
How to use checksums
4fe479009278eb1a703b2f327dfab56c728c87a7404af5a35551936e4e7a73b8
BLAKE2b-256 checksum
How to use checksums
b14558c719ee84ff482afe81ee6cd8fb33f3fa0e64e0eb9c643836cf61ad751b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Release files / span_panel_api_schema_1-1.5.0b1-py3-none-any.whl

Download URL span_panel_api_schema_1-1.5.0b1-py3-none-any.whl
Size 110.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0d982097bf46ab36aa7337aa2bcd14e7da1657427608d09e6a55b5f3e0212c4a
BLAKE2b-256 checksum
How to use checksums
7a13e6a66518bbc2d678faab35ad74e323fd8f5fc62ff1c0d0a3743f292573f1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Security for span-panel-api-schema-1 1.5.0b1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for span_panel_api_schema_1-1.5.0b1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page