Skip to content

IndustryKit Modbus

The Modbus source actively reads the configured Coils, Discrete Inputs, Input Registers, and Holding Registers. Adjacent addresses in the same area are combined into one read.

Configuration hierarchy

Level Purpose
[[sources]] Defines a Modbus collection task. Repeat it to configure multiple devices or units.
[sources.modbus] Configures the TCP/RTU connection and request timeout for the current source.
[sources.modbus.serial] Configures the local serial port for RTU only.
[[sources.modbus.points]] Defines one point to read. Each item adds one output field.

Each [[sources]] entry can contain only one protocol subtable. type = "modbus" must correspond to [sources.modbus]. field is the output field name written to the measurement, while area and address identify the location to read from the device.

Configuration

[[sources]]
id = "plc-tcp"
type = "modbus"
measurement = "modbus_metrics"
interval = "10s"
tags = { device = "plc-01" }

[sources.modbus]
transport = "tcp"
address = "192.0.2.10:502"
unit_id = 1
timeout = "2s"

[[sources.modbus.points]]
field = "pump_running"
area = "coil"
address = 0
data_type = "bool"

[[sources.modbus.points]]
field = "tank_level"
area = "holding"
address = 100
data_type = "uint16"
scale = 0.1

[[sources]]
id = "meter-rtu"
type = "modbus"
measurement = "modbus_metrics"
interval = "10s"
tags = { device = "meter-01" }

[sources.modbus]
transport = "rtu"
unit_id = 7
timeout = "2s"

[sources.modbus.serial]
device = "/dev/ttyUSB0"
baud_rate = 19200
data_bits = 8
parity = "even"
stop_bits = 1

[[sources.modbus.points]]
field = "energy_total"
area = "holding"
address = 0
data_type = "uint64"
byte_order = "big"
word_order = "high"

On Windows, use a COM device name for the serial port, such as COM3. Check Device Manager for the actual port name.

Options

[[sources]]

Field Default Description
id None Required and unique within the configuration. It is also added as the source_id tag.
type None Must be set to modbus.
measurement industrial Name of the reported metric measurement or log source.
interval 10s Polling interval. It must be greater than 0.
tags {} Static tags for this source.

[sources.modbus]

Field Default Description
transport None Required: tcp or rtu.
address Empty Required for TCP, in host:port format. Do not set it for RTU.
unit_id TCP: 0; RTU: none Modbus Unit/Slave ID. For RTU, explicitly set it to 1–247 according to the device manual.
timeout 2s Timeout for one protocol request. It must be greater than 0.

[sources.modbus.serial]

This table is used only when transport = "rtu".

Field Default Description
device None Required serial device for RTU, such as /dev/ttyUSB0 on Linux or COM3 on Windows.
baud_rate 19200 Serial baud rate.
data_bits 8 Number of data bits, in the range 5..8.
parity even Parity mode: none, even, or odd.
stop_bits 1 Number of stop bits: 1 or 2.

[[sources.modbus.points]]

Field Default Description
field None Required output field name.
category metric Output category: metric or logging.
tags {} Static tags for this point.
area None Required: coil, discrete, input, or holding.
address 0 Zero-based PDU address, not a displayed address such as 40001 from a device manual.
data_type None Required: bool, int16, uint16, int32, uint32, int64, uint64, float32, float64, or string.
length 1 Number of registers used only by string, in the range 1..125.
byte_order big Byte order within each register: big or little.
word_order high Word order for multi-register values: high or low.
scale 1 Multiplier used for numeric transformation.
offset 0 Numeric transformation offset. The final value is value * scale + offset.
on_change false Whether a metric is sent only when its value changes. Logging data is always sent on change.
emit_initial false Whether to send the first observed value for logging data or a metric with on_change enabled.
status info Status field used only for logging data.

Displayed addresses such as 40001 in a device manual are usually not PDU addresses. For example, 40001 often corresponds to address = 0. Always verify the mapping against the device manual.

Linux serial-port permissions

The IndustryKit service runs as the industrykit user by default. Modbus TCP requires no additional permissions. Before using Modbus RTU, make sure this user can read and write the configured serial device. Run the following commands as root.

First, check which group owns the device:

ls -l /dev/ttyUSB0

If the device belongs to the dialout group, run:

usermod -aG dialout industrykit
systemctl restart industrykit

Some distributions use the uucp group. In that case, replace dialout with uucp in the command. You must restart the service after adding the supplementary group so that the new process receives the permission. Switch to the industrykit user to verify read and write access:

su -s /bin/sh -c 'test -r /dev/ttyUSB0 && test -w /dev/ttyUSB0' industrykit

If the serial device does not have an appropriate group, do not add industrykit to the root group. An administrator should use a udev rule to grant a dedicated group read and write access based on the serial adapter's Vendor ID and Product ID.

Data and limitations

  • coil and discrete points can only use bool.
  • Each source must contain at least one point. The same combination of field and final tags cannot be repeated.
  • Only read operations are supported. Writing Coils or Holding Registers is not supported.

Feedback

Is this page helpful?