219 lines
10 KiB
Markdown
219 lines
10 KiB
Markdown
# YamBMS - Understanding ESPHome Modbus
|
||
|
||
[](https://www.gnu.org/licenses/gpl-3.0)
|
||
[](https://github.com/Sleeper85/esphome-yambms/releases/latest)
|
||

|
||

|
||

|
||
|
||
> **Work in progress.** The ESPHome Modbus stack is being reworked by
|
||
> [@exciton](https://github.com/exciton) through a long series of pull requests.
|
||
> The first of them landed in ESPHome 2026.7, and more are on the way — including
|
||
> a full overhaul of `modbus_controller`
|
||
> ([#11781](https://github.com/esphome/esphome/pull/11781)) that will change how
|
||
> commands are queued and how offline devices are handled. This page tracks that
|
||
> work and will be updated progressively as the PRs are merged.
|
||
|
||
Starting with **ESPHome 2026.7**, the Modbus client timing defaults have changed
|
||
(`send_wait_time` 250 ms → 2000 ms, `turnaround_time` 100 ms → 600 ms).
|
||
These new defaults are safe for slow third-party hardware, but they are far too
|
||
conservative for a YamBMS setup where many fast ESP32-based servers share one bus.
|
||
|
||
YamBMS therefore ships its own defaults:
|
||
|
||
```yaml
|
||
substitutions:
|
||
# UART
|
||
modbus_baud_rate: '19200' # 9600 / 19200 / 115200
|
||
# Modbus
|
||
modbus_id: '1'
|
||
modbus_send_wait_time: '200ms' # Timeout: max time to wait for the FIRST byte of a response
|
||
modbus_turnaround_time: '0ms' # Pause after a completed response before the next command
|
||
# Modbus Controller
|
||
modbus_update_interval: '5s' # Frequency with which BMS/Balancer/Shunt (modbus servers) are queried
|
||
|
||
modbus_controller:
|
||
max_cmd_retries: 1 # Retransmissions after a timeout (default is 4)
|
||
offline_skip_updates: 5 # Server re-polled every 30s with an update_interval of 5s
|
||
```
|
||
|
||
> **The one idea to remember:** what costs time on the bus is the **number of
|
||
> Modbus commands per cycle**, not the number of servers. A BMS whose register
|
||
> map has gaps generates several commands instead of one. Reducing the command
|
||
> count is usually worth more than raising the baud rate.
|
||
|
||
---
|
||
|
||
## What each parameter does
|
||
|
||
### `send_wait_time` — response timeout
|
||
|
||
Maximum time the client waits for the **first byte** of a response. If nothing
|
||
has started arriving within this time, the command is treated as failed.
|
||
|
||
* It is a **latency** budget, not a transmission budget: it does not depend on
|
||
the baud rate or on the response length. Once the first byte arrives, the
|
||
client waits for the whole response however long it takes.
|
||
* It only costs time **when a server does not answer**. Lowering it has no effect
|
||
on a healthy bus — it just bounds the price of a failure.
|
||
|
||
An ESPHome server on ESP32 answers within one pass of its main loop (16 ms by
|
||
default). `200ms` leaves ample margin for an occasional slow loop (WiFi burst,
|
||
API reconnect, flash write) without ever mistaking a busy server for a dead one.
|
||
|
||
### `turnaround_time` — inter-command pause
|
||
|
||
Pause inserted after a completed response, before the next command. It exists to
|
||
give slow devices time to get ready for the next frame.
|
||
|
||
**It is charged per command, not per server** — including between two commands
|
||
sent to the same BMS. With 24 BMS generating 4 commands each, a
|
||
`turnaround_time` of 100 ms would add 96 × 100 ms = **9.6 s** to every cycle.
|
||
|
||
`0ms` is the right value for an all-ESPHome bus. It never produces truly
|
||
back-to-back frames: the Modbus specification silence (3.5 characters) is always
|
||
enforced, and the ESPHome main loop adds its own scheduling delay on both sides.
|
||
|
||
### `update_interval` — polling frequency
|
||
|
||
How often each `modbus_controller` reads **all** its register ranges. All
|
||
controllers fire at roughly the same time and the resulting commands are
|
||
serialized on the bus, one conversation at a time.
|
||
|
||
### `max_cmd_retries` — retransmissions
|
||
|
||
Retransmissions of a timed-out command before giving up (not counting the initial
|
||
transmission). ESPHome defaults to `4`; YamBMS uses `1`. One retry absorbs a
|
||
transient glitch, and a genuinely dead server is handed to `offline_skip_updates`
|
||
quickly instead of blocking the bus.
|
||
|
||
### `offline_skip_updates` — offline back-off
|
||
|
||
Once a server has exhausted its retries it is marked **offline**, and this many
|
||
update cycles are skipped before it is probed again. With `5`, a silent server is
|
||
re-polled every `(5 + 1) × update_interval` = **30 s**. As soon as it answers a
|
||
probe it is marked online and normal polling resumes — no reboot or manual action
|
||
needed.
|
||
|
||
---
|
||
|
||
## Reducing the number of commands
|
||
|
||
ESPHome merges **consecutive** registers into a single range, and reads each
|
||
range with one Modbus command. A single unmapped register in the middle splits
|
||
the range in two — and every extra command costs a request frame, a response
|
||
frame, and a fixed scheduling overhead.
|
||
|
||
### Fill the gaps with `register_count`
|
||
|
||
`register_count` can span a gap. Set it on the sensor **before** the gap, sized
|
||
to reach the next register you actually want. The registers in between are read
|
||
and discarded.
|
||
|
||
Example — a PACE BMS map with gaps at register 8 and registers 13–14:
|
||
|
||
| Sensor to modify | Value | Effect |
|
||
|------------------|-------|--------|
|
||
| last sensor before the gap (address 7) | `register_count: 2` | absorbs register 8 |
|
||
| last sensor before the gap (address 12) | `register_count: 3` | absorbs registers 13–14 |
|
||
|
||
Ranges `0–7`, `9–12` and `15–36` then merge into a **single command covering
|
||
0–36**, taking that BMS from 4 commands per cycle down to 2 — roughly a third off
|
||
the total cycle time, for the cost of 3 useless registers read (6 bytes).
|
||
|
||
> Check first that the skipped registers are actually **readable** on your
|
||
> device. An invalid register anywhere inside a range makes the whole command
|
||
> fail with a Modbus exception.
|
||
|
||
### `force_new_range` — use sparingly
|
||
|
||
`force_new_range: true` (default `false`, available on every `modbus_controller`
|
||
platform) prevents a sensor from joining the previous range, forcing a separate
|
||
command. It works in the *opposite* direction to the optimisation above, so use
|
||
it only to isolate genuinely static registers that can then carry a high
|
||
`skip_updates`.
|
||
|
||
Two things to know:
|
||
|
||
* `skip_updates` applies to the **whole range**, and ESPHome keeps the lowest
|
||
non-zero value among its sensors. One fast sensor inside a large block forces
|
||
the entire block to the fast rate.
|
||
* Sensors marked `force_new_range` are sorted **before** all others, ahead of the
|
||
address sort. Marking one sensor in the middle of a block does not split it in
|
||
two — it pulls that sensor to the front and lets the rest merge. To split a
|
||
block, mark the first sensor of each intended segment.
|
||
|
||
It is also set automatically for any sensor using `custom_command`.
|
||
|
||
### Sensors can share a range for free
|
||
|
||
Several sensors may read the same registers without any extra bus traffic — they
|
||
all decode the same response buffer. A `delta cell voltage` sensor declared at the
|
||
same address as `cell voltage 1`, with a lambda walking all 16 cells, costs
|
||
**zero** additional commands. Two declarations at the same address produce one
|
||
transaction, not two.
|
||
|
||
### YAML order: when it matters
|
||
|
||
Sensors are sorted internally (by register type, `force_new_range`, address, then
|
||
offset), so their order in the file is normally irrelevant.
|
||
|
||
**Except when two sensors share the same address and offset.** The final
|
||
tie-break is allocation order — that is, YAML order — and the sensor that comes
|
||
first defines the range's `register_count`.
|
||
|
||
With `cell voltage 1` (1 register) and `delta cell voltage`
|
||
(`register_count: 16`) both at address 15:
|
||
|
||
* `cell voltage 1` **first** → the range opens with count 1, cells 2–16 extend it
|
||
normally → **one command**. ✅
|
||
* `delta` **first** → the range opens with count 16, cell 2 no longer fits the
|
||
extension test → **a second range starts**, and registers 16–30 are read twice. ❌
|
||
|
||
Leave a comment in your YAML so nobody reorders these by accident.
|
||
|
||
---
|
||
|
||
## Tuning guide
|
||
|
||
* **`send_wait_time`**: set it to the slowest observed "time to first byte" of any
|
||
server on the bus, with generous margin. `200ms` suits all-ESPHome/ESP32 buses.
|
||
Raise it only if a device that is genuinely alive produces spurious timeouts.
|
||
Do **not** raise it "to be safe": it is the unit price of every dead-server
|
||
event.
|
||
* **`turnaround_time`**: keep `0ms` on an all-ESPHome bus. For a slow third-party
|
||
device try `10–30ms` first; `100ms` (the old ESPHome default) is the safe
|
||
fallback for unknown hardware, and `200–600ms` only for VFDs and gateways.
|
||
Remember the cost is per command.
|
||
* **Mixed buses**: `turnaround_time` belongs to the *hub*, so one slow device
|
||
imposes its value on all your BMS. Put slow third-party hardware on a **second
|
||
UART** with its own `modbus:` hub rather than raising the global value.
|
||
* **`modbus_baud_rate`**: `19200` is a good default. Gains flatten out above it,
|
||
because per-command scheduling overhead starts to dominate transmission time —
|
||
merge ranges before reaching for a higher baud rate.
|
||
* **`update_interval`**: leave enough headroom that the full cycle still fits when
|
||
a server is dead. If some entities stop refreshing while others keep updating,
|
||
the cycle is overrunning the interval — reduce the command count, raise the
|
||
interval, or split the bus.
|
||
* **`offline_skip_updates`**: `(value + 1) × update_interval` is the re-probe
|
||
period. `5` → every 30 s at a 5 s interval. Lower it to `3` for faster recovery
|
||
detection.
|
||
|
||
---
|
||
|
||
## Checking your configuration
|
||
|
||
Set the logger to `DEBUG` (or `VERBOSE` for the range details) and watch a few
|
||
cycles:
|
||
|
||
```yaml
|
||
logger:
|
||
level: DEBUG
|
||
```
|
||
|
||
* Ranges are logged as they are built — the quickest way to confirm that a
|
||
`register_count` gap fill actually merged what you expected.
|
||
* `Modbus command timed out` on a device that is alive means `send_wait_time` is
|
||
too low, or the bus is saturated.
|
||
* `Modbus device=N set offline` / `back online` traces the offline back-off.
|