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¶

Modbus TCPModbus RTU

[[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.