MODBUS Messaging on TCP/IP Implementation Guide V1.

0b Modbus Organization

MODBUS MESSAGING ON TCP/IP IMPLEMENTATION GUIDE

V1.0b

CONTENTS
1 INTRODUCTION ........................................................................................................... 2
1.1 OBJECTIVES ....................................................................................................... 2
1.2 CLIENT / SERVER MODEL................................................................................... 2
1.3 REFERENCE DOCUMENTS ................................................................................. 3
2 ABBREVIATIONS .......................................................................................................... 3
3 CONTEXT ..................................................................................................................... 3
3.1 PROTOCOL DESCRIPTION ................................................................................. 3
3.1.1 General communication architecture ......................................................... 3
3.1.2 MODBUS On TCP/IP Application Data Unit ............................................... 4
3.1.3 MBAP Header description ......................................................................... 5
3.2 MODBUS FUNCTIONS CODES DESCRIPTION .................................................... 6
4 FUNCTIONAL DESCRIPTION........................................................................................ 7
4.1 MODBUS COMPONENT ARCHITECTURE MODEL ............................................... 7
4.2 TCP CONNECTION MANAGEMENT ....................................................................10
4.2.1 Connections management Module ............................................................10
4.2.2 Impact of Operating Modes on the TCP Connection ..................................13
4.2.3 Access Control Module ............................................................................14
4.3 USE of TCP/IP STACK ........................................................................................14
4.3.1 Use of BSD Socket interface ....................................................................15
4.3.2 TCP layer parameterization .....................................................................18
4.3.3 IP layer parameterization .........................................................................19
4.4 COMMUNICATION APPLICATION LAYER ...........................................................20
4.4.1 MODBUS Client .......................................................................................20
4.4.2 MODBUS Server ......................................................................................26
5 IMPLEMENTATION GUIDELINE ...................................................................................32
5.1 OBJECT MODEL DIAGRAM ................................................................................32
5.1.1 TCP management package ......................................................................33
5.1.2 Configuration layer package .....................................................................35
5.1.3 Communication layer package..................................................................36
5.1.4 Interface classes......................................................................................37
5.2 IMPLEMENTATION CLASS DIAGRAM .................................................................37
5.3 SEQUENCE DIAGRAMS......................................................................................39
5.4 CLASSES AND METHODS DESCRIPTION ..........................................................42
5.4.1 MODBUS Server Class ............................................................................42
5.4.2 MODBUS Client Class..............................................................................43
5.4.3 Interface Classes .....................................................................................44
5.4.4 Connexion Management class ..................................................................45

October 24, 2006 http://www.Modbus.org 1/46

MODBUS Messaging on TCP/IP Implementation Guide V1.0b Modbus Organization

1 INTRODUCTION

1.1 OBJECTIVES

The objective of this document is to present the MODBUS messaging service over
TCP/IP , in order to provide reference information that helps software developers to
implement this service. The encoding of the MODBUS function codes is not described
in this document, for this information please read the MODBUS Application Protocol
Specification [1].

This document gives accurate and comprehensive description of a MODBUS messaging

service implementation. Its purpose is to facilitate the interoperability between the
devices using the MODBUS messaging service.

This document comprises mainly three parts:

• An overview of the MODBUS over TCP/IP protocol
• A functional description of a MODBUS client, server and gateway
implementation.
• An implementation guideline that proposes the object model of an MODBUS
implementation example.

1.2 CLIENT / SERVER MODEL

The MODBUS messaging service provides a Client/Server communication between
devices connected on an Ethernet TCP/IP network.
This client / server model is based on four type of messages:

• MODBUS Request,
• MODBUS Confirmation,
• MODBUS Indication,
• MODBUS Response

Request Indication

MODBUS Client Confirmation Response MODBUS Server

A MODBUS Request is the message sent on the network by the Client to initiate a
transaction,

A MODBUS Indication is the Request message received on the Server side,

A MODBUS Response is the Response message sent by the Server,

A MODBUS Confirmation is the Response Message received on the Client side

The MODBUS messaging services (Client / Server Model) are used for real time
information exchange:

• between two device applications,

• between device application and other device,
• between HMI/SCADA applications and devices,
• between a PC and a device program providing on line services.

