DOC-8 review: say the field guide PDF is rebuilt, still v0.1.0

README and FIELD-GUIDE.md said the PDF was not rebuilt; it was, on 2026-10-17. Its content is still v0.1.0 and outdated. Rewrap the DOCS.md intro line. Text only. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
DOC-8: update test_mqtt digest pins for the new manufacturer string
2026-10-17 03:27:35 +02:00 · 2026-10-17 02:16:34 +02:00 · 2026-10-17 01:53:33 +02:00 · 2026-10-17 01:09:42 +02:00
11 changed files with 35 additions and 34 deletions
@@ -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
@@ -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`.

@@ -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.
@@ -154,7 +154,7 @@ figcaption { font-size:9pt; color:#5b6169; margin-top:1.2mm; }
    <table style="margin-bottom:2mm">
      <tr><th style="width:34mm">Tag</th><th>Platform</th><th style="width:30mm">Verdict</th></tr>
      <tr><td><code>ESU EMU ESA BPS<br>BPU EMJ IJL</code></td>
-          <td><b>Platform 105</b> — ES / EM / BP, AA55-era meter bus</td>
+          <td><b>Platform 105</b> — ES / EM / BP, AA55-era</td>
          <td><b>SUPPORTED</b></td></tr>
      <tr><td><code>SPB SPN</code></td><td>SBP <b>G2</b> (GW…-SBP-20) — platform 745</td><td><b>NO</b></td></tr>
      <tr><td><code>ESN ESC</code></td><td>ES <b>G2</b> (GW…-ES-20) — platform 745</td><td><b>NO</b></td></tr>
@@ -162,7 +162,7 @@ figcaption { font-size:9pt; color:#5b6169; margin-top:1.2mm; }
      <tr><td><code>SDT DST MSU NSU …</code></td><td>PV-only inverters — <b>no battery to control</b></td><td><b>NO</b></td></tr>
    </table>
    <p style="margin:0"><small>Reference unit: <code>95000BPS225W0290</code> → <code>BPS</code> → 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. <b>If the tag is not on the supported list, stop — do not quote the job.</b></small></p>
  </div>

@@ -208,13 +208,13 @@ figcaption { font-size:9pt; color:#5b6169; margin-top:1.2mm; }
 <!-- ============ PAGE 3 ============ -->
 <div class="page" id="p3">
  <h2>Steps 1–3 — Hardware</h2>
-  <div class="warn"><b>Qualified persons only.</b> Mains AC and battery DC are present. The meter bus
+  <div class="warn"><b>Qualified persons only.</b> Mains AC and battery DC are present. The RS485 EMS port
  is low-voltage but sits inside an energised installation.</div>

  <div class="step">
    <h3><span class="num">1</span> Survey and record</h3>
    <ol class="do">
-      <li><b>Photograph</b> the meter-port wiring before touching it.</li>
+      <li><b>Photograph</b> the EMS-port wiring before touching it.</li>
      <li>Identify the RS485 pair (A/B) running to the vendor controller.</li>
      <li>Record inverter model + serial, battery capacity (Ah) and nominal voltage.</li>
    </ol>
@@ -226,7 +226,7 @@ figcaption { font-size:9pt; color:#5b6169; margin-top:1.2mm; }
    <ol class="do">
      <li>Bring the system to <b>0 W</b> — battery neither charging nor discharging (check the
          inverter display).</li>
-      <li>Disconnect the vendor controller from the meter port.</li>
+      <li>Disconnect the vendor controller from the inverter's EMS port.</li>
      <li>Leave it physically mounted but unplugged — that keeps the install reversible and gives
          you a rollback story.</li>
    </ol>
@@ -237,7 +237,7 @@ figcaption { font-size:9pt; color:#5b6169; margin-top:1.2mm; }
  <div class="step">
    <h3><span class="num">3</span> Fit and power the T-CAN485</h3>
    <ol class="do">
-      <li>Wire <b>A→A, B→B</b> to the meter port, plus its own supply.</li>
+      <li>Wire <b>A→A, B→B</b> to the EMS port, plus its own supply.</li>
      <li>If fitting the e-stop, connect its USB-RS485 adapter to the <b>same pair, in parallel</b>.</li>
      <li>Power the T-CAN485 <b>last</b>.</li>
    </ol>
@@ -119,7 +119,7 @@ figcaption { font-size:9pt; color:#5b6169; margin-top:1.2mm; }
    <table style="margin-bottom:2mm">
      <tr><th style="width:34mm">Tag</th><th>Platform</th><th style="width:30mm">Verdict</th></tr>
      <tr><td><code>ESU EMU ESA BPS<br>BPU EMJ IJL</code></td>
-          <td><b>Platform 105</b> — ES / EM / BP, AA55-era meter bus</td>
+          <td><b>Platform 105</b> — ES / EM / BP, AA55-era</td>
          <td><b>SUPPORTED</b></td></tr>
      <tr><td><code>SPB SPN</code></td><td>SBP <b>G2</b> (GW…-SBP-20) — platform 745</td><td><b>NO</b></td></tr>
      <tr><td><code>ESN ESC</code></td><td>ES <b>G2</b> (GW…-ES-20) — platform 745</td><td><b>NO</b></td></tr>
@@ -127,7 +127,7 @@ figcaption { font-size:9pt; color:#5b6169; margin-top:1.2mm; }
      <tr><td><code>SDT DST MSU NSU …</code></td><td>PV-only inverters — <b>no battery to control</b></td><td><b>NO</b></td></tr>
    </table>
    <p style="margin:0"><small>Reference unit: <code>95000BPS225W0290</code> → <code>BPS</code> → 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. <b>If the tag is not on the supported list, stop — do not quote the job.</b></small></p>
  </div>

@@ -173,13 +173,13 @@ figcaption { font-size:9pt; color:#5b6169; margin-top:1.2mm; }
 <!-- ============ PAGE 3 ============ -->
 <div class="page" id="p3">
  <h2>Steps 1–3 — Hardware</h2>
-  <div class="warn"><b>Qualified persons only.</b> Mains AC and battery DC are present. The meter bus
+  <div class="warn"><b>Qualified persons only.</b> Mains AC and battery DC are present. The RS485 EMS port
  is low-voltage but sits inside an energised installation.</div>

  <div class="step">
    <h3><span class="num">1</span> Survey and record</h3>
    <ol class="do">
-      <li><b>Photograph</b> the meter-port wiring before touching it.</li>
+      <li><b>Photograph</b> the EMS-port wiring before touching it.</li>
      <li>Identify the RS485 pair (A/B) running to the vendor controller.</li>
      <li>Record inverter model + serial, battery capacity (Ah) and nominal voltage.</li>
    </ol>
@@ -191,7 +191,7 @@ figcaption { font-size:9pt; color:#5b6169; margin-top:1.2mm; }
    <ol class="do">
      <li>Bring the system to <b>0 W</b> — battery neither charging nor discharging (check the
          inverter display).</li>
-      <li>Disconnect the vendor controller from the meter port.</li>
+      <li>Disconnect the vendor controller from the inverter's EMS port.</li>
      <li>Leave it physically mounted but unplugged — that keeps the install reversible and gives
          you a rollback story.</li>
    </ol>
@@ -202,7 +202,7 @@ figcaption { font-size:9pt; color:#5b6169; margin-top:1.2mm; }
  <div class="step">
    <h3><span class="num">3</span> Fit and power the T-CAN485</h3>
    <ol class="do">
-      <li>Wire <b>A→A, B→B</b> to the meter port, plus its own supply.</li>
+      <li>Wire <b>A→A, B→B</b> to the EMS port, plus its own supply.</li>
      <li>If fitting the e-stop, connect its USB-RS485 adapter to the <b>same pair, in parallel</b>.</li>
      <li>Power the T-CAN485 <b>last</b>.</li>
    </ol>
@@ -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
@@ -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
@@ -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",
 }

@@ -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:
@@ -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")]:
Author	SHA1	Message	Date
glenn schrooyenandClaude Opus 5.5	a4a7ff695e	DOC-8 review: say the field guide PDF is rebuilt, still v0.1.0 checks / unit (pull_request) Successful in 40m29s Details infra-pin / fresh (pull_request) Successful in 1s Details README and FIELD-GUIDE.md said the PDF was not rebuilt; it was, on 2026-10-17. Its content is still v0.1.0 and outdated. Rewrap the DOCS.md intro line. Text only. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-17 03:27:35 +02:00
glenn schrooyenandClaude	b8b357b552	DOC-8: update test_mqtt digest pins for the new manufacturer string infra-pin / fresh (pull_request) Successful in 2s Details checks / unit (pull_request) Successful in 40m23s Details Both digests hash the discovery payloads, which carry the manufacturer. Values regenerated; nothing else changes. Co-Authored-By: Claude <noreply@anthropic.com>	2026-10-17 02:16:34 +02:00
glenn schrooyenandClaude	4584502adb	DOC-8: HA manufacturer says EMS port; rebuild field guide PDF checks / unit (pull_request) Failing after 41m1s Details infra-pin / fresh (pull_request) Successful in 1s Details Device id (identifiers) is unchanged; only the display text moves. test_mqtt baseline updated for that one string. Co-Authored-By: Claude <noreply@anthropic.com>	2026-10-17 01:53:33 +02:00
glenn schrooyenandClaude	fd08090360	DOC-8: say EMS port, not meter bus checks / unit (pull_request) Successful in 40m22s Details infra-pin / fresh (pull_request) Successful in 1s Details 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 <noreply@anthropic.com>	2026-10-17 01:09:42 +02:00