From fd08090360527e41fa8375b8b14796c539dca78a Mon Sep 17 00:00:00 2001 From: glenn schrooyen Date: Sat, 17 Oct 2026 01:09:42 +0200 Subject: [PATCH] DOC-8: say EMS port, not meter bus The add-on is wired to the inverter's RS485 port labelled EMS. Reword README, DOCS, config description, field guide source and HTML. The HA manufacturer string is left unchanged: test_mqtt pins it byte for byte. Co-Authored-By: Claude --- HANDOVER.md | 2 +- README.md | 10 +++++----- docs/build_guide.py | 12 ++++++------ docs/field-guide.html | 12 ++++++------ goodwe_controller/DOCS.md | 8 ++++---- goodwe_controller/app/main.py | 2 +- goodwe_controller/config.yaml | 4 ++-- 7 files changed, 25 insertions(+), 25 deletions(-) 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..c1f52b2 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 @@ -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/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..34777bc 100644 --- a/goodwe_controller/DOCS.md +++ b/goodwe_controller/DOCS.md @@ -1,7 +1,7 @@ # 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 +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 @@ -33,8 +33,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/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: