docs: RS485 gateway guide, and correct the != credit in v1.4.0 notes

The v1.4.0 notes described rejecting over-long responses as an equally
strong signal that costs nothing to catch. The field data says more than
that: all 31 measured mismatches came back LONGER than requested, 30 of
them exactly 125 registers whatever was asked for. A check for short
responses would have caught none of them. The failure is not truncation,
it is a complete valid response to an earlier request replayed to the
current one -- so != count is the entire fix, not a refinement of it.

Adds docs/troubleshooting/rs485-gateways.md collecting what has actually
been measured: the Waveshare RS485 TO POE ETH (B) settings that work,
the PUSR TCP-timeout and AutoFrame changes that helped on #360, the
Olimex ESP32 bridge that did not, and the transparent-passthrough trap
that makes a gateway unusable regardless of hardware quality.

Also records two measurement mistakes worth not repeating: latency read
from log timestamps that was actually the integration's own retry cycle,
and a register scan run while the integration was still polling, which
returned 9 successful reads out of 1304 on a working device.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: 0xAHA

RELEASENOTES.md

@@ -39,6 +39,22 @@ Includes everything from the v1.3.7 pre-release.
   into polls that visibly fail, so your failure count may go **up**. That is the fix
   working.
 
+  **The guard checks `!= count`, not `< count`, and that turns out to be the whole
+  fix.** Every mismatch measured in the field came back **longer** than requested —
+  31 of them, 30 returning exactly 125 registers whatever was asked for. A length check
+  for *short* responses would have caught **none of them**. The failure is not a
+  truncated frame: it is a complete, valid response to an *earlier* request being
+  replayed to the current one. @tdalejandro proposed the `!=` and then measured the data
+  that showed it was doing all the work.
+
+- **Which gateways are affected.** Two independent setups now bracket this. A Waveshare
+  RS485 TO POE ETH (B) doing genuine Modbus-TCP-to-RTU translation showed **zero**
+  mismatches and 26 days of clean statistics from *before* the guard existed — so on good
+  hardware there was never anything to catch. A ShineWiFi-class serial bridge mismatches
+  roughly one poll in three. A persistent socket is not the cause: the clean setup uses
+  the same shared connection and the same 60 s interval. See
+  [RS485 gateways](docs/troubleshooting/rs485-gateways.md).
+
 - **The adaptive backoff never engaged on TCP connections** *(from v1.3.7)*. The shared
   path returned before reaching the failure counters.
 

docs/index.md

@@ -26,6 +26,7 @@ The integration polls your inverter directly over Modbus — the same protocol t
 - **[Raising an Issue](troubleshooting/raising-an-issue.md)** — what to include when reporting a bug
 - **[Diagnostic Service](troubleshooting/diagnostic-service.md)** — Universal Register Scanner
 - **[DTC Debugging](troubleshooting/dtc-debugging.md)** — device type code reference
+- **[RS485 Gateways](troubleshooting/rs485-gateways.md)** — which adapters work, and diagnosing one that doesn't
 - **[Adding Sensors](developer/adding-sensors.md)** — add registers and sensors to an existing profile
 - **[New Profile](developer/new-profile.md)** — support a new or unsupported inverter model
 - **[Release Notes](release-notes.md)** — changelog

docs/troubleshooting/rs485-gateways.md

