UM14001 Emmodbus

emModbus
CPU independent
Modbus stack for
embedded applications
User & Reference Guide
Document: UM14001
Software version: 1.00
Revision: 2
Date: July 1, 2014
A product of SEGGER Microcontroller GmbH & Co. KG
www.segger.com
2
Disclaimer
Specifications written in this document are believed to be accurate, but are not guar-
anteed to be entirely free of error. The information in this manual is subject to
change for functional or performance improvements without notice. Please make sure
your manual is the latest edition. While the information herein is assumed to be
accurate, SEGGER Microcontroller GmbH & Co. KG (SEGGER) assumes no responsibil-
ity for any errors or omissions. SEGGER makes and you receive no warranties or con-
ditions, express, implied, statutory or in any communication with you. SEGGER
specifically disclaims any implied warranty of merchantability or fitness for a particu-
lar purpose.
Copyright notice
You may not extract portions of this manual or modify the PDF file in any way without
the prior written permission of SEGGER. The software described in this document is
furnished under a license and may only be used or copied in accordance with the
terms of such a license.
© 2014 SEGGER Microcontroller GmbH & Co. KG, Hilden / Germany
Trademarks
Names mentioned in this manual may be trademarks of their respective companies.
Brand and product names are trademarks or registered trademarks of their respec-
tive holders.
Contact address
SEGGER Microcontroller GmbH & Co. KG
In den Weiden 11
D-40721 Hilden
Germany
Tel.+49 2103-2878-0
Fax.+49 2103-2878-28
E-mail: [email protected]
Internet: http://www.segger.com
UM14001 User & Reference Guide for emModbus © 2014 SEGGER Microcontroller GmbH & Co. KG
3
Manual versions
This manual describes the current software version. If any error occurs, inform us
and we will try to assist you as soon as possible.
Contact us for further information on topics or routines not yet specified.
Print date: July 1, 2014
Software Revision Date By Description

1.00 2 140601 MC Updated file information.
1.00 1 140314 MC "Getting Started", "Tasks and Interrupt usage". Spelling.
1.00 0 140224 MC Initial version.
4
5
About this document

Assumptions
This document assumes that you already have a solid knowledge of the following:
• The software tools used for building your application (assembler, linker, C com-
piler)
• The C programming language
• The target processor
• DOS command line
If you feel that your knowledge of C is not sufficient, we recommend The C Program-
ming Language by Kernighan and Richie (ISBN 0-13-1103628), which describes the
standard in C-programming and, in newer editions, also covers the ANSI C standard.
How to use this manual
This manual explains all the functions and macros that the product offers. It assumes
you have a working knowledge of the C language. Knowledge of assembly program-
ming is not required.
Typographic conventions for syntax
This manual uses the following typographic conventions:
Style Used for
Body Body text.
Text that you enter at the command-prompt or that appears on

Keyword
the display (that is system functions, file- or pathnames).
Parameter Parameters in API functions.

Sample Sample code in program examples.
Sample comment Comments in programm examples.
Reference to chapters, sections, tables and figures or other docu-

Reference
ments.
GUIElement Buttons, dialog boxes, menu names, menu commands.
Emphasis Very important sections.

Table 1.1: Typographic conventions
UM14001 User & Reference Guide for emModbus © 2014 SEGGER SEGGER Microcontroller GmbH & Co. KG
6
SEGGER Microcontroller GmbH & Co. KG develops

and distributes software development tools and ANSI C
software components (middleware) for embedded sys-
tems in several industries such as telecom, medical
technology, consumer electronics, automotive industry
and industrial automation.
SEGGER’s intention is to cut software development time
for embedded applications by offering compact flexible and easy to use middleware,
allowing developers to concentrate on their application.
Our most popular products are emWin, a universal graphic software package for embed-
ded applications, and embOS, a small yet efficient real-time kernel. emWin, written
entirely in ANSI C, can easily be used on any CPU and most any display. It is comple-
mented by the available PC tools: Bitmap Converter, Font Converter, Simulator and
Viewer. embOS supports most 8/16/32-bit CPUs. Its small memory footprint makes it
suitable for single-chip applications.
Apart from its main focus on software tools, SEGGER develops and produces programming
tools for flash micro controllers, as well as J-Link, a JTAG emulator to assist in develop-
ment, debugging and production, which has rapidly become the industry standard for
debug access to ARM cores.
Corporate Office: United States Office:

http://www.segger.com http://www.segger-us.com
EMBEDDED SOFTWARE SEGGER TOOLS

(Middleware)
emWin Flasher
Graphics software and GUI Flash programmer
emWin is designed to provide an effi- Flash Programming tool primarily for micro con-
cient, processor- and display control- trollers.
ler-independent graphical user
interface (GUI) for any application that J-Link
operates with a graphical display. JTAG emulator for ARM cores
USB driven JTAG interface for ARM cores.
embOS
Real Time Operating System J-Trace
embOS is an RTOS designed to offer JTAG emulator with trace
the benefits of a complete multitasking USB driven JTAG interface for ARM cores with
system for hard real time applications Trace memory. supporting the ARM ETM (Embed-
with minimal resources. ded Trace Macrocell).
embOS/IP J-Link / J-Trace Related Software

TCP/IP stack Add-on software to be used with SEGGER’s indus-
embOS/IP a high-performance TCP/IP try standard JTAG emulator, this includes flash
stack that has been optimized for programming software and flash breakpoints.
speed, versatility and a small memory
footprint.
emFile
File system
emFile is an embedded file system with
FAT12, FAT16 and FAT32 support. Vari-
ous Device drivers, e.g. for NAND and
NOR flashes, SD/MMC and Compact-
Flash cards, are available.
USB-Stack
USB device/host stack
A USB stack designed to work on any
embedded system with a USB control-
ler. Bulk communication and most stan-
dard device classes are supported.
7
Table of Contents
1 Introduction to emModbus ...............................................................................................9

1.1 The Modbus standard ............................................................................... 10
1.2 emModbus.............................................................................................. 14
1.3 Tasks and interrupt usage......................................................................... 16
2 Getting Started...............................................................................................................21
2.1 Installation ............................................................................................. 22
2.2 Upgrade a trial version ............................................................................. 23
2.3 Upgrade an embOS start project................................................................ 24
2.4 Create a project from scratch .................................................................... 29
3 Example applications .....................................................................................................31

3.1 Overview ................................................................................................ 32
4 Core functions................................................................................................................35
4.1 API functions .......................................................................................... 36
4.2 emModbus data structures ........................................................................ 64
4.3 Error codes ............................................................................................. 69
5 Configuring emModbus..................................................................................................71
5.1 Compile-time configuration ....................................................................... 72
6 Debugging......................................................................................................................75
6.1 Message output ....................................................................................... 76
6.2 Using a network sniffer to analyse ethernet communication problems ............. 81
6.3 Testing emModbus applications ................................................................. 82
7 OS Integration................................................................................................................83
7.1 General information ................................................................................. 84
7.2 OS layer API functions.............................................................................. 85
8 Resource usage.............................................................................................................97
8.1 Memory footprint..................................................................................... 98
8
9
Chapter 1
Introduction to emModbus
This chapter provides an introduction to using emModbus. It explains the basic con-
cepts behind emModbus.
10 CHAPTER 1 Introduction to emModbus
1.1 The Modbus standard

The Modbus protocol was originally published in 1979 by Modicon (which later
became Schneider Electric) and has since evolved into a standard communications
protocol for industrial electronic devices. In 2004, Schneider transfered rights to the
protocol to the Modbus Organization, which since is in charge of the open standard’s
further development.
1.1.1 Modbus message basics

The modbus protocol is an application layer messaging protocol used for communica-
tions between devices that are connected to different types of buses or networks.
It uses a master-slave-technique in which one device, the master, initiates transac-
tions (called “queries”). Other devices, the slaves, respond by performing the action
requested in the query or by supplying the requested data to the master.
The protocol determines how each device will know its address, how it will recognize
a message addressed to it, how it will determine the kind of action to be taken and
how it will extract data or any other information contained in the message. It also
determines how slaves construct and send reply messages.
1.1.1.1 Message frames

Several Modbus messaging formats ("frames") exist and are used for different pur-
poses and environments, though many of them are not compliant to the Modbus
standard. The standard-compliant frame variants are listed in the following table:
Protocol Description
Original Modbus standard. Binary data is sent via serial connec-
RTU
tions such as RS-232 or similar.
ASCII Similar to RTU. Instead of raw binary, data is encoded in ASCII.
Binary data is encapsulated in a TCP frame and sent via net-
Modbus/TCP work connections such as Ethernet. This variant can also be
used with UDP instead of TCP and is then called Modbus/UDP.
Table 1.1: Standard-compliant variants of Modbus message frames
When using ASCII frames or RTU frames via serial connection, parameters such as
baud rate and parity bits must be set correctly for all connected devices.
When using Modbus/TCP, setting these parameters is not required, but correct IP
address and port number are required instead. The standard port number for Mod-
bus/TCP is port 502.
11
1.1.1.2 Message fields

