Home Assistant Modbus: How Do You Set Up Modbus TCP and RTU Devices?

Your heat pump has an Ethernet port that speaks Modbus TCP, the energy meter in your panel has two RS485 terminals, and the ventilation controller in the garage talks Modbus too. The short answer: Home Assistant Modbus support works through a connection (called a hub) with individual entities underneath it, each of which reads one register. Modbus TCP needs only the device’s IP address; Modbus RTU also needs a bridge from RS485 to your Home Assistant machine.

The real work is in the details: device address, register type, data type, byte order and scaling. Where neither cable nor Wi-Fi reaches, LoRaWAN helps.

How does the Modbus integration in Home Assistant work?

Modbus is a request-response protocol: Home Assistant acts as the client (older manuals say “master”) and polls the devices at fixed intervals. Each device has an address between 1 and 247, called the slave ID, unit ID or device address depending on the manual.

The data lives in four areas: coils are writable bits like a relay, discrete inputs are read-only bits like a fault contact. Input registers hold read-only 16-bit values like measurements, and holding registers are 16-bit values you can read and often write, such as a setpoint. Where each value sits is documented in the manufacturer’s register map, and you need it, because Modbus only defines the transport, not what the numbers mean.

There are two routes. Many device-specific integrations use Modbus under the hood and are set up in the UI like any other integration: you enter host and port or the serial port, and the integration already knows the registers. If no such integration exists for your device, you use the generic Modbus integration, which is configured in configuration.yaml only. Check for a dedicated integration first; it saves you the register map work.

Home Assistant Modbus TCP: what does the configuration.yaml look like?

A Modbus TCP connection consists of a hub with a name, type, host and port, plus at least one entity, otherwise the integration does not load. The standard Modbus TCP port is 502. Here is a complete example for a temperature stored in a holding register with a factor of 0.1:

modbus:
  - name: heating
    type: tcp
    host: 192.168.1.50
    port: 502
    sensors:
      - name: Flow temperature
        slave: 1
        address: 100
        input_type: holding
        data_type: int16
        scale: 0.1
        precision: 1
        unit_of_measurement: "°C"
        device_class: temperature
        state_class: measurement
        scan_interval: 30

The slave key is the slave ID of the device. Current documentation calls the same field device_address; both spellings mean the same thing, and both default to 1. The address matters once a gateway bundles several RS485 devices behind one IP.

scan_interval sets how often Home Assistant reads the register. The default is 15 seconds, and 0 turns regular polling off. For a flow temperature, 30 or 60 seconds is plenty. Overly short intervals are a common cause of an overloaded connection.

For more devices, add further hubs under the same modbus: key, each with its own unique name. Restart Home Assistant after every change, since YAML hubs load at startup.

How do you connect RS485 Modbus RTU devices to Home Assistant?

Modbus RTU runs over a serial line, almost always RS485. The machine running Home Assistant has no such port, so you need a bridge. The simplest option is a USB-to-RS485 adapter. In configuration.yaml this becomes a hub of type serial with the required keys port, baudrate, bytesize, method, parity and stopbits, with method set to rtu. Use the stable path under /dev/serial/by-id/ rather than /dev/ttyUSB0, so the mapping survives reboots and extra USB devices. In a virtual machine, pass the adapter through to the VM.

If your server sits far from the device, a serial device server on your network is the alternative: an RS485-to-Ethernet converter. Depending on its mode, it either translates Modbus RTU into true Modbus TCP (use type tcp) or passes the RTU frames through unchanged, which is RTU over TCP (use type rtuovertcp). With a socket:// URL, Home Assistant does not pass on a baud rate, so you set it on the device server itself.

The serial settings must match exactly on both sides. The Modbus spec names 8 data bits, even parity and 1 stop bit as the default, yet many devices ship with 9600 baud and 8N1. A parity mismatch makes a device go silent.

Wiring follows the usual RS485 rules: a twisted pair for A and B, devices daisy-chained in a line rather than in a star, a 120-ohm termination resistor at both ends of the line, and a common reference ground where the devices provide one. At low baud rates, runs of around 1,200 meters (about 4,000 feet) are possible. Manufacturers don’t use the A and B labels consistently, so if nothing answers, swapping the two wires is a quick and harmless test.

Only one client may poll an RS485 bus. If a controller or energy manager already polls the devices, you can’t simply wire Home Assistant in parallel.

How to set data type and scaling for Modbus registers in Home Assistant

A register holds exactly 16 bits. Larger values are spread across two or four consecutive registers. You tell Home Assistant how to read the bits with data_type, which defaults to int16. Only for string and custom do you set the register count yourself with count. Here is how typical register map entries line up:

The “Registers” column decides whether you read the right range at all. With 32-bit values, register order matters too: some devices send the high word first, others the low word. That is what swap is for: byte swaps the bytes (AB becomes BA), word swaps the two registers (ABCD becomes CDAB), and word_byte reverses everything (ABCD becomes DCBA). word and word_byte are not allowed with 16-bit types.

If the map says “resolution 0.1 °C”, the device sends 215, and with scale: 0.1 and precision: 1 Home Assistant shows 21.5 °C. Also watch how addresses are counted: some maps list registers as 40001, others start at 1, while the protocol itself starts at 0. Home Assistant expects the protocol address. A value off by exactly one register almost always comes from this offset.

Whether you read a holding register or an input register is set with input_type. Sensors accept holding (the default) and input; binary sensors can also read coil and discrete_input. The wrong area gives you an error or, worse, a plausible but wrong value.

Modbus proxy in Home Assistant: when do you need one?

