gatewaytimeout

Author: kellerza

docs/modbus-connection-plan.md

@@ -64,8 +64,8 @@ classDiagram
 
 ## `for_unit` is the server id
 
-Yes. `connection.for_unit(id)` is the Modbus **unit id** (also called slave id, device id, or server
-id). It is the same value as:
+Yes. `connection.for_unit(id)` is the Modbus **unit id** (server id; device id). It is the same
+value as:
 
 - `Sunsynk.server_id` today
 - add-on `MODBUS_ID` / `InverterOptions.modbus_id`

docs/modbus-connection.md

@@ -22,8 +22,8 @@ The public API stays `Sensor` + `Sunsynk.read_sensors(sensors)`. Internally, hol
 goes to a unit. The add-on stores one `ModbusConnection` per port and passes
 `connection.for_unit(modbus_id)` into each inverter.
 
-`for_unit(id)` is the Modbus **server id** (slave / device id): today’s `Sunsynk.server_id` and
-add-on `MODBUS_ID`. It is not a register address.
+`for_unit(id)` is the Modbus **server id** (device id): today’s `Sunsynk.server_id` and add-on
+`MODBUS_ID`. It is not a register address.
 
 ## What hurts today
 

docs/timeouts.md

@@ -47,10 +47,11 @@ all `for_unit()` handles on that port). **0** disables the gap.
 
 Library callers that omit `message_spacing` still get `DEFAULT_MESSAGE_SPACING` (0.05).
 
-On **timeout**, `Sunsynk` calls `ModbusConnection.disconnect()` (not `close()`) so the next FC03
-reconnects with an empty receive buffer. tmodbus already disconnects on desync (bad function code /
-header mismatch); it did not disconnect on timeout, which left garbage bytes for the next poll
-(`Received data with no pending requests`, `0x79`).
+On **timeout** and **gateway target failed to respond** (Modbus exception **0x0B** /
+`GatewayTargetError`), `Sunsynk` calls `ModbusConnection.disconnect()` (not `close()`) so the next
+FC03 reconnects with an empty receive buffer. Gateways often return 0x0B when the inverter misses
+the reply window; a late frame then shows up as `Received unexpected response with Transaction ID`.
+tmodbus already disconnects on desync (bad function code / header mismatch).
 
 ---
 
@@ -74,8 +75,8 @@ v1.0.0 **tmodbus** is stricter:
    before a new frame. tmodbus enforces that gap from the **send** time (`_last_frame_ended_at` is
    updated when the request is written). By the time the inverter replies, that interval has already
    elapsed, so the **next poll can go out immediately** after the response is parsed.
