Skip to content

Modbus Device Service Component

The Modbus Device Service component provides communication and control with devices supporting the Modbus protocol. Modbus supports communication using either RS485 serial or Ethernet connections. These are referred to as RTU and TCP/IP respectively.

Using the device service with Modbus RTU differs subtly from using it for Modbus TCP connections, so we'll cover the differences on this page. No driver-specific configuration is required for the Modbus device service.

The Modbus Device Service supports the following key features:

  • Read. Data can be read from each primary table using the appropriate function code:
Primary Table Modbus Function
Coils 1
Discrete Inputs 2
Holding Registers 3
Input Registers 4
  • Write. Data can be written to each writable primary table using the appropriate function code:
Primary Table Modbus Function
Coils 15
Holding Registers 16
  • Support for Modbus RTU connection types
  • Support for Modbus TCP/IP connection types
  • Batch read operation. Read multiple values in a single Modbus call from each primary table, using the function codes seen in the first table above
  • Batch write operation. Write multiple values in a single Modbus call to each writable primary table, using the function codes seen in the second table above

Modbus Device Service Configuration


Since there are no driver-specific configuration options for Modbus, please refer to Device Service Component Configuration for all the relevant core components that will need populated in order to run the Modbus device service.

An example configuration can be seen below:

  "Library": "<Name of shared object to use>",
  "Factory": "<Name of service factory>",
  "Name": "<Name of device service>",
  "QueueMax": <maximum number of requests to queue>,
  "AutoRegister": <true|false>,
  "PublishRegisteredDevices": <true|false>,
  "PublishAttributes": <true|false>,
  "ProfileDir": "<path to directory containing service profiles>",
  "StateDir": "<path to directory containing service state>",
  "Scheduler": "<Scheduler component name>",
  "Logger": "<Logger component name>",
  "ThreadPool": "<ThreadPool component name>",
  "Bus": "<Bus component name>"

Modbus Device Profile

Details on general profile usage can be found on the Device Profiles page.

Required Profile Attributes

Ensure that the following profile attributes are defined in the device profile:

Attribute Description
primaryTable Identifies the primary table. The primary table must be one of the following:
startingAddress The address at which to start reading/writing in the Modbus device's representation of memory

The Property value type decides how many registers are read. Like Holding registers, a register has 16 bits. If the device manual specifies that a value has two registers, define it as FLOAT32, INT32, or UINT32 in the device profile.

Once we run a command, device-modbus knows its value type and register type, startingAddress, and register length. So, it can read or write a value using the Modbus protocol.

Optional Profile Attributes

The Modbus Device Service also allows you to define optional attributes.

The following optional profile attributes can be defined in the device profile:

Attribute Description
rawtype Defines the binary data read from the Modbus device and uses a value descriptor data type to identify the data type that the user wants to receive
isByteSwap Defines whether to swap the byte on reading little-endian data to transform to big-endian format.

The Modbus Device Service uses big-endian format.

If the Modbus device uses little-endian format, set this attribute to true to correctly convert the data.
isWordSwap Defines whether to use 16-bit segments, also known as words, to re-order the byte sequence with big-endian or little-endian formats

To re-order the byte sequence, set this attribute to true
boolIndex Retrieves the bool value from the specified bit of a register

The default is 0

For HOLDING_REGISTER and INPUT_REGISTERS, the valid range is 0 to 15, inclusive

For COILS and DISCRETE_INPUT, the value is 0
stringEncoding The supported string encoding

Valid values are UTF8 or ASCII

Default is UTF8
stringRegisterSize Defines the capacity of the device resource for the string data

Valid range is from 1 to 123 , inclusive

Default is 1

For example, to store the "Hello World" string in ASCII encoding, we need 96 bits (12 characters multiplied by 8 bits), so the required stringRegisterSize would be 6 (96 bits divided by 16 bits)

For the read command, the Modbus device reads the data types from the specified startingAddress for the length specified in the stringRegisterSize and parses the binary data to a sting with the encoding specified in stringEncoding

For the write command, the Modbus device checks that the parameter is a valid string in the specified encoding, converts the string to data bytes and writes it back to the register

Data Types

The Modbus Device Service supports the following data types:

  • Boolean
  • UInt8, UInt16, UInt32, UInt64
  • Int8, Int16, Int32, Int64
  • Float32, Float64

Device Commands

See the Device Commands page for details on how to define device commands for grouping device resources for fewer requests.

Modbus Device Provisioning

When provisioning a device for use in XRT, we must provide it with the protocol properties. In order to do this, add the devices to the file pointed to by the stateDir field of modbus_device_service.json.

An example of where to assign this field can be found in Modbus Device Service Configuration

Modbus Protocol Properties

The available Modbus protocol properties are described in the following table:

Protocol Property Description Valid Values
UnitID The station identifier Values up to 247
Address For Modbus TCP/IP, the IP address or host name

For Modbus RTU, the path to the serial device
Port Used for Modbus TCP/IP only

The TCP port of the Modbus device
BaudRate Used for Modbus RTU only

The baud rate for a serial device

The provided baud rate must match for devices using the same address
Unsigned integer
DataBits Used for Modbus RTU only

The number of bits of data
Valid values are as follows:
  • 5
  • 6
  • 7
  • 8
StopBits Used for Modbus RTU only

The number of stop bits
Valid values are as follows:
  • 1
  • 2
Parity Used for Modbus RTU only

The parity value

Specify N for no parity

Specify E for even parity

Specify O for odd parity
Valid values are as follows:
  • N
  • E
  • O

Modbus Device Service Provisioning Example

An example configuration for the Modbus TCP Device Service component is provided below, using the DENT.Mod.PS6037 network power meter as an example:

  • Name: DENT.Mod.PS6037
  • Address: (an IP address since it's Modbus TCP)
  • Unit ID: 1
  • Port: 1502

Representation in <stateDir>/devices.json

  "DENT.Mod.PS6037": {
    "profile": "Network Power Meter",
    "protocols": {
      "modbus-tcp": {
        "Address": "",
        "Port": "1502",
        "UnitID": "1"
    "name": "DENT.Mod.PS6037"

Modbus Device Service Interaction

Run the Modbus Device Services

Find details on how to run the Modbus device service on the Run Device Services page.

In addition to the environment variables described on that page, you will also need to set the following for Modbus prior to running it:

  • MODBUS_DEVICE_ADDRESS: This is the variable pointing to the location of the target modbus device

    • IP address in the case of TCP connections (e.g.
    • Serial ID for RTU connections (e.g. /dev/ttyUSB0).
  • MODBUS_DEVICE_PORT: This is the target port of the modbus device

    • Typically 502, but this may be different on some devices, so we've included a variable for configuring it if desired.
Back to top