Library Documentation

Building

Automation

Library Documentation
WagoAppPlcModbus.library

Version 0.0.0.3
2 WagoAppPlcModbus.library
Library Documentation

© 2016 by WAGO Kontakttechnik GmbH & Co. KG

All rights reserved.

WAGO Kontakttechnik GmbH & Co. KG

Hansastraße 27
D-32423 Minden

Phone: +49 (0) 571/8 87 – 0

Fax: +49 (0) 571/8 87 – 1 69

Email: [email protected]

Online: http://www.wago.com

Technical Support

Phone: +49 (0) 571/8 87 – 5 55

Fax: +49 (0) 571/8 87 – 85 55

Email: [email protected]

Every conceivable measure has been taken to ensure the accuracy and
completeness of this documentation. However, as errors can never be fully
excluded, we always appreciate any information or suggestions for improving the
documentation.

We wish to point out that the software and hardware terms, as well as the
trademarks of companies used and/or mentioned in the present document are
generally protected by trademark or patent.

Version 0.0.0.3
WagoAppPlcModbus.library Overview 3
Library Documentation

Information about This Documentation

Copyright
This documentation, including all figures and illustrations contained therein, is
subject to copyright protection. Any use of this documentation that infringes upon
the copyright provisions stipulated herein is prohibited. Reproduction, translation,
electronic and phototechnical filing/archiving (e.g., photocopying), as well as any
amendments require the written consent of WAGO Kontakttechnik GmbH & Co.
KG, Minden, Germany. Non-observance will entail the right of claims for
damages.

Number Notation
Table 1: Number Notation
Number System Example Comment
Decimal 100 Normal notation
Hexadecimal 0x64 C notation
Binary '100' In single quotes,
'0110.0100' nibble separated by a period

Font Conventions
Table 2: Font Conventions
Font Type Explanation
italic Names of paths and files are shown in italics, e.g.:
C:\Programs\WAGO-I/O-CHECK
Menu Menu options are shown in bold, e.g.,:
Save
> A “greater than” symbol between two names denotes the selection of
a menu option, e.g.:
File > New
Input Names of input or selection fields are shown in bold, e.g.:
Start of measurement range
“Value” Input or selection values are shown in quotation marks, e.g.:
Enter the value “4mA” under Start of measurement range.
[Button] Button labels within the dialogs are bold and enclosed in square
brackets, e.g.:
[Input]
[Key] Key labels on the keyboard are shown in bold and enclosed in square
brackets, e.g.:
[F5]

Version 0.0.0.3
4 Overview WagoAppPlcModbus.library
Library Documentation

Symbols

DANGER Warning against personal injury!

Indicates a high-risk, imminently hazardous situation which, if not avoided,
will result in death or serious injury.

DANGER Do not work on components while energized!

Indicates a high-risk, imminently hazardous situation which, if not avoided,
will result in death or serious injury.

WARNING Warning against personal injury!

Indicates a moderate-risk, potentially hazardous situation which, if not
avoided, could result in death or serious injury.

CAUTION Warning against personal injury!

Indicates a low-risk, potentially hazardous situation which, if not avoided,
may result in minor or moderate injury.

NOTICE Warning against damage to property!

Indicates a potentially hazardous situation which, if not avoided, may result
in damage to property.

ESD Warning against damage to property caused by electrostatic discharge!

Indicates a potentially hazardous situation which, if not avoided, may result
in damage to property.

Note Important note!

Indicates a potential malfunction, but one which will not result in damage to
property if not avoided.

Information Additional information

Refers to additional information which is not an integral part of this
documentation (e.g., the Internet).

Version 0.0.0.3
WagoAppPlcModbus.library Overview 5
Library Documentation

Legal Principles

Subject to Change
WAGO Kontakttechnik GmbH & Co. KG reserves the right to make any
alterations or modifications that serve the purpose of technical progress. WAGO
Kontakttechnik GmbH & Co. KG owns all rights arising from granting patents or
from the legal protection of utility patents. Third-party products are always
mentioned without any reference to patent rights. Thus, the existence of such
rights cannot be excluded.

Personnel Qualification
The use of the product described in this document is exclusively geared to
specialists having qualifications in PLC programming, electrical specialists or
persons instructed by electrical specialists who are also familiar with the
appropriate current standards.

