v0.2.0 — SPAN firmware r202627 parent/child data model

The 0.2.0 release migrates the integration to the parent/child Homie 5 data model that lands in SPAN firmware r202627. The panel publishes itself as a tree — panel root + per-lug / per-BESS / per-MID / per-PV / per-EVSE / per-circuit child devices — and the integration walks that tree, registering one HA device per Homie device. The old flat data model is gone.

BREAKING — unique-IDs reset. Every entity gets a new unique_id of the form {panel-serial}_{device-id}_{capability}_{property-id} reflecting the new tree shape. No 0.1.x → 0.2.0 translation is provided; old entities surface as unavailable orphans in HA's registry after upgrade. Recommended cleanup is delete + re-add each panel config entry for a clean state. See README §"Upgrading from 0.1.x" for details.

Added

• Tree-walked entity model. Each Homie device becomes its own HA device: panel root + 2 lugs devices (upstream / downstream) + 1 BESS per commissioned battery + 1 MID grandchild per BESS + 1 PV per inverter + 1 EVSE + 1 device per circuit. Per-device entities are scoped to their owning device rather than all hanging off the panel.
• MID (Microgrid Interconnect Device) entities — every commissioned BESS now has a synthesized MID grandchild with vendor / serial / product / model / firmware-version / hardware-version diagnostics plus islanding-state (ON_GRID / OFF_GRID / UNKNOWN), grid-state (UP / DOWN / DEGRADED / UNKNOWN), and grid-forming-entity ("GRID" when grid-tied, the BESS device-id when islanded). Surfaces what's actively forming the grid at any moment, particularly useful during outages.
• Shed forecast (BTR — battery time remaining) entities — total-time-remaining, time-to-priority-shed, plus full-charge variants of both, all in minutes, plus a confidence (LOW/MEDIUM/HIGH) enum. Surfaces SPAN's runtime estimate of how long the panel can sustain its current load on battery.
• Shed override switch — a settable switch on the panel root that forces shed-priority configuration to actually shed. Replaces the settable half of the retired 0.1.x core/dominant-power-source select. The panel firmware silently ignores writes outside the spec-defined preconditions (off-grid + degraded BESS comms).
• Connection capability on lugs and circuits — publishes feeds-device-id / feeds-device-type / feeds-device-status (and fed-by-* on upstream lugs), letting consumers walk the per-circuit DER attribution graph. Replaces the retired 0.1.x bess/feed, bess/relative-position, pv/feed, pv/relative-position, evse/feed entities — derive position from the connection-graph instead.
• PCS capability on the panel root — surfaces 17 entities covering import / feed-import / grid-import / off-grid-import / requested-import limits, their enablement enums, and their active boolean siblings. Joined by the relocated grid-islandable and breaker-rating from the old core node.
• Per-direction lugs entities — upstream lugs and downstream lugs are now distinct HA devices ("c192x Upstream Lugs" / "c192x Downstream Lugs"), each with its own info / meter / connection capability entities. The composite-suffix {serial}_lugs-upstream_imported-energy unique-ID format is replaced by the cleaner per-device shape.
• Auto-refresh of device names. Whenever any device's init→ready edge fires, the integration walks the descendant tree and refreshes HA's device names from the publisher's current values (circuit user-labels in particular). Picks up renames in the SPAN app without a HA restart.
• Auto-derived multi-panel hierarchy. When a panel is fed from an upstream sister panel, the integration reads lugs-up/connection/fed-by-device-id (a SPAN firmware r202627 feature — each panel publishes its upstream-topology pointer on its lugs-up connection capability) and sets via_device on the downstream panel's HA device automatically. Daisy chains render nested under their feeder in Settings → Devices and in Energy Dashboard Sankeys with no user action — replacing the manually-invoked link_subpanel service from 0.1.x. The via_device link re-evaluates on every init→ready cycle, so a publisher-side topology change propagates without a reload.
• Auto-add of late-arriving descendants. Slow boot cascades that deliver a descendant's $state=ready after initial setup completes (observed on heavily-loaded panels with 19+ circuits) are now caught by a post-setup tree-state hook and registered automatically — no manual reload needed.

