Migration Guide: v1 dsmState to v2 dominant-power-source #8

a bit more for the brain pan...

Additional Open Questions

1. Firmware reclaim behavior: After a user/automation /sets DPS, does
   firmware reclaim it when BESS comms are restored? Or is the /set latched
   until explicitly changed back? This determines whether /set is a momentary
   nudge or a persistent override.

2. Panel-independent grid detection: Does the panel use any of its own
   measurements (power-flows/grid, lugs-upstream/active-power, voltage) to
   independently determine grid status, or does it rely entirely on BESS for
   grid-up/grid-down awareness?

3. DPS update source: Is DPS always computed from BESS reporting, or are
   there other inputs (e.g., voltage collapse detection, ATS position sensing)?

4. Generator interaction: On 32-tab panels where generator feeds through the
   same lugs as grid, does DPS=GENERATOR exist in firmware today or is it
   reserved for future use? How would the panel distinguish utility from
   generator?

Stale DPS Scenario Matrix

The core problem: the panel depends on BESS for grid state awareness. When BESS
comms are lost, DPS is stale. Our dsm_state sensor addresses this by combining
bess/grid-state, dominant-power-source, power-flows/grid, and
lugs-upstream/active-power — signals the panel has but doesn't use for DPS
computation. The scenarios below show where this combined signal detects what DPS
alone cannot.

DPS /set Safety by Direction

Not all /set directions carry equal user risk. Shedding unnecessarily is annoying;
failing to shed during an outage means unmanaged battery drain which in some cases
could affect life support so it's worth being proactive.

This is too much information for even a savvy DIY so local automation
might be appropriate.

@cayossarian

Thanks for the thorough analysis across your comments.
I want to address everything systematically, including a few items from your earlier posts that I hadn't fully responded to yet.

A note on terminology: I'll use DPS as shorthand for the dominant-power-source property throughout this reply.

Important: Scope of SPAN API

Before diving into the technical details, I want to be clear about scope.

The SPAN Panel and its integrated BESS/backup support are designed, engineered, tested, and listed to applicable electrical standards (NEC, UL). Load shedding, grid islanding, and MID management are product-level features operating within that certified framework.

SPAN API provides best-effort visibility into the panel's state and limited, specific control capabilities — it is intended to let clients understand and track the panel's behavior, not to replace or replicate the panel's built-in control logic.

An API client that attempts to implement its own load-shedding decisions, grid-state detection, or other critical automation is operating outside the scope of what SPAN API was designed and engineered for. Such use is entirely at the client developer's and homeowner's own risk and may void the SPAN Panel Limited Warranty. See the SPAN API Scope & Responsibility Model in the SPAN API documentation.

The technical discussion in this thread is provided to help integration developers understand how the panel works — it is not a specification for building critical systems on top of SPAN API.

DPS Hierarchy

You proposed:

1 - Grid / Generator (even if PV sending energy to grid)
2 - Battery when grid down
3 - PV (only if battery missing/depleted and panel can run islanded?)

That's correct. The hierarchy follows the grid-forming entity (GFE): whichever source is forming the electrical grid that the home is synchronized to. When the utility grid is present, it's the GFE regardless of what PV or battery are doing — they're grid-following. When islanded, the BESS inverter becomes the GFE. PV as a DPS value would apply only if a PV inverter were capable of grid-forming in isolation (rare today, though some newer Enphase systems may be heading this direction).

UNKNOWN and Fault States

You asked:

Is there another v2 signal that carries the on-grid/off-grid context during a fault, or is this information genuinely unavailable via eBus?

It's genuinely unavailable via eBus. Both v1 fault states (DSM_FAULTED_ON_GRID, DSM_FAULTED_OFF_GRID) map to UNKNOWN in v2, and no other published property distinguishes them. This is intentional: a fault state reflects a hardware condition (inverter fault, Microgrid Interconnect Device fault) where the panel may not be reliably supplying power in either direction. The on-grid/off-grid distinction during a fault is not actionable — "should I start the generator?" is not a safe automation decision when a hardware fault is active. These situations require physical service intervention.

For automation purposes, treating UNKNOWN as "something is wrong, alert the homeowner" is the appropriate response.

Panel-Independent Grid Detection

You asked whether the panel uses its own measurements to detect grid status, or relies entirely on BESS.

The panel has its own voltage monitoring that independently detects grid loss — voltage drop/sag on the main conductors. This is how the panel can respond immediately to an outage without waiting for the BESS to report it.

However, this monitoring is on the home side of the Microgrid Interconnect Device (MID) — the component within or alongside the BESS that manages grid disconnect/reconnect. That means:

• Grid loss: Detected reliably. When the MID opens during an outage, voltage drops momentarily on the home side until the BESS inverter begins forming the microgrid.
• Grid restoration while islanded: Not detectable. While the MID is open, the home side sees BESS-generated voltage, which is indistinguishable from utility voltage. Grid restoration on the utility side of the open MID is invisible to the panel.