@@ -0,0 +1,89 @@
+# RS485-to-TCP Gateways
+
+Most problems that look like integration bugs turn out to be the box between Home Assistant and the inverter. This page collects what has actually been measured on real hardware, with the issue numbers behind each claim.
+
+> A gateway can look correctly configured, pass a casual test, and still be the thing that's broken. Some fail loudly. The dangerous ones fail quietly.
+
+---
+
+## The one setting that matters most
+
+Your gateway must do **Modbus TCP to RTU translation**, not transparent passthrough.
+
+This integration uses `pymodbus`'s `ModbusTcpClient`, which speaks Modbus TCP with MBAP framing. A transparent passthrough forwards raw RTU bytes with no MBAP header, and the client cannot parse them. It will not work at all, no matter how good the hardware is.
+
+That is a **mode setting**, not a hardware quality question. Check it before buying anything or blaming anything else.
+
+---
+
+## Field-tested hardware
+
+### ✅ Waveshare RS485 TO POE ETH (B) — known good
+
+Firmware V1.523, reported in [#367](https://github.com/0xAHA/Growatt_ModbusTCP/issues/367) on a MID 25KTL3-XH.
+
+| Setting | Value |
+|---|---|
+| Protocol | `Modbus TCP to RTU` — **not** "None"/transparent |
+| Instruction Timeout | 288 ms — must exceed the transmission time of your largest block |
+| RS485 Conflict Gap | 20 ms |
+
+Measured: zero short/misaligned reads, 89 sensors populated, two full register scans of 2300 registers across 17 ranges with no read errors, and **26 days of statistics from before the v1.3.7 guard existed with no corrupt values at all**. On this gateway there was never anything to catch.
+
+### ⚠️ PUSR / ShineWiFi-class serial bridges — replay stale frames
+
+Reported in [#360](https://github.com/0xAHA/Growatt_ModbusTCP/issues/360) and [#367](https://github.com/0xAHA/Growatt_ModbusTCP/issues/367).
+
+These can return **a complete, valid response to an earlier request** when answering the current one. Measured at roughly **one poll in three**, with 30 of 31 mismatches returning exactly 125 registers regardless of what was asked for.
+
+Since v1.3.7 the integration detects this and discards the frame, so the data is safe — but you will see `Short/misaligned read at N: got X of Y registers` warnings. If you are on an older version, this is the failure mode that published a serial-number fragment as 85,893,614.8 W of AC power.
+
+Two settings materially improved a PUSR unit on #360:
+
+| Setting | Change | Why |
+|---|---|---|
+| TCP timeout | disabled → **30 s** | With it disabled, dead sessions are never reaped and eventually every connection slot is held by a connection to nobody |
+| UART AutoFrame | disabled → **100 ms** | Frame fragmentation causes the parser to lock onto the wrong byte offset and read a nonsense unit ID |
+
+### ❌ Olimex ESP32-POE-ISO + `esphome_modbus_bridge` — unstable
+
+Reported in [#367](https://github.com/0xAHA/Growatt_ModbusTCP/issues/367). Repeated dropouts, TCP host unreachable for two to three minutes at a time, recovering on its own with no pattern tied to load, time of day or PV production. RS485 bias resistors made no difference, which pointed at the network side rather than the serial side. Replaced with the Waveshare above.
+
+---
+
+## Diagnosing your own gateway
+
+**Is it replaying stale frames?** Look for `Short/misaligned read` warnings. Note whether the count returned is *larger* than requested — a reply longer than the request cannot be a truncation, and points at a replayed earlier response.
+
+**Is latency per-request or per-register?** This decides whether a smaller block size helps or hurts. Read the same register range at several block sizes and compare total time:
+
+- If time scales with the number of registers, smaller blocks help.
+- If time is roughly **fixed per request**, smaller blocks are much worse.
+
+On the PUSR unit in #367, 113 registers cost the same as 1 — every read landed in one of two clusters ~500 ms apart, which looks like an internal scheduling tick. Block size 1 would have meant ~113 requests of ~0.8 s each in place of a single 1.3 s read. **Block size 25 was kept.**
+
+**Careful measuring latency from logs.** A 15-18 s figure reported on #367 turned out to be the integration's own failure cycle — a 10 s timeout plus reset and retry — not gateway latency. Measure with raw sockets and the integration disabled.
+
+**Running a register scan?** Disable the integration entry first (**⋮ → Disable**, don't delete), wait ~30 s, then scan. The scanner opens a second connection, and on a sensitive gateway that contends with the poller. A scan taken while polling came back with 9 successful reads out of 1304 rows, every range reporting "no response" on a device that was working fine.
+
+---
+
+## Does a persistent connection cause this?
+
+No — and this was tested directly.
+
+The integration holds one socket per host:port across polls. It was suspected of allowing a stale frame to linger in the buffer, but the clean Waveshare setup uses **the same shared connection and the same 60 s interval** with zero mismatches. A persistent socket is not the mechanism; it is what exposes a gateway that replays. Since v1.3.7 a detected mismatch also drains the receive buffer, so a misaligned stream does not persist into the next read.
+
+| Gateway | Socket | Result |
+|---|---|---|
+| ShineWiFi-class | persistent | mismatch ~1 poll in 3 |
+| ShineWiFi-class | fresh per read | 21/21 clean |
+| Waveshare RS485 TO POE ETH (B) | persistent | clean |
+
+---
+
+## Keeping the cloud app working
+
+You do not necessarily have to choose. On both systems in #367 the inverter has a **`SYS COM` port separate from the USB port the ShineWiFi dongle occupies**, so a second RS485 master can run alongside the stock dongle. Home Assistant gets a local Modbus path, and the dongle keeps feeding Growatt's own app.
+
+Note this is one local path and one cloud path — not two paths into Home Assistant. If you keep the dongle, be aware the Growatt cloud can overwrite local writes to control registers within seconds; the integration logs a `Write reversion detected` warning when it sees this.