Changed

• BREAKING — entity unique-ID format — see release header.
• BREAKING — required SPAN firmware — r202627 or later (the release in which the tree data model lands). Earlier firmware publishes the flat data model that this integration version no longer understands. Stay on the 0.1.x line until your panel takes the OTA.
• BREAKING — required ebus-sdk version — ebus-sdk >= 0.3.1 (ships the tree-rooted Controller mode and the description-after-state reconcile fix that this integration's discovery flow depends on).
• Lugs are HA devices now. In 0.1.x, lug entities hung off the panel device with composite unique-IDs ({serial}_lugs-upstream_imported-energy). In 0.2.0 the upstream and downstream lugs each get their own HA device under the panel, with simple property-only entity IDs.
• Site metering is gone as a sub-device. The 0.1.x power-flows sub-device is now a power-flows capability on the panel root device. The four directional entities (pv-power, battery-power, grid-power, site-power) live on the panel device itself.
• Property renames picked up on the wire (publisher dual-name handling means both the legacy and spec names are recognised during the firmware-side rename roll-out window): core/software-version → info/firmware-version, core/door → door/state, status/vendor-cloud → status/cloud-connection, circuit/space → info/tab-number, evse/status → status/operational-state.
• Circuit boolean trio retired. circuit/sheddable and circuit/isNeverBackup are gone (derivable from priority/shed-priority + priority/relay-controllable). circuit/alwaysOn is polarity-flipped to priority/relay-controllable (true = relay can be commanded).
• Energy entity names depend on direction. Upstream lugs use the friendly "Energy" / "Energy Returned" naming (= grid consumption / grid export) per the README convention. Downstream lugs use literal "Imported Energy" / "Exported Energy" since the semantic flips between directions and SPAN doesn't currently populate the downstream side anyway.
• BREAKING — link_subpanel service removed. Replaced by the auto-derived multi-panel hierarchy in the Added section above. Existing users on 0.1.x are unaffected (their installs don't run this code); downgrading-then-upgrading isn't a supported path so there's no migration concern.

Fixed

• Energy counter monotonicity workaround preserved. The total_increasing energy sensors continue to suppress occasional 0.1 Wh decreases from the firmware (AN-001 still applies). Held-value behavior is unchanged from 0.1.x.
• Active-power firmware bug now publisher-fixed in tree-v1. SPAN's r202627 firmware publishes circuit active-power and PV nameplate-capacity in correct units (W rather than the legacy mis-declared kW). The mapper still hard-codes W regardless of what the description says, so a panel that hasn't taken the fix surfaces correctly either way.
• Lugs connection entities create reliably on first setup (SPAN-urn). Previously the lugs connection mapper bailed when its info/direction property hadn't been delivered yet at the moment of initial tree-walk — leaving 8 connection entities silently absent across both lugs devices. Now the mapper falls back to the device-id suffix (-lugs-up / -lugs-dn) when the property isn't loaded yet, so entities create on the first pass regardless of property-arrival timing.
• Late-arriving descendant cascades self-heal. When the SDK delivers a descendant's $state=ready after initial setup has timed out — observed on busy panels where retained-message backlog delays $state arrival — the post-setup tree-state hook re-registers the descendant automatically.
• Circuit renames in the SPAN app propagate to HA device names. Previously the info/name property-update callback called async_get_or_create, which silently ignores the name= kwarg on already-existing devices — so renaming a breaker in the SPAN app updated the entity values but left the HA device label stale. Now the callback routes through async_update_device when the device exists (and respects name_by_user so user-set custom labels stick).

Known issues

• Paho silent subscription dropout on heavily-loaded connections (panels with 19+ circuits) may leave a single descendant — typically a MID — un-discovered, with no error logged. Manual escape hatch: reload the integration config entry, which creates a fresh paho client. Tracked as ebus-sdk SDK-1v0; doesn't affect entity shape, only delivery reliability of retained messages on the first connection.

Compatibility

• Companion tool: hass-atlas needs ≥ commit 2fb80d4 for tree-model support. Earlier versions read the 0.1.x flat shape and degrade silently against 0.2.0.