Promotic

PmModbusMr - Driver for communication by the Modbus Master protocol

Before using this driver in the PROMOTIC application it is highly recommended to watch "PROMOTIC video tutorial 4 - Communication drivers".

Basic properties of the driver:
- Usage of this driver requires purchase of the PmModbus licence. When developing the application in the freeware mode PmFree, or with development environment and while testing it in runtime, this component is always functional.
- The communication is done for Ethernet (PROMOTIC application is client) or for serial link (COM1, COM2 ...).
- The PROMOTIC application is the Master (it means that it initiates the data transfer) from this communication point of view. For Slave communication can be used: PmModbusSl - Driver for communication by the Modbus Slave protocol.
- The driver is incorporated into the PROMOTIC system by means of the PmaComm object.
The driver supports the usage of both PmaCommMsg and PmaCommGroup objects. For common case of the data transfer, it is better to use the PmaCommGroup object.
For easy integration of this driver into the application it is handy to use: Preconfigurations in group "Modbus"
- This is a network communication, it means that one PmaComm object can communicate with multiple devices (the protocol supports multiple device addressing).
- The driver supports the TCP, RTU and ASCII transfer modes.
- It is possible to transfer standard 1-bit (bits) and 16-bits (registers) values and less standard 32-bits values of the float and long type and 64-bit values (float double precision).
- The driver can be used also for the JBUS protocol. The JBUS protocol is the subset of the Modbus RTU protocol. All implemented messages in this driver (see below) are also supported by the JBUS protocol.


