fix(gateway): keep configured inverters when the hub cannot read them (#5471)

[springfall2008]

Fixes #5471. Fixes #5478.

The problem

On a Hub site, a battery inverter the Hub could not read when Predbat started was left out of auto-config and stayed out until the next restart. Predbat planned and controlled on fewer inverters than the site has and reported no error (one site ran on half its capacity for about 37 hours).

automatic_config() only took inverters that were primary with battery data present, then recorded every serial in the status message as configured. _needs_reconfigure() only re-runs for a serial it has not seen, so the dropped inverter never triggered a re-run.

What this changes

With gateway_inverter_serial set: the list decides the site

• Discovery records. For each listed serial the gateway records what the Hub reports it to be: type, whether it has a battery, battery size and model. Records are saved through the Storage component (gateway / discovery_<device id>, JSON), loaded in run() before the MQTT listener starts, and saved when one changes. A save the storage refuses stays pending and is retried after five minutes.
• Not updated while offline. A record is only taken from an inverter the Hub is reading, so an offline inverter never overwrites what is known about it. "Has a battery" only ever turns on, because an early status can carry an inverter's other readings before its battery ones.
• A discovered inverter keeps its slot. A listed inverter with a record is configured even when the Hub is not reading it or leaves it out of the status message, including straight after a restart. num_inverters no longer shrinks.
• Not yet discovered. A listed inverter the Hub has never reported readings for is left out, with a warning, and configured on the first status that carries its readings.
• A status naming no inverter. With at least one record held, a status with an empty inverter list is every discovered inverter unread, not nothing to do: they are bound at start-up, and once running their powers go to zero and the error is raised. It does not count towards the Hub being alive. With no record yet (or no serial list) it is ignored, as before.
• A changed list wins. Stored records for serials no longer in the list are dropped at load and not used.
• PV-only inverters. A listed inverter with readings but no battery gets no slot and is never a write target. Its pv_power and pv_today entities are appended after the bound inverters' so its generation is counted (the same pattern solis.py uses).
• Errors. A configured inverter the Hub is not reading logs an Error when that starts and marks each run as having had errors until it returns.

The coordinator rule is unchanged: a Plant EMS, or a Gateway with two or more battery AIOs, is still the single control target, so a list naming a Gateway and its AIOs behaves as it does today.

With no serial list

Selection uses the same primary-and-battery filter as before: auto-config uses the inverters it finds, and inverters can come and go. The discovery records are still stored for every inverter the Hub reads, but only for their last known battery size, rates and export limit. An inverter that is in the records but not in the status, or not being read, is not held on to. One change to selection: an inverter that was unusable at start-up is now registered on the first status in which it becomes usable, without a restart. It does not re-run auto-config on every status while the inverter stays unusable, and removals are still ignored.

All gateway sites: stale, not zero

An inverter with no readings at all keeps the state of charge, battery size and settings it last reported, as an inverter behind an offline cloud API does. Previously the empty message was published, which read as a 0% battery. Its power readings (battery, PV, grid, load, inverter) do go to zero: a power is a rate, and a stale one would read as an inverter still discharging hours after it dropped out. An inverter with no entities yet is published once with defaults (and its stored battery size, if known) so the core has something to read.

Entities are also published again straight after a successful auto-config, before the API is declared started. An inverter that is only published once bound (one the Hub does not flag primary, or a PV-only one) would otherwise have no entities until the next status message.

Keeping the site's readings sound while an inverter is unread

• Shared CT. With gateway_shared_ct the grid and load power and today's import, export and load are read from the first inverter's entities only. While that inverter is unread they are filled from the next inverter on the clamp, which reports the same readings.
• gateway_integrate_power. Integration still stops while an inverter with a slot is missing or disconnected, as before, but midnight now resets the day's figures in that state too. A PV-only inverter's generation is added to the load. Each inverter's generation is tracked by serial, so auto-config re-running and changing the slots (a PV-only inverter gaining a battery, an inverter becoming usable later) neither loses it nor mixes it with another inverter's. After auto-config runs, the status it ran on is taken as the baseline for the new slots, so an inverter is counted from the status it joined on.
• Coordinator sites. An unread battery inverter behind a Gateway or Plant EMS is reported as an error, not only an inverter with a slot of its own.
• Stored records. A stored record that cannot be read is dropped with a warning instead of stopping auto-config.
• Battery size. A slot with no battery size known is left unbound for soc_max (automatic sizing), as on main, and is re-bound on the first status that reports a size.

Ratings the Hub stops reporting (#5478)

A status with an inverter's ratings unpopulated, seen for a few minutes after a Hub restart, was published as a 6000 W battery and inverter rate with no export limit. A 3 kW inverter was planned on, and written to, at 6 kW.

• Last good value. A zero battery rate, inverter rate or export limit now keeps the last real value the Hub reported for that inverter. The two rates and the export limit are also kept in the stored discovery record, with or without a serial list, so they survive a restart. A battery size the Hub leaves out is published from the record in the same way.
• Reserve. A reserve the Hub leaves out (reads as 0%) also keeps the last real value, so Predbat no longer rewrites it for nothing. A 0% that Predbat itself writes is taken as real, and the next 0 from the Hub is then published as 0. That only applies once the write has gone out: if the publish fails the last value is kept, and if the Hub refuses the write it is put back.
• Never reported. An inverter that has never reported a maximum rate is still published with the 6000 W default, because the plan needs a figure, but the gateway no longer writes it directly: a charge or discharge rate write above zero for that inverter is not sent, and nor is its set_rate_cap. Predbat reads the unchanged rate back and tries again, so the write goes through once the rating arrives. A rate of zero is always sent, so a charge or discharge can still be stopped. A Gateway or Plant EMS is not held. The execution plan still carries the fleet rate from the core, which includes the default: that relies on the Hub, which cannot write to an inverter it has not discovered and clamps the plan power to the real rating of one it has.

Behaviour changes to check in review

• A Hub that never reports rate_max_w for a battery inverter can no longer have its charge or discharge rate raised above zero. Before, such a site ran on the 6000 W default. If any firmware in the field never reports the rating, this needs a decision before merge.

• With a serial list, the Hub's primary flag no longer decides whether a listed battery inverter is used.

• "Discovered" means the Hub has reported readings for the inverter at least once, not merely listed its serial. Readings are needed to tell a battery inverter from a PV-only one.

• A PV-only inverter contributes PV only. Its load, grid, import and export readings are not used.

• The error is a log line plus the run's error flag. The text of predbat.status is not changed.

Not covered

• The other control values (target SoC, charge and discharge rate, enables) are still published as the Hub sends them.
• A reserve of 0% set on the inverter by something other than Predbat reads as the last non-zero reserve, because the Hub's 0 cannot be told apart from "not reported".
• The last good reserve is held in memory only, so it is lost if Predbat restarts.
• Without a serial list, records for inverters that have gone for good stay in the stored file. They are not used for anything unless that serial is reported again.
• An inverter whose first status carries some readings but no battery block is configured as PV only until its battery readings arrive, when auto-config re-runs and gives it a slot.
• A listed inverter the Hub cannot read on the very first run with this change has no record yet, so it is left out, with a warning, until the Hub reads it. That is deliberate: without readings there is no way to tell a battery inverter from a PV-only one, and a PV-only inverter must not be given a slot.
• What the Hub actually sends for an inverter it refuses with not_polled is not known. If it sends some readings with an empty battery block, the battery values are still published as zero.
• Load and save are tested by calling _load_discovery() / _save_discovery() with a fake storage, not through run() or the real Storage backend.

Testing

• 47 new tests in TestGatewayUnitControlBinding and TestIntegratePower (test_gateway.py). The first 18 cover: never-read inverter left out then bound; stored inverter bound when unread or absent at start-up; changed list beating stored records; records saved, updated and left alone while offline; last known values stored and used without a list, while inverters still come and go; offline error raised and cleared; stale entity values; PV-only configuration and its later promotion to a battery inverter; no re-run of auto-config per status; a failed save retried after a wait; a newly bound inverter published on the same status. The rest cover the section above: shared-CT readings carried by the next inverter, powers zeroed, coordinator-site errors, unreadable stored records, PV-only entities after a restart, battery size re-binding, the midnight reset and PV-only generation under gateway_integrate_power. The last ten cover Gateway MQTT: a missing max battery rate is replaced with a hard-coded 6000 W, which is then written to the inverter #5478: the reserve kept and a written 0% honoured, a stored export limit (including a limit of zero) after a restart, ratings kept when the Hub stops reporting them, a zero export limit kept, defaults when never reported, stored ratings after a restart, rate writes and rate caps held on an assumed rating, and coordinators not held. Five more cover the second review round: PV tracked across a promotion to a slot and for an inverter that joins later, and a status naming no inverter at start-up, once running, and with no list or record. Four more cover the third round: the integration rebased after auto-config (directly and through _process_telemetry()), and the reserve kept when a write of 0% fails or is refused.
• The existing PV-only deferral test (test_incomplete_battery_telemetry_waits_then_excludes_pv_only_unit) is unchanged and passes.
• ./run_all --test gateway passes, ./run_all --quick passes, and pre-commit passes on both changed files.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

Initial unread inverters can still be omitted, save failures lose durability, and first-frame entities may be missing.

3 open findings

• Storage write failures clear dirty state without retry · New
• Configured unreadable inverters are omitted on first startup · New
• Newly bound inverters miss entities until a later status update · New

What changed in this PR

Adds durable Gateway inverter discovery so configured inverters remain bound during telemetry outages.

Changes:

• Persists inverter discovery metadata and retains stale entity values.
• Supports PV-only listed inverters and dynamic reconfiguration.
• Adds extensive Gateway regression tests.

File	Description
apps/​predbat/​gateway.py	Implements discovery persistence, binding, offline handling, and PV-only support.
apps/​predbat/​tests/​test_gateway.py	Adds coverage for discovery, outages, persistence, and reconfiguration.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

Empty telemetry, partial capacity telemetry, and PV-only promotion still cause incorrect configuration or accounting.

3 open findings

• Partial live telemetry drops stored battery capacity · New
• PV tracking loses generation after promotion to a battery slot · New
• Stored inverter fallback is unreachable when discovery returns no inverters · New

3 resolved since last review

• Newly bound inverters miss entities until a later status update
• Configured unreadable inverters are omitted on first startup
• Storage write failures clear dirty state without retry

🧠 Review effort: Balanced

[Copilot]

🟡 Changes recommended

Cached plans can still use assumed unsafe rates, and reconfiguration can lose integrated energy data.

3 open findings

• Prevent assumed ratings from publishing unsafe plan power · New
• Re-baseline energy integration after inverter slot changes · New
• Preserve reserve until zero command is confirmed · New

3 resolved since last review

• Stored inverter fallback is unreachable when discovery returns no inverters
• PV tracking loses generation after promotion to a battery slot
• Partial live telemetry drops stored battery capacity

🧠 Review effort: Balanced