This is the fundamental reason /set exists as a safeguard, and it directly affects your scenario matrix (see below).

Note on terminology: in generator installations, the equivalent component is typically an Automatic Transfer Switch (ATS) or Manual Transfer Switch (MTS) — sometimes called a transfer-switch — which is external to both SPAN and the generator. I'll use "MID" when discussing BESS configurations and "transfer-switch" for generator contexts.

DPS Update Source

DPS is determined from multiple inputs:

• The BESS (grid state reporting, authoritative when communicating)
• The panel's own voltage monitoring (detects grid loss independently)

It's not entirely BESS-dependent for detecting outages, but for detecting grid restoration while islanded, the BESS is the only source.

Firmware Reclaim After /set

I've confirmed the behavior. The panel's internal state is event-driven — when you /set DPS, the panel transitions its grid state accordingly. When the BESS reconnects and reasserts its authoritative grid state, that produces a new state transition that overrides the previous /set.

The key point: the most recent state transition wins. A user /set is not a persistent latch — it's a temporary override for the BESS-communication-loss window. Once the authoritative source (the BESS) is back, it reclaims control automatically.

One implementation note per the Homie Convention: values published to /set topics must be published non-retained. This is a client-side responsibility — integrations should publish /set commands with retain=false.

Generator Interaction

Per our generator support article, SPAN is always installed downstream of a transfer-switch (ATS or MTS), and "today, there is no communication wiring possible between the SPAN panel and an upstream generator." The panel sees whatever voltage the transfer-switch feeds it — DPS reports GRID when on generator because the panel literally cannot tell the difference. From the same article: "SPAN power flows will present all generator power as coming from the grid during an outage."

GENERATOR as a DPS value is reserved for possible future use — it is not currently active. Distinguishing generator from utility would require either communication with the generator/transfer-switch or a grid-side voltage sensor, neither of which exists in this configuration.

Also worth noting: no automatic load shedding is available with generators — that requires a compatible integrated BESS.

Non-Integrated BESS

One more data point for your configuration matrix. Per our storage integrations article, for non-compatible battery systems: "During an outage, the SPAN Home App will continue to report all energy coming into the home as grid power." This means DPS = GRID even when actually off-grid with a non-integrated BESS — the panel has no communication with the battery system and cannot know it's islanded. No automatic load shedding is available in this configuration.

This underscores the broader point: DPS reflects what the panel knows, which depends on what systems are communicating with it.

Scenario Matrix — Revisions

Your scenario matrix is a valuable framework. However, scenarios 3 and 5 need revision based on the MID topology described above.

When the MID is open (islanded), all published signals measure the home side: lugs-upstream/active-power, power-flows/grid, and voltage measurements all reflect BESS-supplied power. Grid restoration on the utility side of the open MID does not change these readings.

The key insight: scenario 4 self-corrects (the panel detects grid loss independently), but scenarios 3 and 5 do not (the panel cannot detect grid restoration while islanded). Your multi-signal derivation doesn't help for 3 and 5 because the signals themselves are measuring the home side of the open MID.

Where Your Multi-Signal Approach Does Help

Your integration's combined signal approach (bess/grid-state + DPS + power-flows/grid + lugs-upstream/active-power) adds genuine value for:

• Transient inconsistencies during normal BESS communication
• Scenario 4 (grid drops while on-grid with BESS comms already lost — MID still closed, power measurements reflect reality)
• Defense-in-depth for edge cases not yet enumerated

But for the core stale-DPS scenarios (3 and 5 — grid restored while islanded, BESS comms lost, MID open) — passive signals cannot help. /set is the only path.

/set Risk by Direction

Your risk analysis on the asymmetry of /set directions is a useful framework. To restate it with the scope caveat at the top of this reply in mind:

• GRID → BATTERY (start shedding): The more conservative direction — worst case is unnecessary shedding, which is disruptive but not harmful.
• BATTERY → GRID (stop shedding): The higher-risk direction — getting this wrong means unmanaged battery drain, and as you correctly noted, this could affect critical equipment. Should require user confirmation or high-confidence corroborating signal.

Configuration Matrix

You and others have asked for a configuration matrix mapping system configurations to expected DPS values. That's a reasonable request — we'll take it under consideration as we continue to develop the API documentation.

Schema Documentation

We agree the $description could better convey the grid-forming-entity semantics — thanks for the suggestion.

Reference Links

• Storage System Integrations with SPAN
• Adding Battery Backup to your SPAN Panel
• Can I install SPAN with a standby generator?

Note: The SPAN eBus/MQTT API discussed in this thread is currently available on the SPAN Panel MAIN 32 model.