MODBUS library

Description of the MODBUS library

MODBUS_UDP.lib

Version 0.1

TABLE OF CONTENTS

1 GENERAL INFORMATION 2

2 USING THE LIBRARY 3

2.1 The program CyclicReceive 3
2.2 The function block ModBusReadCoils 3
2.3 The function block ModBusReadMultipleRegisters 4
2.4 The function block ModBusWriteCoils 4
2.5 The function block ModBusWriteMultipleRegisters 5
2.6 The function block GetCommEventCounter 5
2.7 The functionblock ModBusReadWriteMultipleRegisters 6

3 THE EXAMPLE MODBUS_EXAMPLE.PRO 8

 3S - Smart Software Solutions GmbH 1

ModBus Lib Description_E.doc Page 1 of 9
MODBUS library

1 General information

The MODBUS Protocol is a client-server communication protocol for the simple exchange of data
between intelligent devices. It was developed by MODICON in 1979 and has established itself as an
industrial standard.

The library MODBUS_UDP.lib was implemented for the programming system „CoDeSys“ from 3S –
Smart Software Solutions GmbH.
It is based on the documents
- MODBUS MESSAGING ON TCP/IP IMPLEMENTATION GUIDE 1.0 and
- the protocol specification „Modicon Modbus Protocol Reference Guide“,
which are both available for download on the web page www.modbus.org.
The library implements the functions
- FC1 Read Coil Status
- FC3 Read Holding Registers
- FC15 Force Multiple Coils (Write Coils)
- FC16 Preset Multiple Registers (Write Multiple Registers)
- FC11 Fetch Comm Event Counter
All other functions of the protocol specification were not implemented in this version of the library.
(They are needed fairly seldom and can partly be replaced by the implemented functions.)
The MODBUS library is based on the libraries SysLibSockets (TCP/UDP-connections) and the
SysLibCallbacks (system calls). Both are delivered along with a 3S runtime system (e.g. SoftPLC).

 3S - Smart Software Solutions GmbH 2

ModBus Lib Description_E.doc Page 2 of 9
MODBUS library

2 Using the library

In order to be able to use the MODBUS library in a CoDeSys application (PLC program) it has to be
inserted in CoDeSys.
To do so open the library manager and choose “insert -> Additional library…“.
Then select the ModBus_UDP.lib. The system libs “SysLibCallback“ and “SysLibSockets“ are then
automatically inserted.
Only the function blocks and the program “CyclicReceive“ of the library may be used by the
application. All other functions are used internally by the library itself as only the library can make
sensible use of them.

2.1 The program CyclicReceive

The program CyclicReceive must be called cyclically by the application. This means the user has to
write:
“CyclicReceive()“
into the POU connected to the task which manages the MODBUS communication (if no task
configuration is used, this is done by PLC_PRG).
This POU receives the telegrams of the other MODBUS devices in the network and distributes them
among the callers (the function blocks of the library).

2.2 The function block ModBusReadCoils

The function block ReadCoils implements the MODBUS function FC1 (ReadCoilStatus). The following
parameters are passed at the inputs of the POUs listed below:
- The target address of the MODBUS device to whom the query is to be sent. The address is
passed as a 32-bit value so that the 4-byte IP address of the user is written in the 4 bytes of
the DWORD. The IP address “192.168.100.32“ for example is passed as 16#C0A86420. (C0
in hexadecimal is 192 in decimal and so on)
- The target port of the recipient used to receive the telegram. Port No. 502 is defined as the
standard port in the MODBUS protocol specification and has to be supported by all MODBUS
devices. This means the constant 502 is passed here under normal circumstances.
- The start address from which BitCount bits are read from the device. (On a Wago I/O node for
example the entries of the node are read beginning with the start address 0)
- Enable flag. A rising edge at this entry results in a query being sent out.
POUs parameters are passed at:
- DestAddress : DWORD;
- DestPort : WORD;
- StartAddress : WORD;
- BitCount : WORD; (*Is limited to a maximum of 64 bits.*)
- Enable : BOOL.
The POU reacts by resetting its ready output and is cyclically called by the application. If the response
corresponding to the query is received the POU enters the length and the data of the response into its
output parameters Data and DataLen. Ready switches to TRUE. In case of error i.e. if the response
was an exception (an error on the device has occurred) the output error is switched to TRUE. The
exception code is then written in data [0].
The execution time of the POU has to be monitored by the application. After the POU has been
executed it has to be called once with Enable := FALSE in order to be able to recognize the next rising
edge.
 3S - Smart Software Solutions GmbH 3
ModBus Lib Description_E.doc Page 3 of 9
MODBUS library

2.3 The function block ModBusReadMultipleRegisters

