EverSolar: several inverters on one bus, as eversolar-monitor already does

[Timdebruijn]

Follow-up to #63, which fixed the dishonest flag (a second device is now refused cleanly instead of knocking out the first). This is the feature that refusal is standing in for.

Why this matters more than an average enhancement

Anyone migrating from eversolar-monitor already has several inverters on one RS485 loop, served by one machine. That is not an exotic setup — it is what the reference implementation does by default, and this project's own protocol document says so:

The reference repeats steps 2-4 every minute to find new inverters (:1037-1040)

— docs/eversolar-protocol.md

So for that user Heliograph is not "missing a nice-to-have", it is a regression against the tool they are leaving. One bridge per inverter works today and is a reasonable interim answer, but it is extra hardware to do something their old setup did with none.

What the protocol already gives us

Everything needed is documented and partly implemented:

• Addresses are assigned by the PMU, incrementing from 0x10 (START_INVERTER_ADDRESS). Not fixed slave addresses — the address is the result of registration.
• A registered inverter ignores further broadcast offline queries, so the next unregistered one answers. That is the enumeration mechanism, and it needs no arbitration.
• All four registration steps are read-only; nothing is configured in the inverter except a volatile bus address it forgets on power loss.

The three obstacles (from #63)

1. registerDevice() runs the enumeration loop exactly once. Nothing repeats it, so a second inverter is never discovered.
2. No address option, and assignedAddress is never set. Compare solax_driver.cpp, which reads its "address" option into exactly this field.
3. begin() broadcasts RE_REGISTER unconditionally, telling every inverter on the line to forget its address.

The design question worth settling first

The reference sends RE_REGISTER once at startup and then repeats steps 2-4 forever. That shape does not map onto this project's device model, where one driver instance serves one device and is constructed from one config entry. Two candidate shapes:

• A bus owner. One EverSolar driver instance owns the line, enumerates, and yields N devices. Matches the protocol and the reference exactly. Needs the device layer to accept one driver producing several devices, which nothing supports today.
• Cooperating instances. Each config entry gets its own address option; only the first instance may send RE_REGISTER. Fits the current model with no framework change, but the "only the first" rule is a coordination problem between instances that are meant to be independent — and getting it wrong de-registers a working inverter.

The first is the honest one. The second is cheaper and would probably work. Worth deciding deliberately rather than discovering by implementation.

Verification: this one really does need hardware

Two inverters on one bus, because the interesting behaviour only exists with two:

• Both answer the first broadcast offline query — on half duplex. Does that collide, and does it converge?
• Does the first inverter reliably stay silent for the second query once registered?
• Does a power cycle of one inverter re-register only that one?
• Does the periodic re-enumeration disturb a device that is already polling happily?

A fake second device in test/support/fake_eversolar_device.h can cover the loop and — the property that matters most — assert that discovering a second inverter does not de-register the first. That is host-testable and worth having regardless. It cannot answer the half-duplex collision question.

Interim answer for anyone who lands here

One bridge per inverter works today, and is not a bad arrangement: AA55 has one master per line, so each ESP owns its own bus and the inverters appear as separate devices in Home Assistant. It costs an extra board per inverter.

Related

• EverSolar: supportsMultipleDevices is true, but a second inverter cannot work (and would break the first) #63 — the flag over-promised; now refuses cleanly (option 1 of three)
• docs/eversolar-protocol.md — the registration sequence and addressing

[Timdebruijn]

Read the reference implementation, and it settles the design question

Fetched eversolar.pl from https://github.com/solmoller/eversolar-monitor rather than reasoning about it. It is unambiguously the bus-owner shape, and the mechanism is simpler than assumed above.

register_inverter() registers at most ONE inverter per call

Its own comment says so (:596):

send the register packet to any inverters out there, and register inverter that responds first

One offline query, one serial number, one address assigned from $next_inverter_address, then $next_inverter_address++ (:645). There is no loop until silence — the issue text above assumed one, and there isn't.

The multi-inverter behaviour is entirely in the CADENCE

Two call sites:

• :1008-1009 — a tight loop while no inverters are known at all: while (keys(%inverters) == 0) { register_inverter(); }. Aggressive until the first is found.
• :1038-1039 — once a minute thereafter: if ($min != $last_min) { register_inverter(); }.

So three inverters are discovered over roughly three minutes, one per round. A registered inverter ignores the broadcast offline query, so each round the next unregistered one answers.

RE_REGISTER runs once, at connection setup — not per inverter

re_register_inverters() has exactly one caller: inverter_connect() (:822), which also resets $next_inverter_address to START_INVERTER_ADDRESS (:819). It broadcasts 8 times, despite its own comment claiming "3 times as per protocol specs" (:584-585).

This is the direct counterpart of the bug in #63: the reference treats RE_REGISTER as a bus operation done once when the line comes up, while our driver does it in begin(), which runs per driver instance.

Inverters live in a map keyed by assigned address

%inverters, keyed by the address the PMU handed out, carrying id string, serial, connect timestamp and per-inverter counters. The poll loop is foreach $inverter (keys(%inverters)), one QUERY_NORMAL_INFO per inverter per cycle (:1046-1047).

What this means for the two shapes above

The bus-owner shape wins, and not on elegance — cooperating instances cannot express this. Address assignment is sequential state ($next_inverter_address) owned by whoever runs the enumeration, and inverters are keyed by an address that is a result, not configuration. Independent instances each holding a configured address would have to agree on that counter, and the thing they would be coordinating is exactly what the protocol assigns dynamically.

And the half-duplex worry raised above is smaller than stated

There is no arbitration, and none is needed. If two unregistered inverters answer the same broadcast, whatever comes back fails to parse as a serial number, the round yields nothing, and the next round tries again a minute later. The reference does not handle collisions — it retries past them. Worth confirming on hardware, but it is not the design blocker it was made out to be.

Revised sketch

1. One EverSolar driver instance owns the bus; RE_REGISTER moves out of per-instance begin() to a once-per-bus startup.
2. It keeps an address → inverter map and enumerates one new inverter per pass — aggressively while none are known, then at a low cadence.
3. The device layer must accept one driver yielding several devices. That is the genuine framework change.

Step 3 is the only real unknown left. The protocol side is now fully mapped and none of it needs guessing.

[Timdebruijn]

Hard constraint: a single-inverter setup must keep working, unchanged

Stated by Tim, and it is the requirement that most constrains the design — more than the enumeration itself. Concretely, four things that a bus-owner refactor could break without anyone noticing until it is in the field.

1. The device id must stay byte-identical

Today a single EverSolar's device id comes from identity().deviceId(), which prefers the serial number. If the bus owner starts keying devices on the assigned address — which is what the reference's %inverters hash does — then an existing install's device id changes. That orphans its retained MQTT topics, re-creates every Home Assistant entity under a new unique_id, and breaks the recorder history behind them.

The address is also the wrong key on its own merits: it is volatile, reset to 0x10 on every reconnect, and an inverter that registers second one day and first the next would swap identities with its neighbour.

So: the serial stays the identity, the address stays an implementation detail of the bus. This is the same trap mockSerialNumber() documents for the mock — instance 1 is byte-identical to the old constant precisely so existing installs keep their ids. Whatever lands here needs the equivalent test.

2. RE_REGISTER must not disappear from the recovery path

Moving RE_REGISTER out of per-instance begin() is right (that is the #63 bug), but it must not become "only ever at bus startup". test_registration_recovers_a_registered_but_forgotten_inverter pins a real, field-observed state: the inverter holds an address from an earlier session while the driver starts fresh, the offline query alone stays silent forever, and only a RE_REGISTER broadcast breaks the deadlock.

That recovery has to survive the refactor. It is the thing that makes a bridge reboot work at all.

3. The re-enumeration cadence adds traffic to a bus that is currently quiet

The reference sends a broadcast offline query every minute, forever, even when it already has every inverter it will ever see. On a single-inverter install that is a new broadcast per minute on a bus that today carries nothing but the poll.

Almost certainly harmless — it is a read-only query a registered inverter ignores — but it is a behaviour change for every existing user, and it is the sort of thing that turns up as "my logs are noisier now" or, worse, interacts with a device that answers when it should not. Options: only re-enumerate while fewer devices are known than configured, make it opt-in, or run it at a much lower cadence than the reference's minute.

4. Discovery must still identify a single inverter the same way

The probe path uses the same registration handshake, and the wizard's confidence scoring depends on it. A bus owner that changes when registration happens changes what a probe observes.

Acceptance, stated plainly

A bridge with one EverSolar, upgraded to the version that adds this, must:

• keep the same device id, MQTT topics and Home Assistant entities;
• keep polling across the upgrade with no manual step;
• recover from a reboot exactly as it does today, including the forgotten-address case;
• not gain bus traffic that a user would notice.

Worth writing those as tests against the existing fake device before any of the enumeration work, so the refactor has something to fail against rather than being checked by hand afterwards.

[Timdebruijn]

Staying open deliberately, as the place the first report from someone with two inverters lands.

The limitation is now written down where it will actually be found rather than only here: the README device table says "one inverter per bridge" on the EverSolar row, and docs/eversolar-protocol.md carries a section with the reference implementation's approach — line-referenced to eversolar.pl, so it can be checked rather than trusted — plus the three compatibility constraints any implementation must not break for the single-inverter installs that exist today.

If you have two or more EverSolar / Zeversolar inverters on one RS485 loop, please say so here. Even without running anything: knowing somebody is affected is what moves this from theory to work worth doing. If you are willing to test, the protocol side is fully mapped and the remaining unknown is on our side, not the wire's.