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 ReadingTags configured by Strings can be simple Tags or Block Tags, with their Device and Item fields with the same syntax.
Device FieldIn 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 FieldThe 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 Mandatory and Optional FieldsMandatory 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.
ExceptionsModbus 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 SpaceInstead 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
Data TypesThe 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
User-Defined Data TypesIn 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).
Examples1.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"
Size of Data TypesBCD- 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 OrderAs 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
* 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.
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 TagsIn 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
|