Moreover, the persons named here must also be familiar with all of the products
cited in this document, along with the operating instructions. They must also be
capable of correctly predicting any hazards which may not arise until the products
are combined.

WAGO Kontakttechnik GmbH & Co. KG assumes no liability resulting from

improper action and damage to WAGO products and third-party products due to
non-observance of the information contained in this document.

Limitation of Liability
This documentation describes the use of various hardware and software
components in specific example applications. The components may represent
products or parts of products from different manufacturers. The respective
operating instructions from the manufacturers apply exclusively with regard to
intended and safe use of the products. The manufacturers of the respective
products are solely responsible for the contents of these instructions.

The sample applications described in this documentation represent concepts, that

is, technically feasible applications. Whether these concepts can actually be
implemented depends on various general conditions. For example, different
versions of the hardware or software components may require different handling
than that described here. Therefore, the descriptions contained in this
documentation do not form the basis for assertion of a particular product
characteristic.

Responsibility for safe use of a specific software or hardware configuration lies

with the party that produces or operates the configuration. This also applies if one
of the concepts described in this document was used for implementation of the
configuration.

WAGO Kontakttechnik GmbH & Co. KG assumes no liability for the realization
of these concepts.

Version 0.0.0.3
6 Overview WagoAppPlcModbus.library
Library Documentation

Table of Contents
Table of Contents................................................................................................... 6
1 Overview ....................................................................................................... 7
2 Master (Client) ............................................................................................. 8
2.1 FbMbMasterSerial..................................................................................... 8
2.2 FbMbMasterUdp ....................................................................................... 9
2.3 FbMbMasterTcp ........................................................................................ 9
3 Slave (Server) ............................................................................................. 10
3.1 Data Areas ............................................................................................... 11
3.2 Simple Modbus Slaves ............................................................................ 12
3.2.1 FbMbSimpleServerSerial ................................................................... 12
3.2.2 FbMbSimpleServerTcp ...................................................................... 13
3.2.3 FbMbSimpleServerUdp ...................................................................... 13
3.3 Advanced Modbus Slaves ....................................................................... 14
3.3.1 Area Composers ................................................................................. 14
3.3.2 Data Models........................................................................................ 16
3.3.2.1 FbMbSlaveDataModel ................................................................... 19
3.3.2.2 FbMbKompositorDataModel ........................................................ 19
3.3.3 Servers ................................................................................................ 20
3.3.3.1 FbMbServerSerial .......................................................................... 20
3.3.3.2 FbMbServerTcp ............................................................................. 20
3.3.3.3 FbMbServerUdp ............................................................................ 20
3.3.4 Data Model Switches .......................................................................... 21
3.4 FbMbAccessInfo ..................................................................................... 21
3.4.1 FbShowMbAccessInfo ....................................................................... 21
3.5 I_DataAccessListener ............................................................................. 22
3.5.1 beforeAccess(..) .................................................................................. 23
3.5.2 afterAccess(..) ..................................................................................... 23
4 Appendix ..................................................................................................... 25
4.1 Overview ................................................................................................. 25
4.2 Examples ................................................................................................. 26
4.2.1 Simple Server ..................................................................................... 26
4.2.2 Multi Server ........................................................................................ 27
4.2.3 Multi Server Multi Areas.................................................................... 28
4.2.4 Multi Server Multi Data Model .......................................................... 29
4.2.5 Multi Server Multi Data Model Multi Area ....................................... 30

Version 0.0.0.3
WagoAppPlcModbus.library Overview 7
Library Documentation

1 Overview
The WagoAppPlcModbus.library library provides the PLC programmer with
various MODBUS functions on different levels.

A distinction is made between master functions and slave functions.

The master (client) sends a query to a slave (server) and waits for a response.

A query consists first of a slave address (unit ID), which addresses a data model,
and a function code, which specifies which data space (discrete inputs, coils, input
register or holding register) should be accessed and how (read or write).

Besides the function code that specifies the data space, the address provided in the
query is used to select the memory locations within the selected data space that
are to be addressed.

The library contains the following masters (clients):

 FbMbMasterSerial
This master is designed for a serial communication connection between
masters and slaves. This master supports the Modbus RTU and Modbus
ASCII protocols.

 FbMbMasterTcp
This master is designed for a TCP connection between master and slave.
This master supports the Modbus TCP, Modbus RTU over Ethernet TCP
and Modbus ASCII over Ethernet TCP protocols.

 FbMbMasterUdp
