diff --git a/FIELD-GUIDE.md b/FIELD-GUIDE.md index 1d71b4b..3e1524f 100644 --- a/FIELD-GUIDE.md +++ b/FIELD-GUIDE.md @@ -4,9 +4,9 @@ The guide technicians carry is the PDF: **`docs/GoodWe-RS485-Field-Guide.pdf`** — 10 pages, A4, print it double-sided. -⚠️ **Outdated: it is v0.1.0.** Its `slew_w` row is corrected in `build_guide.py` -and `field-guide.html`, but the PDF has not been rebuilt (see below). Where the -guide disagrees with `goodwe_controller/DOCS.md`, DOCS.md wins. +⚠️ **Outdated: the content is still v0.1.0.** The PDF was rebuilt on 2026-10-17 +for the EMS-port wording and the `slew_w` row only. Where the guide disagrees with +`goodwe_controller/DOCS.md`, DOCS.md wins. It covers, in the order the work is done: pre-visit checks, hardware, firmware, add-on install and configuration, how to read the Web UI, the six commissioning diff --git a/HANDOVER.md b/HANDOVER.md index c926f1f..565da3e 100644 --- a/HANDOVER.md +++ b/HANDOVER.md @@ -156,7 +156,7 @@ that looks hung gets deleted. **A GoodWe "-20" / G2 inverter cannot be driven by this.** Platform comes from characters 6–8 of the serial number. Only -`ESU EMU ESA BPS BPU EMJ IJL` — platform 105, the AA55-era meter bus — are +`ESU EMU ESA BPS BPU EMJ IJL` — platform 105, the AA55-era generation — are supported. SBP G2 (`SPB`/`SPN`) and ES G2 (`ESN`/`ESC`) are platform 745, a different protocol. The reference unit is `BPS`. diff --git a/README.md b/README.md index 53438fc..d9711d4 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # 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. +net grid exchange at zero by sending the inverter a grid reading over its RS485 +EMS port, and runs the monthly battery maintenance cycle the vendor box was doing. ``` repository.yaml add-on repository metadata @@ -30,7 +30,7 @@ goodwe_controller/ the add-on 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; outdated) +docs/GoodWe-RS485-Field-Guide.pdf the guide techs carry (10pp, A4; rebuilt 2026-10-17, content still v0.1.0 and outdated) docs/build_guide.py its single source - rebuilds the HTML and PDF FIELD-GUIDE.md how to edit and rebuild the guide docs/RELEASE.md how a change reaches the battery - `master` is @@ -118,17 +118,17 @@ the platform tag: | tag | platform | verdict | |---|---|---| -| `ESU EMU ESA BPS BPU EMJ IJL` | 105 — ES/EM/BP, AA55-era meter bus | **supported** | +| `ESU EMU ESA BPS BPU EMJ IJL` | 105 — ES/EM/BP, AA55-era | **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 +A "-20" or "G2" suffix means a different platform with a different 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) +- GoodWe **ES / BP family** inverters (AA55 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. diff --git a/docs/GoodWe-RS485-Field-Guide.pdf b/docs/GoodWe-RS485-Field-Guide.pdf index 42f4264..cfada9f 100644 Binary files a/docs/GoodWe-RS485-Field-Guide.pdf and b/docs/GoodWe-RS485-Field-Guide.pdf differ diff --git a/docs/build_guide.py b/docs/build_guide.py index f006f71..0e5f554 100644 --- a/docs/build_guide.py +++ b/docs/build_guide.py @@ -154,7 +154,7 @@ figcaption { font-size:9pt; color:#5b6169; margin-top:1.2mm; } - + @@ -162,7 +162,7 @@ figcaption { font-size:9pt; color:#5b6169; margin-top:1.2mm; }
TagPlatformVerdict
ESU EMU ESA BPS
BPU EMJ IJL		Platform 105 — ES / EM / BP, AA55-era meter busPlatform 105 — ES / EM / BP, AA55-era SUPPORTED
SPB SPNSBP G2 (GW…-SBP-20) — platform 745NO
ESN ESCES G2 (GW…-ES-20) — platform 745NO
SDT DST MSU NSU …PV-only inverters — no battery to controlNO

Reference unit: 95000BPS225W0290 → BPS → supported. - A “-20” or “G2” suffix in the model name means a different platform with a different meter + A “-20” or “G2” suffix in the model name means a different platform with a different protocol. If the tag is not on the supported list, stop — do not quote the job.