Although the different message frames are each handled differently by the protocol,
RTU frames and ACSCII frames each include the same four fields. Field 2 and 3 con-
stitute the Protocol Data Unit (PDU), which is part of Modbus/TCP message frames as
well, while all 4 fields together constitute the Application Data Unit (ADU):
Field 1 includes the address of a slave device, either indicating the slave that is des-
ignated to receive the message from its master, or indicating the slave that sent the
message towards its master. This address, which is refered to as "unit ID" or "slave
address", is a number from 1 to 247 and is uniquely assigned to a single slave
device, allowing these devices to listen for messages containing their specific ID.
Additionaly, ID 0 is used to send broadcasts and ID 255 usually is reserved for com-
munications with a Modbus gateway.
Field 2 includes a function code, which, when sent by a master, indicates the instruc-
tion a slave is asked to carry out. When sent by a slave, on the other hand, the func-
tion code indicates the instruction the slave is responding to.
Field 3 contains variable amounts of data, e.g. certain data addresses a master wants
a slave to read, or the data a slave is reporting towards its master.
In field 4 Modbus messages carry a checksum to allow their respective recipients to
determine wether a message has arrived completely.
RTU message frames
When using RTU frames, each byte contained in a message is sent as binary data.
The main advantage of this mode is its greater density, allowing better data through-
put for the same baud rate when compared to ASCII frames. To indicate the start of
an RTU frame, the ADU is preceded by a silent interval of at least 3.5 Byte times,
hence the length of that interval depends on the configuration of the devices in use.
To indicate the end of a frame, another silent interval of 3.5 Byte times succeeds the
ADU. Note that one single interval of silence can, at the same time, indicate the end
of one frame and the beginning of another frame. RTU frames use Cyclic Redundancy
Checks (CRC).
A complete RTU frame can be depicted as shown below:
ASCII message frames

When using ASCII frames, each byte contained in a message is encoded and sent as
two ASCII characters. This allows time intervals of up to one second to occur
between characters without causing an error. To indicate the start of a frame, the
ADU is preceded by a single character, which always is a colon (0x3A). To indicate the
end of a frame, another two trailing characters succeed the ADU, which always are
"Carriage Return" and "Line Feed" (0x0D and 0x0A, respectively). ASCII frames use
Longitudinal Redundancy Checks (LRC).
A complete ASCII frame can be depicted as shown below:
Modbus/TCP message frames

When using Modbus/TCP frames, an additional header called "Modbus Application
Header" precedes the PDU. Its four fields contain the transaction ID, the protocol ID,
the length of the following frame and the slave address.
The transaction ID is a number from 0 to 65,535 encoded into two bytes. A master
device will increment this number for every request it sends to a slave, while slaves
simply echoe the number back to their master. By doing so, the master is able to
decide wether messages got lost or delayed in transmission.
The protocol ID is a two-byte value, too, but is always 00 00. The length field con-
sists of two more bytes indicating the length of the remaining message.
Finally the address field contains a unit ID, similar to that included in ASCII frames or
RTU frames. But with Modbus/TCP, it does not necessarily serve a purpose, as the IP
address is used instead to indicate the message’s recipient. However, the unit ID is
still part of the message and might be used to decide whether a device forwards a
message onto a serial connection, thereby allowing devices without networking capa-
bilities to be used in these environments, too.
A complete Modbus/TCP frame can be depicted as shown below:
13
1.1.2 Modbus data basics

Modbus was specifically designed for usage in supervisory control and data acquisi-
tion systems, connecting a supervisory computer with one or several remote terminal
units (RTU). Therefore, data types used in Modbus communications have been named
according to that implementation. When the Modbus protocol was extended in 1999
to include TCP frames via Ethernet, the data types’ names were left unchanged.
Four primary data types are used by Modbus:
Data type Description

Coil single bit, alterable by an application program, read-write
Discrete Input single bit, provided by an I/O system, read-only
Holding Register 16-bit, alterable by an application program, read-write
Input Register 16-bit, provided by an I/O system, read-only
Table 1.2: Primary Modbus data types
For referencing data, Modbus uses a concept of data tables, which are arrays or
blocks of memory used to store data. This data can then be referenced by using data
table addresses, represented by simple integer values between 0 and 65,535. While
it is fully standard-compliant to implement up to 65,536 addresses for each data
type, the number of addresses implemented in a particular device usually is much
lower. Therefore, Modbus implementations might even assign specific address ranges
of a single table to each type of data. While the Modbus standard itself does not
specify distinct address ranges, typical Modbus implementations utilize the following
assignments:
• 0xxxx-ranged addresses store coils.
• 1xxxx-ranged addresses store discrete inputs.
• 3xxxx-ranged addresses store input registers.
• 4xxxx-ranged addresses store holding registers.
Modbus uses a big-endian representation for data table addresses as well as for the
actual data itself. Therefore, the most significant byte is sent first when a numerical
quantity larger than a single byte is transmitted. For example
• (16-bits) 0x1234 gets send as 0x12 0x34 and
• (32-bits) 0x12345678 gets send as 0x12 0x34 0x56 0x78.
In addition to single bit data types (e.g. representing boolean values) and 16-bit data
types (e.g. representing integers), it is also possible to use large data types such as
long integers, floating point numbers and strings by splitting them over several
addresses. However, the Modbus standard does not stipulate this, hence it is up to
the individual user to split and store data accordingly.
1.1.3 Further reading

This guide explains the usage of the emModbus stack. It describes all functions which
are required to build a Modbus application. For a deeper understanding of the official
Modbus protocol, please refer to the following references.
• Modbus Organization official website: http://www.modbus.org/
1.2 emModbus
emModbus is written in ANSI C and can be used on virtually any CPU. It combines a
maximum of performance with a small memory footprint and comes with all features
typically required by embedded systems. RAM usage has been kept to a minimum by
smart buffer handling.
1.2.1 Features of emModbus

Features of emModbus include:
• Easy to integrate.
• Low memory footprint.
• ANSI-C code is completely portable and runs on any target.
• Follows the SEGGER coding standards: Efficient and compact, yet easy to read,
understand & debug.
• Supports ASCII, RTU and Modbus/TCP (and UDP) protocol.
• Sample applications for all protocols included.
• Kernel abstraction layer: can be used with or without any RTOS.
• Works out-of-the-box with embOS.
• Modbus/TCP can be used with standard socket interface and any TCP/IP stack.
• Works out-of-the-box with embOS/IP.
• Project for executable on PC for Microsoft Visual Studio available.
The following table shows the contents of the emModbus root directory:
Directory Content
Contains example applications to run

Application\*.c
emModbus with UART or embOS/IP.
Contains the emModbus configuration files.

Config\*.* Refer to Configuring emModbus on
page 71 for further information.
Contains the emModbus sources such as

MB\*.* MB_Core.c, MB_CHANNEL.c, MB_MASTER.c
and MB_SLAVE.c
Contains optimized memcpy routines to

Util\*.c
speed up the stack.
Contains the source(s), project file(s) and

Windows\*.* a executable(s) to run emModbus on a
Microsoft Windows host.
Table 1.3: Supplied directory structure of emModbus shippings
1.2.2 emModbus requirements

TCP/IP stack
For usage of Modbus/TCP, emModbus requires a TCP/IP capable stack. emModbus can
be used with any TCP/IP stack that supports BSD Standard Sockets. The shipment
includes an implementation which uses the socket API of embOS/IP.
Multi tasking
Although emModbus can be used completely without an RTOS, it is recommended to
use emModbus in a multi tasking system, at least when implementing a Modbus mas-
ter.
15
1.2.3 Development environment (compiler)

The CPU used is of no importance; only an ANSI-compliant compiler complying with
at least one of the following international standard is required:
• ISO/IEC/ANSI 9899:1990 (C90) with support for C++ style comments (//)
• ISO/IEC 9899:1999 (C99)
• ISO/IEC 14882:1998 (C++)
If your compiler has some limitations, let us know and we will inform you if these will
be a problem when compiling the software. Any compiler for 16/32/64-bit CPUs or
DSPs that we know of can be used; most 8-bit compilers can be used as well.
• A C++ compiler is not required, but can be used. The application program can
therefore also be programmed in C++ if desired.
1.3 Tasks and interrupt usage

emModbus can be used in an application in two different ways.
• With tasks dedicated to the stack.
• Without tasks dedicated to the stack.
The following chapters provide information on these ways for both ASCII and RTU
frames as well as for Modbus/TCP (or UDP) frames.
1.3.1 ASCII / RTU slave with tasks dedicated to the stack

To use tasks dedicated to the stack is the simplest way to use emModbus with ASCII
and/or RTU frames. The MB_SLAVE_Task handles housekeeping operations and eval-
uation of incoming frames. The "Store byte" operation is called and performed from
within the Interrupt Service Routine, hence no additional task is required.
Interrupt (ISR)
emModbus slave (ASCII / RTU)
Task
Routine / Action
Rx
MB_SLAVE_
Application tasks
Task
MB stack
Driver
MB_SLAVE_
MB_OnRx()
Exec()
App. App.
task 1 ... task n
Evaluat e Store
fram e byt e
17
1.3.2 ASCII / RTU slave without tasks dedicated to the stack

emModbus ASCII and/or RTU frames can also be used without any task dedicated to
the stack, if an application task calls MB_SLAVE_Exec() periodically. The "Store byte"
operation is called and performed from within the Interrupt Service Routine.
Interrupt (ISR)
emModbus slave (ASCII / RTU)
Task
Routine / Action
Rx
Application tasks
MB stack
Driver
MB_SLAVE_
MB_OnRx()
Exec()
App. App.
task 1 ... task n
Evaluat e Store
fram e byt e
1.3.3 TCP / UDP slave with tasks dedicated to the stack

To use tasks dedicated to the stack is the simplest way to use emModbus/TCP. The
MB_SLAVE_Task handles housekeeping operations and evaluation of incoming
frames. The "Read frame" operation is called and performed by another task,
MB_SLAVE_PollChannel, which periodically polls for incoming frames.
Interrupt (ISR)
emModbus slave (TCP / UDP)
Task
Routine / Action
MB_SLAVE_ MB_SLAVE_
Application tasks
Task PollChannel
MB stack
Driver
MB_SLAVE_
Exec()
App. App.
task 1 ... task n
Evaluat e Read
fram e frame
19
1.3.4 TCP / UDP slave without tasks dedicated to the stack

emModbus/TCP can also be used without any task dedicated to the stack, if an appli-
cation task consecutively calls MB_SLAVE_PollChannel() and MB_SLAVE_Exec() peri-
odically.
Interrupt (ISR)
emModbus slave (TCP / UDP)
Task
Routine / Action
MB_SLAVE_
Application tasks
PollChannel()
MB stack
Driver
MB_SLAVE_
1.) Exec()
App. App.
task 1 ... task n
2.)
Evaluat e Read
fram e frame
1.3.5 emModbus master