This master is designed for UDP communication between master and
slave. This master supports the Modbus UDP, Modbus RTU over Ethernet
UDP and Modbus ASCII over Ethernet UDP protocols.

In addition, the library contains various slaves (servers) with different levels of
complexity.

In most cases, FbMbSimpleServer… should cover the requirements.

For more extensive requirements, there are various advanced modules that allow
versatile combination of data models, address ranges and servers.

All modules of this library should be called cyclically.

Version 0.0.0.3
8 Master (Client) WagoAppPlcModbus.library
Library Documentation

2 Master (Client)
The masters of this library support the following function codes:

 FC01 (0x01) Read Coils

 FC02 (0x02) Read Discrete Inputs

 FC03 (0x03) Read Holding Registers

 FC04 (0x04) Read Input Registers

 FC05 (0x05) Write Single Coil

 FC06 (0x06) Write Single Register

 FC11 (0x0B) Get Comm Event Counter

 FC15 (0x0F) Write Multiple Coils

 FC16 (0x10) Write Multiple Registers

 FC22 (0x16) Mask Write Register

 FC23 (0x17) Read/Write Multiple Registers

2.1 FbMbMasterSerial
This function block provides MODBUS master functionality over a serial
connection. It supports a choice of either the Modbus RTU or the Modbus ASCII
protocol. The protocol type is specified with the eFrameType input parameter.

Version 0.0.0.3
WagoAppPlcModbus.library Master (Client) 9
Library Documentation

2.2 FbMbMasterUdp
This function block provides MODBUS master functionality via a UDP server. It
supports a choice of either the Modbus UDP, the Modbus RTU over Ethernet
UDP or the Modbus ASCII over Ethernet UDP protocol. The protocol type is
specified with the eFrameType input parameter.

2.3 FbMbMasterTcp
This function block provides MODBUS master functionality via a TCP server. It
supports a choice of either the Modbus TCP, the Modbus TCP over Ethernet TCP
or the Modbus ASCII over Ethernet TCP protocol. The protocol type is specified
with the eFrameType input parameter.

Version 0.0.0.3
10 Slave (Server) WagoAppPlcModbus.library
Library Documentation

3 Slave (Server)
The slaves (servers) implemented in this library support the following MODBUS
function codes:

 16#01 Read Coils

 16#02 Read Discrete Inputs

 16#03 Read Holding Registers

 16#04 Read Input Registers

 16#05 Write Single Coil

 16#06 Write Single Register

 16#08 (only sub-function 0x0000) Loop Back

 16#0F Write Multiple Coils

 16#10 Write Multiple Registers

 16#16 Mask Write Register

 16#17 Read/Write Multiple Registers

Furthermore, the servers for serial communication support the Modbus RTU and
Modbus ASCII protocols.

Besides Modbus Ethernet, the servers for ETHERNET communication also

support the transport of serial Modbus RTU frames or Modbus ASCII frames.

Version 0.0.0.3
WagoAppPlcModbus.library Slave (Server) 11
Library Documentation

3.1 Data Areas

A data area is the physical memory that can be provided to a data model for
access via MODBUS telegrams.

A data area is represented by an ARRAY of type BOOL or WORD.

ARRAY[a..b] OF WORD

ARRAY[x..y] OF BOOL

The bounds of this range are freely specifiable within the number space 0 …
65535, where the lower bound is less than or equal to the upper bound.

The values of these bounds also specify the address space for MODBUS access.

A MODBUS client (master) cannot access different areas (across areas) with one
MODBUS query.

Use of the UNION data type can support structured access to a data area.

Version 0.0.0.3
12 Slave (Server) WagoAppPlcModbus.library
Library Documentation

3.2 Simple Modbus Slaves

The 30 Simple Modbus Slaves folder of the library contains easy-to-use
MODBUS servers (slaves) for Modbus RTU/ASCII and Modbus TCP/UDP.

These servers just need the corresponding data areas and the connection
parameters required by the server to be defined.

The oMbAccessInfo output object provides information about the last access to the
internal data model (who, what).

Reading the isReadAccess or isWriteAccess properties provides information about

whether corresponding access by a master has occurred since the last time these
properties were read.

3.2.1 FbMbSimpleServerSerial
This module allows simple access via a serial connection with the Modbus RTU
or Modbus ASCII protocol to the discrete inputs, coils, input register and holding
register data areas (see also: Data Areas).

