Configuration Properties for Modbus Protocol Adapter

Modbus specific configurations are stored in the modbus_source block, and there are two types: Modbus Flat and Modbus Sink Flat.

The following fields are common to both block types:
Table 1. Common Configuration Properties
Field Type Required Default
transport_addr string yes
data_map array yes
log_level string 'off'
log_name string
default_byte_order boolean true
first_16_bit_low boolean true
first_32_bit_low boolean true
options object

transport_addr

The transport_addr field determines the location of the Modbus endpoint the block will communicate with. Its prefix can be any of the following:
  • 'modbus-tcp'
  • 'modbus-rtu'
  • 'modbus-ascii'
  • 'modbus-rtu-tcp'
  • 'modbus-ascii-tcp'

data_map

The data_map field defines what registers to retrieve data from on the Modbus endpoint and how to convert that data to flat JSON format. The data_map is an array of objects of the following structure:
Field Type Required
alias String yes
reg_type String yes
address Integer yes
type String yes if reg_type is 'holding' or 'input'
bit_index Integer yes if type is 'bool'
count Integer yes if type is 'string' or reg_type is 'coil'
  • The alias field of the data_map determines the name of the requested value that should mean something to the target application. Examples are “temperature” and “pressure”.
  • The reg_type field determines what register type to retrieve data from. Possible values are:
    • 'holding'
    • 'input'
    • 'coil'
  • The address determines the starting address of the data point. This should be any number that is a valid Modbus register.
  • The type determines the type of data to pull from the Modbus endpoint. This value will determine how many registers are accessed and how to combine the registers to form the requested type. Possible values are:
    • 'bool'
    • 'int8'
    • 'uint8'
    • 'int16'
    • 'uint16'
    • 'int32'
    • 'uint32'
    • 'int64'
    • 'uint64'
    • 'float'
    • 'double'
    • 'string'
  • The bit_index is used only when type is 'bool'. This specifies which bit the boolean value is stored in.
  • The count is used only when type is 'string' or reg_type is 'coil'. This specifies the number of registers or bytes to read in order to form a string or byte array.

log_level and log_name

For details about the log_level and log_name fields, see the Generic CDP Blocks section of the Protocol Adapters documentation page.

default_byte_order

The byte order used by the Modbus adapter can be changed from the default Modbus byte ordering (big endian) to Intel byte ordering (little endian) by using this option. By default it is the normal setting for Modbus compatible devices. If the device uses Intel byte ordering, setting this option to false will enable the Modbus driver to properly read Intel formatted data.

first_16_bit_low

Two consecutive registers’ addresses in a Modbus device are used for 32-bit data types, like Integer and Float. It can be specified whether the adapter should assume the first 16 bits is the low or the high word of the 32-bit value. The default, first word low, follows the convention of the Modicon Modsoft programming software. This is also applicable to the two 32-bit data in 64-bit data types, like Long and Double.

first_32_bit_low

Four consecutive registers’ addresses in a Modbus device are used for 64-bit data types, like Long and Double. It can be specified whether the driver should assume the first 32 bits is the low or the high double word of the 64-bit value. The default, first 32 bits low, follows the default convention of 32-bit data types.

Note: The interaction of multi-register values (e.g., 32-bit integers, 64-bit doubles, long strings) with these settings is a little unintuitive. This is an illustration of the behavior on a 64-bit unsigned integer 0x8877665544332211 for a few configurations.
default_byte_order first_16_bit_low first_32_bit_low transmitted as
true true true [11][22][33][44][55][66][77][88]
false true true [22][11][44][33][66][55][88][77]
true false true [33][44][11][22][77][88][55][66]
true true false [55][66][77][88][11][22][33][44]
false true false [66][55][88][77][22][11][44][33]

You can think of these settings as only applying within “chunks” of the next largest size, i.e., default_byte_order controls byte orders within two-byte registers. first_16_bit_low controls byte orders within four-byte “double registers”, and first_32_bit_low controls byte orders within 8-byte “quad registers”. The National Instruments publication “The Modbus Protocol In-Depth” contains another discussion of byte order in Modbus.

options

The options field contains any other miscellaneous configuration options necessary for the desired Modbus communication.