Many Modbus TCP devices accept only one connection at a time. This is common with solar inverters, EV chargers and energy meter gateways. If an energy manager or a second system already polls the device, one side keeps losing its connection, and your values keep dropping to “unavailable”.

A Modbus proxy solves this. It holds the single connection to the device and offers its own Modbus TCP port that several clients can share. A transparent proxy forwards every request, so the device still carries all the load; a caching proxy polls the device itself and answers clients from its cache.

First check whether you really create two connections. Home Assistant bundles device integrations that use the same address and port onto one shared connection, but a YAML hub always opens its own. So if you run an integration for your device and also a YAML hub pointing at the same IP, you get two connections. Dropping one of the two routes is often simpler than adding a proxy.

ESPHome Modbus: when is ESPHome the better option?

ESPHome flips the approach. Instead of running an RS485 cable to your Home Assistant machine, you place an ESP32 with an RS485 transceiver module right next to the device. The ESP32 polls the registers and sends finished values over Wi-Fi through the ESPHome API. You configure a UART, the modbus component and a modbus_controller with the device address. Sensors get a register type, address and value type such as U_WORD or FP32.

ESPHome is the better choice when the device is far from your server but within Wi-Fi range, say in a basement boiler room or a detached garage. By default, modbus_controller polls every 60 seconds and retries a failed command up to four times; both can be adjusted.

Know the limits: you build and maintain the hardware yourself, you need an enclosure and a clean power supply, and the link is only as reliable as your Wi-Fi at that spot. Also, YAML hubs cannot use an ESPHome serial proxy as their interface. With ESPHome, the ESP32 handles all Modbus polling itself.

Modbus timeout in Home Assistant: what to do when a device does not respond

A timeout means no usable reply arrived within the waiting period. By default Home Assistant waits 3 seconds (timeout), and on serial connections it also leaves 30 milliseconds between two messages (message_wait_milliseconds). If the device sends an exception response, such as “illegal data address”, it understood you, and the problem lies in the register or register type. If nothing comes back at all, the fault is further upstream: address, serial settings, wiring or network.

For Modbus RTU, check in this order: is the slave ID right, do baud rate, parity and stop bits match, are A and B wired correctly, are the termination resistors at the ends rather than in the middle, and is no second client polling the same bus? For Modbus TCP, check the IP address, port, firewall and a possible second connection. A successful ping doesn’t prove the Modbus service answers.

Some devices need a moment after the connection opens; delay adds a wait before the first message. If the error only shows up now and then, look at the polling load: requests on one hub run one after another. An unreachable device holds the connection until the timeout expires on every attempt, and every other entity waits with it. Generous scan_interval values and removing dead entities help more than a longer timeout.

If you are still stuck, enable debug logging for homeassistant.components.modbus and pymodbus. The log shows whether a reply arrives, is garbled or contains an exception.

Can you bring Modbus devices into Home Assistant over LoRaWAN?

Yes, with one extra step: for a device in an outbuilding or plant room without a network, you put an RS485-to-LoRaWAN converter next to it. The converter acts as the Modbus client on site, polls the configured registers at fixed intervals and sends the values by radio to a LoRaWAN gateway. A network server such as The Things Stack or ChirpStack decodes them and hands them to Home Assistant over MQTT. In Home Assistant they show up as MQTT sensors, not through the Modbus integration.

Three devices cover this path. The Milesight UC100 has an RS485 port for Modbus RTU devices, supports baud rates from 1,200 to 115,200, up to 32 polling channels with one or two registers each, and selectable byte orders. Response time and retries are configurable; it runs on 5 to 24 V DC. The RAKwireless RAK7431 accepts 8 to 48 V DC, addresses up to 16 RS485 devices with up to 32 commands, and offers a transparent mode alongside polling. The Dragino RS485-LN is the third option for the same job. Our guide to RS485 and LoRaWAN covers the converter setup step by step.

The limits are real. LoRaWAN carries small payloads, and in the European 868 MHz band a 1 percent duty-cycle rule limits how often a device may transmit. Intervals of minutes make sense, not seconds. Writes travel as downlinks and only arrive at the next contact. Fine for meter readings, temperatures and fault alarms; not for fast control loops.

Where can you buy a LoRaWAN Modbus converter?

Before you pick a converter, start with your device’s register map: which values do you need, which register type holds them, and are they 16-, 32- or 64-bit values? That tells you how many polling channels you need and whether the converter must support a particular byte order. The converter must also support your device’s baud rate, parity and stop bits.

Power at the installation site matters too. A wide input range lets you feed the converter from an existing 24 V supply in a control cabinet. On the radio side, a LoRaWAN gateway must reach the location, and your network server must pass the values to Home Assistant over MQTT. Expect intervals of minutes and check that this suits your values. If a cable or stable Wi-Fi is available, a direct link through a USB-to-RS485 adapter or ESPHome is usually faster and cheaper.

If you’re looking for a converter for your Home Assistant Modbus setup, you’ll find our models in the Modbus category.

Home Assistant Modbus FAQ

Can Home Assistant poll multiple Modbus devices at the same time?

Yes. You can define several hubs, for example one per TCP device, and poll several devices with different slave IDs on one RS485 bus through a single hub. Requests within one hub run sequentially, so keep polling intervals generous with many devices.

Does Home Assistant support Modbus RTU over TCP?

Yes, through the hub type rtuovertcp. It is meant for serial device servers that pass RTU frames through the network unchanged. If your gateway converts the data into true Modbus TCP instead, use type tcp.

Why does Home Assistant show wrong Modbus values?

Usually one of four settings is off: the data type, the byte or word order (swap), the scaling, or a register address shifted by one. Huge numbers where you expect small values point to the wrong order, and 65,535 instead of −1 points to a missing signed type. Compare the raw value with the register map.