SPAN API beta officially released.

[sargonas]

As some folks involved in this project may be aware, SPAN has reached out to several of us last week in preparation to announce a new API exactly for our needs rolling out today. Initially the API is only for SPAN 32 via firmware r202603, purely for a logistics reason in that its a minor update to the SPAN 32 software stack on top of what is already there. They have, however, already made a direct commitment to us to add it for all other SPAN panels on the newer stack, by the end of the year (most likely at some points doing H2 2026).

Full details can be found on their blog post here: https://www.span.io/blog/introducing-span-api-and-span-home-on-premise-public-beta

And full API info is here: https://github.com/spanio/SPAN-API-Client-Docs

In short: this means current issues with SPAN 4X support will be resolveable as time goes on, and access to this local api is added to those devices... and a better, well documented and official access is now available for the original 32 devices via firmware r202603 which is in the process of rolling out now, and will be generally available to all by end of month!

However this does mean that all previous undocumented, unsupported SPAN Panel MAIN 32 APIs and local access that we have been relying on up until this point will be deprecated as of December 31, 2026 at the end of year firmware release, so we need to ensure folks are migrated over to the new system by then.

(Along side all of this, it's interesting to note they have also added Span On Premise, a locally run web UI on all devices for home users as well)

[cayossarian]

Also nice to see them address access to SPAN drive, etc which folks were after.

[cayossarian]

Lots of interest in this new API, need to decide how these other efforts overlap. (https://github.com/electrification-bus/span-netbox-importer)

[dcj]

I wrote span-netbox-importer for my own use, IDK how many other folks manage their home networking & computing infrastructure using NetBox, but just-in-case there are any, I shared it...

There is no (or very little) overlap between that and Home Assistant, AFAICT.
My current work to implement a HASS integration using SPAN API is mentioned in a subsequent post.

[dcj]

SPAN API adopts and implements the Electrification Bus (eBus) framework for Home Energy Infrastructure Device integrations.

Electrification Bus GitHub org provides eBus developer resources, python-sdk may be of interest/help.

@sargonas writes:

However this does mean that all previous undocumented, unsupported SPAN Panel MAIN 32 APIs and local access that we have been relying on up until this point will be deprecated as of December 31, 2026 at the end of year firmware release, so we need to ensure folks are migrated over to the new system by then.

I am actively working on a new HASS integration based on eBus and SPAN API, and hope to publish that ASAP, I decided to take a greenfield approach, and IDK if that will end up being good or not-so-good, we shall see. My integration is currently functional, but seems to have a serious memory leak, which I am attempting to debug, even as I write this post.

[dcj]

Announcing an early alpha release of span-hass, a Home Assistant integration for SPAN smart electrical panels, using SPAN API.

Also announcing hass-atlas a command-line tool for auditing and configuring Home Assistant energy dashboards, area assignments, and device topology. Designed as a companion to span-hass (the span_ebus HA integration for SPAN smart panels), but works with other energy integrations — Tesla Powerwall, Enphase, SolarEdge, and more.

[cayossarian]

Well @dcj you've been busy! Currently this repo is the default HAC's SPAN repo and there is an organization that supports it. Essentially we would have done what you have done so we can take this either one of a few ways generally guided by what is good for the community.

Most user's are not going to want to part with their historical data so alignment of the sensor unique keys, entity id's would be necessary to make that a reality. Unique keys, are of course unique so history is tied to those keys.

Aside from that there are some minor outstanding features that others have, over the years, asked for like syncing panel names, etc that would need to be added to any implementation.

My suggestion is to provide a migration and it would seem the best way to do that is to work as a single team with some structure so there is no churn. If you're amenable we could move the repo into this organization and give you admin rights and work so users do not face disruption.

Once we have something suitable and meet the HA requirements move it into core if that seems like something that is appealing. I can tell you from first hand experience that is not without its own headaches but it's an option. You're tied to their processes, oversight, release schedules, etc.

What do you think?

[dcj]

Most user's are not going to want to part with their historical data so alignment of the sensor unique keys, entity id's would be necessary to make that a reality. Unique keys, are of course unique so history is tied to those keys.

This is an important (critical) requirement/constraint that I didn't consider in my new integration, because I haven't been running SpanPanel/span, years ago I wrote an external daemon that polled the "legacy" (now v1) API, published/bridged to MQTT, and then I configred MQTT "things" (IDK the exact/precise HASS terminology) in HASS to pick them up. I could/should have used MQTT Discovery, but I didn't, I had my daemon spiit out the YAML I needed, which I manually added to my HASS configuration.
And then "something broke" and I never got around to fixing it, so it has been 1-2 years since I had any SPAN panel metering data in my HASS, so there is/was no data/history for me to preserve.

I can easily imagine that supporting the same keys/ids is super important.

I'll need to think about that, and explore/investigate/learn more.
Or, most likely, you folks understand this best/completely, and therefore are best suited to designing this transition.
Whatever works!!!
If none of the code Claude & I generated is of any use, so be it, if any of it is useful, then great!

My goal in coding the new integration was to prove to myself that SPAN API was well-suited to this task, and to solve my own need for a new SPAN integration, it is working well for me so far, but it is "early days"....

[cayossarian]

I'm working on an update for the new SPAN API as the firmware is in my 32 panel. This update will put us in good shape for a non-breaking update when the other panels are supported later in the year. The goal is not to break folks existing dashboards and automations lest we hear a deafening roar from the user base.

[sargonas]

FWIW I just got r202603 as well, so I'm free to start hammering at putting it through it's paces when needed on my secondary testing instance.

[dcj]

on my secondary testing instance

Given the potential need for me to better understand how SpanPanel/span works, the keys/ids it generates, I'm thinking I should probably set up another Pi to run HASS, install & configure SpanPanel/span, and poke around.
Does this "just work", or do I need to do anything special to keep a second HASS instance from interfering with my "production" instance? I'll go Internet search for an answer, hoping/guessing this is documented/explained somewhere, but if not, I'd welcome any advice/tips/pointers about how best to do that.

[sargonas]

I've had no issues with "just doing it". I set it up initially as a duplicate LXC container, but eventually moved to the offical Addon that just lets you run a duplicate core on your existing install. The key thing, and what I did, was that I did not mirror my system, I just setup a second fresh vanilla one, and I did not configure or activate any integrations that I did not absolutely need, and it has no automations. The two integrations I dabble with are the only ones enabled, and as a result I've never had any notable conflicts. I do also, just in case, spin it down whenever I am going long stretches of time not needing it and historical data from it wont be of use to me to collect.

…

On Tue, Feb 24, 2026 at 4:36 PM Don Jackson ***@***.***> wrote: on my secondary testing instance Given the potential need for me to better understand how SpanPanel/span <https://github.com/SpanPanel/span> works, the keys/ids it generates, I'm thinking I should probably set up another Pi to run HASS, install & configure SpanPanel/span, and poke around. Does this "just work", or do I need to do anything special to keep a second HASS instance from interfering with my "production" instance? I'll go Internet search for an answer, hoping/guessing this is documented/explained somewhere, but if not, I'd welcome any advice/tips/pointers about how best to do that. — Reply to this email directly, view it on GitHub <#173 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAALDF7N4BYEOEH7EBX4S6D4NTVCRAVCNFSM6AAAAACV5KLQVOVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTKOJRG4ZDEMA> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[cayossarian]

i pushed a branch for the span-panel-api to cover the e-bus API. This package uses a hybrid HA model since a purely push model might challenge any pi hardware and most of the integrations of any size use a hybrid model for this reason. In fact when we were doing the gRPC stuff the team soon figured out that the CPU usage was untenable and went to the hybrid model. I should have a testable span repo within a day or two.

@dcj i will send an org invite. I did some analysis of the feasibility of a clean cutover but it was more work to reimplement all the features and risk to the user base. There is plenty to do at any rate.

[dcj]

@cayossarian wrote:

Just brainstorming for ways to provide integration points with user's other energy systems in HA WRT to our SPAN bits which you seemed to be tangentially associated with.

:-)

This is great feedback, yes I am extremely well-acquainted with the SPAN colleagues that developed the Home On-premise dashboard app, and I'll ensure that receive this...

[cayossarian]

In order to embed the page one would also need a way to auth. In the end we may have to build an actual card for HA but nice design as a staring point, hats off to them!

[dcj]

@cayossarian
Not directly relevant to the above, but here is kind of a user-guide for SPAN Home On-premise

[dcj]

@cayossarian wrote: "In order to embed the page one would also need a way to auth"

What if the panel's HTTP server supported a way to provide the auth credential via a query-parameter?

[cayossarian]

Yes a query parameter should work

[cayossarian]

No extra work, the full set of features that need to be retained will come out in the upgrade plan, which will be in docs/Dev when I push that branch in the next day or so. Right now a lot of this knowledge is just in code or implicit in the README but the upgrade/migration plan will shed a lot of light on how some of this is newly handled in the rework of the coordinator. I would certainly welcome another set of hands and eyes once the initial standing straw man is out.

As with any software the migration path is some of the hardest to get right and downstream we could definitely work to retire some of this technical debt of migration by forcing folks to upgrade in a precise order, e.g. 1.1.x - 1.2.x - 1.3.x. The first step will strip out a lot the prior migration logic. A lot of folks who would not have upgraded will be forced to upgrade once SPAN retires the old API which for our purposes is gold. Gold because we get a forced diet but also get some new features like native solar sensors, SPAN drive, etc.

[Griswoldlabs]

Great to see official API support rolling out for the MAIN 32. This is a big step forward.

For anyone working on the migration or integration updates — happy to help where needed. I built the Gen3 gRPC integration (PR #171) and have been deep in the span-panel-api library, so I'm familiar with both the old and new transport layers.

On the Gen3 side (MAIN 40 / MLO 48), PR #171 is still open for anyone on pre-7.2.0 firmware. For everyone else, we'll be waiting on the H2 2026 official API rollout for those models. If there's anything I can contribute in the meantime, just tag me.

[cayossarian]

Do you have a 32 panel as well? Anyway if not you can take a look at the span-panel-api code if you like.

I'm just releasing to get a span beta up so those with a 32 can test it but any input on the code would be appreciated. It works but no upgrade testing has been done yet (that's always a chore). All my typing is strict and it's enforced as you likely noticed.

After we get this beta up and we are more or less comfortable I'll do my best not to simply merge without sign off from somebody...lone ranger needs company :-)

[cayossarian]

32 panel first INTERNAL beta - no upgrade testing, this is Wilbur Wright's first flight and I know of a few issues I need to address on the upgrade side so do not install this over any production stuff. I'll test the upgrade path tomorrow. There is a setting for update interval, it runs fine on my hardware at the default 1 second (0 is complete push) but a pi would need something higher.

https://github.com/SpanPanel/span/releases/tag/v2.0.0b1

[cayossarian]

Pushed beta v2.0.0b2 with inverted solar fix.

@sargonas, @dcj, @pavandave or other folks with batteries and the new 32 panel software, I don't have a battery integrated with SPAN or this data in order to see the BESS data in MQTT. If someone can check, provide the topics/data or screenshots of MQTT Explorer we can add those as sensors.

There's a battery power sensor already working and also panel SOC but don't know if the energy values are also provided in the data. If someone wants to add them to the ebus_integration branch using the same pattern for pv that's fine or just share the data with me.

[dcj]

Note that the endpoint api/v2/homie/schema provides the complete superset Homie schema, which is useful for purposes like this.

[dcj]

Also, consider taking a gander at https://github.com/electrification-bus/hass-atlas, it knows how to work around and configure things for the HA Energy Dashboard, based on how my proof-of-concept integration works, but YMMV

[cayossarian]

ah yes, duh

[sargonas]

Dont have batteries but can otherwise test as usual, however I made a right mess of my testing instance for reasons unrelated to this project while trying to dust it off and get it ready for testing. Working on fixing that now but not physically at my primary home so have to remote tweak some of my homelab to get it back up. Once the instance is happily chugging along again as as econdary HA instance, I can finall pull down these changes and put them through their paces!

[dcj]

@cayossarian et. al.
Let's discuss how this integration is going to deal with changes to SPAN API, breaking, and non-breaking.
I am happy to discuss that here, or to start a new Discussion topic focused on that topic, you decide, and I will follow your lead.

• I imagine that non-breaking changes will not be a huge problem! :-). E.g. if some new functionality is supported, this integration will unlikely to be able to take advantage or support those features until it is updated to do so, but that is life.
• Obviously breaking changes are the primary concern, for example, in the next release (r202609) of the MAIN 32 firmware, I have it on good authority that the following two issues will be fixed: [Docs]: model value string in mDNS _device-info._tcp advertisement is incorrect spanio/SPAN-API-Client-Docs#4 [Docs]: Potentially incorrect units in the Homie $description spanio/SPAN-API-Client-Docs#2