Following Modbus data types are supported:
- b = Bit (1Bit):
In the PLC device: 1bit. In the PROMOTIC application: Boolean data type.
- W = Word (2Byte Unsigned Integer):
16 Bit Unsigned, Big-endian
In the PLC device: 16 bits (value from 0 to 65535). In the PROMOTIC application: Long data type.
The binary format of this type is the same as in the PROMOTIC application, only the bytes order is changed (bytes order PC:12, PLC:21).
- W2 = Word (2Byte Unsigned Integer):
16 Bit Unsigned, Little-endian
Identical as the previous data type, only the bytes order stays the same - as in the PROMOTIC application (bytes order PC:12, PLC:12).
- I = Int (2Byte Signed Integer):
16 Bit Signed, Big-endian
In the PLC device: 16 bits (value from -32767 to +32767). In the PROMOTIC application: Integer data type.
The binary format of this type is the same as in the PROMOTIC application, only the bytes order is changed (bytes order PC:12, PLC:21).
- I2 = Word (2Byte Signed Integer):
16 Bit Signed, Little-endian
Identical as the previous data type, only the bytes order stays the same - as in the PROMOTIC application (bytes order PC:12, PLC:12).
- L1 = Long type 1 (4Byte Signed Integer):
32-bit Signed, Big-endian byte swap
In the PLC device: 32 bits. In the PROMOTIC application: Long data type.
Only for messages of the 03, 04, 16 type.
The binary format of this type is the same as in the PROMOTIC application, only the bytes order is changed (bytes order PC:1234, PLC:2143).
Use for example: Modicon, Wago, etc.
- L2 = Long type 2 (4Byte Signed Integer):
32-bit Signed, Big-endian
Identical as the previous data type, only the bytes order is changed (bytes order PC:1234, PLC:4321).
Use for example: JUMO.
- L3 = Long type 3 (4Byte Signed Integer):
32-bit Signed, Little-endian
Identical as the previous data type, only the bytes order stays the same - as in the PROMOTIC application (bytes order PC:1234, PLC:1234).
- L4 = Long type 4 (4Byte Signed Integer):
32-bit Signed, Little-endian byte swap
Identical as the previous data type, only the bytes order is changed (bytes order PC:1234, PLC:3412).
- UL1 = ULong type 1 (4Byte Unsigned Integer):
32-bit Unsigned, Big-endian byte swap
In the PLC device: 32 bits. In the PROMOTIC application: Double data type.
Only for messages of the 03, 04, 16 type.
The binary format of this type is the same as in the PROMOTIC application, only the bytes order is changed (bytes order PC:1234, PLC:2143).
- UL2 = ULong type 2 (4Byte Unsigned Integer):
32-bit Unsigned, Big-endian
Identical as the previous data type, only the bytes order is changed (bytes order PC:1234, PLC:4321).
- UL3 = ULong type 3 (4Byte Unsigned Integer):
32-bit Unsigned, Little-endian
Identical as the previous data type, only the bytes order stays the same - as in the PROMOTIC application (bytes order PC:1234, PLC:1234).
- UL4 = ULong type 4 (4Byte Unsigned Integer):
32-bit Unsigned, Little-endian byte swap
Identical as the previous data type, only the bytes order is changed (bytes order PC:1234, PLC:3412).
- LL2 = LongLong type 2 (8Byte Signed Integer):
64-bit Signed, Big-endian
In the PLC device: 64 bits. In the PROMOTIC application: Double data type. (bytes order PLC:87654321)
Only for messages of the 03, 04, 16 type.
8-byte integer cannot be stored in requested data type with full precision. Here it is stored to the value of the Double type, but for some very big numbers the precision may suffer (maximum difference +-2047).
Use for example: Energy meter iEM3100(Schneider-Electric), Multimeter EPM-07S(ENTES) ...
- R = Float type 1 (4Byte - IEEE 754):
32-bit Float, Big-endian byte swap
In the PLC device: 32 bits. In the PROMOTIC application: Single data type.
Only for messages of the 03, 04, 16 type.
The binary format of this type is standardized by IEEE-754, so it is the same as in the PROMOTIC application, only the bytes order is changed (bytes order PC:1234, PLC:2143).
- R2 = Float type 2 (4Byte - IEEE 754):
32-bit Float, Big-endian
Identical as the previous data type, only the bytes order is changed (bytes order PC:1234, PLC:4321).
Use for example: ABB AC500.
- R3 = Float type 3 (4Byte - IEEE 754):
32-bit Float, Little-endian
Identical as the previous data type, only the bytes order stays the same - as in the PROMOTIC application (bytes order PC:1234, PLC:1234).
- D1 = Float Double-precision type 1 (8Byte - IEEE 754):
64-bit Float, Big-endian byte swap
In the PLC device: 64 bits In the PROMOTIC application: Double data type.
Only for messages of the 03, 04, 16 type.
The binary format of this type is standardized by IEEE-754, so it is the same as in the PROMOTIC application, only the bytes order is changed (bytes order PC:12345678, PLC:21436587).
- D2 = Float Double-precision type 2 (8Byte - IEEE 754):
64-bit Float, Big-endian
Identical as the previous data type, only the bytes order is changed (bytes order PC:12345678, PLC:87654321).
- D3 = Float Double-precision type 3 (8Byte - IEEE 754):
64-bit Float, Little-endian
Identical as the previous data type, only the bytes order stays the same - as in the PROMOTIC application (bytes order PC:12345678, PLC:12345678).
- S1 = String type 1 (byte order: 214365..):
In the PLC device: 2*N bytes, where N is the number of registers where the text is stored. In the PROMOTIC application: String data type.
Only for messages of the 03, 04, 16 type.
In the PLC device, the text string is saved in different order compared to the in the PROMOTIC application.
It is used for example in the PLC device Modicon M340.
If there is a binary zero in the string, then in the PROMOTIC application this string is shortened (the zero ends the text string).
This data type cannot be used in the PmaCommMsg object.
- S3 = String type 3 (byte order: 123456..):
Identical as the previous data type, only the bytes order stays the same - as in the PROMOTIC application.
This data type cannot be used in the PmaCommMsg object.


Recommended values of the PmaComm object parameters:

Recommended values for the Serial link parameters:
Number data bits8 for RTU mode, 7 for ASCII mode
Number of stop bits1 if parity is used, 2 if parity is NO
Recommended values for the Ethernet-client parameters:
TCP/UDP remote port number502 (for MODBUS TCP/IP data type)
 
