adminandClaude Opus 5
5aba220046
0.10.0 was cut by PKG-14 on 2026-09-16 and three tickets have merged into release/1.0 since. Two of them change the built image - one is a CONTROL LAW change and one adds three MQTT entities - and neither is described anywhere in this file. Tagging that tree today would stamp a number on contents the changelog does not account for. FOLDED RATHER THAN CUT AS 0.11.0, AND THE ARGUMENT IS CONDITIONAL. 0.10.0 has never been built or pulled anywhere: the reference install is on 0.7.0 (PKG-14's own predeploy run records `deployed on the box : 0.7.0`), the repository carries exactly one tag, `v0.2.1`, and no release. So the string `0.10.0` does not yet name a tree anyone is running, and the PKG-06/PKG-07 no-op that forbade re-cutting `0.9.0` does not reach it. Cutting 0.11.0 would burn a number on a release that never left the repository. The condition is checkable and the section now says so: run against a box already reporting 0.10.0, `tools/predeploy_check.py` refuses with THE DEPLOY WOULD BE A NO-OP and names the runtime commits since the bump. `config.yaml` stays at 0.10.0, so `test_version_gate.py` 11b still finds the two sides equal. SAFETY-48 IS THE ENTRY THAT MATTERED MOST TO GET RIGHT, AND WHAT IT PROMISES IS LESS EXPORT - NOT A LOWER BILL. The measured result is export 39.61 -> 34.07 kWh over the committed 16-day replay, 14 % of the replayed figure, falling at every plant and tuning variant swept (~4 % to ~16 %, median near an eighth). The section says in its own heading and its first line that the control law changed, and it says PLAINLY that the billed quarter is not a claim: at every plant lag <= 5.0 s - including the one that best reproduces the recorded export - release/1.0's worst quarter is ALREADY 3434 W and this changes it by exactly zero. The 3739 -> 3434 W headline exists at the single longest fitted lag, and the lag is not identified by the recording. The costs are in the entry too: the cap moves a saturation-frozen integrator on 1095 of 79 160 frozen ticks, 679 of them outward; SAFETY-13's settle values moved; SAFETY-39's "the slew does not own the over-absorption" is now false. TEL-10 gets the three site rows, what each one is, and the two things a reader would otherwise get wrong: the lead is NOT a subtraction of two published rows, and `Loop reason` is not the `Why` row. It repeats neither of the two sentences TEL-10's own review retracted - EIGHT messages stay first and the ninth, `goodwe_ctl/availability`, is byte-identical but deliberately moves to last. CI-9 IS DELIBERATELY NOT IN THIS FILE, AND THE OMISSION IS WRITTEN DOWN RATHER THAN SILENT. It changes one file, `.gitea/workflows/checks.yml`, outside `goodwe_controller/` entirely: not in the built image, not in `is_runtime()`'s list, and not observable on any version of the add-on. This file is the release note the Supervisor shows beside the version number, and a row here has to be something the person deciding whether to press Update could act on. The note above SAFETY-48 says so and says the rule is about audience, not importance. THE STRAY `## Unreleased` AT LINE 1777 IS NOT TOUCHED, AND THAT IS A DECISION. It is the 0.8.0-era block PKG-14 annotated: every row in it has shipped, the annotation says which release each went to, and re-filing it is PKG-08's card. It is also load-bearing - `test_version_gate.py` 11d pins the count of `## Unreleased` blocks below the newest section at EXACTLY one, so deleting it is red on the commit that does it, and so is adding a second. TWO MEASURED FIGURES IN PKG-14'S PROSE WENT STALE AND ARE RE-DERIVED, NOT ADJUSTED. The runtime-commit count since `86bdf49` is now 32, not 28, of which the contents table accounts for 24, not 21; both re-run through `predeploy_check.is_runtime()` itself. The other eight are the three misfiled tickets (SAFETY-43 x2, SAFETY-44 x3, TEST-21 x2) and `cb3f686`, PKG-14's own bump, which edits `config.yaml` and so counts as runtime - it was HEAD when PKG-14 measured and is inside the range now. PKG-14's `CLEARED, exit 0` predeploy transcript was NOT re-run and now carries the check that says why it still holds: `config.yaml` is untouched by both tickets; `app/validate.py` imports neither `main` nor `mqtt`, and the three names it takes from `control` - SLEW_RAIL_FRAC, LOOP_TICK_S, PLANT_SETTLE_S - are byte-identical across cb3f686..HEAD. Verified: the full suite in the CI image, `cp -a` of the tree, purged, `:ro` mount, one file at a time, exactly the command in .gitea/workflows/checks.yml - 30/30, exit 0. No runtime file is in this diff. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BwRLw7eKYj2byVdwB6kbjU
GoodWe RS485 Controller — Home Assistant add-on repository
Replaces a GoodWe battery inverter's vendor controller with a local one: holds net grid exchange at zero by emulating the inverter's smart meter over RS485, and runs the monthly battery maintenance cycle the vendor box was doing.
repository.yaml add-on repository metadata
goodwe_controller/ the add-on
config.yaml manifest + options schema (the per-site config form)
app/ the controller
control.py the control law — pure functions, no I/O
maintenance.py the monthly cycle state machine
hass.py Supervisor/Core API access
store.py persistent state in /data
mqtt.py optional status entities
web.py ingress UI — routes only, status and configuration
config_page.py the configuration page's markup, style and script
configui.py its field model, built from the Supervisor's own
schema + translations — owns no key, label or rule
selfconfig.py reading and writing this add-on's own options,
with the validate-first / compare-and-swap gate
main.py orchestration, heartbeat, failsafe behaviour
test_control.py runnable checks — no framework needed
test_maintenance.py runnable checks — walks a full cycle in fake time
DOCS.md the add-on's documentation tab
MUTATION.md how to run a mutation so the result means something
tools/mutation_run.sh the mutation harness - purges bytecode, then grades
tools/supervisor_selfapi_probe.py what the Supervisor really permits and
returns, run against its own release image
firmware/goodwe-master.yaml ESPHome config for the T-CAN485
estop/rs485_log.py optional RS485 e-stop / bus witness
docs/GoodWe-RS485-Field-Guide.pdf the guide techs carry (10pp, A4)
docs/build_guide.py its single source - rebuilds the HTML and PDF
FIELD-GUIDE.md how to edit and rebuild the guide
Picking this up after a break? Read HANDOVER.md first — current state,
what is known broken, and what to do next.
Install
Settings → Add-ons → Add-on store → ⋮ → Repositories → add
https://gittea.kammenstraatha.duckdns.org/admin/goodwe-addon
then install GoodWe RS485 Controller.
⚠️ The repository must be PUBLIC for this to work. Home Assistant clones it
anonymously; against a private repo the store shows nothing and gives no useful
error. If it must stay private, install locally instead: copy
goodwe_controller/ into the machine's /addons/ folder, then
ha store reload — it appears as a Local add-on.
⚠️ Bump version: in goodwe_controller/config.yaml for every change.
Supervisor keys the built image by that version, so without a bump it silently
reuses the old image and your fix appears not to work — on your bench and on
every client's machine.
Requires Home Assistant OS or Supervised. Add-ons cannot be installed on HA Container or Core.
Read this first
The inverter holds its last command forever. It has no meter-timeout of its own — a controller that dies mid-command leaves the battery running until a human intervenes. Measured on real hardware: 5 kW of discharge held for 113 seconds after a controller went silent.
Three layers exist because of that, and only the third covers the Home Assistant machine itself dying:
- ESP32 watchdog — no fresh setpoint for ~30 s → command 0 W, and keep commanding it.
- Wind-down before firmware updates — 0 W written before the update starts.
- RS485 e-stop (optional) — writes 0 W after 30 s of total bus silence.
Sites sold without the e-stop must have the acknowledgement in FIELD-GUIDE.md
§10 signed.
Development
The control law and the maintenance machine are pure Python with no Home Assistant imports, so they run anywhere:
cd goodwe_controller
python3 test_control.py
python3 test_maintenance.py
Both must pass before shipping any change. To prove a check bites - the way
almost every claim in this repository was established - mutate the module and
run tools/mutation_run.sh, which clears __pycache__ first. It is not
optional: a same-size edit reverted inside one second leaves CPython reusing the
old bytecode, and the run grades code that is not there. goodwe_controller/MUTATION.md
has the mechanism, the measurement, and what the flags do not do. They are not unit-test theatre —
each assertion corresponds to a rule whose absence produced an observed failure
on real hardware, and the comments in control.py say which.
Compatibility
Check the serial number, not the model name. Characters 6-8 of the serial are the platform tag:
| tag | platform | verdict |
|---|---|---|
ESU EMU ESA BPS BPU EMJ IJL |
105 — ES/EM/BP, AA55-era meter bus | supported |
SPB SPN |
745 — SBP G2 (GW…-SBP-20) |
no |
ESN ESC |
745 — ES G2 (GW…-ES-20) |
no |
ETU EHU BTU … |
205/745/753 — ET/EH/BT hybrids | no |
SDT DST MSU NSU … |
PV-only inverters — no battery to control | no |
A "-20" or "G2" suffix means a different platform with a different meter
protocol. The tags come from the goodwe library's PLATFORM_105_MODELS, which
is also what Home Assistant's own integration uses to pick a protocol.
- GoodWe ES / BP family inverters (AA55 / RS485 meter-bus generation)
- The protocol is reverse-engineered. There is no vendor contract, and a firmware change on GoodWe's side could break every installation at once. Say so when you sell it.