Modbus is how Home Assistant talks to real industrial equipment. A greenhouse boiler controller, a variable-frequency drive on a pump, a commercial HVAC system, an environmental controller in a compliance-grade operation — all of these typically speak Modbus as their integration protocol. For agricultural operations with any substantial commercial equipment, Modbus is the bridge between Home Assistant and the industrial world. The protocol is older than most others covered in this sub-section, wired rather than wireless, slightly more complex to configure, and extremely reliable once working. This page covers Modbus fundamentals, the distinction between RTU (serial) and TCP (networked) variants, register mapping and the common data types encountered in agricultural equipment, the Home Assistant configuration patterns, and the failure modes that affect Modbus integrations. An operation integrating a commercial controller through Modbus gains access to the data and control that commercial systems often hide behind vendor apps.
Modbus fundamentals.
Modbus is an industrial communication protocol developed in 1979 by Modicon (now Schneider Electric). It has remained dominant in industrial automation for four decades because of its simplicity, openness, and broad hardware support.
The client-server model.
Modbus uses a client-server architecture (historically called master-slave). A client initiates requests; a server responds. For Home Assistant integrations:
- Home Assistant is typically the client. It reads values from and writes values to devices. - Industrial equipment (boiler controllers, VFDs, sensors) is typically the server. It provides its data through a Modbus interface.
Multiple servers can share a single bus (for RTU) or a single network (for TCP), each identified by a unique address (Unit ID or Slave ID).
RTU vs. TCP.
Modbus RTU. Binary protocol over serial (RS-485 typically). One client, many servers on a shared bus. Wire pairs between devices; termination resistors at each end of the bus. Simple, robust, range typically hundreds of meters on a single RS-485 bus.
Modbus TCP. Modbus protocol over TCP/IP networks. Each server has its own IP address and port. No shared bus; the Ethernet network connects devices. Higher-performance, simpler topology for many-device deployments.
Modbus RTU over TCP. A hybrid — RTU framing over TCP. Less common but sometimes encountered in gateway devices that convert RTU buses to Ethernet.
Many devices support both RTU and TCP. Choice depends on the deployment — RTU for simple daisy-chained deployments and legacy equipment; TCP for modern installations where equipment has Ethernet ports.
Register types.
Modbus data lives in four register spaces:
- Coils. Single-bit read/write values (on/off states). Used for switches, valves, binary outputs. - Discrete inputs. Single-bit read-only values. Used for sensor inputs (door open, pressure switch tripped). - Holding registers. 16-bit read/write values. Used for setpoints, configuration, and multi-bit control values. - Input registers. 16-bit read-only values. Used for sensor readings, status values.
Many agricultural integrations live in holding registers (for readable and controllable values like setpoints) and input registers (for sensor readings).
Data types within registers.
A 16-bit register holds small values directly (integer 0-65535 or -32768 to 32767). Larger values or fractional values pack into multiple registers:
- 32-bit integer or float. Two consecutive registers. Byte order matters (big-endian vs. little-endian; word order within the 32-bit value also varies). - String. Multiple consecutive registers, each holding two ASCII characters. - Scaled integer. A register holds an integer that must be divided by a scaling factor to produce the real value (register value 2345 with scale 0.1 represents 234.5).
The device's documentation specifies which registers hold which values, which data types they use, and any scaling factors. This documentation is essential for configuring the integration.
Common agricultural devices that speak Modbus.
Equipment categories that commonly use Modbus:
Boiler and heating controllers.
Commercial greenhouse heating boilers and their associated controls typically speak Modbus. Integration allows reading current temperature, target setpoint, boiler status, fuel consumption, and commanding setpoint changes. A greenhouse with a commercial boiler controller usually can expose its data through Modbus without changing the existing control system.
Variable-frequency drives (VFDs).
VFDs control pump and fan speeds. Industrial VFDs (ABB, Siemens, Schneider, Mitsubishi, others) speak Modbus — typically RTU over RS-485, sometimes TCP. Integration allows reading current speed, power draw, fault status, and commanding speed changes. Useful for variable-speed ventilation and variable-speed pumping where Home Assistant should adjust speed based on conditions.
Industrial environmental controllers.
Dedicated environmental controllers for commercial greenhouses and indoor farms typically have Modbus interfaces. Provides a bridge from the commercial controller's detailed environmental logic to Home Assistant's dashboards, alerting, and automation.
Solar inverters.
Many solar inverters speak Modbus for monitoring and some control. For operations with solar systems, this integration brings energy data into Home Assistant.
Commercial HVAC.
Larger HVAC units — rooftop units, split systems with BMS integration, chillers — commonly support Modbus. For packhouses and workspaces with commercial HVAC, integration provides monitoring and control.
Power monitoring and energy meters.
Industrial power meters, current transformers, and energy monitors frequently use Modbus. Provides detailed energy monitoring beyond what smart plugs can offer for larger circuits.
Water treatment and fertigation equipment.
Commercial fertigation controllers and water treatment systems often have Modbus interfaces. Integration brings nutrient concentration, pH, EC, and flow data into Home Assistant.
Motor starters and relay controllers.
Industrial relay controllers and motor starters with Modbus interfaces. More flexible than smart plugs for switching larger loads.
Modbus hardware for Home Assistant.
The Home Assistant host needs a way to talk Modbus.
For Modbus TCP.
No additional hardware beyond the existing network. The Home Assistant host connects to Modbus TCP devices through the regular Ethernet network. Devices need IP addresses; Home Assistant connects via IP.
For Modbus RTU.
The Home Assistant host needs an RS-485 interface. Options:
USB-to-RS485 adapter. little. Plugs into a USB port on the host. Widely available. Quality varies; isolated adapters are preferred for industrial environments to protect the host from electrical issues on the RS-485 bus.
RS-485 expansion card. For deeper integration, PCIe or similar cards provide RS-485 ports with good performance and isolation.
Ethernet-to-RS485 gateway. A small network-connected device that bridges Ethernet to RS-485. The host connects via Ethernet; the gateway handles the RS-485 bus. Useful when the Modbus devices are far from the host or when using a single host for multiple RTU buses at different locations.
For mixed environments.
Operations with both Modbus TCP and Modbus RTU devices can use each appropriately. A single Home Assistant integration configuration can include multiple Modbus hubs (one TCP, one RTU) and map devices across them.
Home Assistant Modbus configuration.
Modbus in Home Assistant is configured in YAML (in configuration.yaml or a separate included file). The configuration defines hubs (connections to Modbus networks) and devices on those hubs.
A basic TCP configuration.
A basic RTU configuration.
Multi-device configurations.
For deployments with many Modbus devices, the YAML grows accordingly. Separating the Modbus configuration into its own file (with `!include` in configuration.yaml) keeps things manageable.
Polling cadence.
Home Assistant polls Modbus devices at a configurable interval (`scan_interval`). Faster polling means more current data but more bus traffic. For most sensor data, 10-30 second polling is appropriate; control-critical values may need faster polling.
RTU buses have capacity limits — very fast polling of many devices can saturate a single RS-485 bus. Staggered polling or grouping related registers into single requests (block reads) reduces bus traffic.
Register mapping.
The most time-consuming part of Modbus integration is mapping the device's registers to Home Assistant entities.
Getting the register documentation.
Each Modbus device has its own register map. This comes from:
- Device manufacturer's documentation (often a specific "Modbus register map" document). - Sometimes available in the device's user manual. - For custom devices, whatever documentation exists.
Register maps specify: - Register address (0-65535) - Register type (coil, discrete input, holding register, input register) - Data type (bit, int16, int32, float32, string) - Scaling factor - Units - Meaning
Indexing conventions.
A source of confusion: Modbus register addresses can be expressed in two conventions:
- 0-indexed. Register 40001 in 1-indexed convention becomes register 0 in 0-indexed. Home Assistant configuration typically uses 0-indexed. - 1-indexed (40001 style). Some documentation uses 5-digit register addresses where the first digit indicates register type (4xxxx for holding registers, 3xxxx for input registers). Subtract 1 and strip the type prefix to get the 0-indexed address.
When a device's documentation says "holding register 40050," the Home Assistant configuration likely uses `address: 49` (40050 - 40001 = 49, 0-indexed holding register).
Byte and word order.
Multi-register values (32-bit floats, 32-bit integers) require the correct byte/word order:
- Big-endian / little-endian for bytes within a register. - Word order (which register comes first) for multi-register values.
Common patterns: "AB CD" (standard big-endian), "CD AB" (byte-swapped), "BA DC" (word-swapped), "DC BA" (fully reversed). The device documentation specifies the order; getting it wrong gives wildly wrong values.
Testing register reads.
Before adding a device to Home Assistant permanently, a command-line tool (mbpoll, pymodbus's CLI, Modscan) can verify communication. Reading a known register and comparing the value to the device's display confirms the Modbus address and data type are correct.
Common Modbus tasks for agriculture.
Specific tasks that come up in agricultural Modbus integrations.
Reading a temperature.
Single register holding a scaled integer. Register address, data type, scaling factor (often 0.1 for degrees), unit of measurement.
Reading a 32-bit value.
Two consecutive registers interpreted as one value. Data type (int32 or float32), word/byte order.
Writing a setpoint.
A register the device accepts writes to. Home Assistant can provide a number input entity that writes to the register when changed.
Reading a status bit.
A single bit within a register, or a coil/discrete input. Often used for equipment status (running, tripped, in-alarm).
Reading a group of related values.
Many devices expose groups of related values in consecutive registers. Configuring Home Assistant to read the group in a single request (block read) is more efficient than individual reads.
Commanding a control action.
Writing a specific value to a specific register triggers an action on the device. Depends heavily on the device — consult its documentation for the specific command protocol.
Modbus failure modes.
Specific problems that affect Modbus deployments.
The register address that was off by one. Device documentation used 1-indexed addresses; Home Assistant uses 0-indexed. Reads returned wrong values or nothing. Fix: check indexing convention, subtract 1 from documented addresses.
The byte order that was wrong. A float value read back as a nonsense number. Investigation: byte/word order didn't match device. Fix: try alternative orders (AB CD, CD AB, BA DC, DC BA) until values make sense.
The bus termination that was missing. RS-485 bus without proper termination resistors had intermittent communication — most reads worked, some failed. Fix: 120 ohm termination resistors at each end of the RS-485 bus.
The RS-485 wiring that was reversed. A/B wires were swapped. No communication at all. Fix: check wiring against device documentation; RS-485 wiring is sensitive to A/B orientation.
The baud rate mismatch. Host configured for 9600 baud; device configured for 19200. No communication. Fix: verify baud rate at both ends and match.
The shared bus that got too busy. RS-485 bus with 15 devices polled every second became saturated. Some requests timed out. Fix: reduce polling frequency, stagger polls, or split devices across multiple buses.
The isolation that was missing. A non-isolated USB-to-RS485 adapter allowed electrical noise from industrial equipment to reach the Home Assistant host, causing occasional host issues. Fix: isolated RS-485 adapter, or fiber-optic isolation between buses.
The device that changed its addresses after a firmware update. Firmware update shifted register addresses; Home Assistant configuration was stale. Symptoms: wrong values or unavailable sensors. Fix: check firmware release notes, update Home Assistant configuration.
The device that needed specific bit-field interpretation. A register held multiple status bits, each meaning something different. Reading it as a simple integer produced a meaningless number. Fix: template sensors that extract specific bits from the raw register value.
The network that wasn't. Modbus TCP device was on a different network segment than Home Assistant host; routing wasn't configured. No connection. Fix: verify network path; add routes or move devices as appropriate.
What not to do.
Don't skip the register-map documentation. Modbus integration without the device's register map is a guessing game with many wrong answers.
Don't assume byte order. Try both possibilities when reads return nonsense; match what the device actually uses.
Don't skimp on RS-485 installation. Proper wiring (twisted pair, correct A/B orientation) and termination matter. Failed RTU buses often come back to wiring issues.
Don't mix unrelated devices on the same bus at high poll rates. Bus capacity is finite; many devices polled fast can saturate a single bus.
Don't use unisolated RS-485 adapters in industrial environments. Electrical noise protection matters. An isolated adapter is little more than a non-isolated one.
Don't write to registers without understanding the consequences. A wrong value to a control register can cause equipment to malfunction. Test writes in non-production contexts first.
Don't assume Modbus integration makes a device's safety interlocks irrelevant. Existing hardware safety remains critical regardless of Modbus visibility.
Don't neglect polling cadence. Too fast saturates buses; too slow misses changes. Tune per device.