14.00.04 EMMODBUS MASTER SSL - SEGGER

A product of SEGGER Microcontroller GmbH & Co. KG

emModbus

Document: UM14001

Software version: 1.00

Revision: 2

Date: July 1, 2014

User & Reference Guide

CPU independent

Modbus stack for

embedded applications

www.segger.com

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.

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.

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: support@segger.com

Internet: http://www.segger.com

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.

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.

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.

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

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 Reference to chapters, sections, tables and figures or other docu-

ments.

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

Emphasis Very important sections.

Table 1.1: Typographic conventions

EMBEDDED SOFTWARE

(Middleware)

emWin

Graphics software and GUI

emWin is designed to provide an effi-

cient, processor- and display control-

ler-independent graphical user

interface (GUI) for any application that

operates with a graphical display.

embOS

Real Time Operating System

embOS is an RTOS designed to offer

the benefits of a complete multitasking

system for hard real time applications

with minimal resources.

embOS/IP

TCP/IP stack

embOS/IP a high-performance TCP/IP

stack that has been optimized for

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.

SEGGER TOOLS

Flasher

Flash programmer

Flash Programming tool primarily for micro con-

trollers.

J-Link

JTAG emulator for ARM cores

USB driven JTAG interface for ARM cores.

J-Trace

JTAG emulator with trace

USB driven JTAG interface for ARM cores with

Trace memory. supporting the ARM ETM (Embed-

ded Trace Macrocell).

J-Link / J-Trace Related Software

Add-on software to be used with SEGGER’s indus-

try standard JTAG emulator, this includes flash

programming software and flash breakpoints.

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:

http://www.segger.com

United States Office:

http://www.segger-us.com

UM14001 User & Reference Guide for emModbus © 2014 SEGGER Microcontroller GmbH & Co. KG
7
 Introduction to emModbus ...............................................................................................9
1 The Modbus standard ...............................................................................10
2 emModbus..............................................................................................14
3 Tasks and interrupt usage.........................................................................16
 Getting Started...............................................................................................................21
1 Installation .............................................................................................22
2 Upgrade a trial version .............................................................................23
3 Upgrade an embOS start project................................................................24
4 Create a project from scratch .................................................................... 29
 Example applications.....................................................................................................31
1 Overview................................................................................................ 32
 Core functions................................................................................................................35
1 API functions ..........................................................................................36
2 emModbus data structures........................................................................ 64
3 Error codes .............................................................................................69
 Configuring emModbus..................................................................................................71
1 Compile-time configuration .......................................................................72
 Debugging......................................................................................................................75
1 Message output.......................................................................................76
2 Using a network sniffer to analyse ethernet communication problems .............81
3 Testing emModbus applications ................................................................. 82
 OS Integration................................................................................................................83
1 General information .................................................................................84
2 OS layer API functions.............................................................................. 85
 Resource usage.............................................................................................................97
1 Memory footprint.....................................................................................98
Table of Contents

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:

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.

Protocol Description

RTU Original Modbus standard. Binary data is sent via serial connec-

tions such as RS-232 or similar.

ASCII Similar to RTU. Instead of raw binary, data is encoded in ASCII.

Modbus/TCP

Binary data is encapsulated in a TCP frame and sent via net-

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

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:

12 CHAPTER 1 Introduction to emModbus

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:

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:

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/

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

14 CHAPTER 1 Introduction to emModbus

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:

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.

Directory Content

Application\*.c Contains example applications to run

emModbus with UART or embOS/IP.

Config\*.*

Contains the emModbus configuration files.

Refer to Configuring emModbus on

page 71 for further information.

MB\*.*

Contains the emModbus sources such as

MB_Core.c, MB_CHANNEL.c, MB_MASTER.c

and MB_SLAVE.c

Util\*.c Contains optimized memcpy routines to

speed up the stack.

Windows\*.*

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

a executable(s) to run emModbus on a

Microsoft Windows host.

Table 1.3: Supplied directory structure of emModbus shippings

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.

16 CHAPTER 1 Introduction to emModbus

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.

...

Task

Routine / Action

Interrupt (ISR) emModbus slave (ASCII / RTU)

MB_SLAVE_

Exec()

Evaluate

frame

MB_OnRx()

MB_SLAVE_

Task

App.

task n

App.

task 1

