How to Write a Modbus V2 Adapter Script

In this article, we'll explain the basics of the Modbus V2 adapter script and what makes it different from other integration protocols. 

Note: See the Adapter Script Overview-V2 for an overall look at the V2 adapter scripts.

Specify Version

As with all other V2 adapter scripts, the first line within your Modbus Adapter Script should be indicating which version of Adapter Script you're using. To use a V2 adapter script, enter the following.

version: 2

Note: If there is no version set, version 1 will be assumed.

Basic Settings

Next, we'll want to declare some Modbus specific parameters to control how data is polled and interpreted. There are a few options to choose to include:

• byte-order
• word-order
• address-space
• string-encoding
• scan-interval

Here we'll go into a little more detail as to what these are and mean.

byte-order

• required: no
• valid range: [big, little]
• default value: big

All Modbus registers are 16-bit, and the byte-order settings dictate the ordering of the two bytes within the returned values. If 16-bit values are returned significantly larger or smaller than expected, try switching the byte order.

word-order

• required: no
• valid range: [big, little]
• default value: big

All Modbus registers are 16-bit, so representing larger values such as 32-bit floats requires transmitting data in multiple adjacent registers. The word-order setting dictates the ordering of the two (or more) registers returned to represent a large value. If 16-bit values read correctly but 32-bit values are returned significantly larger or smaller than expected, try switching the word order.

address-space

• required: no
• valid range: [1, 2, 3, 4, mixed]
• default value: mixed

Modbus supports 4 different functions for reading data, and there is a well-defined convention for identifying which function to use based on the value of the address being looked up. This convention, represented by the mixed value for the address-space option, is as follows:

• Addresses 00001 - 09999: Read from range [0 - 9998] with function 1 (discrete output coils)
• Addresses 10001 - 19999: Read from range [0 - 9998] with function 2 (discrete input contacts)
• Addresses 40001 - 49999 : Read from range [0 - 9998] with function 3 (output holding registers)
• Addresses 30001 - 39999 : Read from range [0 - 9998] with function 4 (input registers)

Each read function in Modbus has its own independent address space in the range [0 - 65535], but the mixed address convention remaps addresses into the much smaller range [0 - 9998] for each function.

Some Modbus devices need to utilize the full address space of one (or more) of the available read functions, and by specifying the address-space as one of the function numbers, addresses will be passed as-is to the Modbus device using the specified function.

string-encoding

• required: no
• valid range: [ascii, utf8, ucs2, utf16le]
• default value: ascii

Modbus devices may represent text strings in memory in different text encodings, including 1-byte, 2-byte, and variable-byte encodings. Set the string-encoding if text is not transferred as ASCII.

scan-interval

• required: no
• valid range: > 0
• default value: 1.0

The scan-interval is the amount of time in seconds that the adapter waits between scanning the modbus device for the full list of coils and registers. If the scan cannot be completed within the interval’s time period, the next scan will be delayed until the current one completes.

None of these fields are required, but you'll want to understand their uses just in case there are connection issues once the adapter script is fully written and trying to output data.

Here's how your adapter script could look after this step:

version: 2
byte-order: big
word-order: little
string-encoding: ascii
address-space: mixed

Coils

version: 2
byte-order: big
word-order: little
string-encoding: ascii
address-space: mixed
coils:

The coils block is where you list all the modbus coils that should be read (functions 1 and 2). Coils can be specified in a shorthand or longhand format. An example of shorthand coils is:

coils:
  coil1: 1
  coil2: 10007

Each coil is listed as an identifier and a coil address. The interpretation of the address (and subsequent coil function used) is determined by your top-level address-space setting. Identifiers can be used as data sources in other sections of your adapter script, such as variables or data-items.

version: 2
byte-order: big
word-order: little
string-encoding: ascii
address-space: mixed
coils:
  coil1: 1
  coil2: 10007

Registers

version: 2
byte-order: big
word-order: little
string-encoding: ascii
address-space: mixed
coils:
 coil1: 1
 coil2: 10007
registers:

The registers block is where you list all the modbus coils that should be read (functions 3 and 4). Registers in modbus are 16-bit numbers but can be used to represent different-size signed and unsigned integers, floating-point values, strings, or packed bit fields. There is only a longhand representation for registers.

The keys for each register are identifiers that can be used as data sources in other parts of your adapter script, such as variables or data-items.

The available register options are:

• address
• func
• type
• size
• scan-interval

address

• required: yes
• valid range:
  • Mixed mode: [30001 - 49999]
  • Functions 3, 4: [0 - 65535]

An explicit modbus address must be provided for each register. Addresses follow the rules outlined in the address-space description in the Basic Settings section. The interpretation of addresses can be further overridden by specifying a read function with the func option.

func

• required: no
• valid range: [3, 4, mixed]

Overrides the global address-space setting for this specific register. If the global address-space setting is not valid for registers (functions 1, 2), then a function must be supplied to avoid an error.

type

• required: yes
• valid range: [int16, uint16, int32, uint32, float32, string]

A valid type must be specified for each register.

• The int16 and uint16 types refer to signed and unsigned 16-bit integers, which consume 1 register in modbus.
• The int32, uint32, and float32 types refer to signed and unsigned 32-bit integers and 32-bit floating-point values, which consume 2 registers each in modbus.
• The string type refers to text stored in a contiguous array of registers.

If a string type is specified, a size option must also be supplied.

size

• required:
  • string types: yes
  • other types: no
• valid range: [1 - 246]

A size must be provided when specifying a string type for the register. Sizes are provided in bytes, not registers or characters. The number of registers consumed or the number of characters represented will depend on the global string-encoding. For ASCII text, the bytes and characters of a string will be the same.

scan-interval

• required: no
• valid range: > 0

Overrides the global scan-interval setting for this specific register. This allows some registers to be read more or less frequently than the others.

Once you've determined what metric the register will be inputting, add it to the adapter script like this:

version: 2
byte-order: big
word-order: little
string-encoding: ascii
address-space: mixed
coils:
 coil1: 1
 coil2: 10007
registers:
  execution:
     address: 30005
     type: float32
     scan-interval: 2

Next Steps

After the registers section is complete, the standard data-items section will be filled in like any other adapter script. For more information on data-items follow this link.

Have Questions? 

Reach out to support@machinemetrics.com for additional help.