The emModbus master API is independent of the usage of any Real-time operating
system. However, by utilizing an RTOS the emModbus interface becomes more easy
and comfortable to integrate into any desired application.
21
Chapter 2
Getting Started
The first step in getting started with emModbus is to compile it for and run it on the
target system. This chapter explains how to do this.
In this document the IAR Embedded Workbench® IDE is used for all examples and
screenshots, but every other ANSI C toolchain can be used as well. It is also possible
to use makefiles; in this case, “add to the project” translates into “add to the make-
file”.
22 CHAPTER 2 Getting Started
2.1 Installation
emModbus is typically shipped as a .zip file in electronic form. In order to install
emModbus, extract it to any folder of your choice, preserving the directory structure
of the .zip file.
To create a running emModbus project, there are 3 different ways available:
• Upgrade a trial version by adding source code.
• Upgrade an embOS start project.
• Create a project from scratch.
The following example procedures describe each of these ways. They focus on inte-
grating an emModbus slave device using Modbus/TCP frames, but any other emMod-
bus project can be created as well by following the same steps.
emModbus via TCP is optimized to be used with embOS/IP, SEGGER’s TCP/IP stack.
However, emModbus can be used with any other TCP/IP stack as well. Note that when
using ASCII frames or RTU frames, the integration of a TCP/IP stack is not required
and should be omitted for smaller code size. Similarly, if no real-time operating sys-
tem is required, the integration of an RTOS should be omitted as well.
23
2.2 Upgrade a trial version

Various trial packages for different target hardware are available at SEGGER’s web-
site.
Note that not all trial packages currently available contain a trial of emModbus. If you
are interested in a specific package that does not contain emModbus yet, feel free to
contact us. Including emModbus in a trial package can be done in short time. Addi-
tionally, trial packages that do not contain embOS/IP do lack an appropiate TCP/IP
stack, which is required for Modbus/TCP frames. However, ASCII frames and RTU
frames might be used regardless of a TCP/IP stack.
Replace libraries with sources
After downloading the trial package, extract the project contained in the .zip file to
any folder of your choice and open the workpace/project file. Copy the source files
from the folder MB of your emModbus shipment into the folder MB of your down-
loaded package, add the files to the project and exclude the trial libraries from build.
Build the project

Build the project; it should compile without errors and warnings. If any problem is
encoutered during the build process, checking the include paths and project configu-
rations is advisable as first step. When done building, download the output into the
designated target and start the application.
Test the project
We recommend testing emModbus devices by using their respective counterparts,
e.g. using a emModbus/TCP master to test a emModbus/TCP slave and vice versa.
Alternatively, devices can also be tested with a desktop computer running an appro-
piate Modbus application.
Refer to Testing emModbus applications on page 82 for additional information.
2.3 Upgrade an embOS start project

Begin with a sample project for embOS, SEGGER’s real-time operating system, then
include embOS/IP and emModbus into the project.
The emModbus default configuration is preconfigured with valid values, which match
the requirements of most applications.
Procedure to follow
Integration of emModbus is a relatively simple process, which consists of the follow-
ing steps:
• Step 1: Open an embOS start project.
• Step 2: Add embOS/IP to the start project.
• Step 3: Add emModbus to the start project.
• Step 4: Build the project.
25
2.3.1 Step 1: Open an embOS start project

We recommend that you use one of the supplied embOS start projects for your target
system. Compile the project and run it on your target hardware.
2.3.2 Step 2: Adding embOS/IP to the start project

Add all source files in the following directories to your project:
• Config
• IP
• UTIL (optional)
The Config folder includes all configuration files of embOS/IP. The configuration files
are preconfigured with valid values that match the requirements of most applica-
tions. Add the hardware configuration IP_Config_<TargetName>.c supplied with the
driver shipment.
If your hardware is currently not supported, use the example configuration file and
the driver template to write your own driver. The example configuration file and the
driver template is located in the Sample\Driver\Template folder.
The Util folder is an optional component of the embOS/IP shipment. It contains
optimized MCU and/or compiler specific files, for example an optimized memcopy
function.
Replace BSP.c and BSP.h of your embOS start project
Replace the BSP.c source file and the BSP.h header file used in your embOS start
project with the one which is supplied with the embOS/IP shipment. Some drivers
require a special functions which initializes the network interface of the driver. This
function is called BSP_ETH_Init(). It is used to enable the ports which are connected
to the network hardware. All network interface driver packages include the BSP.c
and BSP.h files irrespective if the BSP_ETH_Init() function is implemented.
Configuring the include path
The include path is the path in which the compiler looks for include files. In cases
where the included files (typically header files, .h) do not reside in the same direc-
tory as the C file to compile, an include path needs to be set. In order to build the
project with all added files, you will need to add the following directories to your
include path:
• Config
• Inc
• IP
27
2.3.3 Step 3: Adding emModbus to the start project

Add all source files in the following directories to your project:
• Config
• MB
• UTIL (optional)
The Config folder includes all configuration files of emModbus. The configuration files
are preconfigured with valid values, which match the requirements of most applica-
tions.
Configuring the include path
The include path is the path in which the compiler looks for include files. In cases
where the included files (typically header files, .h) do not reside in the same direc-
tory as the C file to compile, an include path needs to be set. In order to build the
project with all added files, you will need to add the following directories to your
include path:
• Config
• MB
Select the start application
For quick and easy testing of your emModbus integration, start with the code found
in the folder Application. Add one of the applications to your project (for example
OS_IP_MB_SlaveTCP.c).
2.3.4 Step 4: Build the project

Build the project
Test the project
29
2.4 Create a project from scratch

To create a project from scratch, some steps have to be taken:
• A project or make file has to be created for the specific toolchain.
• The project configurations may need adjustments.
• The hardware routines have to be implemented.
• The path of any required header files has to be set as include path.
To get the target up and running is a lot easier if taget hardware drivers are already
available. In that case, these drivers can be used.
Creating the project or make file
The screenshot below gives an idea about a possible project setup:
Build the project

Test the project
31
Chapter 3
Example applications
In this chapter, you will find a description of the emModbus example applications that
are delivered together with the emModbus shipment.
32 CHAPTER 3 Example applications
3.1 Overview
Example applications for emModbus are supplied in source code in the Application
folder. These can be used for testing the correct installation and proper function of
the device running emModbus.
The following start application files are provided:
File Description
Demonstrates the functionality of a Modbus

OS_IP_MB_MasterTCP.c
Master device using TCP frames via network.

OS_IP_MB_SlaveTCP.c
Slave device using TCP frames via network.

OS_MB_MasterASCII.c Master device using ASCII frames via serial con-
nection.

OS_MB_MasterRTU.c Master device using RTU frames via serial con-
nection.

OS_MB_SlaveASCII.c Slave device using ASCII frames via serial con-
nection.