MB stack

Driver

Application tasks

Store

byte

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.

...

Task

Routine / Action

Interrupt (ISR) emModbus slave (ASCII / RTU)

App.

task n

App.

task 1

MB stack

Driver

Application tasks

MB_SLAVE_

Exec()

Evaluate

frame

MB_OnRx()

Store

byte

18 CHAPTER 1 Introduction to emModbus

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.

...

Task

Routine / Action

Interrupt (ISR) emModbus slave (TCP / UDP)

Read

frame

App.

task n

App.

task 1

MB stack

Driver

Application tasks MB_SLAVE_

PollChannel

MB_SLAVE_

Exec()

Evaluate

frame

MB_SLAVE_

Task

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.

...

Task

Routine / Action

Interrupt (ISR) emModbus slave (TCP / UDP)

App.

task n

App.

task 1

MB stack

Driver

Application tasks MB_SLAVE_

PollChannel()

MB_SLAVE_

Exec()

Evaluate

frame

Read

frame

1. )

2.)

20 CHAPTER 1 Introduction to emModbus

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.

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.

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

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.

24 CHAPTER 2 Getting Started

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.

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.

26 CHAPTER 2 Getting Started

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

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).

28 CHAPTER 2 Getting Started

2.3.4 Step 4: Build the project

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.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

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.

30 CHAPTER 2 Getting Started

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

OS_IP_MB_MasterTCP.c Demonstrates the functionality of a Modbus

Master device using TCP frames via network.

OS_IP_MB_SlaveTCP.c Demonstrates the functionality of a Modbus

Slave device using TCP frames via network.

OS_MB_MasterASCII.c

Demonstrates the functionality of a Modbus

Master device using ASCII frames via serial con-

nection.

OS_MB_MasterRTU.c

Demonstrates the functionality of a Modbus

Master device using RTU frames via serial con-

nection.

OS_MB_SlaveASCII.c

Demonstrates the functionality of a Modbus

Slave device using ASCII frames via serial con-

nection.

OS_MB_SlaveRTU.c

Demonstrates the functionality of a Modbus

Slave device using RTU frames via serial con-

nection.

Table 3.1: emModbus example applications

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

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 function s

MB_CHANNEL_Disconnect() Disconnects a connected channel.

Master specific core functions

MB_MASTER_AddASCIIChannel() Adds a master channel that uses ASCII

frames via serial connection.

MB_MASTER_AddIPChannel() Adds a master channel that uses TCP

frames via network.

MB_MASTER_AddRTUChannel() Adds a master channel that uses RTU

frames via serial connection.

MB_MASTER_DeInit()

De-Initializes master resources and

channels and removes the master end-

point from the global endpoint list.

MB_MASTER_Init() Initializes master resources and adds

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

MB_SLAVE_AddASCIIChannel() Adds a slave channel that uses ASCII

frames via serial connection.

MB_SLAVE_AddIPChannel() Adds a slave channel that uses TCP

frames via network.

MB_SLAVE_AddRTUChannel() Adds a slave channel that uses RTU

frames via serial connection.

MB_SLAVE_DeInit()

De-Initializes the slave resources and

channels and removes the slave endpoint

from the global endpoint list.

MB_SLAVE_Exec()

Loops over all slave channels once and

processes data when channel has been

signalled ready.

MB_SLAVE_Init() Initializes slave resources and adds slave

endpoint to global endpoint list.

MB_SLAVE_PollChannel()

Polled periodically for each slave channel

that requires requesting data instead of

getting it via interrupt.

MB_SLAVE_Task() Wrapper function that runs

MB_SLAVE_Exec() in a task.

Other core functions

MB_ConfigTimerFreq()

Function allowing to set a user defined

timer frequency instead of the default

frequency of 1kHz.

Table 4.1: emModbus API function overview

MB_OnRx()

Function called by byte oriented trans-

mission channels that receive an inter-

rupt for new data received.

MB_OnTx()

Function called by byte oriented trans-

mission channels once a Tx complete

interrupt has been received.

MB_TimerTick()

Function called on each timer interrupt to

manage internal RTU timeout with serial

channels using the RTU protocol.

Function Description

Table 4.1: emModbus API function overview (Continued)

38 CHAPTER 4 Core functions

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

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

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

}

Parameter Description

