Modbus

Connect a Modbus TCP device and read or write its registers and coils as tags.

Modbus reads and writes the registers and coils of a Modbus TCP device. You add the device with its network connection, then create a tag for each register or coil you want to collect.

Connecting a Modbus device

Setting	What it does
Name	Identifies the device in the project. An optional custom name gives it a friendlier alias.
Enabled	Whether THMI connects to the device to receive data. Turn it off to stop all communication and value collection without deleting the device.
Host	The hostname or IP address used to reach the device on the network.
Port	The TCP port of the Modbus device. Defaults to 502, the standard Modbus TCP port.
Timeout	How long to wait for a response before treating the request as failed. Defaults to 5 seconds (5000 ms).
Unit ID	Identifies the specific device within the Modbus network — used when several devices sit behind one gateway. Ranges from 0–255 (default 1).

Reading a value: the function

Each Modbus tag reads from one of four areas, chosen with the function. This also determines whether the value can be written back:

Function	Holds	Access
Coils	Single on/off bits	Read and write
Discrete inputs	Single on/off bits	Read-only
Holding registers	16-bit registers	Read and write
Input registers	16-bit registers	Read-only

Coils and discrete inputs are single bits, so they map to a bool data type. Holding and input registers are 16-bit, so larger numbers are read from several consecutive registers:

Data type	Registers spanned
`int16` / `uint16`	1 register
`int32` / `uint32` / `float`	2 registers
`int64` / `double`	4 registers

The start address is the register or coil address where the tag begins reading. Array data types read several values back-to-back from there; set the number of values to control how many.

Byte and word order (swap mode)

When a value spans more than one register, devices disagree on the order those bytes and 16-bit words are laid out in. The swap mode corrects for this so the number is reconstructed correctly. Take the 32-bit value 0x12345678, read from two registers:

Swap mode	Effect	`0x12345678` becomes
None	Bytes as received.	`12 34 56 78`
Bytes	Swap the two bytes within each word.	`34 12 78 56`
Words	Swap the order of the words.	`56 78 12 34`
Bytes and words	Swap both.	`78 56 34 12`

If a multi-register number reads as garbage or wildly wrong, the swap mode is almost always what needs adjusting — match it to the byte order in the device’s documentation. Swap mode doesn’t apply to single-bit coil and discrete-input values.

See Data types for the full list and what each one means.

Polling and writing

Polling interval — how often, in milliseconds, THMI reads the value. Defaults to 5000 (5 seconds).
Writable — lets users with permission manually change the value (see Values and history). It’s only available for the read-write functions (coils and holding registers) and single (non-array) values; discrete inputs and input registers are always read-only.