OS_MB_SlaveRTU.c Slave device using RTU frames via serial con-
nection.
Table 3.1: emModbus example applications
33
3.1.1 OS_IP_MB_MasterTCP.c
This sample demonstrates emModbus master functionalities using the Modbus/TCP
protocol. It opens a channel and tries to establish a TCP connection to a Modbus
slave device, which is known to the master by the slave’s IP address as defined at the
beginning of the file. The master also uses a given port for this connection, which is
defined at the beginning of the file, too (e.g. port 502, the standard port for Modbus
communications). When a connection is established, the master repeatedly sends
queries to the slave, asking it to perform the function “write coil”, and waits for
appropiate responses.
3.1.2 OS_IP_MB_SlaveTCP.c
This sample demonstrates emModbus slave functionalities using the Modbus/TCP pro-
tocol. It opens a channel and waits for incoming TCP connections on a given port,
which is known to the slave as defined at the beginning of the file. When an incoming
connection from a Modbus master device has been established, the slave reacts to
queries it receives from the master. When ordered to write a coil (like the associated
Modbus master sample does), the slave will toggle LEDs to signal its new status.
3.1.3 OS_MB_MasterASCII.c
This emModbus sample demonstrates emModbus master functionalities using ASCII
frames. It opens a channel and repeatedly sends queries to a Modbus slave device
(specified by its slave ID as defined at the beginning of the file), asking it to perform
the function “write coil”, and waits for appropiate responses.
3.1.4 OS_MB_MasterRTU.c
This emModbus sample demonstrates emModbus master functionalities using RTU
frames. It opens a channel and repeatedly sends queries to a Modbus slave device
(specified by its slave ID as defined at the beginning of the file), asking it to perform
the function “write coil”, and waits for appropiate responses.
3.1.5 OS_MB_SlaveASCII.c
This sample demonstrates emModbus slave functionalities using ASCII frames. It
opens a channel and waits for incoming queries from a Modbus master device. When
ordered to write a coil (like the associated Modbus master sample does), the slave
will toggle LEDs to signal its new status.
3.1.6 OS_MB_SlaveRTU.c
This sample demonstrates emModbus slave functionalities using RTU frames. It opens
a channel and waits for incoming queries from a Modbus master device. When
ordered to write a coil (like the associated Modbus master sample does), the slave
will toggle LEDs to signal its new status.
34 CHAPTER 3 Example applications
35
Chapter 4
Core functions
In this chapter, you will find a description of each emModbus core function.
36 CHAPTER 4 Core functions
4.1 API functions

The table below lists the available API functions within their respective categories.
Function Description
Channel specific core functions
MB_CHANNEL_Disconnect() Disconnects a connected channel.
Master specific core functions
Adds a master channel that uses ASCII
MB_MASTER_AddASCIIChannel()
frames via serial connection.
Adds a master channel that uses TCP
MB_MASTER_AddIPChannel()
frames via network.
Adds a master channel that uses RTU
MB_MASTER_AddRTUChannel()
De-Initializes master resources and
MB_MASTER_DeInit() channels and removes the master end-
point from the global endpoint list.
Initializes master resources and adds
MB_MASTER_Init()
master endpoint to global endpoint list.
Master instruction set
MB_MASTER_ReadCoils() Reads Coils from a slave.
MB_MASTER_ReadDI() Reads Discrete Inputs from a slave.
MB_MASTER_ReadHR() Reads Holding Registers from a slave.
MB_MASTER_ReadIR() Reads Input Registers from a slave.
MB_MASTER_WriteCoil() Writes a single coil to a slave.
MB_MASTER_WriteCoils() Writes multiple coils to a slave.
MB_MASTER_WriteReg() Writes a single register to a slave.
MB_MASTER_WriteRegs() Writes multiple registers to a slave.
Slave specific core functions
Adds a slave channel that uses ASCII
MB_SLAVE_AddASCIIChannel()
Adds a slave channel that uses TCP
MB_SLAVE_AddIPChannel()
frames via network.
Adds a slave channel that uses RTU
MB_SLAVE_AddRTUChannel()
De-Initializes the slave resources and
MB_SLAVE_DeInit() channels and removes the slave endpoint
from the global endpoint list.
Loops over all slave channels once and
MB_SLAVE_Exec() processes data when channel has been
signalled ready.
Initializes slave resources and adds slave
MB_SLAVE_Init()
endpoint to global endpoint list.
Polled periodically for each slave channel
MB_SLAVE_PollChannel() that requires requesting data instead of
getting it via interrupt.
Wrapper function that runs
MB_SLAVE_Task()
MB_SLAVE_Exec() in a task.
Other core functions
Function allowing to set a user defined
MB_ConfigTimerFreq() timer frequency instead of the default
frequency of 1kHz.
Table 4.1: emModbus API function overview
37
Function called by byte oriented trans-
MB_OnRx() mission channels that receive an inter-
rupt for new data received.
Function called by byte oriented trans-
MB_OnTx() mission channels once a Tx complete
interrupt has been received.
Function called on each timer interrupt to
MB_TimerTick() manage internal RTU timeout with serial
channels using the RTU protocol.
Table 4.1: emModbus API function overview (Continued)
4.1.1 Channel specific core functions

4.1.1.1 MB_CHANNEL_Disconnect()
Description
Disconnects a previously connected channel, if the channel did any connect at all and
is currently connected.
Prototype
void MB_CHANNEL_Disconnect ( MB_CHANNEL *pChannel );
Parameter
Parameter Description
pChannel [IN] Pointer to element of MB_CHANNEL.
Table 4.2: MB_CHANNEL_Disconnect() parameter list
39
4.1.2 Master specific core functions

4.1.2.1 MB_MASTER_AddASCIIChannel()
Description
Adds a master channel that uses ASCII frames via serial connection.
Prototype
void MB_MASTER_AddASCIIChannel ( MB_CHANNEL *pChannel,
MB_IFACE_CONFIG_UART *pConfig,
const MB_IFACE_UART_API *pIFaceAPI,
U32 Timeout,
U8 SlaveAddr,
U32 Baudrate,
U8 DataBits,
U8 Parity,
U8 StopBits,
U8 Port );
Parameter
pChannel [IN] Pointer to element of MB_CHANNEL that is added to linked list.
pConfig [IN] Pointer to element of MB_IFACE_CONFIG_UART.
[IN] Pointer to element of MB_IFACE_UART_API used to read/write
pIFaceAPI
from/to interface.
Timeout [IN] Timeout [in ms] to wait for answer.
SlaveAddr [IN] Slave address to access.
Baudrate [IN] Desired baudrate in UART protocol.
DataBits [IN] Number of data bits used in UART protocol.
Parity [IN] Parity used in UART protocol.
StopBits [IN] Number of stop bits used in UART protocol.
Port [IN] UART port number used by this channel.
Table 4.3: MB_MASTER_AddASCIIChannel() parameter list
Example
//
// Static declarations
//
static MB_CHANNEL _MBChannel;
static MB_IFACE_CONFIG_UART _MBConfig;
static const MB_IFACE_UART_API _IFaceAPI = {
_SendByte, _Init, _DeInit, NULL, NULL, NULL, NULL, NULL, NULL
};
//
// Code running in its own task
//
static void _MasterTask(void) {
MB_MASTER_Init(); // Init master
MB_MASTER_AddASCIIChannel(&_MBChannel, &_MBConfig, &_IFaceAPI, 3000, 1,
38400, 8, 0, 1, 0); // Add master channel
do { ... } // e.g. master/slave communications
}
4.1.2.2 MB_MASTER_AddIPChannel()
Description
Adds a master channel that uses TCP frames via network.
Prototype
void MB_MASTER_AddIPChannel ( MB_CHANNEL *pChannel,
MB_IFACE_CONFIG_IP *pConfig,
const MB_IFACE_IP_API *pIFaceAPI,
U32 Timeout,
U8 SlaveAddr,
U32 IPAddr,
U8 Port );
Parameter
pConfig [IN] Pointer to element of MB_IFACE_CONFIG_IP.
[IN] Pointer to element of MB_IFACE_IP_API used to read/write
pIFaceAPI
from/to interface.
IPAddr [IN] IP address of slave.
Port [IN] Slave port to connect to.
Table 4.4: MB_MASTER_AddIPChannel() parameter list
Example
//
//
static const MB_IFACE_IP_API _IFaceAPI = {
NULL, NULL, NULL, _Send, _Recv, _Connect, _Disconnect, NULL, NULL
};
//
//
MB_MASTER_AddIPChannel(&_MBChannel, &_MBConfig, &_IFaceAPI, 3000, 1,
IP_BYTES2ADDR(192,168,1,80), 502); // Add master channel
}
41
4.1.2.3 MB_MASTER_AddRTUChannel()
Description
Adds a master channel that uses RTU frames via serial connection.
Prototype
void MB_MASTER_AddRTUChannel ( MB_CHANNEL *pChannel,
U32 Timeout,
U8 SlaveAddr,
U32 Baudrate,
U8 DataBits,
U8 Parity,
U8 StopBits,
U8 Port );
Parameter
pIFaceAPI
from/to interface.
Table 4.5: MB_MASTER_AddRTUChannel() parameter list
Example
//
//
_SendByte, _Init, _DeInit, NULL, NULL, NULL, NULL, _InitTimer, _DeInitTimer
};
//
//
MB_MASTER_AddRTUChannel(&_MBChannel, &_MBConfig, &_IFaceAPI, 3000, 1,
38400, 8, 0, 1, 0); // Add master channel
}
4.1.2.4 MB_MASTER_DeInit()
Description
De-Initializes the master resources and channels and removes the master endpoint
from the global endpoint list.
Prototype
void MB_MASTER_DeInit ( void );
43
4.1.2.5 MB_MASTER_Init()
Description
Initializes the master resources and adds the master endpoint to the global endpoint
list.
Prototype
void MB_MASTER_Init ( void );
4.1.3 Master instruction set