pChannel [IN] Pointer to element of MB_CHANNEL that is added to linked list.

pConfig [IN] Pointer to element of MB_IFACE_CONFIG_UART.

pIFaceAPI [IN] Pointer to element of MB_IFACE_UART_API used to read/write

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

40 CHAPTER 4 Core functions

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

Example

// Static declarations

static MB_CHANNEL _MBChannel;

static MB_IFACE_CONFIG_UART _MBConfig;

static const MB_IFACE_IP_API _IFaceAPI = {

NULL, NULL, NULL, _Send, _Recv, _Connect, _Disconnect, NULL, NULL

};

// Code running in its own task

static void _MasterTask(void) {

MB_MASTER_Init(); // Init master

MB_MASTER_AddIPChannel(&_MBChannel, &_MBConfig, &_IFaceAPI, 3000, 1,

IP_BYTES2ADDR(192,168,1,80), 502); // Add master channel

do { ... } // e.g. master/slave communications

}

Parameter Description

pChannel [IN] Pointer to element of MB_CHANNEL that is added to linked list.

pConfig [IN] Pointer to element of MB_IFACE_CONFIG_IP.

pIFaceAPI [IN] Pointer to element of MB_IFACE_IP_API used to read/write

from/to interface.

Timeout [IN] Timeout [in ms] to wait for answer.

SlaveAddr [IN] Slave address to access.

IPAddr [IN] IP address of slave.

Port [IN] Slave port to connect to.

Table 4.4: MB_MASTER_AddIPChannel() parameter list

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,

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

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, _InitTimer, _DeInitTimer

};

// Code running in its own task

static void _MasterTask(void) {

MB_MASTER_Init(); // Init master

MB_MASTER_AddRTUChannel(&_MBChannel, &_MBConfig, &_IFaceAPI, 3000, 1,

38400, 8, 0, 1, 0); // Add master channel

do { ... } // e.g. master/slave communications

}

Parameter Description

pChannel [IN] Pointer to element of MB_CHANNEL that is added to linked list.

pConfig [IN] Pointer to element of MB_IFACE_CONFIG_UART.

pIFaceAPI [IN] Pointer to element of MB_IFACE_IP_API used to read/write

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.5: MB_MASTER_AddRTUChannel() parameter list

42 CHAPTER 4 Core functions

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 );

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 );

44 CHAPTER 4 Core functions

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

Return value

<0: Error

0: OK

Example

// Static declarations

static int _result;

static MB_CHANNEL _MBChannel;

static U8 *_pData;

// Code running in its own task

static void _MasterTask(void) {

MB_MASTER_Init(); // Init master

MB_MASTER_AddASCIIChannel( ... ); // Add master channel

_result = MB_MASTER_ReadCoils(&_MBChannel, &_pData, 1000, 2);// Read Coils

}

Parameter Description

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

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

Return value

<0: Error

0: OK

Example

// Static declarations

static int _result;

static MB_CHANNEL _MBChannel;

static U8 *_pData;

// Code running in its own task

static void _MasterTask(void) {

MB_MASTER_Init(); // Init master

MB_MASTER_AddASCIIChannel( ... ); // Add master channel

_result = MB_MASTER_ReadDI(&_MBChannel, &_pData, 1000, 2); // Read Discrete Input

}

Parameter Description

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 inputs to access.

NumItems [IN] Number of items to read.

Table 4.7: MB_MASTER_ReadDI() parameter list

46 CHAPTER 4 Core functions

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

Return value

<0: Error

0: OK

Example

// Static declarations

static int _result;

static MB_CHANNEL _MBChannel;

static U8 *_pData;

// Code running in its own task

static void _MasterTask(void) {

MB_MASTER_Init(); // Init master

MB_MASTER_AddASCIIChannel( ... ); // Add master channel

_result = MB_MASTER_ReadHR(&_MBChannel, &_pData, 1000, 2);// Read Holding Register

}

Parameter Description

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 registers to access.

NumItems [IN] Number of items to read.

Table 4.8: MB_MASTER_ReadHR() parameter list

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

Return value

<0: Error

0: OK

Example

// Static declarations

static int _result;

static MB_CHANNEL _MBChannel;

static U8 *_pData;

// Code running in its own task