See: Wikipedia: A list of TCP and UDP port numbers used by protocols to run network applications.
Ethernet transfer typeTCP (for MODBUS TCP/IP data type)
Description and recommended values for the Protocol parameters:
Protocol data typeOnly for Ethernet. Specifies the protocol data form. It is possible to choose:
MODBUS TCP/IP - Standard Ethernet MODBUS communication. Compared to the data for serial link a special header is included and it is transferred via Ethernet TCP on port 502.
The same data as for serial link - This option can be selected, for example, if the device is equipped with the serial link and it is connected to the Ethernet through the RS232/Ethernet converter. If the converter does no modifications to the transmitted data, then it is a very easy way how to communicate via Ethernet with the device not equipped with Ethernet interface.
Response receipt timeoutOnly for serial link. The recommended value is for example 2000 ms. The time (in milliseconds) the driver is waiting for the response on sending the message.
If no response comes during this time, then the transmission of the message is terminated (the onEndOfTransfer event is triggered with error 24 or 66).
Transfer modeThe Modbus protocol includes two transfer options.
In the message parameters of the PmaCommMsg object, the mode can be changed (for special cases, when necessary to communicate with multiple PLCs in different modes).
RTU - Most commonly used transfer mode, where the data is being transferred in binary form.
ASCII - The transfer mode, where the data is transferred in ASCII form. This mode is not supported for MODBUS TCP/IP.

The communication description by means of the PmaCommGroup object

The PmaCommGroup objects can be used for this driver. For usual data transmissions it is more favourable than using the PmaCommMsg object.
The variables in the PmaCommGroup object (or even better the variables in the PmaData object with ExtComm data extension) can be of arbitrary number, type and order. The driver uses optimalised internal communication messages for reading the data from the device.
All variables are read (if the "Data refresh enabled" configurator is checked). When writing into the variable, only the single variable is sent into the device (if the "Auto send when writing to item" configurator is checked).

Description of the "ItemId" configurator:
ItemId is the text identifier of the item that is used for addressing the item in the device. The "ItemId" configurator tells the driver how to receive or send the item value.
The text can be written manually, or it can be assembled in the window opened by the button to the right of the configurator.
Macro expression can be used for input (it is evaluated after the application is launched).

The ItemId identifier may look like for example "dev2.Ri33.W", where:
dev2 = the item is in the PLC device (device) with address 2. The devD (=default address) can be entered instead of the number and the device address will be determined according to the "Default device address" configurator.
Ri33 = is from the data area "Input registers on relative address 33. The address 33 is only relative address. During communication, the value defined in the "Area base addresses" configurator is added to this number.
A list of data areas:
- Bo = the area "Coil status / Output bits".
For data receive the Modbus function is used: FN01 (Read Coil Status, Read Output Bits).
For data write the Modbus function is used: FN05 (Force Single Coil, Write 1 Bit).
- BoM = the area "Coil status / Output bits".
For data receive the Modbus function is used: FN01 (Read Coil Status, Read Output Bits).
For data write the Modbus function is used: FN15 (Force Multiple Coils, Write n Bits).

The difference from the Bo area is only the write method (FN15 is used instead of FN05).
- Bi = the area "Input status / Input bits".
For data receive the Modbus function is used: FN02 (Read Input Status, Read Input Bits).
Data write is not possible.
- Ro = the area "Holding/Output registers".
For data receive the Modbus function is used: FN03 (Read Holding/Output Registers).
For data write the Modbus function is used: FN16 (Preset Multiple Registers, Write n Registers).
- RoS = the area "Holding/Output registers".
For data receive the Modbus function is used: FN03 (Read Holding/Output Registers).
For data write the Modbus function is used: FN06 (Preset Single Register, Write 1 Register).

The difference from the Ro area is only the write method (FN06 is used instead of FN16).
Caution: The function FN06 cannot write 4 and more byte values (for example data types Long and Float).
- RoB = the area "Holding/Output registers". Transmission of individual bits.
For data receive the Modbus function is used: FN03 (Read Holding/Output Registers).
For data write the Modbus function is used: FN22 (22-Mask Write Register).