4.1.3.1 MB_MASTER_ReadCoils()
Description
Reads coils from a slave.
Prototype
int MB_MASTER_ReadCoils ( MB_CHANNEL *pChannel,
U8 *pData,
U16 Addr,
U16 NumItems );
Parameter
pChannel [IN] Pointer to channel configured to interface a slave.
pData [OUT] Pointer to application buffer where to store the read data.
Addr [IN] Address in slave where to find the coils to access.
NumItems [IN] Number of items to read.
Table 4.6: MB_MASTER_ReadCoils() parameter list
Return value
<0: Error
0: OK
Example
//
//
static int _result;
static U8 *_pData;
//
//
MB_MASTER_AddASCIIChannel( ... ); // Add master channel
_result = MB_MASTER_ReadCoils(&_MBChannel, &_pData, 1000, 2);// Read Coils
}
45
4.1.3.2 MB_MASTER_ReadDI()
Description
Reads Discrete Inputs from a slave.
Prototype
int MB_MASTER_ReadDI ( MB_CHANNEL *pChannel,
U8 *pData,
U16 Addr,
U16 NumItems );
Parameter
Addr [IN] Address in slave where to find the inputs to access.
Table 4.7: MB_MASTER_ReadDI() parameter list
Return value
<0: Error
0: OK
Example
//
//
static int _result;
static U8 *_pData;
//
//
_result = MB_MASTER_ReadDI(&_MBChannel, &_pData, 1000, 2); // Read Discrete Input
}
4.1.3.3 MB_MASTER_ReadHR()
Description
Reads Holding Registers from a slave.
Prototype
int MB_MASTER_ReadHR ( MB_CHANNEL *pChannel,
U8 *pData,
U16 Addr,
U16 NumItems );
Parameter
Addr [IN] Address in slave where to find the registers to access.
Table 4.8: MB_MASTER_ReadHR() parameter list
Return value
<0: Error
0: OK
Example
//
//
static int _result;
static U8 *_pData;
//
//
_result = MB_MASTER_ReadHR(&_MBChannel, &_pData, 1000, 2);// Read Holding Register
}
47
4.1.3.4 MB_MASTER_ReadIR()
Description
Reads Input Registers from a slave.
Prototype
int MB_MASTER_ReadIR ( MB_CHANNEL *pChannel,
U8 *pData,
U16 Addr,
U16 NumItems );
Parameter
Table 4.9: MB_MASTER_ReadIR() parameter list
Return value
<0: Error
0: OK
Example
//
//
static int _result;
static U8 *_pData;
//
//
_result = MB_MASTER_ReadIR(&_MBChannel, &_pData, 1000, 2);// Read Input Register
}
4.1.3.5 MB_MASTER_WriteCoil()
Description
Writes a single coil to a slave.
Prototype
int MB_MASTER_WriteCoil ( MB_CHANNEL *pChannel,
U16 Addr,
U8 OnOff );
Parameter
Addr [IN] Address in slave where to find the coil to access.
OnOff [IN] Write Coil to 0: Off or 1: On.
Table 4.10: MB_MASTER_WriteCoil() parameter list
Return value
<0: Error
0: OK
Example
//
//
static int _result;
//
//
_result = MB_MASTER_WriteCoil(&_MBChannel, 1000, 1); // Write Coil
}
49
4.1.3.6 MB_MASTER_WriteCoils()
Description
Writes multiple coils to a slave
Prototype
int MB_MASTER_WriteCoils ( MB_CHANNEL *pChannel,
U8 *pData,
U16 Addr,
U16 NumItems );
Parameter
[IN] Pointer to application buffer where the values to write are
pData
stored.
Addr [IN] Address in slave where to find the coils to access.
NumItems [IN] Number of items to write.
Table 4.11: MB_MASTER_WriteCoils() parameter list
Return value
<0: Error
0: OK
Example
//
//
static int _result;
static U8 _data;
//
//
_result = MB_MASTER_WriteCoils(&_MBChannel, &_data, 1000, 2);// Write Coils
}
4.1.3.7 MB_MASTER_WriteReg()
Description
Writes a single register to a slave.
Prototype
int MB_MASTER_WriteReg ( MB_CHANNEL *pChannel,
U16 Data,
U16 Addr );
Parameter
Data [IN] 16-bit data to write to register.
Addr [IN] Address in slave where to find the register to access.
Table 4.12: MB_MASTER_WriteReg() parameter list
Return value
<0: Error
0: OK
Example
//
//
static int _result;
static U16 _data;
//
//
_result = MB_MASTER_WriteReg(&_MBChannel, _data, 1000); // Write Register
}
51
4.1.3.8 MB_MASTER_WriteRegs()
Description
Writes multiple registers to a slave.
Prototype
int MB_MASTER_WriteRegs ( MB_CHANNEL *pChannel,
U16 *pData,
U16 Addr,
U16 NumItems );
Parameter
[IN] Pointer to application buffer where the values to write are
pData
stored.
NumItems [IN] Number of items to write.
Table 4.13: MB_MASTER_WriteRegs() parameter list
Return value
<0: Error
0: OK
Example
//
//
static volatile int _result;
static U16 _data;
//
//
_result = MB_MASTER_WriteRegs(&_MBChannel, &_data, 1000, 2);// Write Registers
}
4.1.4 Slave specific core functions

4.1.4.1 MB_SLAVE_AddASCIIChannel()
Description
Adds a slave channel that uses ASCII frames via serial connection.
Prototype
void MB_SLAVE_AddASCIIChannel ( MB_CHANNEL *pChannel,
const MB_SLAVE_API *pSlaveAPI,
U8 SlaveAddr,
U8 DisableWrite,
U32 Baudrate,
U8 DataBits,
U8 Parity,
U8 StopBits,
U8 Port );
Parameter
[IN] Pointer to elemtent of MB_SLAVE_API used to read/write
pSlaveAPI
from/to target.
pIFaceAPI
from/to interface.
SlaveAddr [IN] Slave address to listen on.
DisableWrite [IN] Disable write access on this channel.
Table 4.14: MB_SLAVE_AddASCIIChannel() parameter list
Example
//
//
_SendByte, _Init, _DeInit, NULL, NULL, NULL, NULL, NULL, NULL
};
static const MB_SLAVE_API _SlaveAPI = {
_WriteCoil, _ReadCoil, _ReadDI, _WriteReg, _ReadHR, _ReadIR
};
//
// Code running in main task
//
void MainTask(void) {
MB_SLAVE_Init(); // Init slave
MB_SLAVE_AddASCIIChannel(&_MBChannel, &_MBConfig, &_SlaveAPI, &_IFaceAPI, 1, 0,
38400, 8, 0, 1, 0); // Add slave channel
OS_CREATETASK( ... ); // Start slave task
}
53
4.1.4.2 MB_SLAVE_AddIPChannel()
Description
Adds a slave channel that uses TCP frames via network.
Prototype
void MB_SLAVE_AddIPChannel ( MB_CHANNEL *pChannel,
MB_IFACE_CONFIG_IP *pConfig,
const MB_IFACE_IP_API *pIFaceAPI,
U8 SlaveAddr,
U32 DisableWrite,
U32 IPAddr,
U8 Port );
Parameter
pConfig [IN] Pointer to element of MB_IFACE_CONFIG_IP.
pSlaveAPI
from/to target.
pIFaceAPI
from/to interface.
[IN] Filter address. If set, only connections on this address
IPAddr
should be accepted.
Port [IN] Port that accepts connections for this channel.
Table 4.15: MB_SLAVE_AddIPChannel() parameter list
Example
//
//
static const MB_IFACE_IP_API _IFaceAPI = {
NULL, _Init, _DeInit, _Send, _Recv, _Connect, _Disconnect, NULL, NULL
};
};
//
//
OS_CREATETASK( ... ); // Start slave task
MB_SLAVE_AddIPChannel(&_MBChannel, &_MBConfig, &_SlaveAPI, &_IFaceAPI, 1, 0,
0, 502); // Add slave channel
OS_CREATETASK( ... ); // Start polling task for this channel
}
4.1.4.3 MB_SLAVE_AddRTUChannel()
Description
Adds a slave channel that uses RTU frames via serial connection.
Prototype
void MB_SLAVE_AddASCIIChannel ( MB_CHANNEL *pChannel,
const MB_SLAVE_API *pSlaveAPI,
U8 SlaveAddr,
U8 DisableWrite,
U32 Baudrate,
U8 DataBits,
U8 Parity,
U8 StopBits,
U8 Port );
Parameter
pSlaveAPI
from/to target.
pIFaceAPI
from/to interface.
SlaveAddr [IN] Slave address to listen on.
Table 4.16: MB_SLAVE_AddRTUChannel() parameter list
Example
//
//
_SendByte, _Init, _DeInit, NULL, NULL, NULL, NULL, _InitTimer, _DeInitTimer
};
};
//
//
MB_SLAVE_AddRTUChannel(&_MBChannel, &_MBConfig, &_SlaveAPI, &_IFaceAPI, 1, 0,
38400, 8, 0, 1, 0); // Add slave channel
OS_CREATETASK( ... ); // Start slave task}
}
55
4.1.4.4 MB_SLAVE_DeInit()
Description
De-Initializes the slave resources and channels and removes the slave endpoint from
the global endpoint list.
Prototype
void MB_SLAVE_DeInit ( void );
4.1.4.5 MB_SLAVE_Exec()
Description
Loops once over all slave channels, processes data when the channel has been sig-
nalled ready.
Prototype
void MB_SLAVE_Exec ( void );
57
4.1.4.6 MB_SLAVE_Init()
Description
Initializes the slave resources and adds the slave endpoint to the global endpoint list.
Prototype
void MB_SLAVE_Init ( void );
4.1.4.7 MB_SLAVE_PollChannel()
Description
Function that has to be periodically polled for each slave channel that requires
requesting data instead of getting it via interrupt.
Prototype
void MB_SLAVE_PollChannel ( MB_Channel *pChannel );
Parameter
Table 4.17: MB_SLAVE_PollChannel() parameter list
Return value
<0: Error
0: No complete Modbus message signaled.
1: Complete Modbus message signaled.
Example
//
// Polling a slave channel in a task, allowing it to sleep when possible.
//
static void _PollSlaveChannelTask(void *pChannel) {
while (1) {
MB_SLAVE_PollChannel((MB_CHANNEL*)pChannel);
}
}
59
4.1.4.8 MB_SLAVE_Task()
Description
Wrapper function that runs MB_SLAVE_Exec() in a task.
Prototype
void MB_SLAVE_Task ( void );
4.1.5 Other core functions