static void _MasterTask(void) {

MB_MASTER_Init(); // Init master

MB_MASTER_AddASCIIChannel( ... ); // Add master channel

_result = MB_MASTER_ReadIR(&_MBChannel, &_pData, 1000, 2);// Read Input Register

}

Parameter Description

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 registers to access.

NumItems [IN] Number of items to read.

Table 4.9: MB_MASTER_ReadIR() parameter list

48 CHAPTER 4 Core functions

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

Return value

<0: Error

0: OK

Example

// Static declarations

static int _result;

static MB_CHANNEL _MBChannel;

// Code running in its own task

static void _MasterTask(void) {

MB_MASTER_Init(); // Init master

MB_MASTER_AddASCIIChannel( ... ); // Add master channel

_result = MB_MASTER_WriteCoil(&_MBChannel, 1000, 1); // Write Coil

}

Parameter Description

pChannel [IN] Pointer to channel configured to interface a slave.

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

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

Return value

<0: Error

0: OK

Example

// Static declarations

static int _result;

static MB_CHANNEL _MBChannel;

static U8 _data;

// Code running in its own task

static void _MasterTask(void) {

MB_MASTER_Init(); // Init master

MB_MASTER_AddASCIIChannel( ... ); // Add master channel

_result = MB_MASTER_WriteCoils(&_MBChannel, &_data, 1000, 2);// Write Coils

}

Parameter Description

pChannel [IN] Pointer to channel configured to interface a slave.

pData [IN] Pointer to application buffer where the values to write are

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

50 CHAPTER 4 Core functions

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

Return value

<0: Error

0: OK

Example

// Static declarations

static int _result;

static MB_CHANNEL _MBChannel;

static U16 _data;

// Code running in its own task

static void _MasterTask(void) {

MB_MASTER_Init(); // Init master

MB_MASTER_AddASCIIChannel( ... ); // Add master channel

_result = MB_MASTER_WriteReg(&_MBChannel, _data, 1000); // Write Register

}

Parameter Description

pChannel [IN] Pointer to channel configured to interface a slave.

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

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

Return value

<0: Error

0: OK

Example

// Static declarations

static volatile int _result;

static MB_CHANNEL _MBChannel;

static U16 _data;

// Code running in its own task

static void _MasterTask(void) {

MB_MASTER_Init(); // Init master

MB_MASTER_AddASCIIChannel( ... ); // Add master channel

_result = MB_MASTER_WriteRegs(&_MBChannel, &_data, 1000, 2);// Write Registers

}

Parameter Description

pChannel [IN] Pointer to channel configured to interface a slave.

pData [IN] Pointer to application buffer where the values to write are

stored.

Addr [IN] Address in slave where to find the registers to access.

NumItems [IN] Number of items to write.

Table 4.13: MB_MASTER_WriteRegs() parameter list

52 CHAPTER 4 Core functions

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,

MB_IFACE_CONFIG_UART *pConfig,

const MB_SLAVE_API *pSlaveAPI,

const MB_IFACE_UART_API *pIFaceAPI,

U8 SlaveAddr,

U8 DisableWrite,

U32 Baudrate,

U8 DataBits,

U8 Parity,

U8 StopBits,

U8 Port );

Parameter

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

};

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

}

Parameter Description

pChannel [IN] Pointer to element of MB_CHANNEL that is added to linked list.

pConfig [IN] Pointer to element of MB_IFACE_CONFIG_UART.

pSlaveAPI [IN] Pointer to elemtent of MB_SLAVE_API used to read/write

from/to target.

pIFaceAPI [IN] Pointer to element of MB_IFACE_UART_API used to read/write

from/to interface.

SlaveAddr [IN] Slave address to listen on.

DisableWrite [IN] Disable write access on this channel.

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.14: MB_SLAVE_AddASCIIChannel() parameter list

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

Example

// Static declarations

static MB_CHANNEL _MBChannel;

static MB_IFACE_CONFIG_UART _MBConfig;

static const MB_IFACE_IP_API _IFaceAPI = {

NULL, _Init, _DeInit, _Send, _Recv, _Connect, _Disconnect, 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

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

}

Parameter Description

pChannel [IN] Pointer to element of MB_CHANNEL that is added to linked list.

pConfig [IN] Pointer to element of MB_IFACE_CONFIG_IP.

pSlaveAPI [IN] Pointer to elemtent of MB_SLAVE_API used to read/write

