glenn schrooyenandClaude Opus 5
7b4877d56d
checks / unit (pull_request) Successful in 3m35s
FCST-03's developer reverted `self.provisional` to `here.provisional`, re-ran, and reported the mutation as a survivor. It was not one. CPython validates a cached `.pyc` on (source size, source mtime truncated to whole seconds), and that edit moved neither number - same length, same second - so the interpreter loaded the bytecode it already had. Disassembly settled it at the time: the source read `here`, the running code loaded `self`. A mutation run had graded code that was not there, with no error and exit status 0. This does not make the results already on the record wrong. It makes them UNVERIFIED, and that distinction is the whole card - so nothing here re-runs a campaign and nothing here quietly assumes the old numbers hold. REPRODUCED, THEN CLOSED. test_bytecode.py builds a real package whose two return values are the same length, imports it in a real subprocess, rewrites it inside the same second (retrying until both writes land in one whole second - milliseconds, no sleep) and reads back which value ran. Part 1 shows the interpreter running SELF off a file that says HERE. AND THE TWO OBVIOUS MITIGATIONS DO NOT WORK. Measured, not read off documentation: `python3 -B` and PYTHONDONTWRITEBYTECODE=1 are write-side only. Neither stops an EXISTING stale .pyc being read, and a mutation run always has one, because the previous run wrote it. Part 2 grades both still running the old code. The advice in test_control.py's coverage audit led with `-B`; it is corrected here - the purge is the half that works, and `-B` earns its place by keeping THIS run from leaving a cache for the NEXT edit to inherit. NO SLEEP ANYWHERE. One-second mtime resolution is the mechanism, not the enemy. Waiting it out would slow every run down and would still only cover the edit somebody remembered to slow down. THE HARNESS. tools/mutation_run.sh purges, prints a sha256/byte fingerprint of every app/*.py it is about to grade - so a mutation report can say WHICH source produced it, which is the reviewer's addition to this card - runs each suite under `python3 -B`, refuses a tree with no test_*.py (CI-01's rule, for CI-01's reason), and fails if a cache appears during the run. It takes the tree as an argument so the infra repo's replay harnesses can call it without being moved. WHERE IT IS SAID (AC 2). MUTATION.md carries the mechanism, the measurement, the reporting rules and the survey, and every one of the 16 suites now points at it from its docstring. That list is DERIVED FROM THE TREE by test_bytecode.py part 5, so a new suite that joins this directory without the pointer is red - the same failure shape CI-01's file glob exists to prevent. CI WAS ALREADY IMMUNE, AND IS DESCRIBED THAT WAY (AC 4). Verified rather than reasoned: with the checkout bind mounted `-v "$WS:/w:ro"` the interpreter writes no __pycache__ into the tree at all, and it fails SILENTLY - no error, exit status 0 - while the same probe on a writable mount produces one. Each job also rm -rf's its workspace and clones afresh, so nothing crosses between jobs on the shared runner. PYTHONDONTWRITEBYTECODE=1 is added as belt and braces only: the `:ro` is one character wide and the next person debugging a write will be tempted by it. Part 6 grades both ON THE DOCKER COMMAND LINE rather than on the file - the first draft searched the whole workflow and stayed green after the flag was deleted, because the comment explaining it still named it. THE SHIPPED ADD-ON IS NOT AFFECTED and the question is closed: goodwe_controller/Dockerfile has set PYTHONDONTWRITEBYTECODE=1 since it was written. There is no deploy-side finding. THE SURVEY (AC 3), in MUTATION.md, scoped BY THE PROPERTY. The defect is one-directional - a mutation that never took leaves the suite green, so stale bytecode manufactures SURVIVORS and cannot manufacture a red - which puts every "all red, no survivors" claim in the window out of scope, along with mutations executed in-process (SAFETY-07's B1/B2/B3, test_peakguard parts 7 and 10, where no source file is edited) and everything run after the purge discipline landed on 2026-08-31 (SAFETY-24, SAFETY-26, OPT-04, FCST-03's re-run). What is left is the recorded SURVIVORS from source-edit runs before that date. Two were re-run here under the harness and both still stand: TARIFF-01's record_block() ignoring its policy argument, and SAFETY-03's abs() on the clamp limit - 15 suites green each, on the tree as it stood. The rest are labelled still-unverified rather than assumed or re-run; each is one harness run to close, and the moment to spend it is when somebody next touches that module. OUT OF SCOPE AND RECORDED: the infra repo's sim/ replay harnesses import the add-on and write bytecode into both trees (goodwe/sim/__pycache__ exists today), so SAFETY-02's headline replay carries the same exposure. mutation_run.sh takes a tree argument for exactly that, but the change belongs in that repo and some of those harnesses want the rig. RED AND GREEN. Every new check was broken and watched fail: the purge commented out of the harness turns part 4 red (and its non-vacuity probe already proves the fixture would mis-grade without it); one docstring pointer removed turns part 5 red naming the file; `:ro` and the `-e` flag removed from the workflow turn part 6 red. Full suite green, 16 files, in the CI image on a read-only mount - the shape the runner uses. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
117 lines
5.1 KiB
Markdown
117 lines
5.1 KiB
Markdown
# 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
|
|
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
|
|
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:
|
|
|
|
1. **ESP32 watchdog** — no fresh setpoint for ~30 s → command 0 W, and keep
|
|
commanding it.
|
|
2. **Wind-down before firmware updates** — 0 W written before the update starts.
|
|
3. **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:
|
|
|
|
```bash
|
|
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.
|