4.1.5.1 MB_ConfigTimerFreq()
Description
This function allows setting a user defined timer frequency instead of the default fre-
quency of 1kHz.
Prototype
void MB_ConfigTimerFreq ( U32 Freq );
Parameter
[IN] Timer frequency that shall be used for all all channels to cal-
Freq
culate the RTU timeout.
Table 4.18: MB_ConfigTimerFreq() parameter list
61
4.1.5.2 MB_OnRx()
Description
Function called by byte oriented transmission channels that receive an interrupt for
new data received.
Prototype
void MB_OnRx ( MB_CHANNEL *pChannel,
U8 Data );
Parameter
Data [IN] Received character.
Table 4.19: MB_OnRx() parameter list
4.1.5.3 MB_OnTx()
Description
Function called by byte oriented transmission channels once a Tx complete interrupt
has been received to send the next byte or report back that there is no more to send.
Prototype
int MB_OnTx ( MB_CHANNEL *pChannel );
Parameter
Table 4.20: MB_OnTx() parameter list
Return value
<0: Error
0: More data sent
1: No more data to send
63
4.1.5.4 MB_TimerTick()
Description
Function called on each timer interrupt to manage internal RTU timeout with serial
channels using the RTU protocol.
Prototype
void MB_TimerTick ( void );
4.2 emModbus data structures

4.2.1 Interface configuration structures
4.2.1.1 Structure MB_IFACE_CONFIG_IP
Description
This structure holds configurations for IP communications.
Prototype
struct {
MB_SOCKET Sock;
MB_SOCKET ListenSock;
U32 IPAddr;
U16 Port;
U16 xID;
} MB_IFACE_CONFIG_API;
Member Description
Sock Socket used for send and receive.
ListenSock Socket used by TCP for listen() and accept(). Not needed for UDP.
Master: Addr. to connect to.
IPAddr Slave: Filter address. If set only connections on this address should
be accepted.
Master: Port to connect to.
Port
Slave: Port that accepts connections for this channel.
Master: Transaction ID that is incremented for each send.
xID
Slave: Ignored.
Table 4.21: Structure MB_IFACE_CONFIG_IP member list
65
4.2.1.2 Structure MB_IFACE_CONFIG_UART

Description
This structure holds configurations for UART communications.
Prototype
struct {
U32 Cnt;
U32 CntReload;
U32 Baudrate;
U8 DataBits;
U8 Parity;
U8 StopBits;
U8 Port;
} MB_IFACE_CONFIG_UART;
Member Description
Cnt RTU timeout countdown.
CntReload RTU countdown reload value.
Baudrate Baudrate to use.
DataBits Number of data bits.
Parity Parity as interpreted by application.
StopBits Number of stop bits.
Port Interface index.
Table 4.22: Structure MB_IFACE_CONFIG_UART member list
Additional information
MB_IFACE_CONFIG is of type MB_IFACE_CONFIG_UART.
4.2.2 Interface function structures

4.2.2.1 Structure MB_IFACE_IP_API
Description
This structure holds function pointers for IP communications.
Prototype
struct {
void ( *pfSendByte ) ( MB_IFACE_CONFIG_UART *pConfig,
U8 Data );
int ( *pfInit ) ( MB_IFACE_CONFIG_UART *pConfig );
void ( *pfDeInit ) ( MB_IFACE_CONFIG_UART *pConfig );
int ( *pfSend ) ( MB_IFACE_CONFIG_UART *pConfig,
const U8 *pData,
U32 NumBytes );
int ( *pfRecv ) ( MB_IFACE_CONFIG_UART *pConfig,
U8 *pData,
U32 NumBytes,
U32 Timeout );
int ( *pfConnect ) ( MB_IFACE_CONFIG_UART *pConfig,
U32 Timeout );
void ( *pfDisconnect ) ( MB_IFACE_CONFIG_UART *pConfig );
void ( *pfInitTimer ) ( U32 MaxFreq );
void ( *pfDeInitTimer ) ( void );
} MB_IFACE_IP_API;
Member Description
Send first byte. Every next byte will be sent via MB_OnTx() from
pfSendByte interrupt.
NULL if stream oriented interface, as pfSendByte gets used instead.
Init IP and get listen socket and bring it in listen state if needed.
pfInit
NULL if not needed.
Close listen socket and de-init IP.
pfDeInit
NULL if not needed.
Send data for stream oriented interface.
pfSend
NULL if byte oriented interface is used, as pfSend gets used instead.
pfRecv Request more data.
Master: Connect to slave.
pfConnect Slave: Accept connection if needed.
NULL if not needed.
Master: Disconnect from slave.
pfDisconnect Slave: Close connection if needed.
NULL if not needed.
pfInitTimer NULL.
pfDeInitTimer NULL.
Table 4.23: Structure MB_IFACE_IP_API member list
67
4.2.2.2 Structure MB_IFACE_UART_API

Description
This structure holds function pointers for UART communications.
Prototype
struct {
void ( *pfSendByte ) ( MB_IFACE_CONFIG_UART *pConfig,
U8 Data );
int ( *pfInit ) ( MB_IFACE_CONFIG_UART *pConfig );
void ( *pfDeInit ) ( MB_IFACE_CONFIG_UART *pConfig );
int ( *pfSend ) ( MB_IFACE_CONFIG_UART *pConfig,
const U8 *pData,
U32 NumBytes );
int ( *pfRecv ) ( MB_IFACE_CONFIG_UART *pConfig,
U8 *pData,
U32 NumBytes,
U32 Timeout );
int ( *pfConnect ) ( MB_IFACE_CONFIG_UART *pConfig,
U32 Timeout );
void ( *pfDisconnect ) ( MB_IFACE_CONFIG_UART *pConfig );
void ( *pfInitTimer ) ( U32 MaxFreq );
void ( *pfDeInitTimer ) ( void );
} MB_IFACE_UART_API;
Member Description
Send first byte. Every next byte will be sent via MB_OnTx() from
pfSendByte interrupt.
NULL if stream oriented interface, as pfSend gets used instead.
Init hardware.
pfInit
NULL if not needed.
De-Init hardware.
pfDeInit
NULL if not needed.
Send data for stream oriented interface.
pfSend
NULL if byte oriented interface, as pfSendByte gets used instead.
Typically data is received via MB_OnRx() from interrupt.
pfRecv
NULL if not using polling mode.
pfConnect NULL.
pfDisconnect NULL.
Typically needed for RTU interfaces only. Initializes a timer needed
pfInitTimer for RTU timeout.
NULL if not needed.
De-initialize RTU timer.
pfDeInitTimer
NULL if not needed.
Table 4.24: Structure MB_IFACE_UART_API member list
Additional information
MB_IFACE_API is of type MB_IFACE_UART_API.
4.2.3 Slave structures

4.2.3.1 Structure MB_SLAVE_API
Description
This structure holds function pointers used by slaves.
Prototype
struct {
int ( *pfWriteCoil ) ( U16 Addr, char OnOff );
int ( *pfReadCoil ) ( U16 Addr );
int ( *pfReadDI ) ( U16 Addr );
int ( *pfWriteReg ) ( U16 Addr, U16 Val );
int ( *pfReadHR ) ( U16 Addr, U16 *pVal );
int ( *pfReadIR ) ( U16 Addr, U16 *pVal );
} MB_SLAVE_API;
Member Description
pfReadCoil Read coil status.
pfReadDI Read discrete input registers.
pfReadHR Read holding register.
pfReadIR Read input register.
pfWriteCoil Write coil.
pfWriteReg Write register.
Table 4.25: Structure MB_SLAVE_API member list
69
4.3 Error codes

The following table contains a list of emModbus error codes.
Generally, success is indicated by 0 and definite errors are indicated by negative
numbers.
Symbolic name Value Description

