timeouts

Author: kellerza

docs/timeouts.md

@@ -253,7 +253,8 @@ User-facing keys from [multi-options](../www/docs/reference/multi-options.md) (a
 
 `DRIVER` is obsolete and ignored (startup fails if it is still set). mbusd has its own `TIMEOUT` if
 you use that add-on as a serial-to-TCP gateway. The mbusd timeout should always be lower than the
-addon timeout.
+addon timeout. User-facing comparison (add-on / pymodbus / mbusd / Solarman):
+[Wait times by component](../www/docs/reference/multi-options.md#wait-times-by-component).
 
 ## Related changes (edge, post-1.0.0)
 

www/docs/guide/fault-finding.md

@@ -124,7 +124,8 @@ diagnostic sensor on each inverter ([Stats](#stats)) shows whether timeouts are
   **0.15** if timeouts continue.
 - The most reliable way to connect is to use mbusd to the serial port & connect the addon to mbusd
   at `tcp://<ip>:502`. The mbusd instance/addon can be on the same physical device or a remote
-  device.
+  device. mbusd, pymodbus, and the add-on each have their own wait — see
+  [Wait times by component](../reference/multi-options#wait-times-by-component).
 
 Check the cabling and connection again. Use a 1m cable and stand next to the inverter while testing.
 

www/docs/guide/mbusd.md

@@ -10,3 +10,9 @@ When you add the Sunsynk HASS repository, it includes a mbusd addon called "Modb
 Gateway Add-on".
 
 <https://github.com/kellerza/sunsynk/tree/main/hass-addon-mbusd>
+
+Point the Sunsynk add-on at `tcp://homeassistant.local:502` (or the host that runs mbusd). mbusd has
+its own wait/retry on the RS485 leg — in add-on language that is **3** `READ_ATTEMPTS`, **500 ms**
+`TIMEOUT` (`-W`), and **100 ms** `READ_MESSAGE_SPACING` (`-R`). Keep that RTU wait shorter than the
+Sunsynk add-on's `TIMEOUT`. Comparison table:
+[Wait times by component](../reference/multi-options#wait-times-by-component).

www/docs/reference/multi-options.md

@@ -171,6 +171,18 @@ Global. Change these when a gateway or RS485 link is unreliable.
   Each group is tried `READ_ATTEMPTS` times. Increase on slow links. If timeouts persist, lower
   `READ_SENSORS_BATCH_SIZE` or increase `READ_MESSAGE_SPACING`.
 
+### Wait times by component
+
+Same three knobs at every layer. When the add-on talks through **pymodbus** or **mbusd**, those
+layers wait **as well**, so a missing reply can take longer than `TIMEOUT × READ_ATTEMPTS` alone.
+
+| Component                     | `READ_ATTEMPTS` | `TIMEOUT`         | `READ_MESSAGE_SPACING` | Notes                                                                                                                                                                                                                                         |
+| ----------------------------- | --------------- | ----------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Add-on default (tmodbus)      | **3**           | **3 s**           | **0.05 s**             | Per FC03/FC16 group. tmodbus does **not** retry a missing reply; the add-on does. Serial also waits **0.05 s** after connect. Worst case per group: `TIMEOUT × READ_ATTEMPTS`.                                                                |
+| pymodbus (`pymodbus-` `PORT`) | **3** (library) | Add-on `TIMEOUT`  | Add-on spacing         | pymodbus retries **3** times per request **on top of** the add-on. A silent bus waits longer than tmodbus.                                                                                                                                    |
+| mbusd                         | **3** (`-N`)    | **500 ms** (`-W`) | **100 ms** (`-R`)      | Serial-side gateway. Keep this RTU wait **shorter** than the add-on `TIMEOUT` so a dead inverter fails inside one add-on attempt. The mbusd add-on's own `TIMEOUT` option is TCP idle (`-T`, seconds), not `-W`. See [mbusd](../guide/mbusd). |
+| Solarman                      | **3**           | Add-on `TIMEOUT`  | —                      | `socket_timeout` only; no message gap. Prefer slower [schedules](./schedules).                                                                                                                                                                |
+
 ## Schedules
 
 `SCHEDULES` controls how often sensors are read and published. Defaults and Solarman-friendly