October 24, 2006 http://www.Modbus.org 2/46

MODBUS Messaging on TCP/IP Implementation Guide V1.0b Modbus Organization

-
1.3 REFERENCE DOCUMENTS
This section gives a list of documents that are interesting to read before this one:

[1] MODBUS Application Protocol Specification V1.1a.

[2] RFC 1122 Requirements for Internet Hosts -- Communication Layers

2 ABBREVIATIONS
ADU Application Data Unit
IETF Internet Engineering Task Force
IP Internet Protocol
MAC Medium Access Control
MB MODBUS
MBAP MODBUS Application Protocol
PDU Protocol Data Unit
PLC Programmable Logic Controller
TCP Transport Control Protocol
BSD Berkeley Software Distribution
MSL Maximum Segment Lifetime

3 CONTEXT

3.1 PROTOCOL DESCRIPTION

3.1.1 General communication architecture

A communicating system over MODBUS TCP/IP may include different types of device:

• A MODBUS TCP/IP Client and Server devices connected to a TCP/IP network

• The Interconnection devices like bridge, router or gateway for interconnection

between the TCP/IP network and a serial line sub-network which permit
connections of MODBUS Serial line Client and Server end devices.

October 24, 2006 http://www.Modbus.org 3/46

MODBUS Messaging on TCP/IP Implementation Guide V1.0b Modbus Organization

MODBUS
Client
Serial Line

MODBU MODBU
S Client S Client
TCP/IP TCP/IP Client
TCP/IP

MODBUS

MODBUS MODBUS
MODBU MODBU
Server Server
S Server S Server
Serial Line Serial Line
TCP/IP TCP/IP
Server TCP/IP
gateway

MODBUS Serial

Figure 1: MODBUS TCP/IP communication architecture

The MODBUS protocol defines a simple Protocol Data Unit (PDU) independent of the
underlying communication layers. The mapping of MODBUS protocol on specific buses
or networks can introduce some additional fields on the Application Data Unit (ADU).

ADU
Additional address Function code Data Error check

PDU

Figure 2: General MODBUS frame

The client that initiates a MODBUS transaction builds the MODBUS Application Data
Unit. The function code indicates to the server which kind of action to perform.

3.1.2 MODBUS On TCP/IP Application Data Unit

This section describes the encapsulation of a MODBUS request or response when it is
carried on a MODBUS TCP/IP network.

MODBUS TCP/IP ADU

MBAP Header Function code Data

PDU

Figure 3: MODBUS request/response over TCP/IP

A dedicated header is used on TCP/IP to identify the MODBUS Application Data Unit. It
is called the MBAP header (MODBUS Application Protocol header).
October 24, 2006 http://www.Modbus.org 4/46
MODBUS Messaging on TCP/IP Implementation Guide V1.0b Modbus Organization

This header provides some differences compared to the MODBUS RTU application data
unit used on serial line:
The MODBUS ‘slave address’ field usually used on MODBUS Serial Line is
replaced by a single byte ‘Unit Identifier’ within the MBAP Header. The
‘Unit Identifier’ is used to communicate via devices such as bridges,
routers and gateways that use a single IP address to support multiple
independent MODBUS end units.
All MODBUS requests and responses are designed in such a way that the
recipient can verify that a message is finished. For function codes where
the MODBUS PDU has a fixed length, the function code alone is sufficient.
For function codes carrying a variable amount of data in the request or
response, the data field includes a byte count.
When MODBUS is carried over TCP, additional length information is
carried in the MBAP header to allow the recipient to recognize message
boundaries even if the message has been split into multiple packets for
transmission. The existence of explicit and implicit length rules, and use of
a CRC-32 error check code (on Ethernet) results in an infinitesimal chance
of undetected corruption to a request or response message.

3.1.3 MBAP Header description

The MBAP Header contains the following fields:

Fields Length Description - Client Server

Transaction 2 Bytes Identification of a Initialized by the Recopied by the

Identifier MODBUS Request / client server from the
Response transaction. received
request

Protocol Identifier 2 Bytes 0 = MODBUS protocol Initialized by the Recopied by the

client server from the
received
request

Length 2 Bytes Number of following Initialized by the Initialized by