Slave errors
The function code received in the query
is an illegal function code for the slave.
This may be because the function code
MB_ERR_ILLEGAL_FUNC -1 was not implemented in the selected
device. It could also indicate that the
slave is in the wrong state to process a
request of this type.
The data address received in the query is
an invalid address for the slave. More
MB_ERR_ILLEGAL_DATA_ADDR -2
specifically, the combination of reference
number and transfer length is invalid.
A value contained in the query data field
is an invalid value for the slave. This indi-
MB_ERR_ILLEGAL_DATA_VAL -3 cates a fault in the structure of a
request, such as an incorrect implied
length.
An unrecoverable error occurred while
MB_ERR_SLAVE_FAIL -4 the slave was attempting to perform the
requested action.
The slave has accepted the request and
is processing it, but a long duration of
time will be required to do so. This
MB_ERR_ACK -5
response is returned to prevent a timeout
error from occurring in the master, which
can then poll for process completion.
The slave is engaged in processing a
MB_ERR_SLAVE_BUSY -6 long–duration command. The master
should retransmit the message later.
The requested function cannot be per-
MB_ERR_NACK -7 formed. Issue poll to obtain detailed
device dependent error information.
The slave attempted to perform the
query, but detected a parity error in the
MB_ERR_MEM_PARITY_ERR -8 memory. The master can retry the
request, but service may be required on
the slave device.
Stack internal errors
MB_ERR_MISC -20 Unspecified error.
MB_ERR_CONNECT -21 Error while connecting.
MB_ERR_CONNECT_TIMEOUT -22 Timeout while connecting.
MB_ERR_DISCONNECT -23 Interface signaled disconnect.
MB_ERR_TIMEOUT -24 No answer received on request.
Received message did not pass LRC/CRC
MB_ERR_CHECKSUM -25
check.
MB_ERR_PARAM -26 Parameter error in API call.
Received valid response with wrong slave
MB_ERR_SLAVE_ADDR -27
address.
Table 4.26: emModbus error codes
Symbolic name Value Description

Received valid response with wrong func-
MB_ERR_FUNC_CODE -28
tion code.
Received valid response with wrong ref-
MB_ERR_REF_NO -29
erence number.
Received valid response with more or
MB_ERR_NUM_ITEMS -30
less items than requested.
Received valid response for a single write
MB_ERR_DATA -31
with different data than written.
Trial limit exceeded. When using trial
libraries, this error occurs after 12 hours
MB_ERR_TRIAL_LIMIT -32 of run time. Except from this, the trial
library is fully functional and includes all
features of emModbus.
Table 4.26: emModbus error codes
71
Chapter 5
Configuring emModbus
emModbus can be used without changing any of the compile-time flags. All compile-
time configuration flags are preconfigured with valid values, which match the
requirements of most applications.
The default configuration of emModbus can be changed via compile-time flags which
can be added to MB_Conf.h. MB_Conf.h is the main configuration file for the emMod-
bus stack.
72 CHAPTER 5 Configuring emModbus
5.1 Compile-time configuration

The following types of configuration macros exist:
Binary switches "B"
Switches can have a value of either 0 or 1, for deactivated and activated respectively.
Actually, anything other than 0 works, but 1 makes it easier to read a configuration
file. These switches can enable or disable a certain functionality or behavior.
Switches are the simplest form of configuration macros.
Numerical values "N"
Numerical values are used somewhere in the code in place of a numerical constant. A
typical example is the configuration of the sector size of a storage medium.
Function replacements "F"
Macros can basically be treated like regular functions although certain limitations
apply, as a macro is still put into the code as simple text replacement. Function
replacements are mainly used to add specific functionality to a module which is
highly hardware-dependent. This type of macro is always declared using brackets
(and optional parameters).
5.1.1 Compile-time configuration switches

Type Symbolic name Default Description
System configuration macros
Macro to define if a big endian tar-
B MB_IS_BIGENDIAN 0
get is used.
Debug macros
Macro to define the debug level of
the emModbus build. Refer to
N MB_DEBUG 0 Debug level on page 73 for a
description of the different debug
level.
Optimization macros
Macro to define an optimized
memcmp
memcmp routine to speed up the
(C-routine in
F MB_MEMCMP stack. An optimized memcmp rou-
standard C-
tine is typically implemented in
library)
assembly language.
memcpy routine to speed up the
memcpy
stack. An optimized memcpy rou-
(C-routine in
F MB_MEMCPY tine is typically implemented in
standard C-
assembly language.
library)
Optimized versions for IAR and
GCC compilers are supplied.
memmove
memmove routine to speed up the
(C-routine in
F MB_MEMMOVE stack. An optimized memmove
standard C-
routine is typically implemented in
library)
assembly language.
memset
memset routine to speed up the
(C-routine in
F MB_MEMSET stack. An optimized memset rou-
standard C-
tine is typically implemented in
library)
assembly language.
73
5.1.2 Debug level

emModbus can be configured to display debug information at higher debug levels to
locate a problem (Error) or potential problem. To display information, emModbus
uses the logging routines (see chapter Debugging on page 75). These routines can
be blank, they are not required for the functionality of emModbus. In a target sys-
tem, they are typically not required in a release (production) build, since a produc-
tion build typically uses a lower debug level.
If (IP_DEBUG == 0): used for release builds. Includes no debug options.
If (IP_DEBUG == 1): MP_PANIC() is mapped to MP_Panic().
If (IP_DEBUG >= 2): MP_PANIC() is mapped to MP_Panic() and logging support is
activated.
74 CHAPTER 5 Configuring emModbus
75
Chapter 6
Debugging
emModbus comes with debugging options including optional warning and log outputs.
76 CHAPTER 6 Debugging
6.1 Message output

The debug builds of emModbus include a debug system which helps to analyze the
correct implementation of the stack in your application. All modules can output log-
ging and warning messages via terminal I/O.
77
6.1.1 Debug API functions

I/O functions
This function is called by the stack in debug
MB_Log()
builds with log output.
This function is called if the stack encoun-
MB_Panic()
ters a critical situation.
This function is called by the stack in debug
MB_Warn()
builds with warning output.
Table 6.1: emModbus debug API functions overview
6.1.1.1 MB_Log()
Description
This function is called by the stack in debug builds with log output. In a release build,
this function may not be linked in.
Prototype
void MB_Log ( const char *s );
Parameter
s [IN] String to output.
Table 6.2: MB_Log() parameter list
79
6.1.1.2 MB_Panic()
Description
This function is called if the stack encounters a critical situation. In a release build,
this function may not be linked in.
Prototype
void MB_Panic ( const char *s );
Parameter
s [IN] String to output before running into endless loop.
Table 6.3: MB_Panic() parameter list
6.1.1.3 MB_Warn()
Description
This function is called by the stack in debug builds with warning output. In a release
build, this function may not be linked in.
Prototype
void MB_Warn ( const char *s );
Parameter
s [IN] String to output.
Table 6.4: MB_Warn() parameter list
81
6.2 Using a network sniffer to analyse ethernet com-

munication problems
Using a network sniffer to analyze your local Ethernet traffic may give you a deeper
understanding of the data that is being sent in your network. For this purpose you
can use several network sniffers. Some of them are available for free such as Wire-
shark. An example of a network sniff using Wireshark is shown in the screenshot
below:
6.3 Testing emModbus applications

To solely test emModbus on target hardware, we recommend building a correspond-
ing project for the specific application. For example, the application contained in
OS_IP_MB_SlaveTCP.c, can be tested using a project for the application contained in
OS_IP_MB_MasterTCP.c. Configuration of some parameters (e.g. IP address) is
required before compiling the project and downloading the output into a second tar-
get. When connected to the same network, both devices should then start communi-
cation with each other.
To test emModbus using a desktop computer, an appropiate software package is
required. The shipment contains Windows applications for Modbus master and slave
devices using Modbus/TCP, which can be used to test both devices via that connec-
tion. In addition, several vendors offer Modbus testing applications for Microsoft Win-
dows and other operating systems, many of which are free or at least free to
evaluate for a limited time. We recommend "Modbus Poll" for testing emModbus slave
functionalities and "Modbus Slave" for testing emModbus master functionalities. Both
applications can be downloaded from http://www.modbustools.com.
83
Chapter 7
OS Integration
emModbus is designed to be used in a multitasking environment. The interface to the
operating system is encapsulated in a single file, the MB/OS interface. For embOS, all
functions required for this MB/OS interface are implemented in a single file which
comes with emModbus.
This chapter provides descriptions of the functions required to fully support emMod-
bus in multitasking environments.
84 CHAPTER 7 OS Integration
7.1 General information

All OS interface functions for embOS are implemented in MB_OS_embOS.c, which is
located in the root folder of the emModbus stack.
85
7.2 OS layer API functions

