Files
esphome-yambms/documents/README/Understanding_ESPHome_Modbus.md

10 KiB
Raw Permalink Blame History

YamBMS - Understanding ESPHome Modbus

Badge License: GPLv3 Badge Version GitHub stars GitHub forks GitHub watchers

Work in progress. The ESPHome Modbus stack is being reworked by @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) 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:

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:

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.