As mentioned in SPAN-API-Client-Docs README, there may well be signficiant and breaking changes to the panel's Homie device/node data-model, for example many of the existing nodes may become child devices of the panel, and nodes become "capabilties" (for example, energy-metering). These changes are not going to happen right away, but they are contemplated, and in my personal opinion, more likely than not. SPAN (and I) will attempt to provide advanced notice of any such breaking change, but as noted in the API README, ATM (certainly within the beta period) there are no such guarantees.

Two "tools" that clients currently have at their disposal:

1. The panel's firmware version is available several ways: via mDNS device-info metadata advertisement, via api/v2/homie/schema, and via the software-version property within the core node.
2. The response to api/v2/homie/schema includes the superset schema of the API as of the specified firmware release. A client could have a prior copy of that, and verify/test/compare that the panel to which is is talking reports the same, or compatible schema.

I welcome comments, feedback, suggestions, and proposals for how best to manage changes in SPAN API over time.

[cayossarian]

yes, let's start a new discussion. In general I will say that the span-panel-api abstracts the SPAN api away from the integration and that's why HA in large part requires this model. While we had to adapt the integration to accommodate the push/publish changes that change was likely the largest change and of course sensors come and go. But yeah, let's noodle it, thanks for bring up the topic!

[cayossarian]

