Modbus read task
Read the coils and registers of a Modbus server into channels.
A Modbus read task reads coils and registers from one Modbus server into channels. For example, it can record a tank level from holding registers 0 and 1 of a PLC at 10 Hz.
Before you start, you need a connected server.
Registers and coils
A read task reads four types of data, each with its own address range:
A register holds 16 bits. An 8-bit or 16-bit value uses one register, and an 8-bit value is the low byte. A 32-bit value uses two registers, and a 64-bit value uses four. The Data type of the channel sets the size. A bit channel reads one bit of a register, and a string channel reads two characters from each register.
For each type, the Driver reads the addresses of the task in as few requests as it can. One request holds at most 125 registers or 2000 coils or discrete inputs. A request also reads the addresses between your channels, up to the Max gap of the server. Lower Max registers or Max gap for a device that rejects long reads or unused addresses.
The Driver timestamps each read with the computer clock. See timing.
Byte and word order
By default, the Driver reads the low word of a 32-bit or 64-bit value first (word swap, CDAB). Many devices send the high word first (big-endian, ABCD). The Byte order of the server sets the order for every register channel of the server.
To change the order of one channel, select its Byte order in the channel list. From device uses the order of the server, and names it. The other options set the order of the channel, whatever the server sets:
An 8-bit or 16-bit value fits in one register, so its channel offers only Big-endian
and Little-endian, which set bytes_swapped. In code, leave bytes_swapped and
words_swapped unset to use the order of the server.
Create a Modbus read task
Console
Python
TypeScript
- In the devices toolbar, right-click the server and select Create read task.
- Set Sample rate and Stream rate.
- The task starts with one coil channel. To add more, click Add channel, or click a free address in the register map above the channel list.
- In the channel list, set the Type and the Address of each channel. For a register, select the Data type. For a string, set the Length. For a bit, set the Bit.
- Click (Start).
The register map shows a lane for each register type, on one address scale. An address that a channel uses is filled. A hatched band marks an address that two channels use. Click a used address to select its channel, or right-click it to open the menu of the channel.
The Console creates the channels. For the server Pump skid PLC, a float32 holding
register at address 0 gives Pump_skid_PLC_holding_register_input_0_f32, and a coil at
address 3 gives Pump_skid_PLC_coil_input_3. The index channel is Pump_skid_PLC_time.
Python does not create channels. Create them first.
import synnax as sy
from synnax import modbus
dev = client.devices.retrieve(name="Pump skid PLC")
time = client.channels.create(
name="plc_time", is_index=True, data_type=sy.DataType.TIMESTAMP
)
level = client.channels.create(
name="tank_level", index=time.key, data_type=sy.DataType.FLOAT32
)
pump_on = client.channels.create(
name="pump_on", index=time.key, data_type=sy.DataType.UINT8
)
task = modbus.ReadTask(
name="Pump skid",
device=dev.key,
sample_rate=10,
stream_rate=5,
channels=[
modbus.HoldingRegisterReadChannel(
address=0, data_type="float32", words_swapped=True, channel=level.key
),
modbus.CoilReadChannel(address=3, channel=pump_on.key),
],
)
client.tasks.configure(task)
task.start()TypeScript does not create channels. Create them first.
import { modbus } from "@synnaxlabs/client";
const [dev] = await client.devices.retrieve({
where: { name: { eq: "Pump skid PLC" } },
});
const time = await client.channels.create({
name: "plc_time",
isIndex: true,
dataType: "timestamp",
});
const level = await client.channels.create({
name: "tank_level",
index: time.key,
dataType: "float32",
});
const task = await client.tasks.create({
name: "Pump skid",
rack: dev.rack,
type: "modbus_read",
config: modbus.readConfigZ.parse({
device: dev.key,
sampleRate: 10,
streamRate: 5,
channels: [
{
type: "holding_register",
address: 0,
dataType: "float32",
wordsSwapped: true,
channel: level.key,
},
],
}),
});
await task.start();Task options
Channel reference
Each channel has an address, from 0 to 65535, and a channel, the Synnax channel that
records the value. Each table shows the Console label of a setting, with its Python
field under it.
The Console also accepts a six-digit Modicon address, such as 300001 for input register 0. The first digit is the table: 0 for coils, 1 for discrete inputs, 3 for input registers, and 4 for holding registers. The Console shows the Modicon form next to each address.
Strings
Each register holds two characters, the high byte first. A Byte order of
Little-endian (bytes_swapped set to True) puts the low byte first. The string
ends at the first NUL character. The Synnax channel of a string must have the string
data type.
Troubleshooting
“Illegal data address”
The server does not have one of the addresses in a request. The error names the channels
and the addresses of the request. Check the address map of the device. Some devices
count addresses from 1, so try the address minus 1. If the server does not have the
addresses between two channels, set Max gap of the server to 0.
“unsupported data type: …”
The Driver does not support the data type of the channel. Select a data type from the channel reference.
The values are wrong
Set the byte and word order of the server or the channel. Check that the data type matches the device.
The connection dropped
The Driver reconnects and sends the request again at once, up to the Retries of the server. If that fails, the task keeps running and shows the warning “Failed to read data”. The Driver tries again, up to every 5 seconds, until the server is back.
For other problems, see Connect a Modbus server and Troubleshoot hardware.