Step 0: check for a ready-made integration
Home Assistant's Modbus documentation says that many devices already have their own integration that uses Modbus underneath, so you often do not need to write register maps yourself. Browse the Modbus-controlled category in the HA integrations list or search for your brand when adding an integration. Only if nothing exists do you need to configure registers manually (YAML). The same page also describes a Modbus connections view under Settings > Connectivity > Modbus for checking connections.
Terms that trip people up
- Unit ID (also called slave ID, device address or just address): identifies a device on a Modbus line. HA calls it device_address in YAML (older configs use slave). Most devices default to 1, and each device on one RS-485 line needs a unique one.
- Coils (read/write bits), discrete inputs (read-only bits), input registers (read-only 16-bit) and holding registers (read/write 16-bit). Picking the wrong table is the number one reason for "illegal data address" errors. Sensors are usually input or holding registers, depending on the vendor.
- Function codes: commonly 01/02/03/04 for reads (coils, discrete inputs, holding, input), and 05/06/15/16 for writes.
- Addressing: manuals often use reference numbers like 30001 (input) or 40001 (holding). On the wire, the first register is address 0. Some manuals are zero-based, some one-based, so a point may appear to be off by one. If a value looks wrong, try address minus or plus one.
- 32-bit values take two registers, and vendors disagree on word order. Home Assistant has a swap option for byte and word order. A float that decodes to nonsense, or a counter that jumps around, is almost always the word order.
- Modbus TCP: over Ethernet, usually port 502. Easiest if the device or a gateway has an Ethernet port. Many devices ship with it switched off, so check the manual or app.
- Modbus RTU: serial over RS-485, with settings that must match exactly: baud rate, data bits, parity and stop bits. One master per line, multiple devices on a daisy chain.
- RTU over TCP is a variant where RTU frames travel inside TCP, typically via a serial gateway. HA's hub types include tcp, rtuovertcp, udp and serial.
The HA documentation lists the ways to reach an RTU device: a USB to RS-485 adapter connected to Home Assistant, an ESPHome serial proxy with an RS-485 port, or a serial device server on the network. In practice:
- USB to RS-485 adapter: cheapest and simplest if the meter is near the Home Assistant machine. Prefer an isolated one if you can, since it protects the computer from noise and ground differences.
- ESPHome serial proxy / ESP32 with an RS-485 transceiver: good when the meter is in a remote switchboard, since only Wi-Fi or Ethernet needs to reach it. Check the ESPHome documentation for current details.
- Ethernet serial gateway: a robust option for long distances, and it keeps Modbus on a controlled network.
- Use shielded twisted pair and daisy-chain devices, not a star. Termination (typically 120 ohm) belongs at the two physical ends of the bus only, if the run is long or speeds are high.
- A/B (or D+/D-) labelling is inconsistent between vendors. If you get timeouts and the settings are right, try swapping the two wires. This is normally harmless on a correctly designed RS-485 interface, but check the device manual.
- Connect the signal ground or common where the manuals suggest, and avoid running RS-485 beside mains cable.
Security and reliability
- Modbus TCP has no authentication or encryption. Never port-forward port 502, and keep inverters and meters on a segmented network.
- Write registers only when you must. On some devices, repeatedly writing the same holding register may wear internal memory, so check the manual before automating writes.
- Do not poll faster than you need. Slow serial lines (2400 or 9600 baud) get saturated quickly.
- The HA Modbus docs list a default scan_interval of 15 seconds per entity.
Use a command-line tool such as mbpoll (GPL-3) or the pymodbus library to read registers from a laptop first, then copy the working settings into Home Assistant. The project thread in this forum does exactly this for an Eastron SDM230.
Links
Question for the group: which Modbus devices are you running at home (meter, inverter, heat pump, other), and what was the single biggest hurdle: wiring, addressing or word order?