The function block ModBusReadMultipleRegisters implements the MODBUS function FC3 (Read
Holding Registers). The following parameters are passed at the inputs of the POUs listed below:
- The target address of the MODBUS device to whom the query is to be sent. The address is
passed as a 32-bit value so that the 4-byte IP address of the user is written in the 4 bytes of
the DWORD. The IP address “192.168.100.32“ for example is passed as 16#C0A86420. (C0
in hexadecimal is 192 in decimal and so on)
- The target port of the recipient used to receive the telegram. Port No. 502 is defined as the
standard port in the MODBUS protocol specification and has to be supported by all MODBUS
devices. This means the constant 502 is passed here under normal circumstances.
- The start address from which Count registers are read from the device. (On a Wago I/O node
for example the entry words of the node are read beginning with the start address 0)
- Enable flag. A rising edge at this entry results in a query being sent out.
POUs parameters are passed at:
- DestAddress : DWORD;
- DestPort : WORD;
- StartAddress : WORD;
- Count: WORD; (*Is limited to a maximum of 11 registers.*)
- Enable : BOOL.
The POU reacts by resetting its ready output and is cyclically called by the application. If the response
corresponding to the query is received the POU enters the length and the data of the response into its
output parameters Data and DataLen. DataLen specifies the number of words allowed in the array of
word data. Ready switches to TRUE. In case of error i.e. if the response was an exception (an error
on the device has occurred) the output error is switched to TRUE. The exception code is then written
in data [0].
The execution time of the POU has to be monitored by the application. After the POU has been
executed it has to be called once with Enable := FALSE in order to be able to recognize the next rising
edge.

2.4 The function block ModBusWriteCoils

The function block ModBusWriteCoils implements the MODBUS function FC15 (Force Multiple Coils).
The following parameters are passed at the inputs of the POUs listed below:
- The target address of the MODBUS device to whom the query is to be sent. The address is
passed as a 32-bit value so that the 4-byte IP address of the user is written in the 4 bytes of
the DWORD. The IP address “192.168.100.32“ for example is passed as 16#C0A86420. (C0
in hexadecimal is 192 in decimal and so on)
- The target port of the recipient used to receive the telegram. Port No. 502 is defined as the
standard port in the MODBUS protocol specification and has to be supported by all MODBUS
devices. This means the constant 502 is passed here under normal circumstances.
- The start address from which BitCount bits from Data [0..7] are written into the device. (On a
Wago I/O node for example the output bits of the node are written beginning with the start
address 0)
- Enable flag. A rising edge at this entry results in a query being sent out.
POUs parameters are passed at:
- DestAddress : DWORD;
- DestPort : WORD;

 3S - Smart Software Solutions GmbH 4

ModBus Lib Description_E.doc Page 4 of 9
MODBUS library

- StartAddress : WORD;
- BitCount: WORD; (*Is limited to a maximum of 64 bits.*)
- Enable : BOOL.
- Data: ARRAY[0..7] of BYTE.
The POU reacts by resetting its ready output and is cyclically called by the application. If the response
corresponding to the query is received ready switches to TRUE. In case of error i.e. if the response
was an exception (an error on the device has occurred) the output error is switched to TRUE. The
exception code is then written in data [0].
The execution time of the POU has to be monitored by the application. After the POU has been
executed it has to be called once with Enable := FALSE in order to be able to recognize the next rising
edge.

2.5 The function block ModBusWriteMultipleRegisters

The function block ModBusWriteMultipleRegisters implements the MODBUS function FC16 (Preset
Multiple Registers). The following parameters are passed at the inputs of the POUs listed below:
- The target address of the MODBUS device to whom the query is to be sent. The address is
passed as a 32-bit value so that the 4-byte IP address of the user is written in the 4 bytes of
the DWORD. The IP address “192.168.100.32“ for example is passed as 16#C0A86420. (C0
in hexadecimal is 192 in decimal and so on)
- The target port of the recipient used to receive the telegram. Port No. 502 is defined as the
standard port in the MODBUS protocol specification and has to be supported by all MODBUS
devices. This means the constant 502 is passed here under normal circumstances.
- The start address from which Count registers from Data [0..10] are written into the device. (On
a Wago I/O node for example the output words of the node are written beginning with the start
address 0)
- Enable flag. A rising edge at this entry results in a query being sent out.
POUs parameters are passed at:
- DestAddress : DWORD;
- DestPort : WORD;
- StartAddress : WORD;
- Count: WORD; (*Is limited to a maximum of 10 registers.*)
- Enable : BOOL.
- Data: ARRAY[0..10] of WORD.
The POU reacts by resetting its ready output and is cyclically called by the application. If the response
corresponding to the query is received ready switches to TRUE. In case of error i.e. if the response
was an exception (an error on the device has occurred) the output error is switched to TRUE. The
exception code is then written in data [0].
The execution time of the POU has to be monitored by the application. After the POU has been
executed it has to be called once with Enable := FALSE in order to be able to recognize the next rising
edge.

