String Configuration

Driver Modicon Modbus

String Configuration

Top  Previous  Next

The String configuration of I/O Tags is performed using the Device and Item fields of each Tag.

That new configuration method does not work with Elipse SCADA, which still uses the old numerical configuration (N and B parameters).

N and B parameters are not used when configuring by Strings and they must be left in 0 (zero).

Configuration by Strings makes Tag configuration more readable, making it easy to configure and maintain applications.

 

Block Reading

Tags configured by Strings can be simple Tags or Block Tags, with their Device and Item fields with the same syntax.

 

NOTE

The grouping service of Tags performed by Superblocks is not available for Tags using configuration by Strings. If users want optimization through superblock readings, application Tags must use only Numerical Configuration.

 

Device Field

In the Device field, the Slave Id (device's identification address) must be provided as a number between 1 (one) and 255 followed by a colon, such as "1:", "101:", "225:" etc.

Please remember that, in Modbus protocol, the Slave Id 255 is reserved for broadcasting, which only makes sense if used by writing operations, because there is no return from devices, or else there would be conflicts.

Optionally, the Slave Id may appear at the beginning of the Item field, explained later, and in this case the Device field must be left empty. This option is detailed next.

 

Item Field

The Item field must provide all addressing and operation information to be performed by a Tag, using the following syntax:

<address space><address>[.<type>[<type size>]][.<byte order>][/bit]

 

Where parameters between brackets are optional.

As mentioned earlier, users can alternatively provide a Slave Id at the beginning of the Item field, such as the next example:

<slave id>:<address space><address>[.<type>[<type size>]][.<byte order>][/bit]

 

In this case, as already explained, users must leave the Device field empty.

The next examples show the most common usage cases (notice that quotation marks must not be added to the application):

1.Reading or writing a Holding Register (functions 03 and 16) on address 100 of a device with Id 1, and Slave Id provided in the Device field:

a.Device: "1:"

b.Item: "hr100"

2.Reading or writing a Holding Register (functions 03 and 16) on address 120 of a device with Id 3, and Slave Id provided in the Item field:

a.Device: "" (empty String)

b.Item: "3:hr120"

3.Reading or writing a Coil (functions 01 and 15) on address 65535 (FFFFh) of a device with Slave Id 4, here provided in the Item field:

a.Device: "" (empty String)

b.Item: "4:cl&hFFFF" (or optionally "4:cl65535")

 

The next figure shows examples of String-configured Tags on E3 Developer's Tutorial.

String-configured Tags on E3 Developer's Tutorial

String-configured Tags on E3 Developer's Tutorial

Mandatory and Optional Fields

Mandatory fields for all Tags are described next and individually detailed later in this topic:

1.Address space: A mnemonic defining a set of protocol's reading and writing functions to use (please check the table with all supported mnemonics later on this topic)

2.Address: A numerical value identifying the item's address (register or bit) to read or write within the defined address space. These values can be provided in decimal, hexadecimal, or octal. For decimal values, no prefix is needed, or optionally a "&d" prefix can be used. For hexadecimal values, use the "&h" prefix (for example, "&hFFFF"). For octal values, use the "&ho" prefix (for example, "&o843"). This address can have an offset relative to the address sent in the communication frame, which depends on the convention used by the manufacturer. When in doubt about addressing conventions, please check topic Addressing Tips (Modbus Convention). Particularly, check whether the device implements the default offset of protocol's Data Model (please check the Data Address Model Offset options on Modbus tab)

 

The next fields are optional, used for extensions to the default protocol or for compatibility with devices not fully compliant with the protocol (they are also individually detailed later in this topic):

1.Type: Defines how bytes from the data area of the communication frame must be interpreted. If omitted, the default types of the protocol for the respective functions are used, that is, Word for functions to access registers and Bit for functions to access digital data (Coils and Discrete Inputs). Please check the mnemonics table for all supported types later in this topic.

2.Type size: Users must specify this field only for variable-size types, such as BCD and String. Its numerical value indicates the size of the type in bytes.

3.Byte order: Mnemonic indicating the byte order of numerical values. If omitted, protocol's default order is then used, with the most significant bytes coming first in the communication frame, which is called big endian. Please check more information on the specific section about this option, later in this topic.

4.Bit: Allows returning a specific bit of an integer value, which obviously only makes sense in Modbus functions returning integer values (Words). Usually, users are advised to not use this feature, preferring application's bit mapping. Bit 1 (one) is the least significant and, the greater the value, the most significant is the bit. The maximum allowed value obviously depends on the type size, which is currently 64 for Double types. This field corresponds to the old Use bit mask option on numerical configuration. Please check more information on this option on topic Operations Tab.

 

Exceptions

Modbus protocol's functions 20 and 21, which access files, use a slightly different syntax from the one described previously:

fr<file>.<register>[.<type>[<type size>]][.<byte order>][/bit]

 

Example:

·Device: "" (empty String)

·Item: "1:fr4.101" (reading register 101 from file 4 on Slave Id 1)

 

Specifically for the GenSOE special function (Elipse Generic SOE):

elsoe<N>.<initial addr.>[.<type>[<type size>]][.<byte order>][/bit]

 

Specifically for the SP SOE special function (Sepam SOE), to read all events:

spsoe<event type>.<initial addr.>[.<type>][.<byte order>][/bit]

 

Specifically for the SP SOE special function (Sepam SOE), to read events from specific points:

ptspsoe<event type>.<event addr.>

 

Specifically for the GE SOE special function (GE PAC RX7 SOE):

gesoe<tag type + point index>.<queue base addr.>

 

Please check specific topics about the special functions mentioned previously for more information about configuring the respective Tags using Strings.

 

Address Space

Instead of explicitly defining Modbus functions or special reading and writing functions to use, as performed on the old numerical configuration and its concept of operations, when configuring using Strings users define an address space through mnemonics listed on the next table, already linked to protocol's pre-defined functions and their respective native data types.

Address spaces and mnemonics

Address Space

Mnemonic

Native Type

Function

Comments

Holding Register

hr

Word (16-bit)

Functions 03 and 16

Functions 03 and 16 are protocol's most used ones (Modbus class 0)

Single Holding Register

shr

Word (16-bit)

Functions 03 and 06

Function 06 writes to the same registers of function 16, the difference is that function 16 can only write in Blocks, while function 06 writes to a single register at a time, but with less overhead

Coil

cl

Bit

Functions 01 and 15

 

Single Coil

scl

Bit

Functions 01 and 05

Function 05 writes to the same registers of function 15, but cannot write in Blocks, therefore with less overhead

Discrete Input

di

Bit

Functions 02 and None (read-only)

 

Input Register

ir

Word (16-bit)

Functions 04 and None (read-only)

 

Exception Status

es

Byte

Functions 07 and None (read-only)

 

File Register

fr

Word (16-bit)

Functions 20 and 21

 

ABB MGE 144 - Mass Memory Reading

abbmge

Word (16-bit)

Functions 65 03 and None (read-only)

 

ABB MGE 144 - Reset

abbmge.rst

Not used

Functions None for reading and 65 01 for writing

 

ABB MGE 144 - Zeroes Maximum and Minimum Memory

abbmge.rstmxmn

Not used

Functions None for reading and 65 02 for writing

 

GE PAC RX7 SOE - Reading

gesoe

GE_events

Functions GE SOE for reading and None for writing

 

SEPAM SOE Events

spsoe

SP_events

Functions SP SOE for reading and None for writing

Collects from the meter and returns a structure (with SP_events type) to the Tag with events from any points (please check topic SEPAM SOE)

SEPAM SOE Single Point Events

ptspsoe

Int32

Functions SP SOE for reading and None for writing

Collects from the meter and returns to the Tag an integer value from the Edge field, relative to events from a specific point (please check topic SEPAM SOE)

Elipse Generic SOE

elsoe

Word (16-bit)

Functions GEN SOE for reading (Modbus function 03 with additional algorithms) and 16 for writing

 

 

Data Types

The table on the previous section lists all protocol's native data types, according to the Modbus functions used, as well as some specific data types used in special functions (non-standard). For Tags returning these native data types, the Data Type parameter can be omitted from the Item field's String.

If users must interpret native data in a different way, which is common among devices using Modbus, they must specify the data type to use, as explained in this section.

A list with all native data types supported by this Driver, as well as their description, can be checked on topic Supported Data Types.

The next table lists all mnemonics used in the <type> parameter of the Item field for each supported data type, Driver-native, and also an alias or an alternative name.

Supported data types

Type

Mnemonic

Alias

Char

char

ch

Byte

byte

by or u8

Int8

int8

i8

Int16

int16

i16

Int32

int32

i32

Word or UInt

word

u16

DWord or ULong

dword

u32

Float

float

f

Float_GE

float_GE

fge

Double or Real

double

d

String

string

s

BCD

BCD

bcd

GenTime

GenTime

gtm

Sp_time

Sp_time

sptm

UTC64d

UTC64d

-

UTC32

UTC32

-

 

User-Defined Data Types

In addition to the data types listed on the previous table, users can also provide mnemonics for user-defined data types or structures (please check topic User-Defined Data Types).

To use user-defined data types in the Item field, however, the names of these data types must not be case-insensitive, as the Item field does not differentiate upper and lower case. If that happens, the Driver does not allow using these data types in the Item field (please check topic User-Defined Data Types).

 

Examples

1.Reading or writing Holding Registers (functions 03 and 16) to or from address 100 of a device with Id 1, interpreted as a DWord, with Slave Id in the Device field:

a.Device: "1:"

b.Item: "hr100.u32" or "hr100.dword", or if a hexadecimal is convenient, "hr&h64.u32"

2.Reading or writing Holding Registers (functions 03 and 16) to or from address 150 of a device with Id 3, interpreted as a Float, with Slave Id in the Item field:

a.Device: "" (empty String)

b.Item: "3:hr150.f" or "3:hr150.float", or if a hexadecimal is convenient, "3:hr&h96.f"

3.Reading or writing Holding Registers (functions 03 and 16) to or from address 1500 of a device with Id 5, interpreted as a Double, with Slave Id in the Item field:

a.Device: "" (empty String)

b.Item: "5:hr1500.d" or "5:hr1500.double", or if a hexadecimal is convenient, "5:hr&h5DC.d"

4.Reading or writing Holding Registers (functions 03 and 06) to or from address 100 of a device with Id 5, interpreted as a Word, with Slave Id in the Item field:

a.Device: "" (empty String)

b.Item: "5:shr100" or "5:shr100.u16", or "5:shr100.word". Notice that, because it is a Word, Modbus protocol's native data type for Holding Registers, the data type can be omitted

5.Reading or writing Holding Registers (functions 03 and 06) to or from address 100 of a device with Id 5, interpreted as a user-defined data type named "mytype", with Slave Id in the Item field:

a.Device: "" (empty String)

b.Item: "5:shr100.mytype"

 

NOTE

The address space of Holding Registers in Modbus protocol contains 16-bit registers. Therefore, to read 32-bit data types, such as a DWord or a Float, users must read two "hr" addresses for each Tag accessed. Likewise, reading a Double-type Tag demands the reading of four Holding Register addresses. For the same reasons, reading and writing "hr" Tags with a Byte data type can only be performed in pairs. On the device, each Holding Register address always contains two bytes.

 

Size of Data Types

BCD- and String-data types, as they have a variable size, demand the specification of a data type size, in bytes, right after their data type.

Notice that only data types 2 and 4 are valid (2 and 4 bytes or 4 and 8 digits) for BCD data types. Examples:

1.Reading or writing Holding Registers (functions 03 and 16) to or from address 100 of a device with Id 1, interpreted as a 10-byte-String (five "hr" registers), with Slave Id in the Device field:

a.Device: "1:"

b.Item: "hr100.s10"

2.Reading or writing Holding Registers (functions 03 and 16) to or from address 100 of a device with Id 1, interpreted as an eight-digit-BCD (four bytes or two "hr" registers), with Slave Id in the Item field:

a.Device: "" (empty String)

b.Item: "1:hr100.bcd4"

 

Byte Order

As explained on the syntax of the previous section, users can add an optional byte order parameter in Tag's Item field to specify a byte ordering for devices that do not comply with protocol's standard. If a device complies with Modbus protocol's default ordering, this field can be omitted.

If distorted values are read, which can be observed on early tests with a device, and if these values, converted to hexadecimal, are correct after inverting the position of some bytes, please read this section carefully.

The Modbus protocol uses the big endian format by default, where values are formatted with their most significant coming first in communication frames. This is the default format used by this Driver. There is, however, a large amount of devices in the market that use values with other combinations for byte ordering.

As an example, if a Driver reads a value equal to "1234h" (or "4660" in decimal), by default this Driver waits that data be sent with a byte sequence equal to 12h and 34h. If the device uses an inverted default, which is called little indian, then the byte 34h is sent first and then the byte 12h, and the Driver may interpret it as 3412h, or 13330 in decimal, unless these two bytes were inverted before interpreting.

For 32-bit values, there are cases when Word values are swapped, but with bytes inside Word values keeping their default ordering. For example, the value 12345678h can be received as 56781234h. There are also other situations, with several different combinations for ordering.

To allow communication with these devices that do not follow protocol's standard byte order, this Driver allows users to configure Tags by specifying the order to use.

The byte order parameter corresponds to the swap options from the old numerical configuration, and it may have values "b0", "b1", "b2", "b3", "b4", "b5", "b6", "b7", "alias", or else "alias2" (please check the next table).

If the byte order parameter is omitted, a data is interpreted as the protocol's default, which is equivalent to the "b0" code.

The next table indicates that swap operations (Swap Bytes, Swap Words, and Swap DWords) are performed for each ordering mnemonic (from "b0" to "b7").

Swapping operations

 

Swap Bytes

Swap Words

Swap DWords

Alias

Alias 2 (Swaps)

Byte Order *

b0

 

 

 

msb

-

by7 by6 by5 by4 by3 by2 by1 by0

b1

X

 

 

-

sb

by6 by7 by4 by5 by2 by3 by0 by1

b2

 

X

 

-

sw

by5 by4 by7 by6 by1 by0 by3 by2

b3

X

X

 

-

sb.sw

by4 by5 by6 by7 by0 by1 by2 by3

b4

 

 

X

-

sdw

by3 by2 by1 by0 by7 by6 by5 by4

b5

X

 

X

-

sb.sdw

by2 by3 by0 by1 by6 by7 by4 by5

b6

 

X

X

-

sw.sdw

by1 by0 by3 by2 by5 by4 by7 by6

b7

X

X

X

lsb

sb.sw.sdw

by0 by1 by2 by3 by4 by5 by6 by7

* 64-bit (where "by0" is "lsb" and "b7" is "msb")

That is, "b0" does not perform any swap operation on data bytes, keeping the original ordering of bytes received from the device, which is equivalent to deselecting the swap options on Operations tab from the old numerical configuration.

"b1", on the other hand, performs a byte swapping, two by two, that is, when receiving a Word (unsigned 16-bit integer) with the hexadecimal value 0102h, the value returned to the Tag is 0201h, with its bytes swapped. It is equivalent to the old Swap Bytes option.

"b2" performs a Word swapping, that is, bytes two by two, which obviously affects only 32-bit data or larger. This is the same as selecting the Swap Words option from the old numerical configuration. As an example, if the value 01020304h is received from a device, the value used for application Tags is 03040102h.

"b3" performs byte and Word swapping, which is equivalent to the old Swap Bytes and Swap Words options enabled simultaneously. In this case, the value 01020304h becomes 04030201h.

Likewise, "b4" performs a DWord swapping for 64-bit values, which corresponds to the Swap DWords option from the old numerical configuration, that is, the value 1122334455667788h is interpreted as 5566778811223344h. And so on for all other codes.

The last two table columns specify aliases that users can use for readability, that is, instead of using a "b0" code, users can use an "sw.sdw" alias, and so on.

 

How to Select the Correct Byte Order?

In most cases, device's documentation specifies the byte order used, or how to configure it (there are devices that allow that configuration).

In cases where device's documentation does not contain a configuration, users must contact manufacturer's technical support.

If there is no reliable information, users must perform empirical tests, analyzing the returned values, in hexadecimal, comparing them to the expected values and observing if there are byte order inversions that may explain the differences.

There are basically three situations:

1.For devices providing data using Modbus protocol's default byte order (big endian or Motorola), with the most significant bytes coming first, users must omit this parameter or define it as "b0". This is the most common situation.

2.For devices using another byte order standard, with the least significant bytes coming first (little endian), users must enable all swap options referring to the data type used, which corresponds to the "b7" mnemonic.

3.In the least common case, there are devices that use different byte orders for different data sizes, providing for instance the most significant byte of each Word first, but the least significant Word of each DWord first. Therefore, users must evaluate in which case each swap option must be enabled, thus converting the value returned by the device to protocol's default big endian format.

 

NOTE

All mentioned swap options have no effect for Bit data types or eight-bit-size types (Byte, Char, and Int8). Swapping occurs inside each data type, that is, the Swap Words option has no effect for 16-bit data types, as well as the Swap DWords option has no effect for 32-bit data types. BCD data types do not allow swapping operations either.

 

The topic Frequently Asked Questions lists a few known cases, already observed on technical supports. Examples:

1.Reading or writing Holding Registers (functions 03 and 16) to or from address 1500 of a device with Id 5, interpreted as a Double without byte inversion, with Slave Id in the Item field:

a.Device: "" (empty String)

b.Item: "5:hr1500.d" or "5:hr1500.double", or else "5:hr1500.d.b0"

2.Reading or writing Holding Registers (functions 03 and 16) to or from address 1500 of a device with Id 5, interpreted as a Double with the least significant byte of each Word coming first, and with Slave Id in the Item field:

a.Device: "" (empty String)

b.Item: "5:hr1500.d.b1" or "5:hr1500.double.b1", or else "5:hr1500.double.sb"

3.Reading or writing Holding Registers (functions 03 and 16) to or from address 1500 of a device with Id 5, interpreted as a Double with the least significant byte coming first (little endian), and with Slave Id in the Item field:

a.Device: "" (empty String)

b.Item: "5:hr1500.d.b7" or other variations, such as "5:hr1500.d.lsb" and "5:hr1500.d.sb.sw.sdw"

 

Driver's Special Tags

In addition to all Tags described previously, users can configure Driver's Special Tags using Strings, which are described in details on their specific topics (click an item for more information).

Special Tags

Device

Item

Operation

 

ForceWaitSilence

Writing

<slave id>:

LastExceptionCode

Reading or writing

 
Has this section of the documentation helped you configure this Driver?
Yes No
Comments (optional):