from/to target.

pIFaceAPI [IN] Pointer to element of MB_IFACE_IP_API used to read/write

from/to interface.

SlaveAddr [IN] Slave address to access.

DisableWrite [IN] Disable write access on this channel.

IPAddr [IN] Filter address. If set, only connections on this address

should be accepted.

Port [IN] Port that accepts connections for this channel.

Table 4.15: MB_SLAVE_AddIPChannel() parameter list

54 CHAPTER 4 Core functions

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,

MB_IFACE_CONFIG_UART *pConfig,

const MB_SLAVE_API *pSlaveAPI,

const MB_IFACE_UART_API *pIFaceAPI,

U8 SlaveAddr,

U8 DisableWrite,

U32 Baudrate,

U8 DataBits,

U8 Parity,

U8 StopBits,

U8 Port );

Parameter

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, _InitTimer, _DeInitTimer

};

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_AddRTUChannel(&_MBChannel, &_MBConfig, &_SlaveAPI, &_IFaceAPI, 1, 0,

38400, 8, 0, 1, 0); // Add slave channel

OS_CREATETASK( ... ); // Start slave task}

}

Parameter Description

pChannel [IN] Pointer to element of MB_CHANNEL that is added to linked list.

pConfig [IN] Pointer to element of MB_IFACE_CONFIG_UART.

pSlaveAPI [IN] Pointer to elemtent of MB_SLAVE_API used to read/write

from/to target.

pIFaceAPI [IN] Pointer to element of MB_IFACE_UART_API used to read/write

from/to interface.

SlaveAddr [IN] Slave address to listen on.

DisableWrite [IN] Disable write access on this channel.

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.16: MB_SLAVE_AddRTUChannel() parameter list

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 );

56 CHAPTER 4 Core functions

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 );

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 );

58 CHAPTER 4 Core functions

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

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);

}

Parameter Description

pChannel [IN] Pointer to element of MB_CHANNEL.

Table 4.17: MB_SLAVE_PollChannel() parameter list

4.1.4.8 MB_SLAVE_Task()

Description

Wrapper function that runs MB_SLAVE_Exec() in a task.

Prototype

void MB_SLAVE_Task ( void );

60 CHAPTER 4 Core functions

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

Parameter Description

Freq [IN] Timer frequency that shall be used for all all channels to cal-

culate the RTU timeout.

Table 4.18: MB_ConfigTimerFreq() parameter list

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

Parameter Description

pChannel [IN] Pointer to element of MB_CHANNEL.

Data [IN] Received character.

Table 4.19: MB_OnRx() parameter list

62 CHAPTER 4 Core functions

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

Return value

<0: Error

0: More data sent

1: No more data to send

Parameter Description

pChannel [IN] Pointer to element of MB_CHANNEL.

Table 4.20: MB_OnTx() parameter list

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 );

64 CHAPTER 4 Core functions

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.

IPAddr

Master: Addr. to connect to.

Slave: Filter address. If set only connections on this address should

be accepted.

Port Master: Port to connect to.

Slave: Port that accepts connections for this channel.

xID Master: Transaction ID that is incremented for each send.

Slave: Ignored.

Table 4.21: Structure MB_IFACE_CONFIG_IP member list

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;

Additional information

MB_IFACE_CONFIG is of type 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

66 CHAPTER 4 Core functions

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

pfSendByte

Send first byte. Every next byte will be sent via MB_OnTx() from

interrupt.

NULL if stream oriented interface, as pfSendByte gets used instead.

pfInit Init IP and get listen socket and bring it in listen state if needed.

NULL if not needed.

pfDeInit Close listen socket and de-init IP.

NULL if not needed.

pfSend Send data for stream oriented interface.

NULL if byte oriented interface is used, as pfSend gets used instead.

pfRecv Request more data.

pfConnect

Master: Connect to slave.

Slave: Accept connection if needed.

NULL if not needed.

pfDisconnect

Master: Disconnect from slave.

Slave: Close connection if needed.

NULL if not needed.

pfInitTimer NULL.

pfDeInitTimer NULL.

Table 4.23: Structure MB_IFACE_IP_API member list

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;

Additional information

MB_IFACE_API is of type MB_IFACE_UART_API.

Member Description

pfSendByte