General functions
De-Initializes (removes) all objects required for task
MB_X_OS_DeInitMaster()
syncronisation of the master.
De-Initializes (removes) all objects required for task
MB_X_OS_DeInitSlave()
synchronisation of the slave.
MB_X_OS_DisableInterrupt() Disables interrupts before critical operations.
MB_X_OS_EnableInterrupt() Enables interrupts after critical operations.
MB_X_OS_GetTime() Returns the current system time in ms.
Initializes (creates) all objects required for task syn-
MB_X_OS_InitMaster()
chronisation of the master.
Initializes (creates) all objects required for task syn-
MB_X_OS_InitSlave()
chronisation and signalling of the slave.
Synchronization functions
Sets an object to signaled state, or resumes tasks
MB_X_OS_SignalItem()
which are waiting at the event object.
Wakes tasks waiting for a NET-event or timeout in the
MB_X_OS_SignalNetEvent()
function MB_OS_WaitNetEvent().
MB_X_OS_WaitItemTimed() Suspends a task which needs to wait for an object.
Blocks until a NET-event occurs, meaning
MB_X_OS_WaitNetEvent() MB_OS_SignalNetEvent() is called from another task
or ISR.
Table 7.1: OS layer API functions list
7.2.1 General functions

7.2.1.1 MB_X_OS_DeInitMaster()
Description
De-Initializes (removes) all objects required for task syncronisation of the master.
Prototype
void MB_X_OS_DeInitMaster ( void );
87
7.2.1.2 MB_X_OS_DeInitSlave()
Description
De-Initializes (removes) all objects required for task syncronisation of the slave.
Prototype
void MB_X_OS_DeInitSlave ( void );
7.2.1.3 MB_X_OS_DisableInterrupt()
Description
Disables interrupts before critical operations.
Prototype
void MB_X_OS_DisableInterrupt ( void );
89
7.2.1.4 MB_X_OS_EnableInterrupt()
Description
Enables interrupts after critical operations.
Prototype
void MB_X_OS_EnableInterrupt ( void );
7.2.1.5 MB_X_OS_GetTime()
Description
Returns the current system time in ms. The value will wrap around after approxi-
mately 49.7 days. This is taken into account by the stack.
Prototype
U32 MB_X_OS_GetTime32 ( void );
Return value
System time in ms.
91
7.2.1.6 MB_X_OS_InitMaster()
Description
Initializes (creates) all objects required for task syncronisation of the master. This is
one semaphore for protection of critical code, which may not be executed from multi-
ple tasks at the same time, and a hook in case a task currently executing Modbus
master API is terminated.
Prototype
void MB_X_OS_InitMaster ( void );
7.2.1.7 MB_X_OS_InitSlave()
Description
Initializes (creates) all objects required for task synchronisation and signalling of the
slave.
Prototype
void MB_X_OS_InitSlave ( void );
93
7.2.2 Synchronization functions

7.2.2.1 MB_X_OS_SignalItem()
Description
Sets an object to signaled state, or resumes tasks which are waiting at the event
object.
Prototype
void MB_X_OS_SignalItem (void *pWaitItem );
Parameter
pWaitItem [IN] Pointer to item a task is waiting for.
Table 7.2: MB_X_OS_SignalItem() parameter list
7.2.2.2 MB_X_OS_SignalNetEvent()
Description
Wakes tasks waiting for a NET-event or timeout in the function
MB_OS_WaitNetEvent().
Prototype
void MB_X_OS_SignalNetEvent ( void );
95
7.2.2.3 MB_X_OS_WaitItemTimed()
Description
Suspends a task which needs to wait for an object. This object is identified by a
pointer to it and can be of any type, e.g. channel.
Prototype
void MB_X_OS_WaitItemTimed ( void *pWaitItem,
unsigned Timeout );
Parameter
[IN] Pointer to item a task shall wait for until signalled or timeout
pWaitItem
occurs.
Timeout [IN] Timeout [in ms] to wait for item to be signalled.
Table 7.3: MB_X_OS_WaitItemTimed() parameter list
7.2.2.4 MB_X_OS_WaitNetEvent()
Description
Called from MB_Task() only. Blocks until a NET-event occurs, meaning
MB_OS_SignalNetEvent() is called from another task or ISR.
Prototype
void MB_X_OS_WaitNetEvent ( unsigned ms );
Parameter
ms [IN] Time to wait for a NET-event to occur [in ms]. 0 for infinite.
Table 7.4: MB_X_OS_WaitNetEvent() parameter list
97
Chapter 8
Resource usage
This chapter covers the resource usage of emModbus. It contains information about
the memory requirements in typical systems, which can be used to obtain sufficient
estimates for most target systems.
98 CHAPTER 8 Resource usage
8.1 Memory footprint

emModbus is designed to fit many kinds of embedded design requirements. Some
features might be excluded from a build to get a minimal system. Note that the val-
ues are only valid for the given configurations.
8.1.1 ARM7 system

The following table shows the hardware and the toolchain details of the project:
Detail Description
CPU ARM7
Tool chain IAR Embedded Workbench for ARM V6.30.6
Model ARM7, Thumb instructions; interwork;
Compiler options Highest size optimization;
Table 8.1: ARM7 sample configuration
8.1.1.1 ROM usage

The following table shows the ROM requirement of emModbus:
Description ROM
master using ASCII approx. 1.5 Kbytes
master using TCP approx. 0.9 Kbytes
master using RTU approx. 2.1 Kbytes
slave using ASCII approx. 2.0 Kbytes
slave using TCP approx. 1.6 Kbytes
slave using RTU approx. 2.6 Kbytes
8.1.1.2 RAM usage

emModus requires approximately 30 Bytes of RAM for the stack itself and approxi-
mately 300 Bytes of RAM for each channel added.
Index 99
P
Index Port number (Modbus/TCP) .................. 10
Protocol Data Unit (PDU) ...................... 11
Protocol ID (Modbus/TCP) .................... 12
Q
Query ................................................ 10
S
A Schneider Electric SA ........................... 10
Application Data Unit (ADU) ..................11 SEGGER Microcontroller GmbH & Co. KG .. 6
Slave (device) .................................... 10
C Syntax, conventions used ....................... 5
Coil ....................................................13
Compiler, required compliance ...............15 T
Compile-time flags ...............................71 TCP/IP stack ....................................... 14
Configuration ......................................71 Transaction ID (Modbus/TCP) ................ 12
Contact address ................................... 2
Core functions .....................................36
Cyclic Redundancy Check ......................11 U
Unit ID .............................................. 11
D
Data table ..........................................13
Data types, primary .............................13
Debug functions ..................................77
Discrete Input .....................................13
E
Endianess ...........................................13
F
Frames, Modbus-compliant variants .......10
Function code ......................................11
Function replacements .........................72
H
Holding Register ..................................13
I
Input Register .....................................13
L
Log output ..........................................78
Longitudinal Redundancy Check .............12
M
Master (device) ...................................10
Memory requirement ............................97
Modbus Application Header (Modbus/TCP) 12
Modbus Organization ............................10
Modbus, standard protocol ....................10
Modicon .............................................10
Multi tasking .......................................14
N
Network sniffer ....................................81
O
OS integration functions .......................85
100 Index

UM14001 Emmodbus

Uploaded by

Copyright:

Available Formats

UM14001 Emmodbus

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

UM14001 Emmodbus

Uploaded by

Copyright:

Available Formats

emModbus

User & Reference Guide

A product of SEGGER Microcontroller GmbH & Co. KG

Software Revision Date By Description

About this document

Style Used for

Body Body text.

Text that you enter at the command-prompt or that appears on

Parameter Parameters in API functions.

Reference to chapters, sections, tables and figures or other docu-

GUIElement Buttons, dialog boxes, menu names, menu commands.

Emphasis Very important sections.

SEGGER Microcontroller GmbH & Co. KG develops

Corporate Office: United States Office:

EMBEDDED SOFTWARE SEGGER TOOLS

embOS/IP J-Link / J-Trace Related Software

1 Introduction to emModbus ...............................................................................................9

3 Example applications .....................................................................................................31

1.1 The Modbus standard

1.1.1 Modbus message basics

1.1.1.1 Message frames

1.1.1.2 Message fields

ASCII message frames

Modbus/TCP message frames

1.1.2 Modbus data basics

Data type Description

1.1.3 Further reading

1.2.1 Features of emModbus

Contains example applications to run

Contains the emModbus configuration files.

Contains the emModbus sources such as

Contains optimized memcpy routines to

Contains the source(s), project file(s) and

1.2.2 emModbus requirements

1.2.3 Development environment (compiler)

1.3 Tasks and interrupt usage

1.3.1 ASCII / RTU slave with tasks dedicated to the stack

1.3.2 ASCII / RTU slave without tasks dedicated to the stack

1.3.3 TCP / UDP slave with tasks dedicated to the stack

1.3.4 TCP / UDP slave without tasks dedicated to the stack

1.3.5 emModbus master

2.2 Upgrade a trial version

Build the project

2.3 Upgrade an embOS start project

2.3.1 Step 1: Open an embOS start project

2.3.2 Step 2: Adding embOS/IP to the start project

2.3.3 Step 3: Adding emModbus to the start project

2.3.4 Step 4: Build the project

2.4 Create a project from scratch

Build the project

Demonstrates the functionality of a Modbus

Demonstrates the functionality of a Modbus

Demonstrates the functionality of a Modbus

Demonstrates the functionality of a Modbus

Demonstrates the functionality of a Modbus

Demonstrates the functionality of a Modbus

4.1 API functions

4.1.1 Channel specific core functions

4.1.2 Master specific core functions