I am just about ready to publish this release. Haven't heard any feedback on those that might be running a version, if any. The latest pre-release is 2.0.1RC1.

While I have done my own upgrade testing on a test instance it would be really nice if someone else could verify as well. I don't have a battery but I tested with a simulator for battery and SPAN drive. The simulator is never going to be the real deal but at least it helps test another configuration. No huge key issues this time or at least that's the theory.

If you don't have time or resources I get that and I always warn people to make a backup but folks would rather just push a button and walk away, me included!

[sargonas]

Apologies! I’ve been meaning to try to test more of this for you but it’s been hard because I’ve been at my second home in Los Angeles, and without physical access to some of my hardware it’s been a bit harder to do some of the testing safely without risking sending my whole home automation sideways 250 miles away! However Friday night I’m flying back to my house for two days before going on a work trip and I’m going to try to test all this then if it’s not too late!

…

On Wed, Mar 4, 2026 at 22:48 Bill Flood ***@***.***> wrote: I am just about ready to publish this release. Haven't heard any feedback on those that might be running a version, if any. The latest pre-release is 2.0.1RC1 <https://github.com/SpanPanel/span/releases/tag/v2.0.1RC1>. While I have done my own upgrade testing on a test instance it would be really nice if someone else could verify as well. I don't have a battery but I tested with a simulator for battery and SPAN drive. The simulator is never going to be the real deal but at least it helps test another configuration. No huge key issues this time or at least that's the theory. If you don't have time or resources I get that and I always warn people to make a backup but folks would rather just push a button and walk away, me included! — Reply to this email directly, view it on GitHub <#173 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAALDF2ZPPJY5LD57FWS2X34PEPL3AVCNFSM6AAAAACV5KLQVOVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTMMBQGYYTONY> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[cayossarian]

Perfect, thanks! I made some minor tweaks 2.0.1RC2

The release has passed all the CI so if you test it and we don't get any negative or other feedback you can just merge it into main.

Once you do that I can push a release.

I tested the grace period again through the simulation and it works as before, I know that's your baby. The readme and the change log have the extensive changes. I think folks will be excited with some of the new features.