Send first byte. Every next byte will be sent via MB_OnTx() from

interrupt.

NULL if stream oriented interface, as pfSend gets used instead.

pfInit Init hardware.

NULL if not needed.

pfDeInit De-Init hardware.

NULL if not needed.

pfSend Send data for stream oriented interface.

NULL if byte oriented interface, as pfSendByte gets used instead.

pfRecv Typically data is received via MB_OnRx() from interrupt.

NULL if not using polling mode.

pfConnect NULL.

pfDisconnect NULL.

pfInitTimer

Typically needed for RTU interfaces only. Initializes a timer needed

for RTU timeout.

NULL if not needed.

pfDeInitTimer De-initialize RTU timer.

NULL if not needed.

Table 4.24: Structure MB_IFACE_UART_API member list

68 CHAPTER 4 Core functions

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

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

MB_ERR_ILLEGAL_FUNC -1

The function code received in the query

is an illegal function code for the slave.

This may be because the function code

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.

MB_ERR_ILLEGAL_DATA_ADDR -2

The data address received in the query is

an invalid address for the slave. More

specifically, the combination of reference

number and transfer length is invalid.

MB_ERR_ILLEGAL_DATA_VAL -3

A value contained in the query data field

is an invalid value for the slave. This indi-

cates a fault in the structure of a

request, such as an incorrect implied

length.

MB_ERR_SLAVE_FAIL -4

An unrecoverable error occurred while

the slave was attempting to perform the

requested action.

MB_ERR_ACK -5

The slave has accepted the request and

is processing it, but a long duration of

time will be required to do so. This

response is returned to prevent a timeout

error from occurring in the master, which

can then poll for process completion.

MB_ERR_SLAVE_BUSY -6

The slave is engaged in processing a

long–duration command. The master

should retransmit the message later.

MB_ERR_NACK -7

The requested function cannot be per-

formed. Issue poll to obtain detailed

device dependent error information.

MB_ERR_MEM_PARITY_ERR -8

The slave attempted to perform the

query, but detected a parity error in the

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.

MB_ERR_CHECKSUM -25 Received message did not pass LRC/CRC

check.

MB_ERR_PARAM -26 Parameter error in API call.

MB_ERR_SLAVE_ADDR -27 Received valid response with wrong slave

address.

Table 4.26: emModbus error codes

70 CHAPTER 4 Core functions

MB_ERR_FUNC_CODE -28 Received valid response with wrong func-

tion code.

MB_ERR_REF_NO -29 Received valid response with wrong ref-

erence number.

MB_ERR_NUM_ITEMS -30 Received valid response with more or

less items than requested.

MB_ERR_DATA -31 Received valid response for a single write

with different data than written.

MB_ERR_TRIAL_LIMIT -32

Trial limit exceeded. When using trial

libraries, this error occurs after 12 hours

of run time. Except from this, the trial

library is fully functional and includes all

features of emModbus.

Symbolic name Value Description

Table 4.26: emModbus error codes

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

BMB_IS_BIGENDIAN 0Macro to define if a big endian tar-

get is used.

Debug macros

NMB_DEBUG 0

Macro to define the debug level of

the emModbus build. Refer to

Debug level on page 73 for a

description of the different debug

level.

Optimization mac ros

FMB_MEMCMP

memcmp

(C-routine in

standard C-

library)

Macro to define an optimized

memcmp routine to speed up the

stack. An optimized memcmp rou-

tine is typically implemented in

assembly language.

FMB_MEMCPY

memcpy

(C-routine in

standard C-

library)

Macro to define an optimized

memcpy routine to speed up the

stack. An optimized memcpy rou-

tine is typically implemented in

assembly language.

Optimized versions for IAR and

GCC compilers are supplied.

FMB_MEMMOVE

memmove

(C-routine in

standard C-

library)

Macro to define an optimized

memmove routine to speed up the

stack. An optimized memmove

routine is typically implemented in

assembly language.

FMB_MEMSET

memset

(C-routine in

standard C-

library)

Macro to define an optimized

memset routine to speed up the

stack. An optimized memset rou-

tine is typically implemented in

assembly language.

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

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.

6.1.1 Debug API functions

Function Description

I/O functions

MB_Log() This function is called by the stack in debug

builds with log output.

MB_Panic() This function is called if the stack encoun-

