Discovery catalogue: AlphaESS, Solis, Deye and Sunsynk reporters

[springfall2008]

What this does

Adds AlphaESS, Solis, Deye and Sunsynk as reporters to the discovery catalogue, completing Phase 1 of the reporter rollout. With Fox (#5184) and GivTCP/GE Cloud already reporting, the catalogue now describes hardware from every cloud integration in Phase 1.

#5184 has merged, and this PR now targets main. The branch has main merged in, and the quick suite passes on the result.

Observe-only

None of the four integrations behaves differently. Across the four modules the production change is 350 added lines and no removed ones: an import, a build_discovery() method and one self.refresh_discovery() call in run() per file. Each reporter reads only data its component already holds, so there are no new API calls. refresh_discovery() catches and logs its own failures. No automatic_config(), publish or control code is touched.

Where the call sits

In every component the report is filed after the data is published and before the first-cycle early return and automatic_config(), as Fox does in #5184. A first cycle whose telemetry poll fails still reports, and so does an install that auto-configuration skips. Wiring tests drive each component's real run() down the deferring path, so moving the call below the early return fails a test.

What each reporter says

	inverter_type	Functions	Ratings	Notes
AlphaESS	AlphaESSCloud on every system (battery-less systems are dropped at discovery)	battery, plus solar when the PV rating is non-zero	inverter, PV, battery kWh	ev_charger flag only when live telemetry has seen one
Solis	SolisCloud only where automatic_config() drives it: the detail doesn't report "no battery" and the SoH parses	solar on every inverter, battery on battery inverters, none until the detail has been read	inverter, battery Ah (bank total), pack count, kWh only when solis_nominal_voltage is configured	tou_v2 flag; inverterName never reported
Deye	DeyeCloud on every inverter	solar and battery	inverter, battery kWh, battery Ah	station_id only when the account has exactly one station
Sunsynk	SunsynkCloud on every inverter	solar and battery	inverter, battery kWh, battery Ah	export_limit capability

Each inverter_type rule copies the one in its component's own automatic_config(). The rule is copied rather than shared, so the control path isn't touched.

Deliberately left out: values that change from cycle to cycle (AlphaESS emsStatus, usCapacity, surplusCobat; the Solis SoH value itself), because every change would re-file the report. Also left out are free-text site names and anything not held without a new API call.

Deye and Sunsynk cannot tell a PV-only inverter from a hybrid. Their APIs give no signal and their automatic_config() treats every inverter as a battery inverter, so their records follow that configuration. The docs say so, and describe how a misconfigured PV-only unit shows: battery among its functions but no battery ratings.

Review

Each reporter was reviewed on its own, then the branch as a whole. The whole-branch review led to seven fixes, all in the last commit:

• Solis battery_capacity_ah is now the bank total. Register 172 is Ah per pack. Deye and Sunsynk report the whole bank under the same key, so Solis now multiplies by the pack count, as publish_entities() already does.
• Derived battery_kwh is rounded to 2 dp in the Solis and Sunsynk reporters (Deye already rounded).
• A Solis inverter whose detail hasn't been read yet reports no functions. It previously showed solar only, which reads as PV-only.
• Two new wiring tests: one checks that Solis still files a report when auto-configuration is off, and one checks that a report is re-filed on a later cycle.
• Docstring and docs wording corrections.

First review

Three fixes from the Copilot review, all in a50dc04:

• Sunsynk keeps its last battery ratings through a partial poll. fetch_device_data() rebuilds device_values every poll and drops a battery field the endpoint didn't return. publish_data() then leaves the battery_capacity sensor, and so soc_max, at its last value. The reporter now does the same, rather than filing a thinner report and then re-filing.
• nominal_pack_voltage() warns once per chargeVolt that fits no LiFePO4 stack. It was reached two or three times a cycle and logged the same Warn each time.
• The plan's Solis example is corrected to the bank-total battery_capacity_ah. A new Amendments section records how the executed code differs from the plan.

Serials stay readable

A hardware serial is not secret, so this PR also changes the catalogue's redaction (2967c89). Solis, Deye and Sunsynk serials are all digits, and the guard against a misfiled MPAN used to hide them. It hid the serial, the device_id built from it and the duplicate_serial observation naming it, and logged a Warn per inverter on every catalogue read.

• A serial a record declares (hardware_ids.serial or an entry in serials) now stays readable wherever it appears as a whole token. Only the serial itself is let through: a digit run beside it, or a longer number it merely sits inside, is still checked. Other hardware_ids keys keep the all-digit guard.
• A device_id built from its record's own serial is no longer replaced wholesale just because the record carries account_ids. Deye's deye:{serial} stays readable while its station ID is still pseudonymised. Octopus and Solcast device_ids, which are built from account identifiers, are unchanged.
• Two new coordinator tests use real serial shapes. Mutation checks showed each rule is load-bearing, and the docs' redaction section now states the rule.

Testing

• The quick suite passes and pre-commit is clean.
• Fixtures are each integration's existing captured API samples (ESS_LIST_SAMPLE, the Solis inverter details, Deye's live data list, Sunsynk's confirmed-live constants).
• Each reporter has tests for the records it describes, for devices it excludes, for an empty fleet, and a round trip through validate_report() that checks nothing is dropped.
• The Deye test fails if the reporter calls derive_battery_capacity(), which logs and writes state.
• Placement and evidence rules were each shown to be load-bearing with a temporary mutation that made a test fail.

Known issues, not fixed here

• Capability names need a pass. export_limit means "has the setting" on Fox but "an export limit can be derived" on Sunsynk. Whether functions records evidence or configuration also differs between reporters. This was planned for once several reporters had contributed tokens.

Next

The remaining reporters (Teslemetry, Sigenergy, SolaX, Enphase, Gateway, then myenergi, Kraken, Axle and Carbon) follow the rollout plan. Entity maps remain a separate project.

🤖 Generated with Claude Code

[Copilot]

Copilot review overview

🟡 Changes recommended

Address the two Sunsynk reporter issues and update the stale plan example.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 1

Open (1)

• Preserve battery capacity when telemetry omits fields · New

What changed in this PR

Adds observe-only discovery reporters for AlphaESS, Solis, Deye, and Sunsynk.

Changes:

• Added reporter implementations and runtime wiring.
• Added integration, validation, and lifecycle tests.
• Updated catalogue documentation, rollout plans, and spelling data.

File	Summary
docs/​superpowers/​plans/​2026-09-21-discovery-reporters-alphaess-solis-deye-sunsynk.md	Rollout plan; one stale capacity example remains.
docs/​discovery-catalogue.md	Discovery catalogue documentation updates.
apps/​predbat/​tests/​test_sunsynk_config.py	Sunsynk reporter and lifecycle tests.
apps/​predbat/​tests/​test_solis.py	Solis reporter tests.
apps/​predbat/​tests/​test_deye_api.py	Deye reporter tests.
apps/​predbat/​tests/​test_alphaess_api.py	AlphaESS reporter tests.
apps/​predbat/​sunsynk.py	Sunsynk reporter and runtime wiring; capacity warning amplification and transient rating loss require changes.
apps/​predbat/​solis.py	Solis reporter and runtime wiring.
apps/​predbat/​deye.py	Deye reporter and runtime wiring.
apps/​predbat/​alphaess.py	AlphaESS reporter and runtime wiring.
.cspell/​custom-dictionary-workspace.txt	Added test identifier.

---

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

[Copilot]

Copilot review overview

🟡 Changes recommended

Moderate issues remain in serial-boundary redaction and Sunsynk partial-poll rating consistency.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 2

Open (2)

• Use whole-token boundaries when matching declared serials · New
• Update battery capacity and kWh atomically · New

Resolved since last review (1)

• Preserve battery capacity when telemetry omits fields