Version 0.0.0.3
WagoAppPlcModbus.library Slave (Server) 13
Library Documentation

3.2.2 FbMbSimpleServerTcp
This module allows simple access via a TCP connection with the Modbus TCP,
Modbus RTU over Ethernet TCP or Modbus ASCII over Ethernet TCP protocol
to the discrete inputs, coils, input register and holding register data areas (see
also: Data Areas).

3.2.3 FbMbSimpleServerUdp
This module allows simple access via a UDPconnection with the Modbus UDP or
Modbus RTU over Ethernet UDP or Modbus ASCII over Ethernet UDP protocol
to the discrete inputs, coils, input register and holding register data areas (see
also: Data Areas).

Version 0.0.0.3
14 Slave (Server) WagoAppPlcModbus.library
Library Documentation

3.3 Advanced Modbus Slaves

If your special requirements are not covered by the servers from the 30 Simple
Modbus Slaves folder, then in the 40 Advanced Modbus Slaves folder you will
find a tool kit for customizing your slave.

Features

 Providing data spaces with multiple data areas

 Managing multiple data models

 Providing multiple servers for access to one or more data models

An understanding of the following components is necessary in order to use these

features:

 Area (mandatory)

An “area” is a data range with a start address and end address (for more
information, see also: Data Areas).

 Composer (optional)

A “composer” combines multiple separate data areas into one data space.

 Data model (mandatory)

A “data model” is addressed via a unit ID and manages access to the four
data spaces DiscreteInputs, Coils, InputRegister and HoldingRegister by
MODBUS masters.

 Switch (optional)

A “switch” manages multiple data models and distributes the queries of a

server to the associated data model according to the unit ID.

 Server (mandatory)

A “server” provides access to the corresponding data areas via the

intermediate components for external MODBUS masters via an interface
(RS-232/RS-485/ETHERNET/…).

3.3.1 Area Composers

An area composer combines multiple data areas into one data space.

The Area Composers folder contains various composers for corresponding

requirements.

Version 0.0.0.3
WagoAppPlcModbus.library Slave (Server) 15
Library Documentation

There are composers for Boolean arrays and word arrays with different numbers
of input ports.

For example, the Fb4PortWordAreaKompositor module can combine four word

data areas into one word data space.

The data areas of a composer must not overlap the bounds.

If only one data area is required in each of the four data spaces (DiscreteInputs,
Coils, InputRegister, HoldingRegister), one can forgo use of a composer.

In this case the FbMbSlaveDataModel data model should be used instead of

FbMbKompositorDataModel.

Example of a four-port word area composer:

Version 0.0.0.3
16 Slave (Server) WagoAppPlcModbus.library
Library Documentation

3.3.2 Data Models

The Data Models folder contains two data models to be used depending on the
requirements:

 FbMbKompositorDataModel

This data model is needed when working with a composer where multiple
data areas are to be combined into one data space.

This makes it possible to manage multiple data areas of a data space.

 FbMbSlaveDataModel

This data model should be used if several different data areas are not
required in any data space.

In the implementation of the WagoAppPlcModbus library, one data model

manages the following four data spaces.

Data space Data Master access Function code for access by

type master

DiscreteInputs BOOL RO FC02

Coils BOOL RW FC01, FC05, FC15

InputRegisters WORD RO FC04

HoldingRegisters WORD RW FC03, FC06, FC16, FC22, FC23

The size of an area (array bounds) can be specified freely in the range 0 … 65535.

The specified array bounds also determine the address for the MODBUS master
for access to the data model.

Example:

VAR
myHoldingRegisters : ARRAY[200..3123] OF WORD;
END_VAR

This definition allows the MODBUS master to access the holding registers via
addresses 200 to 3123.

It is possible to define a shared data space for the holding registers and the input
registers.

The discrete inputs and coils data spaces can also be combined.

Version 0.0.0.3
WagoAppPlcModbus.library Slave (Server) 17
Library Documentation

The data model is addressed via the unit ID. The data spaces of a data model are
selected via the function code. An element of a data area is reached via the array
index as a read or write address.

Version 0.0.0.3
18 Slave (Server) WagoAppPlcModbus.library
Library Documentation

Version 0.0.0.3
WagoAppPlcModbus.library Slave (Server) 19
Library Documentation