Example: RoB38.0 is read/write of the bit 0 in register 38.
- Ri = the area "Input registers.
For data receive the Modbus function is used: FN04 (Read Input Registers).
Data write is not possible.
W = in PLC has the Word data type


Description of the "PmaCommGroup > Parameters > Special Parameters" configurator:
Default device addressThe address defined here can be used for definitions in the "ItemId" configurator in variables in this object (i.e. in variables on the "Data" tab or in data extension ExtComm). The address can be entered in ItemId:
- as for example dev1... - then the value will be read from the PLC device with address 1.
- or devD... - the "D" character means default, (it means that the address is taken from this configurator).

This parameter can be modified and read in the script in runtime by methods: SetSpecParam("SlaveAddr") and GetSpecParam("SlaveAddr").
Area base addressesHere, the addresses of the beginnings of the data areas are entered (Bo, Bi, Ro, Ri).
The addresses for these areas are preset to 0. (if the preconfiguration for a specific device is not used - see Preconfigurations / Communication / Protocols and other communications / Modbus). For another PLC types the addresses my be different (e.g. the addresses do not begin with 0, but with 1 or 40001, etc.).
While communicating, the "Data item address" is modified as a sum of the relative item address (defined in the ItemId identificator) and the area base address.
Maximum number of variables received in one messageFor each area (Bo,Bi,Ro,Ri) the maximum number of variables to be transmitted in one message is defined here. These values depend on the device type to communicate with (some PLC devices support transmission of low register numbers in one message, other support higher numbers) - this specification can be found in the device documentation or must be tried/tested.
The preset values are 64 for Bo and Bi, 32 for Ro and Ri (if the preconfiguration for a specific device is not used - see Preconfigurations / Communication / Protocols and other communications / Modbus).
The preset values are very low. Increasing these values (if the device allows it) may cause higher communication speeds because the transmitted data can be sent in a lower number of communication messages.

The communication description by means of the PmaCommMsg object

The PmaCommMsg object can be used for special communications, that cannot be executed by the PmaCommGroup object. For example by the "XX-User defined opened function" type message it is possible to compose any Modbus message types, that are not directly supported by the driver.

The address of the Slave station from which it is read or to which it is written, must be entered in each message. This address is entered on the "Data-sent" tab of the message in the Slave variable (e.g. for the Modicon, valid Slave addresses are in the range of 0-247).
The address 0 is used for the broadcast, i.e. for the messages received by all stations (if the Modbus protocol is used on higher network level, then the broadcast may not be allowed). The driver sends these messages but does not wait for response - therefore it is not relevant to set address 0 for messages that are to read (e.g. messages 01 to 04).

Further the address of the variable in the station is entered on the "Data-sent" tab in the Addr variable. The address value is supposed to be from 0 by default. But some devices (e.g. Modicon, GE-Fanuc) are addressed from 1 and therefore it is necessary to enter the Addr value decreased by 1 at these stations.
The maximum number of values (states, registers) in one message differs according to the PLC device. It can be for example 32, 125, 128, 1024, etc.