2.6 The function block GetCommEventCounter

The function block GetCommEventCounter implements the MODBUS function FC11 (Fetch Comm
Event Counter). The following parameters are passed at the inputs of the POUs listed below:
- The target address of the MODBUS device to whom the query is to be sent. The address is
passed as a 32-bit value so that the 4-byte IP address of the user is written in the 4 bytes of

 3S - Smart Software Solutions GmbH 5

ModBus Lib Description_E.doc Page 5 of 9
MODBUS library

the DWORD. The IP address “192.168.100.32“ for example is passed as 16#C0A86420. (C0
in hexadecimal is 192 in decimal and so on)
- The target port of the recipient used to receive the telegram. Port No. 502 is defined as the
standard port in the MODBUS protocol specification and has to be supported by all MODBUS
devices. This means the constant 502 is passed here under normal circumstances.
- Enable flag. A rising edge at this entry results in a query being sent out.
POUs parameters are passed at:
- DestAddress : DWORD;
- DestPort : WORD;
- Enable: BOOL.
The POU reacts by resetting its ready output and is cyclically called by the application. If the response
corresponding to the query is received ready switches to TRUE. In case of error i.e. if the response
was an exception (an error on the device has occurred) the output error is switched to TRUE. The
exception code is then written in status. The event counter is incremented on the device on every
successful communication event, except if the counter itself is queried. A communication event is a
query.
The execution time of the POU has to be monitored by the application. After the POU has been
executed it has to be called once with Enable := FALSE in order to be able to recognize the next rising
edge.

2.7 The functionblock ModBusReadWriteMultipleRegisters

The functionblock ModBusReadWriteMultipleRegisters implements the Modbus-function FC23.
At the inputs of the FB
- DestAddress : DWORD;
- DestPort : WORD;
- Enable : BOOL;
the following parameters are passed:
The address of the communication partner to which the request should be sent. The address is
passed as a 32-bit value
The port on which the receiver awaits the request.
- Enable-Flag. A rising edge starts a request.
The other inputs are the following:
- StartAddressRead : WORD;
- StartAddressWrite : WORD;
- CountRead : WORD;
- DataWrite : ARRAY[0..50] OF WORD;
- CountWrite : WORD;
- UnitID: BYTE:= 1; Die im Modbusprotokoll beschriebene UnitId.
They are used as:
- The reference number of the first register to be read.
- The reference number of the first register to be written.
- Number of words to be read (registers).

 3S - Smart Software Solutions GmbH 6

ModBus Lib Description_E.doc Page 6 of 9
MODBUS library

- An array with 50 words, containing the data to be written

- The number of words which are valid in DataWrite.
The functionblock will send a request on a rising edge on enable-input. It has to be called cyclically
until the FB sets the READY flag. ThenCountOutData words in DataOut are valid. They have been
received from the slave. If the errorflag is set, CountDataOut will be 1 and the first word of DataOut will
contain the exceptioncode. If the errorflag is set and CountDataOut is 0, then a message was received
with a matching transactionID, but the functioncode is invalid. (Remember transaction-IDs are handled
by the library itself. This is just for understanding, what happens.)
A timeout supervision of the FB has to be performed by the application. To abort a request and make
the FB able to restart a new one, just call it with enable = FALSE.

 3S - Smart Software Solutions GmbH 7

ModBus Lib Description_E.doc Page 7 of 9
MODBUS library

3 The example Modbus_example.pro

The example shipped with the library contains one instance per defined functionblock.
Here you can see how each of these blocks work.
To work with the project, just open it and edit the initializationvalue of the variable TheNode. Use the
IP-address of the desired communicationpartner.
The other values should be used as desired. To determine these values, refer the documentation of
the slave.
Then load the project to the PLC and write one of the flags bDoMbrwmr, bRead, bWrite, bWriteRegs,
bReadRegs or bReadEventCtr to TRUE. Then write the corresponding enableflag to TRUE and the
desired functionblock should set its Readyflag within a short time (if the communicationpartner
answers).
The example and the library were tested together with a WAGO-Ethernet-Koppler 750-842.

 3S - Smart Software Solutions GmbH 8

ModBus Lib Description_E.doc Page 8 of 9
MODBUS library

 3S - Smart Software Solutions GmbH 9

ModBus Lib Description_E.doc Page 9 of 9