-2. **Slow slaves** — Deye inverters and USB-FTDI adapters often need tens of milliseconds after a
-   reply before they accept another master request. Polling back-to-back produces intermittent
+2. **Slow servers** — Deye inverters and USB-FTDI adapters often need tens of milliseconds after a
+   reply before they accept another client request. Polling back-to-back produces intermittent
    timeouts (~every 10s with default `TIMEOUT`, matching field reports in #672).
 3. **FTDI latency** — FT232R and similar chips buffer serial data (default latency timer ~16ms).
    tmodbus documents that true inter-frame silence detection is unreliable on USB serial; it sizes
@@ -150,7 +151,7 @@ Requests are serialized on **one `ModbusConnection` per PORT** string. Multiple
 same gateway share that connection; modbus-connection’s lock and pacer ensure only one transaction
 is in flight at a time.
 
-Timeouts here are usually **gateway or multi-master** issues rather than RTU turnaround:
+Timeouts here are usually **gateway or multi-client** issues rather than RTU turnaround:
 
 - **`Received unexpected response with Transaction ID`** — another client is talking to the same
   gateway, or the gateway returned a late MBAP frame for an earlier request (#672, multi-inverter
@@ -252,6 +253,7 @@ addon timeout.
 - [modbus-connection#213](https://github.com/home-assistant-libs/modbus-connection/pull/213) —
   serial `timeout` passed through to tmodbus (fixes `TIMEOUT` being ignored on RTU; does not add
   spacing).
-- **50ms `message_spacing`** in `open_connection()` — addresses back-to-back polling on serial /
+- **`READ_MESSAGE_SPACING`** (default **0.05s**) plus **disconnect** on timeout and gateway **0x0B**
+  (`GatewayTargetError`) — addresses back-to-back polling and late gateway replies on serial /
   RTU-backed links ([#672](https://github.com/kellerza/sunsynk/issues/672)).
 - Removal of nested **`asyncio.timeout`** wrappers — avoids double cancellation; see edge CHANGELOG.

hass-addon-mbusd/README.md

@@ -1,7 +1,7 @@
 # Modbus TCP to Modbus RTU Gateway Add-on
 
-This Add-on uses the [mbusd](https://github.com/3cky/mbusd) gateway. It provides a TCP-Slave (or
-server) which acts as a RTU-master to get data from Modbus RTU-slave devices.
+This Add-on uses the [mbusd](https://github.com/3cky/mbusd) gateway. It provides a TCP **server**
+which acts as an RTU **client** to get data from Modbus RTU **servers**.
 
 I use this mainly for testing, but mbusd can also be deployed on a low-spec device (i.e. Raspberry
 Pi 1b) to convert an RS-485 connection to TCP.

hass-addon-sunsynk-edge/CHANGELOG.md

@@ -6,6 +6,12 @@
 
 All items below are changes since add-on **1.0.0** (stable release on GitHub `main`).
 
+- **Breaking:** three-phase **Parallel Mode** select options are **Client** (was Master) and
+  **Server** (was Slave). The inverter LCD may still say Master/Slave. Update automations that match
+  the old strings.
+- Docs use Modbus **client** / **server**: the add-on is the client (initiates requests); each
+  inverter is a server (replies). `MODBUS_ID` is the server id. See
+  [Modbus](https://kellerza.github.io/sunsynk/guide/overview#modbus).
 - **Breaking:** leftover `DRIVER` is no longer ignored — startup fails until it is removed. `tcp://`
   plus a non-zero `DONGLE_SERIAL_NUMBER` still remaps to `solarman://`; a dongle serial with a
   serial device path fails instead of warning.
@@ -20,8 +26,9 @@ All items below are changes since add-on **1.0.0** (stable release on GitHub `ma
 - Modbus requests wait **`READ_MESSAGE_SPACING`** seconds after each reply (default **0.05**).
   tmodbus's RTU 3.5-character gap is measured from *send*, so v1.0.0 issued the next poll as soon as
   the previous reply was parsed — too fast for Deye + USB-FTDI / RS485 gateways. Raising `TIMEOUT`
-  does not add that gap. On timeout, the add-on **disconnects** the Modbus link so the next request
-  reconnects with a clean buffer ([#672](https://github.com/kellerza/sunsynk/issues/672)).
+  does not add that gap. On timeout or gateway **0x0B** (`GatewayTargetError`), the add-on
+  **disconnects** the Modbus link so the next request reconnects with a clean buffer
+  ([#672](https://github.com/kellerza/sunsynk/issues/672)).
 - `TIMEOUT` is the client/socket deadline for connect and each register I/O. Nested
   `asyncio.timeout` wrappers (including the **`2 × TIMEOUT`** batch cap) are removed so a hang is
   not cancelled twice. Solarman uses the same `TIMEOUT` for `socket_timeout` and does not retry

src/sunsynk/definitions/three_phase_common.py

@@ -498,7 +498,7 @@
     SelectRWSensor(
         336,
         "Parallel Mode",
-        options={0: "Slave", 1 << 1: "Master"},
+        options={0: "Server", 1 << 1: "Client"},  # inverter LCD: Slave / Master
         bitmask=1 << 1,
     ),
     SelectRWSensor(

src/sunsynk/sunsynk.py

@@ -9,7 +9,7 @@
 from dataclasses import dataclass, field
 from typing import Protocol, cast, runtime_checkable
 
-from modbus_connection import ModbusTimeoutError
+from modbus_connection import GatewayTargetError, ModbusTimeoutError
 from modbus_connection.tmodbus import ModbusConnection
 
 from sunsynk.connection import open_connection
@@ -92,11 +92,11 @@ async def connect(self) -> None:
         if connect is not None:
             await connect()
 
-    async def _flush_modbus_connection(self) -> None:
+    async def _flush_modbus_connection(self, *, reason: str) -> None:
         """Drop the tmodbus link so the next request reconnects with an empty buffer."""
         if self.connection is None or not self.connection.connected:
             return
-        _LOG.debug("Flushing Modbus connection after timeout (%s)", self.port)
+        _LOG.debug("Flushing Modbus connection after %s (%s)", reason, self.port)
         await self.connection.disconnect()
 
     async def write_register(self, *, address: int, value: int) -> bool:
@@ -107,7 +107,13 @@ async def write_register(self, *, address: int, value: int) -> bool:
         except TimeoutError:
             _LOG.error("timeout writing register %s=%s", address, value)
             self.timeouts += 1
-            await self._flush_modbus_connection()
+            await self._flush_modbus_connection(reason="timeout")
+        except GatewayTargetError as err:
+            _LOG.error(
+                "gateway target failed writing register %s=%s: %s", address, value, err
+            )
+            self.timeouts += 1
+            await self._flush_modbus_connection(reason="gateway target error")
         except Exception as err:
             _LOG.error("failed to write register %s=%s: %s", address, value, err)
         return False
@@ -148,8 +154,12 @@ async def read_holding_registers(self, start: int, length: int) -> Sequence[int]
             return await self.unit.read_holding_registers(start, length)
         except TimeoutError:
             self.timeouts += 1
-            await self._flush_modbus_connection()
+            await self._flush_modbus_connection(reason="timeout")
             raise OSError(f"timeout reading register {start}") from None
+        except GatewayTargetError:
+            self.timeouts += 1
+            await self._flush_modbus_connection(reason="gateway target error")
+            raise
 
     async def read_sensors(self, sensors: Iterable[Sensor]) -> None:
         """Read a list of sensors - Sunsynk supports function code 0x03."""

src/tests/sunsynk/test_connection.py

@@ -3,7 +3,12 @@
 from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
-from modbus_connection import ModbusSerialParams, ModbusTcpParams, ModbusUdpParams
+from modbus_connection import (
+    GatewayTargetError,
+    ModbusSerialParams,
+    ModbusTcpParams,
+    ModbusUdpParams,
+)
 from modbus_connection.mock import MockModbusConnection
 
 from sunsynk.connection import DEFAULT_MESSAGE_SPACING, open_connection, url_to_params
@@ -110,3 +115,19 @@ async def test_read_holding_registers_timeout_without_connection(
     with pytest.raises(OSError, match="timeout reading"):
         await ss.read_holding_registers(1, 1)
     assert ss.timeouts == 1
+
+
+async def test_read_holding_registers_gateway_target_flushes(
+    state: InverterState,
+) -> None:
+    """Gateway 0x0B (target failed to respond) flushes the link like a timeout."""
+    unit = MagicMock()
+    unit.read_holding_registers = AsyncMock(side_effect=GatewayTargetError())
+    conn = MagicMock()
+    conn.connected = True
+    conn.disconnect = AsyncMock()
+    ss = Sunsynk(unit=unit, state=state, connection=conn)
+    with pytest.raises(GatewayTargetError):
+        await ss.read_holding_registers(176, 2)
+    assert ss.timeouts == 1
+    conn.disconnect.assert_awaited_once()

www/docs/guide/fault-finding.md

@@ -45,6 +45,10 @@ Modbus read, a timer is armed: if reads are still failing once that many seconds
 the last success, the add-on pauses normal polling for that inverter for the configured skip period,
 then probes the serial register once before resuming or extending stale quiet.
 
+A parallel AC setup (inverter **Parallel Mode** Client / Server) does **not** mean both inverters
+share the RS485 Modbus bus. If the second inverter never appears, see
+[Parallel inverters](#parallel-inverters) below.
+
 If you fail to get a reply from the inverter, typically if step #2 fails, please check the
 following:
 
@@ -149,3 +153,40 @@ RS485 devices are typically multi-drop with a termination resistor on the first
 However, the RS485 BMS port may only be intended to connect to a single device.
 
 ![RS485](../images/rs485-term.jpg =70%x)
+
+## (D) Parallel inverters — second inverter not responding {#parallel-inverters}
+
+The add-on can poll several inverters on **one** adaptor when they share a physical RS485 bus: same
+`PORT`, unique `MODBUS_ID` (and `SERIAL_NR` / `HA_PREFIX`) per unit. See
+[Shared RS485 bus](../reference/multi-options#port).
+
+Parallel Mode does **not** automatically daisy-chain Modbus. If only one inverter answers, or the
+other goes **stale** / startup shows no response, test **one inverter at a time** with the **same**
+USB adaptor. Change only which RJ45 you plug into and the single `INVERTERS` entry. The inverter LCD
+may still say Master / Slave for Parallel Mode; this add-on uses **Client** / **Server**. See
+[Modbus](./overview.md#modbus).
+
+1. **Baseline — inverter 1 only.** Plug the cable into inverter 1. Configure one `INVERTERS` entry
+   for that unit (`MODBUS_ID` matching its **Modbus SN**). If this fails, it is a normal connection
+   problem — follow (A)–(C).
+
+2. **Inverter 2 on its own socket.** Move the **same** cable to inverter 2. Change the config to
+   inverter 2 only (`HA_PREFIX`, `MODBUS_ID`, `SERIAL_NR`). If this fails while plugged into
+   inverter 2, inverter 2 is not answering Modbus: check its Modbus SN, cabling, and whether that
+   model exposes RS485 on the port you are using when Parallel Mode is Server.
+
+3. **Is the bus shared?** Plug the cable back into inverter 1. Keep the **inverter 1** config. Then
+   move the cable to inverter 2 **without changing the config**.
+
+   - If inverter 1 still answers with the cable on inverter 2, the RS485 bus **is** shared — use the
+     **same** `PORT` for both `INVERTERS` entries, with unique `MODBUS_ID`s.
+   - If it goes silent, the bus is **not** shared. Use **two adaptors** (two `PORT`s), one per
+     inverter.
+
+4. **Optional cross-check.** Cable on inverter 1, config for inverter 2 only. A reply means inverter
+   2 is reachable through inverter 1's socket (shared bus). No reply means the bus is not shared, or
+   inverter 2's `MODBUS_ID` is wrong.
+
+When using two adaptors, `MODBUS_ID` must match whatever unit actually answers on **that** adaptor.
+Some units in Server mode still answer as `1` on their own RS485 port even when the display shows a
+different Modbus SN.

www/docs/guide/mbusd.md

@@ -3,7 +3,8 @@
 mbusd is an open-source Modbus TCP to Modbus RTU (RS-232/485) gateway. It presents a network of RTU
 servers as single TCP server.
 
-That is a TCP-Server, which acts as a RTU-Client to get data from Modbus RTU-Server devices.
+That is a TCP server, which acts as an RTU client to get data from Modbus RTU servers. See
+[Modbus](./overview.md#modbus) for client / server.
 
 When you add the Sunsynk HASS repository, it includes a mbusd addon called "Modbus TCP to Modbus RTU
 Gateway Add-on".