List and description of the communication messages:
01-Read Coil Status (Read Output Bits): This message reads n output states (1-bit values) from the specified address Addr.
02-Read Input Status (Read Input Bits): This message reads n input states (1-bit values) from the specified address Addr.
03-Read Holding Registers (Read Output Registers): This message reads n output registers (16-bits values) from the specified address Addr.
04-Read Input Registers: This message reads n input registers (16-bits values) from the specified address Addr.
05-Force Single Coil (Write 1 Bit): This message writes into one state (1-bit value) to the specified address Addr.
06-Preset Single Register (Write 1 Register): This message writes into one register (16-bits value) to the specified address Addr.
15-Force Multiple Coils (Write n Bits): This message writes into n state (1-bit values) from the specified address Addr.
16-Preset Multiple Registers (Write n Registers): This message writes into n registers (16-bits values) from the specified address Addr.
22-Mask Write Register (Modify Register Using both AND & OR Masks): This message writes defined individual bits into a single register (16-bit value) using the AND and OR mask.
There are following variables on the "Data-sent" tab:
Slave - The device address to communicate with.
Addr - the address of the register where the bits will be written.
AND_Mask - mask of bits to be zeroed
OR_Mask - mask of bits to be set
There is no variable on the "Data-received" tab.
XX-User defined opened function:
User-defined Modbus message. It can be used for message types that are not otherwise supported by this driver. The designer can define the complete content of the message (received or sent), but the order and data type of the DataX variables must be observed carefully.
The variables DataX (in Data-sent and in Data-received) represent data in Modbus protocol from the character Function (without this character) and up to the character CRC (for serial RTU, without his character) or up to the end of the message (for Modbus TCP/IP). For ASCII transfer mode the data is defined the same way as for RTU mode and the driver then transforms such data into ASCII form.
There are following variables on the "Data-sent" tab:
TXLength - The size of transmitted data (in bytes). This is not the total size of the sent message, but just the portion that is stored in the DataX variables on this tab. The -1 value means that all variables DataX on this tab are to be sent.
RXLength - Maximum expected size of accepted data (in bytes).
This is not the total size of the received message, but just the portion that will be stored into variables DataX on the "Data-received" tab.
The -1 value means that the expected size will be calculated as the total length of all DataX variables on the "Data-received" tab.
If the size is defined less than the currently received data, then an error occurs and the received data is not processed.
If the size is defined greater than the currently received data, then the transmission takes longer (the system will wait for timeout), but the received data is processed.
Slave - The device address to communicate with.
Function - Number (code) of Modbus function. For example 1 = Read Coil Status, 17 = Report Slave ID etc.
DataX - User-defined data that are to follow after the function number in the message (without the control sum). There may be multiple variables (of different data types) on the tab, but only those that fit into the message will be sent (i.e. according to the value in TxLength).
There are following variables on the "Data-received" tab:
Length - The size of received data (in bytes). It is not the total size of the received message, but only the portion that is stored in DataX variables on this tab.
Function - The number (code) of Modbus function. Normally, there should be the same value here as on the "Data-sent" tab.
DataX - Received data. There may be multiple variables (also different data types) on this tab, but only those that were in the received message will be filled.

History:
Pm8.03.25: Fixed bug: Optimized PmaCommGroup variables assignment into individual communication messages.
Pm8.03.24:
- Generalization: Added Modbus data type: LL2 = LongLong type 2 (8Byte Signed Integer)
- Fixed bug: On data receive it was not tested whether the response came from the correct device.
Pm8.03.19: Generalization for send broadcast type message by means of the PmaCommMsg object, i.e. if the defined Slave address is 0, then the broadcasted message will be received all stations in the network.
Pm8.03.10: Generalization for data writing by Modbus function FN06 (area RoS).
Pm8.03.01: Fixed bug: Reading and writing bit in the registry (i.e. reading and writing area RoB) did not work correctly.
Pm8.02.11: in the message of the XX-User defined opened function type the number of bytes of received data was not saved into the variable on the "Data-received" tab. The total message length was saved instead.
Pm8.02.03: Fixed bug: Bugfix transmission of the message of the XX-User defined opened function type.
Pm8.02.00:
- Now it is possible to transmit messages for user-defined functions. In the PmaCommMsg object parameters, it is now possible to set the function: XX-User defined opened function.
- Now it is possible to write individual bits (in the PmaCommGroup and PmaCommMsg objects) by the 22-Mask Write Register (Modify Register Using both AND & OR Masks) Modbus function.
Pm8.00.05:
- into the PmaCommGroup object, there has been added a new "Default device address" configurator. In some cases the new configurator allows easier address input and administration.
- Fixed bug: there was sometimes an error when sending values in the PmaCommGroup object.
Pm8.00.03:
- Generalization: Added Modbus data type: R2 = Float type 2 (4Byte - IEEE 754)
- Fixed bug: the PmaCommGroup object sometimes incorrectly received the bit values.
Pm8.00.02: Fixed bug: The PmaCommGroup object was unable to read/write 4-byte values (Long, Single).
PROMOTIC 9.0.27 SCADA system documentation MICROSYS, spol. s r.o.

Send page remarkContact responsible person
© MICROSYS, spol. s r.o.