Besides the input parameters for the unit ID and the four data spaces, a data model
also provides the following output parameters:

 I_MbDataModel
Access interface for a communication server

 oMbAccessInfo
Information on the last access to the data model by the communication
server

 oStatus
Information on errors that occurred

 xError
Indicates whether oStatus contains an error

3.3.2.1 FbMbSlaveDataModel

This data model is used if only one linear data area is required for each of the data
spaces discrete inputs, coils, input register and holding register.

3.3.2.2 FbMbKompositorDataModel

This data model is used if multiple data areas are required for one of more of the
data spaces discrete inputs, coils, input register and holding register.

Version 0.0.0.3
20 Slave (Server) WagoAppPlcModbus.library
Library Documentation

3.3.3 Servers
The servers of this library receive queries from external MODBUS masters and
pass them to a data model, conditioned accordingly. The response of the data
model is also conditioned again according to the protocol and returned to the
external master.

Different servers are available for the three different transport mechanisms: serial,
Ethernet TCP and Ethernet UDP.

3.3.3.1 FbMbServerSerial

3.3.3.2 FbMbServerTcp

3.3.3.3 FbMbServerUdp

Version 0.0.0.3
WagoAppPlcModbus.library Slave (Server) 21
Library Documentation

3.3.4 Data Model Switches

A data model switch manages multiple data models. A switch makes it possible to
publish multiple data models over one server. The respective data model is
addressed via the unit ID.

Example of a four-port data model switch

3.4 FbMbAccessInfo
Each data model provides an access object as an output parameter.
Further information about the last access to the data model can be determined via this
object.

3.4.1 FbShowMbAccessInfo
To simplify display of an AccessInfo-Object in the IDE (Integrated Development
Environment) in the graphical programming languages, FBShowMbAccessInfo has been
integrated into this library.

Version 0.0.0.3
22 Slave (Server) WagoAppPlcModbus.library
Library Documentation

3.5 I_DataAccessListener
The I_DataAccessListener makes it possible to monitor data model access.
All data models and SimpleServers offer the option of registering your own Data-Access-
Listener.

This listener must implement the I_DataAccessListener interface and thus must provide
the beforeAccess(..) and afterAccess(..) methods, which are called correspondingly after
the data models are registered.

Version 0.0.0.3
WagoAppPlcModbus.library Slave (Server) 23
Library Documentation

3.5.1 beforeAccess(..)
This method of the registered listener is called by the data model after the query of a
client (master) but before the access to the data.
The identification of the client, the desired function code and the addresses and size of
the desired data are also provided as call parameters.
The method implementation can now check these parameters and allow (return value =
0) or deny (return value <> 0) access.
If access is denied (return value <> 0), the return value is sent to the client as an
exception code.

3.5.2 afterAccess(..)
This method of the registered listener is called by the data model after the query of a
client (master) and successful access to the data.
This method is also called after access is denied.
The identification of the client, the desired function code, the addresses and size of the
desired data and the status object as the result of the access are also provided as call
parameters.
This method does not have a return value.

Version 0.0.0.3
24 Slave (Server) WagoAppPlcModbus.library
Library Documentation

Version 0.0.0.3
WagoAppPlcModbus.library Appendix 25
Library Documentation

4 Appendix
4.1 Overview

Version 0.0.0.3
26 Appendix WagoAppPlcModbus.library
Library Documentation

4.2 Examples
4.2.1 Simple Server

Version 0.0.0.3
WagoAppPlcModbus.library Appendix 27
Library Documentation

4.2.2 Multi Server

Version 0.0.0.3
28 Appendix WagoAppPlcModbus.library
Library Documentation

4.2.3 Multi Server Multi Areas

Version 0.0.0.3
WagoAppPlcModbus.library Appendix 29
Library Documentation

4.2.4 Multi Server Multi Data Model

Version 0.0.0.3
30 Appendix WagoAppPlcModbus.library
Library Documentation

4.2.5 Multi Server Multi Data Model Multi Area

Version 0.0.0.3
WagoAppPlcModbus.library Appendix 31
Library Documentation

Version 0.0.0.3
WAGO Kontakttechnik GmbH & Co. KG
PO box 2880 • D-32385 Minden
Hansastraße 27 • D-32423 Minden
Phone: +49 (0) 571/8 87 – 0
Fax: +49 (0) 571/8 87 – 1 69
Email: [email protected]
Web: http://www.wago.com