@@ -208,13 +208,13 @@ figcaption { font-size:9pt; color:#5b6169; margin-top:1.2mm; }

Steps 1–3 — Hardware

-
Qualified persons only. Mains AC and battery DC are present. The meter bus +
Qualified persons only. Mains AC and battery DC are present. The RS485 EMS port is low-voltage but sits inside an energised installation.

1 Survey and record

    -
  1. Photograph the meter-port wiring before touching it.
    2. +
  2. Photograph the EMS-port wiring before touching it.
  3. Identify the RS485 pair (A/B) running to the vendor controller.
  4. Record inverter model + serial, battery capacity (Ah) and nominal voltage.
@@ -226,7 +226,7 @@ figcaption { font-size:9pt; color:#5b6169; margin-top:1.2mm; }
  1. Bring the system to 0 W — battery neither charging nor discharging (check the inverter display).
    2. -
  2. Disconnect the vendor controller from the meter port.
    3. +
  3. Disconnect the vendor controller from the inverter's EMS port.
  4. Leave it physically mounted but unplugged — that keeps the install reversible and gives you a rollback story.
@@ -237,7 +237,7 @@ figcaption { font-size:9pt; color:#5b6169; margin-top:1.2mm; }

3 Fit and power the T-CAN485

    -
  1. Wire A→A, B→B to the meter port, plus its own supply.
    2. +
  2. Wire A→A, B→B to the EMS port, plus its own supply.
  3. If fitting the e-stop, connect its USB-RS485 adapter to the same pair, in parallel.
  4. Power the T-CAN485 last.
diff --git a/docs/field-guide.html b/docs/field-guide.html index 77570b2..2488c94 100644 --- a/docs/field-guide.html +++ b/docs/field-guide.html @@ -119,7 +119,7 @@ figcaption { font-size:9pt; color:#5b6169; margin-top:1.2mm; } - + @@ -127,7 +127,7 @@ figcaption { font-size:9pt; color:#5b6169; margin-top:1.2mm; }
TagPlatformVerdict
ESU EMU ESA BPS
BPU EMJ IJL		Platform 105 — ES / EM / BP, AA55-era meter busPlatform 105 — ES / EM / BP, AA55-era SUPPORTED
SPB SPNSBP G2 (GW…-SBP-20) — platform 745NO
ESN ESCES G2 (GW…-ES-20) — platform 745NO
SDT DST MSU NSU …PV-only inverters — no battery to controlNO

Reference unit: 95000BPS225W0290 → BPS → supported. - A “-20” or “G2” suffix in the model name means a different platform with a different meter + A “-20” or “G2” suffix in the model name means a different platform with a different protocol. If the tag is not on the supported list, stop — do not quote the job.

@@ -173,13 +173,13 @@ figcaption { font-size:9pt; color:#5b6169; margin-top:1.2mm; }

Steps 1–3 — Hardware

-
Qualified persons only. Mains AC and battery DC are present. The meter bus +
Qualified persons only. Mains AC and battery DC are present. The RS485 EMS port is low-voltage but sits inside an energised installation.

1 Survey and record

    -
  1. Photograph the meter-port wiring before touching it.
    2. +
  2. Photograph the EMS-port wiring before touching it.
  3. Identify the RS485 pair (A/B) running to the vendor controller.
  4. Record inverter model + serial, battery capacity (Ah) and nominal voltage.
@@ -191,7 +191,7 @@ figcaption { font-size:9pt; color:#5b6169; margin-top:1.2mm; }
  1. Bring the system to 0 W — battery neither charging nor discharging (check the inverter display).
    2. -
  2. Disconnect the vendor controller from the meter port.
    3. +
  3. Disconnect the vendor controller from the inverter's EMS port.
  4. Leave it physically mounted but unplugged — that keeps the install reversible and gives you a rollback story.
@@ -202,7 +202,7 @@ figcaption { font-size:9pt; color:#5b6169; margin-top:1.2mm; }

3 Fit and power the T-CAN485

    -
  1. Wire A→A, B→B to the meter port, plus its own supply.
    2. +
  2. Wire A→A, B→B to the EMS port, plus its own supply.
  3. If fitting the e-stop, connect its USB-RS485 adapter to the same pair, in parallel.
  4. Power the T-CAN485 last.
diff --git a/goodwe_controller/DOCS.md b/goodwe_controller/DOCS.md index cd9051c..fb1be9c 100644 --- a/goodwe_controller/DOCS.md +++ b/goodwe_controller/DOCS.md @@ -1,8 +1,9 @@ # GoodWe RS485 Controller -Drives a GoodWe ES/BP battery inverter over its RS485 meter bus: holds net grid -exchange at zero, and runs a monthly battery maintenance cycle so the BMS can -balance cells and recalibrate its coulomb counter. +Drives a GoodWe ES/BP battery inverter over its RS485 EMS port: sends it a grid +reading to hold net grid exchange at zero, and runs a monthly battery +maintenance cycle so the BMS can balance cells and recalibrate its coulomb +counter. Installers: the printed field guide (`docs/GoodWe-RS485-Field-Guide.pdf`) is v0.1.0 and outdated; where it disagrees with this page, this page wins. @@ -33,8 +34,8 @@ v0.1.0 and outdated; where it disagrees with this page, this page wins. You need: -- A GoodWe **ES / BP family** inverter (AA55 / RS485 meter-bus generation) -- The vendor's meter-emulating controller **disconnected** from the bus +- A GoodWe **ES / BP family** inverter (AA55 generation) +- The vendor's controller **disconnected** from the inverter's EMS port - A control board: a T-CAN485 (ESP32) flashed with `firmware/goodwe-master.yaml` - A grid-power sensor already working in Home Assistant, updating every ~5–10 s diff --git a/goodwe_controller/app/main.py b/goodwe_controller/app/main.py index 9e98549..554b1d3 100644 --- a/goodwe_controller/app/main.py +++ b/goodwe_controller/app/main.py @@ -3,7 +3,7 @@ WHAT THIS THING DOES, in one paragraph: it reads the house's net grid power from Home Assistant, decides how hard the battery should charge or discharge to hold that at zero, and writes that figure to an ESP32 which puts it on the inverter's -RS485 meter bus. Once a month it runs a full low->full battery cycle so the BMS +RS485 EMS port. Once a month it runs a full low->full battery cycle so the BMS can balance cells and recalibrate its coulomb counter. ⚠️ THE ONE THING TO UNDERSTAND BEFORE CHANGING ANY OF THIS: the inverter holds diff --git a/goodwe_controller/app/mqtt.py b/goodwe_controller/app/mqtt.py index 56d54cf..d9284d6 100644 --- a/goodwe_controller/app/mqtt.py +++ b/goodwe_controller/app/mqtt.py @@ -29,7 +29,7 @@ _LOG = logging.getLogger("goodwe.mqtt") DEVICE = { "identifiers": ["goodwe_rs485_controller"], "name": "GoodWe", - "manufacturer": "GoodWe (via RS485 meter emulation)", + "manufacturer": "GoodWe (via RS485 EMS port)", "model": "ES/BP series", } diff --git a/goodwe_controller/config.yaml b/goodwe_controller/config.yaml index 6fc77a9..efeea16 100644 --- a/goodwe_controller/config.yaml +++ b/goodwe_controller/config.yaml @@ -2,8 +2,8 @@ name: GoodWe RS485 Controller version: "0.18.2" slug: goodwe_controller description: >- - Drives a GoodWe ES/BP battery inverter over RS485 by emulating its smart - meter, holding net grid exchange at zero and running a monthly battery + Drives a GoodWe ES/BP battery inverter over its RS485 EMS port by sending it a + grid reading, holding net grid exchange at zero and running a monthly battery maintenance cycle. url: https://gittea.kammenstraatha.duckdns.org/admin/goodwe-addon arch: diff --git a/goodwe_controller/test_mqtt.py b/goodwe_controller/test_mqtt.py index 5e4a5b7..ecc9882 100644 --- a/goodwe_controller/test_mqtt.py +++ b/goodwe_controller/test_mqtt.py @@ -104,7 +104,7 @@ def check(name, cond): # release/1.0 rather than against release/1.0. # --------------------------------------------------------------------------- _DEV = ('{"identifiers": ["goodwe_rs485_controller"], "name": "GoodWe", ' - '"manufacturer": "GoodWe (via RS485 meter emulation)", ' + '"manufacturer": "GoodWe (via RS485 EMS port)", ' '"model": "ES/BP series"}') BASELINE = [ @@ -442,7 +442,7 @@ for c_ in unit_cfgs: print(f" regression pin (sha256 of the eight payloads): {_pin}") check("the per-unit payloads are the ones this PR was reviewed with " "(REGRESSION PIN, not a correctness claim - see the comment)", - _pin == "eb5022b0455158d7") + _pin == "b4274714d8557c37") # --------------------------------------------------------------------------- print("\n4. zero overlap between A's entities and B's") @@ -976,7 +976,7 @@ def announce_p2(units=(), omit=(), include=(), modes=(), retract=(), # `git show ed739d4:goodwe_controller/app/mqtt.py` and this loop. ROSTERS = [[], ["inverter-a"], ["inverter-a", "inverter-b"], ["a", "b", "c"], ["inverter-b", "Inverter B", "x", "y"], ["café"]] -ED739D4_OFF = "501a7d93782a260b" +ED739D4_OFF = "057be1d8ad7bb582" # DOC-8: ed739d4 digest with only the manufacturer string changed _h, _n, _subs_off = hashlib.sha256(), 0, [] for _r in ROSTERS: for _om in [(), ("p1_age",), ("p1_age", "grid")]: