Skip to content
dcontrol

ModbusTCP

The ModbusTCP plugin connects to modbus devices over a TCP connection as a client.

Supported data types

The following modbus commands are supported:

  • 0x02 (2): read discrete input
  • 0x01 (1): read read coil
  • 0xf (15): write multiple coils
  • 0x04 (4): read input register
  • 0x03 (3): read holding register
  • 0x10 (16): write multiple holding registers

They are mapped to the following dcontrol types:

  • bool
  • int16
  • float
Data typeBOOLINT8INT16FLOATSTRING
read discrete input (0x02)⤴
read coil (0x01)⤴
write coils (0x15)⤶
read input register (0x04)⤴⤴
1
read holding register (0x04)⤴⤴
1
write holding registers (0x16)⤴⤴
1
  1. The float types map 2 16bit registers to a floating point value.

Depending on the type specified in the mapping, and an optional address prefix the correct modbus command is determined.

where

Discrete Inputs

Discrete inputs must have the bool type, they can optionally have the input_ prefix.

A valid mapping address could be

  • 1
  • input_1
Coils

Coils must have the bool type. To write a coil the address can be the modbus address, but for reading coils the prefix coil_ must be supplied to make it unambiguous from the discrete input. For writing this prefix is optional.

A valid mapping for a coil write (0x15) could be

  • 1
  • coil_1

A valid mapping for a coil read (0x01) could be:

  • coil_1
Input Registers

Input registers can have a int16 or float type. In most circumstances you’ll want the int16 which can hold a single input register value. When using the float type, two input registers will be read into a 32 bit value which becomes available as a float. Input registers can have the optional prefix input_register_. For the float types, some additional prefixes are available: input_register_abcd_, input_register_cdab_, input_register_badc_, input_register_dcba_. For an explanation on what the four letters at the end mean, please have a look at using 32 bit values.

A valid mapping could be

  • 1
  • input_register_1
Holding Registers

Holding registers can have a int16 or float type. In most circumstances you’ll want the int16 which can hold a single holding register value. When using the float type, two holding registers will be read or written into a 32 bit value which becomes available as a float. To write a holding register the address can be the modbus address, but for reading holding registers the prefix holding_register_ must mu supplied to make it unambiguous from the input register. For writing this prefix is optional. For the float types, some additional prefixes are available: holding_register_abcd_, holding_register_cdab_, holding_register_badc_, holding_register_dcba_. For an explanation on what the four letters at the end mean, please have a look at using 32 bit values.

Using 32 bit values

With input registers and holding registers it is possible to combine 2 16bit registers (either input registers or holding registers) into one 32 bit value, which becomes available as a float. To use 32 bit values the lower address must be supplied, and the type must be set as float.

By default, the first address will become the MSB (most significant byte, or 2 bytes to be precise), the second address will become the LSB (the least significant byte, or 2 bytes in this case). Optionally, this behaviour can be altered by adding the byte order to the address. This can be abcd, cdab, badc or dcba. Where each letter represents a single byte (8bits) of the 32 bit end result.

The abcd is the default, and is never necessary to be set, but can help in readability when you have to use multiple byte orders. The lower address becomes the most 2 significant bytes, the higher address becomes the 2 least significant bytes.

With cdab this is the exact opposite. The higher address becomes the 2 most significant bytes, the lower address the 2 least significant bytes.

The two other options, badc and dcba, swap the two bytes in the 16bit value read back from a register.

With badc the bytes in each 16bit value are swapping place, and the lowest address will become the 2 most significant bytes, the higher address the 2 least significant bytes.

With dcba the bytes in each 16bit value are swapping place, and the highest address will become the 2 most significant bytes, the lower address the 2 least significant bytes.

Configuration options

The minimal device config when using the default options would be:

devices:
  - type: modbusTCP
    name: gpio1
    options:
      ip: 10.0.0.8

This assumes that the tcp port is set to 502; and the scan rate at which the interface will be polled is the default of 200ms. The ip address field can be omitted in which case the plugin will fall back to the default 127.0.0.1 address.

A complete config would look like this:

devices:
  - type: modbusTCP
    name: gpio1
    options:
      ip: 10.0.0.8
      port: 502
      scan_rate: 50

where

type

is always “modbusTCP” as this is the name of this plugin.

name

unique arbitrary name.

options/ip

the ip address of modbusTCP node. (default: 127.0.0.1)

options/port

the tcp port that the modbusTCP interface is listening on. (default: 502)

options/scan_rate

this is the polling scan rate in ms and should be an integer. (default: 200)

Metrics

The following metrics are exported by the modbusTCP plugin. They are prefixed / namespaced with modbustcp_, and all of them have the label {instance:"plugin_name"} where plugin_name is the name specified in the settings.yml file with the name attribute.

Metric Name Metric Type Notes
General
connection_state Gauge The connection state of the modbusTCP device.
read_count Counter The total count of modbusTCP reads.
write_count Counter The total count of modbusTCP writes.
Modbus Read
discrete_input_value Gauge The current value for the discrete input.
discrete_input_changed_count Counter The total number of discrete input changes.
input_register_value Gauge The current value for the input register.
input_register_changed_count Counter The total number of input register changes.
coil_read_value Gauge The current value for the coil.
coil_read_changed_count Counter The total number of coil changes.
holding_register_read_value Gauge The current value of the holding register.
holding_register_read_changed_count Counter The total number of holding register changes.
Modbus Write
coil_value Gauge The current value for the coil output.
coil_changed_count Counter The total number of coil changes.
holding_register_value Gauge The current value for the holding register.
holding_register_changed_count Counter The total number of holding register changes.