Skip to content

Modbus Device Service

The Modbus Device Service provides a means of integrating Modbus devices with Edge Xpert. For further information, see the Modbus website.

The Edge Xpert Modbus Device Service can be used to communicate with devices that use either a serial port protocol or an Ethernet protocol that supports the Internet protocol suite, as follows: - Modbus Remote Terminal Unit (Modbus RTU). Used in serial communication and uses a compact, binary representation of the data for protocol automation - Modbus Transmission Control Protocol/Internet Protocol (Modbus TCP). A Modbus variant, which is used for communications over TCP/IP networks and connecting over port 502 by default

Breaking Change in Edge Xpert v2.2

  • The attribute values for startingAddress, boolIndex and stringRegisterSize have changed from strings to integers
  • The attribute values for isByteSwap and isWordSwap have changed from strings to booleans

Key Features

The Modbus Device Service supports the following key features:

  • Support for Modbus RTU connection types
  • Support for Modbus TCP/IP connection types

  • Read functionality. Data can be read from each primary table, as follows:

    Modbus Object Function Name Function Code
    Coils Read Coils 1
    Discrete Inputs Read Discrete Inputs 2
    Holding Registers Read Multiple Holding Registers 3
    Input Registers Read Input Registers 4

  • Write functionality. Data can be written to each primary table, as follows:

    Modbus Object Function Name Function Code
    Coils Write Multiple Coils 15
    Holding Registers Write Multiple Holding Registers 16

  • Batch read operation. Read multiple values in a single Modbus call from each primary table, as described in the first table above

  • Batch write operation. Write multiple values in a single Modbus call to each writable primary table, as described in the second table above

  • Support for parsing Int64, Uint64, Float32, and Float64 data types with byte swap and word swap functionality. See Modbus Swap Operations for more information

Supported Data Types

The Modbus Device Service supports the following data types:

  • Bool
  • Uint8, Uint16, Uint32, Uint64
  • Int8, Int16, Int32, Int64
  • Float32, Float64

Modbus Device Profile

The device profile defines what resources are available on a particular device. Ensure that the following profile attributes are defined in the device profile:

Attribute Type Required Description
primaryTable String Yes Identifies the primary table. The primary table must be one of the following:
  • HOLDING_REGISTERS
  • INPUT_REGISTERS
  • COILS
  • DISCRETES_INPUT
startingAddress Uint16 Yes The address in the Modbus device

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, starting address, and register length. With this information, it can read or write a value using the Modbus protocol.

Optional 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 Type Required Description
rawtype String No 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.
Valid string values are as follows:
  • INT16
  • UINT16
isByteSwap Bool No 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 Bool No 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 Uint8 No 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 from 0 to 15
For COILS and DISCRETE_INPUT, the value is 0
See Example Using BoolIndex for more detail.
stringEncoding String No The supported string encoding
Valid values are UTF8 or ASCII
Default is UTF8
stringRegisterSize Uint8 No Defines the capacity of the device resource for 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 String 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

Example Using BoolIndex

The boolIndex attribute is used within a bool resource to specify a single bit within a Modbus 16-bit register.

By default, the boolIndex is set to 0.

For coils and discrete inputs, the boolIndex will always be set to 0 as these are 1-bit values. For Holding registers and input registers, they are 16-bit registers so the range for the boolIndex value is 0-15.

For example, if a holding register contained the following 16 bits: 0000011111000001

  • To read/write the rightmost bit in this register, you would use boolIndex: 0.
000001111100000[1]

A read on this resource would return true.

  • To read/write the center bit in this register, you would use boolIndex: 7.
00000111[1]1000001

A read on this resource would return true.

  • To read/write the leftmost bit, you would use boolIndex: 15.
[0]000011111000001.

A read on this resource would return false.

Modbus Protocol Properties

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

Protocol Property Description Valid Values Required
UnitID The station identifier Values up to 247 Yes
Address For Modbus TCP/IP, the IP address or host name
For Modbus RTU, the path to the serial device 		When using TCP, a valid IP address
When using RTU, a valid serial address 		Yes
Port Used for Modbus TCP/IP only
The TCP port of the Modbus device 		Any valid port number Yes (for Modbus TCP/IP)
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 Yes (for Modbus RTU)
DataBits Used for Modbus RTU only
The number of bits of data 		Valid values are as follows:
  • 7
  • 8
 Yes (for Modbus RTU)
StopBits Used for Modbus RTU only
The number of stop bits 		Valid values are as follows:
  • 1
  • 2
 Yes (for Modbus RTU)
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
 Yes (for Modbus RTU)
ReadMaxHoldingRegisters Maximum holding registers supported by the device per read operation Any UInt16 value. No - Default value is 125
ReadMaxInputRegisters Maximum input registers supported by the device per read operation Any UInt16 value. No - Default value is 125
ReadMaxBitsCoils Maximum bits supported by the device per read operation on coils Any UInt16 value. No - Default value is 2000
ReadMaxBitsDiscreteInputs Maximum bits supported by the device per read operation on discrete inputs Any UInt16 value. No - Default value is 2000
WriteMaxHoldingRegisters Maximum holding registers supported by the device per write operation Any UInt16 value. No - Default value is 123
WriteMaxBitsCoils Maximum bits supported by the device per write operation on coils Any UInt16 value. No - Default value is 1968

Using the Modbus Device Service

For Examples of setting up and using devices with the Edge Xpert Modbus Device Service, see Modbus TCP/IP Example and Modbus RTU Example. These examples use a simulated device, see Modbus Simulator for more information.