ters a critical situation.

MB_Warn() This function is called by the stack in debug

builds with warning output.

Table 6.1: emModbus debug API functions overview

78 CHAPTER 6 Debugging

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

Parameter Description

s[IN] String to output.

Table 6.2: MB_Log() parameter list

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

Parameter Description

s[IN] String to output before running into endless loop.

Table 6.3: MB_Panic() parameter list

80 CHAPTER 6 Debugging

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

Parameter Description

s[IN] String to output.

Table 6.4: MB_Warn() parameter list

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:

82 CHAPTER 6 Debugging

6.3 Testing emModbus applications

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.

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.

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.

7.2 OS layer API functions

Function Description

General functions

MB_X_OS_DeInitMaster() De-Initializes (removes) all objects required for task

syncronisation of the master.

MB_X_OS_DeInitSlave() De-Initializes (removes) all objects required for task

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.

MB_X_OS_InitMaster() Initializes (creates) all objects required for task syn-

chronisation of the master.

MB_X_OS_InitSlave() Initializes (creates) all objects required for task syn-

chronisation and signalling of the slave.

Synchronization functions

MB_X_OS_SignalItem() Sets an object to signaled state, or resumes tasks

which are waiting at the event object.

MB_X_OS_SignalNetEvent() Wakes tasks waiting for a NET-event or timeout in the

function MB_OS_WaitNetEvent().

MB_X_OS_WaitItemTimed() Suspends a task which needs to wait for an object.

MB_X_OS_WaitNetEvent()

Blocks until a NET-event occurs, meaning

MB_OS_SignalNetEvent() is called from another task

or ISR.

Table 7.1: OS layer API functions list

86 CHAPTER 7 OS Integration

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 );

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 );

88 CHAPTER 7 OS Integration

7.2.1.3 MB_X_OS_DisableInterrupt()

Description

Disables interrupts before critical operations.

Prototype

void MB_X_OS_DisableInterrupt ( void );

7.2.1.4 MB_X_OS_EnableInterrupt()

Description

Enables interrupts after critical operations.

Prototype

void MB_X_OS_EnableInterrupt ( void );

90 CHAPTER 7 OS Integration

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.

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 );

92 CHAPTER 7 OS Integration

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 );

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

Parameter Description

pWaitItem [IN] Pointer to item a task is waiting for.

Table 7.2: MB_X_OS_SignalItem() parameter list

94 CHAPTER 7 OS Integration

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 );

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

Parameter Description

pWaitItem [IN] Pointer to item a task shall wait for until signalled or timeout

occurs.

Timeout [IN] Timeout [in ms] to wait for item to be signalled.

Table 7.3: MB_X_OS_WaitItemTimed() parameter list

96 CHAPTER 7 OS Integration

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

Parameter Description

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

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:

8.1.1.1 ROM usage

The following table shows the ROM requirement of emModbus:

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.

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

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

Index 99

Index

Application Data Unit (ADU) ..................11

Coil ....................................................13

Compiler, required compliance ...............15

Compile-time flags ...............................71

Configuration ......................................71

Contact address ................................... 2

Core functions .....................................36

Cyclic Redundancy Check ......................11

Data table ..........................................13

Data types, primary .............................13

Debug functions ..................................77

Discrete Input .....................................13

Endianess ...........................................13

Frames, Modbus-compliant variants .......10

Function code ......................................11

Function replacements .........................72

Holding Register ..................................13

Input Register .....................................13

Log output ..........................................78

Longitudinal Redundancy Check .............12

Master (device) ...................................10

Memory requirement ............................97

Modbus Application Header (Modbus/TCP) 12

Modbus Organization ............................10

Modbus, standard protocol ....................10

Modicon .............................................10

Multi tasking .......................................14

Network sniffer ....................................81

OS integration functions .......................85

Port number (Modbus/TCP) .................. 10

Protocol Data Unit (PDU) ...................... 11

Protocol ID (Modbus/TCP) .................... 12

Query ................................................ 10

Schneider Electric SA ........................... 10

SEGGER Microcontroller GmbH & Co. KG .. 6

Slave (device) .................................... 10

Syntax, conventions used ....................... 5

TCP/IP stack ....................................... 14

Transaction ID (Modbus/TCP) ................ 12

Unit ID .............................................. 11

100 Index