bytes client ( request) the server (
Response)

Unit Identifier 1 Byte Identification of a Initialized by the Recopied by the

remote slave client server from the
connected on a serial received
line or on other buses. request

The header is 7 bytes long:

• Transaction Identifier - It is used for transaction pairing, the MODBUS server copies
in the response the transaction identifier of the request.

• Protocol Identifier – It is used for intra-system multiplexing. The MODBUS protocol

is identified by the value 0.

• Length - The length field is a byte count of the following fields, including the Unit
Identifier and data fields.

October 24, 2006 http://www.Modbus.org 5/46

MODBUS Messaging on TCP/IP Implementation Guide V1.0b Modbus Organization

• Unit Identifier – This field is used for intra-system routing purpose. It is typically
used to communicate to a MODBUS+ or a MODBUS serial line slave through a
gateway between an Ethernet TCP-IP network and a MODBUS serial line. This field is
set by the MODBUS Client in the request and must be returned with the same value in
the response by the server.

All MODBUS/TCP ADU are sent via TCP to registered port 502.

Remark : the different fields are encoded in Big-endian.

3.2 MODBUS FUNCTIONS CODES DESCRIPTION

Standard function codes used on MODBUS application layer protocol are described in
details in the MODBUS Application Protocol Specification [1].

October 24, 2006 http://www.Modbus.org 6/46

MODBUS Messaging on TCP/IP Implementation Guide V1.0b Modbus Organization

4 FUNCTIONAL DESCRIPTION
The MODBUS Component Architecture presented here is a general model including
both MODBUS Client and Server Components and usable on any device.

Some devices may only provide the server or the client component.

In the first part of this section a brief overview of the MODBUS messaging service
component architecture is given, followed by a description of each component
presented in the architectural model.

4.1 MODBUS COMPONENT ARCHITECTURE MODEL

USER
APPLICATION

Communication Modbus Client Modbus Backend

Application Interface Interface

Layer
Ressource Management

Modbus Client Modbus Server

Flow Control
&

TCP
Management
Stack Connection
Access Ctl
parmeterization Management

TCP/IP Stack

Figure 4: MODBUS Messaging Service Conceptual Architecture

• Communication Application Layer

A MODBUS device may provide a client and/or a server MODBUS interface.

A MODBUS backend interface can be provided allowing indirectly the access to user
application objects.
Four areas can compose this interface: input discrete, output discrete (coils), input
registers and output registers. A pre-mapping between this interface and the user
application data has to be done (local issue).

October 24, 2006 http://www.Modbus.org 7/46

MODBUS Messaging on TCP/IP Implementation Guide V1.0b Modbus Organization

Primary tables Object type Type of Comments

This type of data can be provided by an I/O system.
Discretes Input Single bit Read-Only

This type of data can be alterable by an application

Coils Single bit Read-Write program.
This type of data can be provided by an I/O system
Input Registers 16-bit word Read-Only
This type of data can be alterable by an application
Holding Registers 16-bit word Read-Write program.

Device application memory Device application memory

MODBUS access MODBUS access

Input Discrete Input Discrete

R
W
Coils MODBUS Request Coils MODBUS Request

R
Input Registers Input Registers

W
Output Registers Output Registers

MODBUS SERVER DEVICE MODBUS SERVER DEVICE

Figure 5 MODBUS Data Model with Figure 6 MODBUS Data Model with only
separate blocks 1 block

MODBUS Client

The MODBUS Client allows the user application to explicitly control information
exchange with a remote device. The MODBUS Client builds a MODBUS request from
parameter contained in a demand sent by the user application to the MODBUS Client
Interface.
The MODBUS Client uses a MODBUS transaction whose management includes waiting
for and processing of a MODBUS confirmation.

MODBUS Client Interface

The MODBUS Client Interface provides an interface enabling the user application to
build the requests for various MODBUS services including access to MODBUS
application objects. The MODBUS Client interface (API) is not part of this
Specification, although an example is described in the implementation model.

MODBUS Server

On reception of a MODBUS request this module activates a local action to read, to

write or to achieve some other actions. The processing of these actions is done totally
transparently for the application programmer. The main MODBUS server functions are
to wait for a MODBUS request on 502 TCP port, to treat this request and then to build a
MODBUS response depending on device context.

MODBUS Backend Interface

The MODBUS Backend Interface is an interface from the MODBUS Server to the user
application in which the application objects are defined.

Informative Note: The Backend Interface is not defined in this Specification

October 24, 2006 http://www.Modbus.org 8/46
MODBUS Messaging on TCP/IP Implementation Guide V1.0b Modbus Organization

• TCP Management layer

Informative Note: The TCP/IP discussion in this Specification is based in part upon
reference [2] RFC 1122 to assist the user in implementing the MODBUS Application
Protocol Specification [1] over TCP/IP.

One of the main functions of the messaging service is to manage communication

establishment and ending and to manage the data flow on established TCP
connections.

Connection Management

A communication between a client and server MODBUS Module requires the use of a
TCP connection management module. It is in charge to manage globally messaging
TCP connections.

Two possibilities are proposed for the connection management. Either the user
application itself manages TCP connections or the connection management is totally
done by this module and therefore it is transparent for the user application. The last
solution implies less flexibility.

The listening TCP port 502 is reserved for MODBUS communications. It is

mandatory to listen by default on that port. However, some markets or applications
might require that another port is dedicated to MODBUS over TCP. For that reason, it
is highly recommended that the clients and the servers give the possibility to the user
to parameterize the MODBUS over TCP port number. It is important to note that
even if another TCP server port is configured for MODBUS service in certain
applications, TCP server port 502 must still be available in addition to any
application specific ports.

Access Control Module

In certain critical contexts, accessibility to internal data of devices must be forbidden for
undesirable hosts. That’s why a security mode is needed and security process may be
implemented if required.

• TCP/IP Stack layer

The TCP/IP stack can be parameterized in order to adapt the data flow control, the
address management and the connection management to different constraints specific
to a product or to a system. Generally the BSD socket interface is used to manage the
TCP connections.

Resource management and Data flow control

In order to equilibrate inbound and outbound messaging data flow between the
MODBUS client and the server, data flow control mechanism is provided in all layers
of MODBUS messaging stack.
The resource management and flow control module is first based on TCP internal flow
control added with some data flow control in the data link layer and also in the user
application level.

October 24, 2006 http://www.Modbus.org 9/46

MODBUS Messaging on TCP/IP Implementation Guide V1.0b Modbus Organization

4.2 TCP CONNECTION MANAGEMENT

4.2.1 Connections management Module

4.2.1.1 General description

A MODBUS communication requires the establishment of a TCP connection between a

Client and a Server.
The establishment of the connection can be activated either explicitly by the User
Application module or automatically by the TCP connection management module.
In the first case an application-programming interface has to be provided in the user
application module to manage completely the connection. This solution provides
flexibility for the application programmer but it requires a good expertise on TCP/IP
mechanism.
In the second case the TCP connection management is completely hidden to the user
application that only sends and receives MODBUS messages. The TCP connection
management module is in charge to establish a new TCP connection when it is
required.
The definition of the number of TCP client and server connections is not on the scope of
this document (value n in this document). Depending on the device capacities the
number of TCP connections can be different.

Implementation Rules :

1) Without explicit user requirement, it is recommended to implement the automatic TCP

connection management

2) It is recommended to keep the TCP connection opened with a remote device and not
to open and close it for each MODBUS/TCP transaction,
Remark: However the MODBUS client must be capable of accepting a close request
from the server and closing the connection. The connection can be reopened when
required.

3) It is recommended for a MODBUS Client to open a minimum of TCP connections with

a remote MODBUS server (with the same IP address). One connection per application
could be a good choice.

4) Several MODBUS transactions can be activated simultaneously on the same TCP

Connection.
Remark: If this is done then the MODBUS transaction identifier must be used to
uniquely identify the matching requests and responses.

5) In case of a bi-directional communication between two remote MODBUS entities (

each of them is client and server), it is necessary to open separate connections for
the client data flow and for the server data flow.

6) A TCP frame must transport only one MODBUS ADU. It is advised against sending
multiple MODBUS requests or responses on the same TCP PDU

October 24, 2006 http://www.Modbus.org 10/46