0% found this document useful (0 votes)

18 views

OpenModbusTCP V3 Protocol API 01 EN

This document describes the Open Modbus/TCP protocol application programming interface (API). It provides details on the protocol stack, exchanging data in IO and message mode, and using the application interface including configuration, common operations, and status codes. The API supports both server and client functionality for industrial communication.

Uploaded by

Melih Melik Sonmez

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

18 views

OpenModbusTCP V3 Protocol API 01 EN

Uploaded by

Melih Melik Sonmez

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 104

Protocol API

Open Modbus/TCP

V3.0.0

Hilscher Gesellschaft für Systemautomation mbH

Table of contents
1 Introduction............................................................................................................................................. 4
1.1 Abstract .......................................................................................................................................... 4
1.2 List of revisions............................................................................................................................... 4
1.3 Functional overview ....................................................................................................................... 5
1.4 System requirements ..................................................................................................................... 5
1.5 Intended audience .......................................................................................................................... 5
1.6 Technical data ................................................................................................................................ 6
1.7 Terms, abbreviations and definitions ............................................................................................. 8
1.8 References to documents .............................................................................................................. 8
2 Getting started ........................................................................................................................................ 9
2.1 Client/server and operating modes ................................................................................................ 9
2.2 Structure of the Open Modbus/TCP protocol stack ..................................................................... 10
2.3 Configuration ................................................................................................................................ 11
3 Exchanging data ................................................................................................................................... 12
3.1 Message mode vs IO mode ......................................................................................................... 12
3.2 Command table ............................................................................................................................ 13
3.3 Modbus function codes ................................................................................................................ 13
3.3.1 Troubleshooting ............................................................................................................................... 15
4 The application interface ..................................................................................................................... 16
4.1 Configuration ................................................................................................................................ 17
4.1.1 Configuration via packet .................................................................................................................. 17
4.1.2 Configuration with SYCON.net ........................................................................................................ 18
4.1.3 OMB_IF_SET_CONFIGURATION_REQ – Set configuration request ............................................. 20
4.1.4 OMB_IF_SET_CONFIGURATION_CNF – Confirmation packet for Set configuration .................... 23
4.1.5 Detailed parameter descriptions for Set configuration request ........................................................ 24
4.2 Common operating system packets ............................................................................................. 32
4.3 IO mode: Server Modbus data model .......................................................................................... 34
4.4 Message mode: Server with packets ........................................................................................... 37
4.4.1 Overview ......................................................................................................................................... 37
4.4.2 OMB_IF_RECEIVE_IND/RES – Receive data indication ................................................................ 38
4.4.3 OMB_IF_CONNECTION_IND/RES – Connection indication .......................................................... 46
4.5 Message mode: Client with packets ............................................................................................ 49
4.5.1 Overview ......................................................................................................................................... 49
4.5.2 OMB_IF_SEND_REQ/CNF - Send data request............................................................................. 50
4.6 Message mode: Client with command table ................................................................................ 56
4.6.1 Overview ......................................................................................................................................... 56
4.6.2 CMDTBL_INIT_REQ/CNF – Init command table task ..................................................................... 58
4.6.3 CMDTBL_ADD_TABLE_REQ/CNF – Add new command table ..................................................... 59
4.6.4 CMDTBL_DELETE_TABLE_REQ/CNF – Delete a command table................................................ 62
4.6.5 CMDTBL_ACTIVATE_TABLE_REQ/CNF – Activate a command table .......................................... 64
4.6.6 CMDTBL_DEACTIVATE_TABLE_REQ/CNF – Deactivate a command table................................. 66
4.6.7 CMDTBL_ADD_COMMAND_REQ/CNF – Add a command to a table ........................................... 68
4.6.8 CMDTBL_DELETE_COMMAND _REQ/CNF – Delete a command ................................................ 72
4.6.9 CMDTBL_ACTIVATE_COMMAND_REQ/CNF – Activate a command ........................................... 74
4.6.10 CMDTBL_DEACTIVATE_COMMAND_REQ/CNF – Deactivate a command .................................. 76
4.6.11 CMDTBL_TRIGGER_COMMAND_REQ/CNF – Trigger a command.............................................. 78
4.6.12 CMDTBL_GET_IO_INFO_REQ/CNF – Get IO Info ........................................................................ 80
4.6.13 CMDTBL_DEINIT_REQ/CNF – Table Deinitialization ..................................................................... 82
4.6.14 CMDTBL_START_STOP_REQ/CNF – Table Start/Stop ................................................................ 83
4.6.15 Command Table diagnostic with Status bit fields ............................................................................ 85
4.6.16 Command table timing diagram ....................................................................................................... 87
5 Status/Error codes ............................................................................................................................... 89
5.1 Status/Error codes OMB task....................................................................................................... 89
5.2 Status/Error codes Modbus Core ................................................................................................. 94
5.3 Status/Error codes CMD task....................................................................................................... 95
6 Appendix ............................................................................................................................................... 97
6.1 Modbus Exception Codes ............................................................................................................ 97
6.2 List of tables ................................................................................................................................. 98

Open Modbus/TCP V3 | Protocol API

DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
Introduction 3/104
6.3 List of figures ................................................................................................................................ 99
6.4 Legal notes ................................................................................................................................. 100
6.5 Contacts ..................................................................................................................................... 104

Open Modbus/TCP V3 | Protocol API

1 Introduction
1.1 Abstract
This manual describes the application interface of the Open Modbus/TCP protocol stack. Use this
manual to support and guide you through the integration process of the given stack into your own
application.

1.2 List of revisions

Rev Date Name Revisions
1 2019-06-24 MKr, RGö, Firmware/stack version 3.0.0
HHe Document created
Table 1: List of revisions

Open Modbus/TCP V3 | Protocol API

1.3 Functional overview

The stack has been written in order to meet the Open Modbus/TCP protocol specification. The stack
can operate as a client or as a server.
The main functionality from the application view is:
 Message mode (Client and Server)
 IO mode (Server)
 Command table execution (Client)

1.4 System requirements

This software package has following system requirements to its environment:
 netX chip as hardware platform

1.5 Intended audience

This manual is suitable for software developers with the following background:
 Knowledge of the programming language C
 Knowledge of the use of the real-time operating system rcX
 Knowledge of the TCP/IP protocol suite
 Knowledge of the Open Modbus/TCP protocol

Open Modbus/TCP V3 | Protocol API

1.6 Technical data

The data below applies to Open Modbus/TCP firmware and stack version V3.0.0.
The firmware/stack is based on the MODBUS specifications references in [3] and [4].

Technical data

Feature Value
Maximum number of input data 5760 bytes
Maximum number of output data 5760 bytes
Acyclic communication Read/Write register:
Max. 125 registers per read telegram (FC 3, 4, 23)
Max. 121 registers per write telegram (FC 23),
Max. 123 registers per write telegram (FC 16)
Read/Write coil:
Max. 2000 coils per read telegram (FC 1, 2)
Max. 1968 coils per write telegram (FC 15)
Modbus function codes 1, 2, 3, 4, 5, 6, 7, 15, 16, 23, 43
Modes Message Mode: Client, Server (I/O data area is not used in this mode)
I/O Mode: Server
Command table Max. 16 servers configurable
Max. 256 commands in total *)
Baud rates 10 and 100 MBit/s
Data transport layer Ethernet II, IEEE 802.3
Table 2: Technical data Open Modbus/TCP

Firmware/stack available for netX

netX Available
netX 50 Yes
netX 51 Yes
netX 52 Yes
netX 90 No
netX 100 Yes
netX 500 Yes
netX 4000 No
Table 3: Firmware/stack available for netX

Configuration

Configured by Remark
SYCON.net Download or
by exported configuration files named inibatch.nxd and command.nxd
Application Application can use packets to configure the firmware/stack.
Table 4: Configuration

Open Modbus/TCP V3 | Protocol API

Firmware supports common and extended diagnostic in the dual-port-memory for loadable firmware.

Additional features

Feature Value
DMA transfer Supported for PCI target
Slot number Supported for CIFX 50-RE, CIFX 50E-RE
Integrated WebServer Supported (for details see reference [5])
Table 5: Additional features

Limitations

TCP/IP routing not supported anymore due to change of TCP/IP stack component.
*) For the netRAPID device only 64 commands can be configured.

Open Modbus/TCP V3 | Protocol API

1.7 Terms, abbreviations and definitions

Term Description
AP (task) Application (task) on top of the stack
BOOTP Bootstrap Protocol
DHCP Dynamic Host Configuration Protocol
DPM Dual-port memory
IP Internet Protocol
OMB Open Modbus/TCP
TCP Transmission Control Protocol
UDP User Datagram Protocol
CMD Command Table
Table 6: Terms, abbreviations and definitions

All variables, parameters and data used in this manual have the LSB/MSB (“Intel”) data format. This
corresponds to the convention of the Microsoft C Compiler.
All IP addresses in this document have host byte order.

1.8 References to documents

This document is based on the following specifications:
[1] Hilscher Gesellschaft für Systemautomation mbH: Dual-Port Memory Interface Manual,
netX based products. Revision 15, English, 2019.
[2] Hilscher Gesellschaft für Systemautomation mbH: Packet API, netX Dual-Port Memory,
Packet-based services (netX 90/4000/4100), Revision 1, English, 2019.
[3] MODBUS APPLICATION PROTOCOL SPECIFICATION, V1.1a, June 4,
(http://www.modbus.org)
[4] MODBUS MESSAGING ON TCP/IP IMPLEMENTATION GUIDE, V1.0a, June 4, 2004
(http://www.modbus.org)
[5] Hilscher Gesellschaft für Systemautomation mbH: Application Note: Functions of the
Integrated WebServer, Revision 4, English, 2012

Open Modbus/TCP V3 | Protocol API

2 Getting started
This section explains some essential information you should know when starting to work with the
Open Modbus/TCP protocol API.

2.1 Client/server and operating modes

Open Modbus/TCP is a TCP/IP-based communication protocol. One device operates as client and
requests data from another device which operates as a server. In a request, the client uses a function
code to specify the function which the server should execute. The client can read and write data
memory of the server.

Figure 1: Client/Server principle

Open Modbus/TCP offers two data types:

 register (16-bit value)
 coils (1-bit value)
The Open Modbus/TCP task offers two operation modes:
 Message mode: stack operates as client only, as server only or as client and server
 IO mode: stack operates as server (only)

Open Modbus/TCP V3 | Protocol API

2.2 Structure of the Open Modbus/TCP protocol stack

The figure below shows the internal structure of the tasks which together represent the Open
Modbus/TCP stack.

Figure 2: Structure of Open Modbus/TCP Firmware

The dual-port memory is used for exchange of data, status information and packets. Configuration
and IO data will be transferred using this way.
The user application only accesses the task located in the highest layer namely the AP task which
constitutes the application interface of the Open Modbus/TCP protocol stack.
AP task
The AP task provides the interface to the user application and the control of the stack. It also
completely handles the dual-port memory interface of the communication channel. In detail, it is
responsible for the following:
 Handling the communication channels dual-port memory interface
 Process data exchange (IO mode)
 Channel mailboxes
 Watchdog
 Service the common and extended status field in the dual-port memory
 Configuration management
 Loading the data base file ‘command.nxd’
 Reception and routing of configuration packets sent by the user application
 Mailbox packet handling and routing
 handle of all incoming and outgoing packets to the user application

Open Modbus/TCP V3 | Protocol API

DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
Getting started 11/104
 configuration packets
 send/receive packets
 handle Hilscher common rcX stack packets like HIL_CHANNEL_INIT_REQ
 forward ‘Request’ and ‘Response’ packets from host application context through the
OMB task
 forward ‘Indication’ and ‘Confirmation’ packets from the OMB task through the host
application context
 forward ‘Request’ and ‘Response’ packets from host application context through the
CMD task
 forward ‘Request’ and ‘Response’ packets from host application context through the
TCP/IP task
 Control of LEDs

OMB core component

The OMB core component represents the central part of the Open Modbus/TCP stack
implementation. It manages the conversion of Modbus functions to TCP/IP frames. It is responsible
for the protocol handling, the communication to/from TCP/IP stack and it is the counterpart of the AP
task.
The underlying TCP/IP stack provides basic TCP/IP communication capabilities located at the layers
3 and 4 of the OSI/ISO layer model.
The OMB task is the Open Modbus/TCP stack implementation. It is responsible for the protocol
handling, the communication from and to the TCP/IP stack and it is the counterpart of the AP task.

CMD component

The CMD component (Command Table) executes a previously configured command table. The
command table is a list of configured Open Modbus/TCP request sthat are executed cyclically. The
command table works as Open Modbus/TCP client. It can send reading or writing function codes to
a remote Open Modbus/TCP server. The data that is read or written from a remote Open
Modbus/TCP server are exchanged with the host application via dual-port memory input/output
areas.

2.3 Configuration
The Open Modbus/TCP stack requires configuration parameters e.g. IP address.
Configuration parameters can be set using configuration software or can be set from an application
program using the packet API.

Open Modbus/TCP V3 | Protocol API

3 Exchanging data
3.1 Message mode vs IO mode
The Open Modbus/TCP task offers two basic operation modes:
 Message mode: the stack operates as client only, as server only or as client and server
 IO mode: the stack operates as server (only)
The parameter ulMode sets the operation mode of the Open Modbus/TCP stack. This parameter is
one of the basic configuration parameters, which are described in section Basic parameter on page
23.

Message mode

In message mode, the stack uses packets to communicate with the application. In this mode, a
simultaneous operation of the Open Modbus/TCP task as server and client is possible.
The Open Modbus/TCP stack can handle up to 16 sockets to establish 16 TCP/IP connections
simultaneously. By default, 4 sockets are configured as server sockets and the remaining 12 sockets
can be used as client sockets. The fraction of the available 16 sockets (server sockets to client
sockets) can be parameterized. With the default setting 4 clients can connect to the stack over
TCP/IP. The rest of 12 sockets can be used from a client application to send commands to different
Open Modbus/TCP devices or Open Modbus/TCP application.
In message mode, the application programmer has the option to implement a Modbus data model
of his or her own. The application programmer can decide, which function codes are supported. It is
also possible to support the full Modbus address range of Modbus register and coils.
As an alternative, a command table can be used instead of packets. In this case, the stack
automatically executes the commands of the command table to act as a client and request data from
the Modbus server. The stack uses the input and output area of the dual-port memory to
communicate to the application. The application program cannot use packets when using the
command table at the same time.

IO mode

In IO mode the stack uses the input and output area of the dual-port memory to communicate to the
application. In IO mode, the Open Modbus/TCP task works exclusive as server (No client
functionality is available).
In IO mode the Modbus data model is fixed. The entire handling of Open Modbus/TCP function
codes is done by the Open Modbus/TCP stack. The number of supported registers and coils is limited
by the size of the dual-port input and output area.

Open Modbus/TCP V3 | Protocol API

3.2 Command table

When the Open Modbus/TCP stack is configured in Message mode, it supports a so called
command table. The command table contains a list of commands which contain function codes,
addresses and further parameters. These commands are processed cyclically by the Modbus/TCP
stack. The command table can contain several function codes, which are sent to one or multiple
Open Modbus/TCP servers. The command table is a configuration file, which is created by
SYCON.net or netX Configuration Tool and downloaded to the Open Modbus/TCP task during the
configuration process. Since Modbus/TCP stack version V2.6, it is also possible for the host
application to configure a command table using packets.
When the command table is processed, the data exchange with the host application is done via dual-
port memory input and output area.
When the Modbus/TCP stack executes a reading function code from the command table, then the
data which are read from the remote Modbus/TCP server will be placed into the input image of the
dual-port memory. When the Modbus/TCP stack executes a writing function code from the command
table, then the data which are written to the remote Modbus/TCP server will be taken from the output
image of the dual-port memory.

3.3 Modbus function codes

The Modbus specification defines the function codes for send and receive operations:

Function Value Function Description

code (deci-
mal)
FC1 1 Read coils Coils in the sense of Open Modbus/TCP are status bits, which can
be both read and written.
This function code can be used to read status values of coils in a
remote device. The addresses of the coils must be contiguous.
FC2 2 Read input discretes This function code can be used to read discrete status values of
read-only data in a remote device. The addresses must be
contiguous.
FC3 3 Read multiple registers This function code can be used to read 16-bit registers containing
read-/write data from a remote device. The addresses of the
registers must be contiguous.
FC4 4 Read input registers This function code can be used to read 16-bit registers containing
read-only data from a remote device. The addresses of the
registers must be contiguous.
FC5 5 Write coil
Coils in the sense of Open Modbus/TCP are status bits, which can
be read and written.
This function code can be used to write one status value of a
single coil within a remote device.
FC6 6 Write single register This function code can be used to write a single 16-bit register
containing read-/write data within a remote device.
FC7 7 Read exception status This function code can be used to read the Exception Status of a
remote device. Except the IP address, there are no further
parameters needed.
FC15 15 Force multiple coils Coils in the sense of Open Modbus/TCP are status bits, which can
be read and written.
This function code can be used to write status values of multiple
coils at once to a remote device. The applicable range extends
from 1 to 1968.

Open Modbus/TCP V3 | Protocol API

Function Value Function Description

code (deci-
mal)
FC16 16 Write multiple registers
This function code can be used to write to 16-bit registers containing
read-/write data at a remote device. The addresses of the registers
must be contiguous.
FC23 23 Read/Write multiple registers This function code can be used to perform a combined read/write
access to a 16-bit register as a single Modbus transaction. It can
 write to multiple16-bit registers
 read multiple16-bit registers
These registers contain read/write data at a remote device. The
addresses of the registers must be contiguous.
FC43 43 Read Device Identification This function code allows reading the identification and additional
information relative to the physical and functional description of a
remote device. The Read Device Identification interface is
modeled as an address space composed of a set of addressable
data elements. The data elements are called objects and an object
Id identifies them.
The interface consists of 3 categories of objects:
 Basic Device Identification. All objects of this category
are mandatory: VendorName, Product code, and revision
number.
 Regular Device Identification. In addition to Basic data
objects, the device provides additional and optional
identification and description data objects. All of the objects
of this category are defined in the standard, but their
implementation is optional.
 Extended Device Identification. In addition to regular
data objects, the device provides additional and optional
identification and description private data about the
physical device itself. All of these data are device
dependent.
Table 7: Function codes in detail

Note: Function Code 43 is supported beginning with Modbus/TCP Stack V2.6. The Device
Identification data are configured with the Set Configuration packet. The Modbus/TCP
Stack V2.6 supports the “Basic” and “Regular” Device Identification. The “Conformity
Level” 0x82 is supported. This means the Device Identification data can be accessed per
“stream” or “individual”. The “Extended” Device Identification is not supported for
loadable firmware. But it is optionally supported, in case of custom specific firmware
based on linkable objects. In this case, the Extended Device Identification data are
configured as task start up parameter.

Note: Function Code 43 is only supported as server. This means the Modbus/TCP stack will
respond to FC43 requests from a client. Sending FC43 to a remote server as client is
not supported.

Open Modbus/TCP V3 | Protocol API

Illegal Function

The function code received in the query is not allowed (Server mode). This could be
 because the function code does not belong to the allowed range (currently 1 … 7, 15, 16, 23
or 43).
 because the server is not in the correct state to process such a request, for example because
it has not been configured correctly and is asked to return register values.
These situations might lead to an error message Exception code ILLEGAL FUNCTION (Code
01).
Other possibilities include:
 Wrong number of data in connection of the Modbus reference number
 Wrong data address
These situations might lead to an error message Exception code ILLEGAL DATA ADDRESS
(Code 02).

Illegal Data Address

The data address received in the query is not a correct address for the slave, i.e. the combination of
reference number and transfer length is invalid. For a controller with 100 registers, a request with
offset 96 and length 4 could be executed successfully, while a request with offset 96 and length 5
will cause this error.
In IO mode, this situation might lead to an error message
TLR_E_OMB_IF_MOD_MEM_MOD_START_ADR (0xC0600004).

Open Modbus/TCP V3 | Protocol API

4 The application interface

This chapter describes the application interface of the Open Modbus/TCP stack V3.

Figure 3: Host application accesses the Open Modbus/TCP

The host application communicates with the AP task via the dual-port memory by exchanging
packets. The following chapter describes the packets that may be received or sent by the AP Task.
In general, packets can be divided into “Request/Confirmation” packets and Indication/Response
packets. “Request” packets are sent from the host application to the Open Modbus/TCP stack and
the stack will return a corresponding “Confirmation”. Also the Open Modbus/TCP stack can send
“Indication” packets to the host application and the host application has to send a corresponding
“Response” packet.
The AP task internally communicates with the underlying OMB Task and the CMD Task and TCP/IP
Task.

Open Modbus/TCP V3 | Protocol API

4.1 Configuration
4.1.1 Configuration via packet

Figure 4: Configuration sequence

Open Modbus/TCP V3 | Protocol API

DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
The application interface 18/104
*) These packets are optional.
The diagram above shows the Open Modbus/TCP configuration flow via packet API.
In order to configure the Open Modbus/TCP stack, the following packet configuration procedure is
required:
Packet Explanation
OMB_IF_SET_CONFIGURATION_REQ/CNF This packet is required to provide the configuration data. The
– Set configuration (page 20) configuration data are verified. In case of failure, no data are accepted
and a corresponding error code is set in the confirmation packet. In
case of success, the configuration parameters are stored internally in
the RAM.
HIL_REGISTER_APP_REQ_REQ/CNF – This packet is optional. It is not required in ‘IO-Mode’. It is required in
Register application message mode in order to receive indications packets.
For more information, see reference [1].
HIL_CHANNEL_INIT_REQ/CNF – Channel init Perform a channel initialization to activate the configuration.
and configuration activation For more information, see reference [1].
HIL_START_STOP_COMM_REQ/CNF – Start the Communication
Start/stop communication on the Bus This packet is optional. It is only required, if the start-up behavior has
been set to ‘Application controlled’ mode.
For more information, see reference [1].
Table 8: Configuration sequence

4.1.2 Configuration with SYCON.net

4.1.2.1 Configuration via config file config.nxd
Additionally, it is possible to configure the Open Modbus/TCP stack with a database file called
config.nxd.
This configuration file ‘config.nxd’ is created by the configuration software ‘SyCon.net’ or the ‘netX
Configuration Tool’. It is typically downloaded and stored into the flash file system.
The configuration file ‘config.nxd’ contains the following packets:
1. OMB_IF_SET_CONFIGURATION_REQ/CNF – Set configuration (page 20)
2. HIL_CHANNEL_INIT_REQ/CNF – Channel init and configuration activation (see reference [1])
During system startup, the Open Modbus/TCP stack opens this file and applies this configuration.
This means, the configuration flow is the same as when the user sends the packets from the host
application.

4.1.2.2 Configuration of the command table

If the Open Modbus/TCP stack operates as client with command table as described in chapter
Command table (on page 13), it can be configured:
 By a configuration file command.nxd created by SyCon.net
 By packets from the host application
Beginning with Open Modbus/TCP V2.6, it is possible to configure the command table fully by the
host application without any SyCon.net data base. The following figure shows the configuration
sequence, if the command table is configured by the host application. The configuration packets for
the command table are described in chapter Message mode: Client with command table on page
56.
Open Modbus/TCP V3 | Protocol API
DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
The application interface 19/104

Figure 5: Command table configuration sequence

Open Modbus/TCP V3 | Protocol API

DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
The application interface 20/104
4.1.3 OMB_IF_SET_CONFIGURATION_REQ – Set configuration
request
This packet provides the configuration parameters of the Open Modbus/TCP stack.
The following applies:
 The configuration parameters will be stored internally within volatile memory (i.e. RAM).
 In case of any error, no data will be stored at all.
 In order to activate the parameterized data, a channel init is required.
 This packet does not automatically perform any application registration at the stack.
 Application registration must be done with a separate packet ‘HIL_REGISTER_APP_REQ’
which is described in the netX Dual-Port-Memory Manual [1].
 Application registration is only required when it is intended to receive indication packets.
 This packet will be denied, if the configuration lock flag is set.

Packet structure reference

/* Basic Modbus/TCP Configuration - structure*/
#define OMB_IF_VENDOR_NAME_STR_SIZE 64 /*!< Vendor name string size.*/
#define OMB_IF_PRODUCT_CODE_STR_SIZE 64 /*!< Product code string size. */
#define OMB_IF_MAJ_MIN_REV_STR_SIZE 16 /*!< Revision string size. */
#define OMB_IF_VENDOR_URL_STR_SIZE 64 /*!< Vendor URL string size. */
#define OMB_IF_PRODUCT_NAME_STR_SIZE 64 /*!< Product name string size. */
#define OMB_IF_MODEL_NAME_STR_SIZE 64 /*!< Model name string size. */
#define OMB_IF_USER_APP_NAME_STR_SIZE 64 /*!< Application name string size. */

typedef struct OMB_IF_CONFIG_BASIC_Ttag {

uint32_t ulOpenServerSockets; /* number of sockets to open */
uint32_t ulAnswerTimeout; /* Internal Timeout */
uint32_t ulOmbOpenTime; /* Time to close Socket */
uint32_t ulMode; /* Message or IO-Mode */
uint32_t ulSendTimeout; /* Parameter for TCP-Task */
uint32_t ulConnectTimeout; /* Parameter for TCP-Task */
uint32_t ulCloseTimeout; /* Parameter for TCP-Task */
uint32_t ulSwap; /* Swap Data or not */
} OMB_IF_CONFIG_BASIC_T;

/* TCP/IP Configuration- structure */

typedef struct OMB_IF_CONFIG_IP_Ttag
{
uint32_t ulFlags; /* IP Configuration Flags */
uint32_t ulIpAddr; /* Static IP address */
uint32_t ulNetMask; /* Network mask */
uint32_t ulGateway; /* IP address of gateway */
uint8_t abEthernetAddr[6]; /* Custom MAC address */
} OMB_IF_CONFIG_IP_T;

/* Extended Modbus/TCP Configuration - structure*/

typedef struct OMB_IF_CONFIG_EXT_Ttag
{
uint32_t ulProcessWatchdog; /* process data watchdog */
uint32_t ulInactiveTimeout; /* Server connection inactivity timeout */
uint16_t usMaxRegisterNumber; /* Maximum addressable registers */
uint16_t usMaxCoilsNumber; /* Maximum addressable coils */
uint16_t usFragmentationTimeout; /* Fragmentation Timeout */
uint16_t usReserved; /* Reserved, set to 0 */
}OMB_IF_CONFIG_EXT_T;

/* Ident Configuration – Structure */

typedef struct OMB_IF_CONFIG_IDENT_Ttag
{

Open Modbus/TCP V3 | Protocol API

DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
The application interface 21/104
char szVendorName[OMB_IF_VENDOR_NAME_STR_SIZE];
char szProductCode[OMB_IF_PRODUCT_CODE_STR_SIZE];
char szRevision[OMB_IF_MAJ_MIN_REV_STR_SIZE];
char szVendorUrl[OMB_IF_VENDOR_URL_STR_SIZE];
char szProductName[OMB_IF_PRODUCT_NAME_STR_SIZE];
char szModelName[OMB_IF_MODEL_NAME_STR_SIZE];
char szUseAppName[OMB_IF_USER_APP_NAME_STR_SIZE];
} OMB_IF_CONFIG_IDENT_T;

/* Set Configuration Data – Structure */

typedef struct OMB_IF_SET_CONFIGURATION_REQ_DATA_Ttag
{
uint32_t ulSystemFlags; /* common system config flags */
uint32_t ulWdgTime; /* watchdog time */
OMB_IF_CONFIG_BASIC_T tOmbConfig; /*!< OMB Basic parameters. */
OMB_IF_CONFIG_IP_T tIPConfig; /* TCP/IP configuration */
uint32_t ulFlags; /* misc configuration flags */
/* Parameter starting with V2.6 */
OMB_IF_CONFIG_EXT_T tOmbConfigExt; /* extend. Modbus/TCP config */
OMB_IF_CONFIG_IDENT_T tOmbConfigIdent; /* Ident config for FC43 */
} OMB_IF_SET_CONFIGURATION_REQ_DATA_T;

/* Set Configuration Packet – Structure */

typedef struct OMB_IF_SET_CONFIGURATION_REQ_DATA_T
{
HIL_PACKET_HEADER_T tHead;
OMB_IF_SET_CONFIGURATION_REQ_DATA_T tData;
} OMB_IF_SET_CONFIGURATION_REQ_T;

Open Modbus/TCP V3 | Protocol API

Variable Type Value / Range Description

ulDest uint32_t 0x20/QUE_OM Destination (HIL_PACKET_DEST_DEFAULT_CHANNEL)
BAPTASK
ulLen uint32_t 482 Packet Data Length in bytes
(62)* (66)** OMB_IF_SET_CONFIGURATION_REQ_DATA_SIZE

ulSta uint32_t 0 Status set 0

ulCmd uint32_t 0x3F18 OMB_IF_SET_CONFIGURATION_REQ

Structure OMB_IF_SET_CONFIGURATION_REQ_DATA_T
ulSystemFlags uint32_t Default value: 0 System Flags
indicating BIT 0: AUTOSTART(0) / APPLICATION CONTROLLED(1)
AUTOSTART BIT 2 - 31 not yet implemented
Allowed values: BIT 0 corresponds to
0,1 OMB_IF_SYS_FLAG_COM_CONTROLLED_RELEASE
The meaning of BIT 0 is:
0 - Communication with a remote station after a device start is
allowed without BUS_ON flag, but the communication will be
interrupted if the BUS_ON flag changes state to 0 ;
1 - Communication with a remote station is allowed only with the
BUS_ON flag.
ulWdgTime uint32_t 0, 20 … 65535 Watchdog time (in ms)
0 means the watchdog timer has been switched off.
tOmbConfig STRUCT Open Modbus/TCP Basic configuration data structure:
OMB_IF_CONFIG_BASIC_T
See section Basic parameter on page 23.
tIPConfig STRUCT TCP/IP configuration data structure:
OMB_IF_CONFIG_IP_T
See section TCP/IP parameter on page 26.
ulFlags uint32_t Bit field Configuration Flags
See section Parameter flags on page 28.

Configuration Data starting with Open Modbus/TCP V2.6

tOmbConfigExt STRUCT Open Modbus/TCP Extended configuration data structure:
OMB_IF_CONFIG_EXT_T
See section Extended parameter on page 30.
tOmbConfigIdent STRUCT Modbus TCP Ident configuration data structure:
OMB_IF_CONFIG_IDENT_T
See chapter Ident parameter on page 31.
Table 9: OMB_IF_SET_CONFIGURATION_REQ

* The packet length of 62 bytes is also accepted for compatibility reasons with the older firmware
version V2.0.x. In this case, the parameters ulFlags, tOmbConfigExt, tOmbConfigIdent
are internally set to zero.
** The packet length of 66 bytes is also accepted for compatibility reasons with the older firmware
version V2.5.x. In this case, the parameters tOmbConfigExt, tOmbConfigIdent are internally
set to zero.

Open Modbus/TCP V3 | Protocol API

This parameter contains the system flags area. Currently, this parameter may only have the values
0 or 1. The start of the device can be performed either application controlled or automatically:
 Automatic (0):
Network connections are opened automatically without taking care of the state of the host
application. Communication with a remote controller after a device start is allowed without
BUS_ON flag, but the communication will be interrupted if the BUS_ON flag changes state to 0
 Application controlled (1):
The Open Modbus/TCP stack is forced to wait for the host application before releasing the
network communication. Network communication is allowed with the BUS_ON flag set. Setting
the BUS_ON flag can be performed by using the packet HIL_START_STOP_COMM_REQ/CNF
packet.
The default value is 0 (Automatic).

Parameter ulWdgTime

4.1.4 OMB_IF_SET_CONFIGURATION_CNF – Confirmation packet for

Set configuration
4.1.4.1 Confirmation

Packet structure reference

typedef struct OMB_IF_SET_CONFIGURATION_CNF_Ttag
{
HIL_PACKET_HEADER_T tHead;
} OMB_IF_SET_CONFIGURATION_CNF_T;

Packet description

Variable Type Value / Range Description

Structure HIL_PACKET_HEADER_T
ulLen uint32_t 0 Packet Data Length in bytes
(OMB_IF_AP_SET_CONFIGURATION_CNF_SIZE)
ulSta uint32_t 0 ... 232-1 See section Status/Error codes AP task*)
ulCmd uint32_t 0x3F19 OMB_IF_SET_CONFIGURATION_CNF - Command
Table 10: OMB_IF_SET_CONFIGURATION_CNF –Confirmation of Provide Warmstart Parameters Packet

Open Modbus/TCP V3 | Protocol API

Parameter ulSystemFlags

Parameter ulWdgTime

This parameter contains the time interval for the supervision of data transfer by the internal watchdog
timer (Host activity watchdog timeout). The value must be either the value 0 or a number between
20 and 65535.
If the value 0 is specified, this indicates the watchdog timer has been switched off. Otherwise, the
watchdog timer interval is specified in units of milliseconds.
All further basic parameters are explained in the following table:
Variable Type Value / Range Description
ulOpenServerSock uint32_t 0..4...16
U Number of sockets to provide for server requests.
ets
A value of 0 would mean that the Open Modbus/TCP task
exclusively works as a client, while a value of 16 means that the
Open Modbus/TCP task exclusively works as server in message
mode. The values 1 … 15 mean that the Open Modbus/TCP task
could simultaneously work as a client and a server.
Default value: 4
ulAnswerTimeout uint32_t 1...60000 Server response timeout.
This parameter is only relevant for client jobs in message mode.
After expiration of the specified time, the job will be cancelled
and an error will be sent to the application.
The value is multiplied with 100 ms.
Default value: 20 (equivalent to 2 seconds effectively)
U

Note: This timeout starts after a command is sent to the

destination device via TCP.

Open Modbus/TCP V3 | Protocol API

Variable Type Value / Range Description

ulOmbOpenTime uint32_t 1...60000 Client socket idle timeout.
This parameter is only relevant for client jobs in message mode.
The connection to the destination device stays open, until the
timeout expires.
The specified value is multiplied with 100 ms.
Default value: 10 (= 1 s)
U

Note: This timeout starts after receiving the answer to a

command.
ulMode uint32_t 0, 1 Operation mode of the stack
0: Message mode
1: IO mode (Default)
ulSendTimeout uint32_t 0…
U Max timeout for outgoing TCP packets in ms.
2000000000 Specifies the timeout value for trying to send messages via
TCP/IP.
Default value: 31000
0: activates the default value of 31000 milliseconds.
Note: This parameter is only for client jobs in message mode.
ulConnectTimeout uint32_t 0…
U Max timeout when connecting to a remote server in ms.
2000000000 Specifies the timeout value for trying to establish a connection
with the LWIP.
Default value: 31000
0: activates the default value of 31000 milliseconds.
Note: This parameter is only for client jobs in message mode.
ulCloseTimeout uint32_t 0…
U Max timeout to wait for a local socket to close in ms.
65535000 Specifies the timeout value for trying to close a connection with
the LWIP.
0: activates the default value of 13000 milliseconds.
Note: This parameter is only for client jobs in message mode.
ulSwap uint32_t 0, 1 Data storage mode
0: Data will not be swapped
1: Data will be swapped (default)
This parameter decides, whether register data will be swapped
between application context and network transportation, or not.
The swap option is valid for both directions: sending and
receiving. This means, if the swap option is enabled, the register
values from the application context will be swapped before they
are sent to the network. All received register values from the
network will be swapped before submitted to the application
context. The default value for Swap is "enabled", because
register values of Open Modbus/TCP are specified in MSB
format. But in most cases the applications are in LSB format.
Table 11: Basic parameter: Structure OMB_IF_CONFIG_BASIC_T

The parameters ulSendTimeout, ulConnectTimeout and ulCloseTimeout decide about the

timeout between the Open Modbus Task and the LWIP Task.

Open Modbus/TCP V3 | Protocol API

DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
The application interface 26/104
4.1.5.2 TCP/IP parameter
Additionally, some parameters related to the underlying TCP/IP protocol layers also need to be
configured.
Variable Type Value / Range Description
ulFlags uint32_t 0..63 Bit mask, see below
ulIpAddr uint32_t Valid IP IP address
address This parameter is only effective, if the
OMB_IF_CONFIG_IP_FLAG_IP_ADDR flag is set in
ulFlags.
ulNetMask uint32_t Valid netmask Netmask
This parameter is only effective, if the
OMB_IF_CONFIG_IP_FLAG_NET_MASK flag is set in
ulFlags.
ulGateway uint32_t Valid IP IP address of gateway
address This parameter is only effective, if the
OMB_IF_CONFIG_IP_FLAG_GATEWAY flag is set in
ulFlags.
abEthernetAddr[6] uint8_t [6] Valid Ethernet Ethernet address of the device (6 byte)
address The abEthernetAddr area can be used to overwrite the
device’s default Ethernet address (MAC address). This
parameter is only effective, if the
OMB_IF_CONFIG_IP_FLAG_ETHERNET_ADDR flag is set in
ulFlags.
Not supported in OMB V3.
Table 12: TCP/IP Parameter: Structure OMB_IF_CONFIG_IP_T

Open Modbus/TCP V3 | Protocol API

The ulFlags parameter contains bit-oriented flags according to the following table:
Bits Name (Bit mask) Description
0 OMB_IF_CONFIG_IP_FLAG_IP_ADDR The network interface configuration contains a fixed IP address.
If set, the ulIpAddr parameter will be evaluated.
1 OMB_IF_CONFIG_IP_FLAG_NET_MASK The network interface configuration contains a network address
mask.
If set, the ulNetMask parameter will be evaluated. If the flag is not
set, the stack will assume to be an isolated host which is not
connected to any network. The ulGateway parameter will be
ignored in this case.
2 OMB_IF_CONFIG_IP_FLAG_GATEWAY The network interface configuration contains a gateway IP address.
If set, the ulGateway parameter will be evaluated. If the flag is not
set, the stack will assume that no gateway is present in the
network.
3 OMB_IF_CONFIG_IP_FLAG_BOOTP Enable BOOTP:
If set, the stack tries to obtain its configuration from a BOOTP
server.
4 OMB_IF_CONFIG_IP_FLAG_DHCP Enable DHCP:
If set, the stack tries to obtain its configuration from a DHCP server.
5 OMB_IF_CONFIG_IP_FLAG_ETHERNET Set Ethernet address (MAC address):
_ADDR
If set, the abEthernetAddr area will be evaluated. Not supported
in OMB V3.
31 ... 6 Reserved Reserved for future use
Table 13: TCP/IP Parameter – ulFlags

Please note, that a fallback procedure between the different configuration methods is active, if more
than one choice is enabled in the ulFlags parameter.
 If enabled, the stack will first try to configure using DHCP.
 If DHCP configuration fails, the stack will fall back to BOOTP, if this is enabled.
 In case of a BOOTP failure, the values found in the ulIpAddr, ulNetMask and ulGateway
parameters will be used, if enabled in ulFlags.
 If none of these configuration mechanisms succeeds, the stack will report an error.

Open Modbus/TCP V3 | Protocol API

DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
The application interface 28/104
4.1.5.3 Parameter flags
This parameter relates to the Open Modbus/TCP stack. It holds bit-oriented flags according to the
following table. The default value of this flag field is all bits are 0.
Bits Name (Bit mask) Description
0 OMB_IF_CFG_FLAG_FC1_FC3_OUTPUT Alternative mapping in IO mode
If set, the Function codes FC1 and FC3 are mapped to
the Output Data image of dual-port memory
(abPd0Output[]).Needed e.g. for Clients without FC2,
FC4 support. Also see chapter Reading and writing data.
1 OMB_IF_CFG_FLAG_TCPIP_NO_CONFIG Skip configuration of TCP/IP stack
0: The TCP/IP stack is configured by the Open
Modbus/TCP stack.
1: TCP/IP stack configuring is not performed by the
Open Modbus/TCP stack.
If set, the TCP/IP stack is not configured. This flag
should be used only for special cases!
This means, in that case the TCP/IP stack is configured
in some other way.
Not supported in OMB V3.
2 … 3 *) Fail-Safe mode.
Fail-Safe functionality is applicable only in IO_MODE. Its
effect is triggered in case all connections to clients are
interrupted or closed. Additional condition for applying
the fail-safe is also the process data watchdog
expiration. There are three Fail-safe modes: Clear, Set,
Hold Last State. In mode Clear, when Fail-Safe
triggered, Input and Output DPM areas are cleared. In
mode Set, Input area is set. In mode Hold Last State, no
changes occur.
OMB_IF_CFG_FLAG_FAILSAFE_MASK Failsafe behavior:
OMB_IF_CFG_FAILSAFE_MODE_CLEAR 11b Fail-Safe Mode value can be accessed through this
mask.
OMB_IF_CFG_FLAG_FAILSAFE_SET
00b Failsafe mode clear (default)
OMB_IF_CFG_FLAG_FAILSAFE_HLS
01b Failsafe mode set
10b Failsafe mode hold last state
Only relevant in ‘IO_MODE’
4 *) OMB_IF_CFG_FLAG_PRESET_INPUTS If this bit is set, the entire input image is preset to 0xFF
on Set Configuration request and Channel Init.
Only relevant in ‘IO_MODE’
5 *) OMB_IF_CFG_FLAG_SERVER_CONNECTION_IN Forwarding of Connection Indication packet
D_FORWARDI NG 0: Disable
1: Enable
If this bit is set, the packet Connection Indication will be
forwarded to the host application
6…7 Reserved Reserved set to 0
8 *) OMB_IF_CFG_FLAG_READ_WD_TRIGGER Read Write Watchdog triggering:
0: Only Write function codes will trigger the ProcessData
watchdog (Default)
1: Read and Write function codes will trigger the
ProcessData watchdog
Only relevant in ‘IO_MODE’

Open Modbus/TCP V3 | Protocol API

Bits Name (Bit mask) Description

9 *) OMB_IF_CFG_FLAG_FC7_ENABLE_FORWARDIN FC 7 Forwarding:
G
0: Forwarding FC 7 disabled (Default)
1: Forwarding FC 7 enabled
If this bit is set, function code FC 7 is forwarded to host
application. Normally, FC 7 is handled internally in the
stack.
Only relevant in ‘MESSAGE_MODE’
10 *) OMB_IF_CFG_FLAG_SERVER_DISABLE_FC43 FC43 Disable:
0: FC43 Enabled (Default)
1: FC43 Disabled
If the stack is configured as Server, setting this flag will
force the stack to return a Modbus exception 0x01
(OMB_IF_MB_EXCEPTION_ILLEGAL_FUNCTION) in
case a client requests FC43
11 *) OMB_IF_CFG_FLAG_ENABLE_RANGE_EVALUAT Register and Coil Range evaluation:
ION
0: not evaluated.
1: evaluated.
If this bit is set, the parameters
usMaxRegisterNumber and usMaxCoilsNumber
(part of OMB_IF_CONFIG_EXT_T) are evaluated,
otherwise default maximum values for registers and coils
are set. Only relevant for IO_MODE.
12 **) OMB_IF_CFG_FLAG_ENABLE_FRAME_FRAGMEN Frame fragmentation Enable:
TATION
0: Fragmentation is disabled.
1: Fragmentation is enabled.
If this bit is set the server will expect that the requests
from a client could be fragmented.
The first fragment should not be less than the size of the
MBAP + FC (8 bytes). All other fragments consist of only
PDU data.
The overall message length must be set in the MBAP
header which is part of the first fragment in the
sequence.
All fragments must be received and processed from the
Server in the configured fragmentation time. If the timer
expires the frame is dropped and an error is presented in
the Extended diagnostic of the stack.
Only relevant for OMB Server.
13 ... 31 Reserved Reserved for future use
Table 14: Stack Parameter – ulFlags

Note: The flags marked with *) have been introduced with Open Modbus/TCP Stack V2.6.
The flags marked with **) have been introduced with Open Modbus/TCP Stack V3.0.

Open Modbus/TCP V3 | Protocol API

DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
The application interface 30/104
4.1.5.4 Extended parameter
Variable Type Value / Range Description
ulProcessWatchdog uint32_t 0, 20 … 65535 The process data watchdog monitors read write requests
(ms) from a connected client. This watchdog is only applicable in
server IO_MODE. The watchdog is triggered by receiving any
read/ write requests from a client.
When the watchdog expires, the register and coil data which
are transferred into the DPM input image will be set to the
configured fail safe values.
0 (default): The watchdog is disabled.
Additional information about the Process data watchdog:
If the process watchdog is configured in such a way, that only
the write requests should trigger it, then in case of expiration
any read requests from a client will be rejected with a
Modbus exception 0x04 -
OMB_OMBTASK_EXCEPTION_SLAVE_DEVICE_FAILURE
ulInactiveTimeout uint32_t 0, 20 30000… The inactivity timeout is a timer that monitors the TCP/IP
65535 (ms) traffic on an open TCP/IP connection. If no TCP/IP traffic
appears in this time, the connection will be closed by the
stack. The default value is 30000 ms.
0: If this value is set 0, the stack will internally use the default
value of 30000 ms.
usMaxRegisterNumber uint16_t IO mode: 0 … With the maximum number of registers, it is possible to limit
2880 the allowed accessible Modbus register. If a client tries to
Message access a register above this configured value, the Open
mode: ignored Modbus/TCP stack will immediately return an exception to
the client.
Note:
This parameter is only effective in IO_MODE. The parameter
will be evaluated only, if the flag
OMB_IF_CFG_FLAG_ENABLE_RANGE_EVALUATION is
set. In message mode the parameter will be ignored. The
maximum value of 2880 registers corresponds to the
maximum size of the dual-port input image of 5760 bytes.
usMaxCoilsNumber uint16_t IO mode: 0 … With the maximum number of coils it is possible to limit the
46080 allowed accessible Modbus coils. If a client tries to access a
Message register above this configured value the Open Modbus/TCP
mode: ignored stack will immediately return an exception to the client.
Note:
This parameter is only effective in IO_MODE. The parameter
will be evaluated only if the flag
OMB_IF_CFG_FLAG_ENABLE_RANGE_EVALUATION is
set. In message mode the parameter will be ignored. The
maximum value of 48080 coils corresponds to the maximum
size of the dual-port input image of 5760 bytes.
usFragmentationTimeout uint16_t 0, 20 1000… Fragmentation timeout (new configuration parameter) is used
65535 (ms) to set the maximum allowed time to collect all fragments of a
fragmented frame.
0: If the value is set to 0, the stack will internally use the
default value of 1000 ms. This parameter is only effective for
OMB Server and will be evaluated only if the
OMB_IF_CFG_FLAG_ENABLE_FRAME_FRAGMENTATION
flag is set. For OMB client this parameter is not applicable.
usReserved uint16_t 0 Reserved set to 0.
Table 15: Extended Parameter: Structure OMB_IF_CONFIG_EXT_T

Note: The Extended Parameters are introduced with Open Modbus/TCP Stack V2.6

Open Modbus/TCP V3 | Protocol API

DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
The application interface 31/104
4.1.5.5 Ident parameters
The ident parameters are used internally by the Open Modbus/TCP stack to respond to a FC43
request.
Variable Type Value / Range Description
szVendorName[] uint8_t [64] zero terminated The VendorName is a visible zero terminated string which
visible string represents the vendor name of a device.
e.g. “Hilscher Gesellschaft fuer Systemautomation mbH“
szProductCode[] uint8_t [64] zero terminated The ProductCode is a visible zero terminated string which
visible string represents a product code of a device.
e.g. “ModbusTCP Device”
szRevision[] uint8_t [16] zero terminated The Revision is a visible zero terminated string which
visible string represents a revision of a device.
e.g. “V2.6.0.0”
szVendorUrl[] uint8_t [64] zero terminated The VendorUrl is a visible zero terminated string which
visible string represents e.g. a web address of the vendor.
e.g. “www.hilscher.com”
szProductName[] uint8_t [64] zero terminated Product Name
visible string e.g. “IO Device”
szModelName[] uint8_t [64] zero terminated Model name
visible string The ModelName is a visible zero terminated string which
represents a name of a device.
e.g. “ModbusTCP Device”
szUseAppName[] uint8_t [64] zero terminated Application name
visible string The UseAppName is a visible zero terminated string which
represents an application name.
e.g. “ModbusTCP Demo”
Table 16: Open Modbus/TCP Ident configuration data: Structure OMB_IF_CONFIG_IDENT_T

Open Modbus/TCP V3 | Protocol API

4.2 Common operating system packets

The AP task is responsible for handling common stack commands. Common stack commands are
defined in the command range of the operating system and described in the API Manual of the
Hilscher dual-port memory [1]. The common stack commands are implemented in all Hilscher stacks.
The reason for the common stack commands is to unify the handling with all Hilscher stacks.
The Open Modbus/TCP stack supports the following common stack commands listed below.
Common packet Command
HIL_CHANNEL_INIT_REQ/CNF – Channel init and configuration activation 0x2F80,
0x2F81
This packet causes a channel initialization and activation of the previously provided configuration data.
This packet is an essential packet in conjunction with the configuration process of the Open
Modbus/TCP stack. Refer to the section Configuration how to use this packet.
HIL_REGISTER_APP_REQ_REQ/CNF – Register application 0x2F10,
0x2F11
This packet is used to register the application context to the Open Modbus/TCP stack. It is required in
order to receive ‘Indication’ packets. In ‘Message Mode’ it is vital to send this packet in order to receive
e.g. ‘OMB_IF_RECEIVE_IND’ packets. In ‘IO-Server’ mode the registration is not required.
Note: When sending this packet twice, the second registration will be rejected with an error code.
HIL_UNREGISTER_APP_REQ_ REQ/CNF – Unregister application 0x2F12,
0x2F13
This packet is used to unregister the application context from the Open Modbus/TCP stack. When the
application is unregistered, no further ‘Indication’ packets will be sent from the Open Modbus/TCP stack
to the application context.
HIL_START_STOP_COMM_REQ/CNF – Start/stop communication on the Bus 0x2F30,
0x2F31
This packet is used to start or stop the network communication. This packet must be sent after sending
the ‘OMB_IF_SET_CONFIGURATION_REQ/CNF – Set configuration’ service when the Parameter
ulSystemFlags is configured in ‘Application controlled’ startup behavior. It is not required, if the startup
behavior is configured in ‘Automatic’ startup.
Note: When sending this packet with parameter to stop the network communication the Open
Modbus/TCP stack will reject all incoming requests from a client directly with an exception code.
HIL_LOCK_UNLOCK_CONFIG_REQ/CNF – Lock/unlock configuration on the bus 0x2F32,
0x2F33
This packet is used to enable or disable the so called ‘config lock’ mechanism within the Open
Modbus/TCP stack. This can be used as protection mechanism against unintended stack operation.
Note: When the ‘config lock’ is enabled, other services e.g. for configuration, start/stop communication
or reset are rejected with an error code ‘TLR_E_CONFIG_LOCK’. HIL_DELETE_CONFIG_REQ/CNF
HIL_DELETE_CONFIG_REQ/CNF 0x2F14,
0x2F15
HIL_SET_WATCHDOG_TIME_REQ/CNF 0x2F04,
0x2F05
This packet can be used be to individually set the application watchdog ‘Parameter ulWdgTime’. This
value is the same that has been set with service ‘OMB_IF_SET_CONFIGURATION_REQ/CNF – Set
configuration’.
HIL_GET_WATCHDOG_TIME_REQ/CNF 0x2F02,
0x2F03
This packet can be used to read back the currently configured application watchdog value described in
‘Parameter ulWdgTime’. This value is the same that has been set with service
‘OMB_IF_SET_CONFIGURATION_REQ/CNF – Set configuration’.

Open Modbus/TCP V3 | Protocol API

Common packet Command

HIL_GET_DPM_IO_INFO_REQ/CNF 0x2F0C,
0x2F0D
This packet is used to obtain information about the currently used number of input and output bytes in
the dual-port memory. The number of inputs and outputs depends on the configuration. This information
can be used by the host application for an optimized IO exchange to copy only the amount of configured
IO bytes.
HIL_FIRMWARE_IDENTIFY_REQ/CNF 0x1EB6,
0x1EB7
This packet is used to obtain the version of the Open Modbus/TCP stack.
DIAG_INFO_GET_COMMON_STATE_REQ 0x2F00,
0x2F01
This packet is used to read out the common diagnostic information.
Table 17: Common rcX packets

Open Modbus/TCP V3 | Protocol API

4.3 IO mode: Server Modbus data model

The stack handles 5760 bytes for input data and 5760 bytes for output data in the dual-port memory.
To exchange data between the device and the application, the application program can use the
device driver to read and write the input and output memory. The input and output data images can
be found at:
Input and Output Data Images

Offset Type Name Description

0x1000 uint8_t abPd0Output[5760] Output Data Image
Data To The Network
0x2680 uint8_t abPd0Input[5760] Input Data Image
Data From The Network
Table 18: Input and Output Data Images

The registers and the coils are located within the same memory. Thus, either a word manner or bit
manner access to actually the same data can be selected!

Reading and writing data

Open Modbus/TCP devices can write and read back data in the input data image
abPd0Input[5760] and read data from the output data image abPd0Output[5760] via the
TCP/IP network.
The host applications can write data in the output data image abPd0Output[5760] and read data
from the input data image abPd0Input[5760] via the dual-port memory.

Open Modbus/TCP V3 | Protocol API

Figure 6: Addressing model of Open Modbus/TCP in IO mode (default mapping)

If an Open Modbus/TCP device writes data to one register with function code 6 or function code 16,
another Open Modbus/TCP device is able to read back these data accordingly by using function
codes 1 or 3.

Open Modbus/TCP V3 | Protocol API

DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
The application interface 36/104
Figure 7 shows the alternative mapping which means that function code 1, 3 and 23 read data from
the output area. This mapping is needed for clients that do not support function code 2 and function
code 4 and allows these clients to use function code 1, 3 or 23 to read data from the output area.

Figure 7: Addressing model of Open Modbus/TCP in IO mode (alternative mapping)

To activate the alternative mapping, flag OMB_IF_CFG_FLAG_FC1_FC3_OUTPUT of parameter

ulFlags has to be set.

Open Modbus/TCP V3 | Protocol API

4.4 Message mode: Server with packets

4.4.1 Overview
In Message mode, the Open Modbus/TCP stack can run as Modbus/TCP server. In this case, all
incoming Modbus/TCP requests (function codes) from a remote client are forwarded to the host
application. All requests are forwarded with the packet OMB_IF_RECEIVE_IND/RES – Receive data
indication. This mode is the preferred way to implement a fully user specific Modbus Data model. It
is in scope of the user application to decide, which function codes are supported. Also it is in scope
of the user application, which register and coils are supported. The entire Modbus address range is
available in this mode.

Figure 8: Sequence diagram OMB_IF_RECEIVE_IND

To operate in this mode, three preconditions have to be fulfilled

 The Open Modbus/TCP stack must be configured in Message mode (ulMode = 0)
 The Open Modbus/TCP stack must have configured some server ports (e.g.
‘ulOpenServerSockets’ = 4)
 The host application must be registered with the packet
HIL_REGISTER_APP_REQ_REQ/CNF in order to receive the indication packet.

Open Modbus/TCP V3 | Protocol API

DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
The application interface 38/104
4.4.2 OMB_IF_RECEIVE_IND/RES – Receive data indication
This indication occurs, if a request from a remote client is received. Thus the host application has to
act as a server by answering these requests with response packets OMB_IF_RECEIVE_RES. The
action to take on reception of OMB_IF_RECEIVE_IND depends on the function code transmitted
along with the indication.
The variables of the request and the confirmation packet have the following meaning:
 Variable ulRouting contains the IP address of the client from which the request has been
received or to which the response has to be sent.
 Variable ulUnitId contains the unit identifier, i.e. the identification of a remote slave
connected on a serial line or on other buses. This variable is initialized by the client. Do not
change this value for the response.
 The variable ulFunctionCode contains the function code that has been requested by the
communication client. Possible function codes are FC1, FC2, FC3, FC4, FC5, FC6, FC7,
FC15, FC16 and FC23
 The variable ulException contains zero for the indication. The host application can generate
an exception in the response packet. The exact behavior of exception generation is the
following:
 If the host application sets ulSta unequal to TLR_S_OK, the stack generates the
exception GATEWAY TARGET DEVICE FAILED TO RESPOND (0x0B)
 If the host application sends a wrong response (e.g. a wrong packet length ulLen), the
stack generates also the exception GATEWAY TARGET DEVICE FAILED TO
RESPOND (0x0B)
 If the host application sets ulSta equal to TLR_S_OK and ulFunctionCode greater
than 0x7F (this means, the host application adds 0x80 to the function code to generate
an exception), the stack generates the exception from variable ulException.
 The union variable unData contains various detail information.
The contents of unData is
/*! Maximum user data in bytes (equal to 125 registers or 2000 coils). */
#define OMB_IF_MAX_DATA_BYTESIZE 250

union
{
struct
{
unit32_t ulDataAdr; /* Starting address */
unit32_t ulDataCnt; /* Register- or Bit-Count */

unit8_t abData[OMB_IF_MAX_DATA_BYTESIZE];
} tFcStd; /* Union for FCs 1-6, 15-16 */

} unData; /* Data part of PDU */

Open Modbus/TCP V3 | Protocol API

 Variable ulDataAdr contains the register- or bit-offset depending on the requested function
code, always beginning at offset zero.
 Variable ulDataCnt contains the register- or bit-count depending on the requested function
code.
 The field abData[OMB_MAX_DATA_CNT] contains the user data to be transferred. The field
can contain up to 250 bytes of usable data. This is equivalent to:
 125 16-bit-registers.
 2000 coils
stored at the same location.
 For FC7 ulDataAdr bytes ulDataCnt is unused

Union tFc23 for function code 23

 Variable ulDataAdrRead contains the read register offset, always beginning at offset zero.
 Variable ulDataCntRead contains the read register count.
 Variable ulDataAdrWrite contains the write register offset, always beginning at offset zero.
 Variable ulDataCntWrite contains the write register count.
 The field abData[OMB_MAX_DATA_CNT] contains the user data to be transferred. The field
can contain up to 250 bytes of user data. These are:
 up to 121 16-bit registers for the write part (indication packet)
 up to 125 16-bit registers for the read part (response packet).

Open Modbus/TCP V3 | Protocol API

DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
The application interface 40/104
Packet structure reference
#define OMB_MAX_DATA_CNT 250 /* Maximum user data count in bytes */
/* (125 registers or 2000 coils) */

typedef struct OMB_IF_MODBUS_DATA_Ttag

{
unit32_t ulRouting; /* IP address */
unit32_t ulUnitId; /* Unit identifier */

unit32_t ulFunctionCode; /* Function code (FC) */

unit32_t ulException; /* Exception code */

union
{
struct
{
unit32_t ulDataAdr; /* Starting address */
unit32_t ulDataCnt; /* Register- or Bit-Count */

unit8_t abData[OMB_MAX_DATA_CNT];
} tFcStd; /* Union for FCs 1-6, 15-16 */

} unData; /* Data part of PDU */

} OMB_IF_MODBUS_DATA_T;

typedef struct OMB_IF_RECEIVE_IND_Ttag

{
HIL_PACKET_HEADER_T tHead;
OMB_IF_MODBUS_DATA_T tData;

} OMB_IF_RECEIVE_IND_T;

Open Modbus/TCP V3 | Protocol API

Variable Type Value / Range Description

ulLen uint32_t Packet Data Length in bytes (header excluded, variable length
depending on the transmitted data)
24+n (FC1 … 6, OMB_IF_RECEIVE_IND_FC_STD_DATA_SIZE + n
15, 16) OMB_IF_RECEIVE_IND_FC23_DATA_SIZE + n
32+n (FC23) n is the application data count of abData[250] in bytes
24 (FC7) n = 0 ... OMB_MAX_DATA_CNT (250)*
* The maximum value depends on Function code, see also Table 20:
OMB_IF_RECEIVE_IND - Packet length for length calculation
ulSta uint32_t 0 See section Status/Error codes AP task
ulCmd uint32_t 0x3F06 OMB_IF_RECEIVE_IND - Command

Structure OMB_IF_MODBUS_DATA_T
ulRouting uint32_t IP address of remote station (Modbus client)
ulUnitId uint32_t 0 … 255 Unit identifier
ulFunctionCode uint32_t 1…6,7, 15, 16, Function code
23
ulException uint32_t 0 Exception code
unData union Contains various data, see above
Table 19: OMB_IF_RECEIVE_IND – Receive Data Indication

Packet length ulLen

Function code Packet length ulLen

FC1 OMB_IF_RECEIVE_IND_FC_STD_DATA_SIZE
FC2 OMB_IF_RECEIVE_IND_FC_STD_DATA_SIZE
FC3 OMB_IF_RECEIVE_IND_FC_STD_DATA_SIZE
FC4 OMB_IF_RECEIVE_IND_FC_STD_DATA_SIZE
FC5 OMB_IF_RECEIVE_IND_FC_STD_DATA_SIZE +
OMB_IF_FC5_DATA_LEN
FC6 OMB_IF_RECEIVE_IND_FC_STD_DATA_SIZE +
OMB_IF_FC6_DATA_LEN
FC7 OMB_IF_RECEIVE_IND_FC_STD_DATA_SIZE
FC15 OMB_IF_RECEIVE_IND_FC_STD_DATA_SIZE +
OMB_BYTES_OF_COIL( unData.tFcStd.ulDataCnt )
FC16 OMB_IF_RECEIVE_IND_FC_STD_DATA_SIZE +
OMB_BYTES_OF_REG(unData.tFcStd.ulDataCnt )
FC23 OMB_IF_RECEIVE_IND_FC23_DATA_SIZE +
OMB_BYTES_OF_REG( unData.tFc23.ulDataCntWrite )
Table 20: OMB_IF_RECEIVE_IND - Packet length

Open Modbus/TCP V3 | Protocol API

DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
The application interface 42/104
Packet structure reference
#define OMB_IF_MAX_DATA_BYTESIZE 250 /* Maximum user data count in bytes */
/* (125 registers or 2000 coils) */

typedef struct OMB_IF_MODBUS_DATA_Ttag

{
unit32_t ulRouting; /* IP address */
unit32_t ulUnitId; /* Unit identifier */

unit32_t ulFunctionCode; /* Function code (FC) */

unit32_t ulException; /* Exception code */

union
{
struct
{
unit32_t ulDataAdr; /* Starting address */
unit32_t ulDataCnt; /* Register- or Bit-Count */

unit8_t abData[OMB_IF_MAX_DATA_BYTESIZE];
} tFcStd; /* Union for FCs 1-6, 15-16 */

} unData; /* Data part of PDU */

} OMB_IF_MODBUS_DATA_T;

typedef struct OMB_IF_RECEIVE_RES_Ttag

{
HIL_PACKET_HEADER_T tHead;
OMB_IF_MODBUS_DATA_T tData;

} OMB_IF_AP_RECEIVE_RES_T;

Open Modbus/TCP V3 | Protocol API

Variable Type Value / Range Description

ulDest uint32_t Destination: use value from Indication
ulLen uint32_t Packet Data Length in bytes (header excluded, variable depending on
the transmitted data)
24+n (FC1 … 6, OMB_IF_RECEIVE_RSP_FC_STD_DATA_SIZE + n
7 15, 16) OMB_IF_RECEIVE_RSP_FC23_DATA_SIZE + n
32+n (FC23) n is the application data count of abData[250] in bytes
24+1 (FC7) n = 0 ... OMB_MAX_DATA_CNT (250)*
* The maximum value depends on the function code, see also Table
22: OMB_IF_RECEIVE_RES - Packet length
ulSta uint32_t See section Status/Error codes AP task
ulCmd uint32_t 0x3F07 OMB_IF_RECEIVE_RES - Command

Structure OMB_IF_MODBUS_DATA_T
ulRouting uint32_t IP address of remote station (Modbus client), unchanged
ulUnitId uint32_t 0 … 255 Unit identifier, unchanged
ulFunctionCode uint32_t 1…6, 7, 15, 16, Function code, unchanged or 0x80 added to generate an exception -
23 see variable ulException in this chapter
(if so, + 0x80)
ulException uint32_t Exception code - see variable ulException in this chapter
unData union Contains various data, see above
Table 21: OMB_IF_RECEIVE_RES– Receive Data Response

Packet length ulLen

Function code Packet length ulLen

FC1 OMB_IF_RECEIVE_RSP_FC_STD_DATA_SIZE +
OMB_BYTES_OF_COIL( unData.tFcStd.ulDataCnt )
FC2 OMB_IF_RECEIVE_RSP_FC_STD_DATA_SIZE +
OMB_BYTES_OF_COIL( unData.tFcStd.ulDataCnt )
FC3 OMB_IF_RECEIVE_RSP_FC_STD_DATA_SIZE +
OMB_BYTES_OF_REG(unData.tFcStd.ulDataCnt )
FC4 OMB_IF_RECEIVE_RSP_FC_STD_DATA_SIZE +
OMB_BYTES_OF_REG(unData.tFcStd.ulDataCnt )
FC5 OMB_IF_RECEIVE_RSP_FC_STD_DATA_SIZE +
OMB_IF_FC5_DATA_LEN
FC6 OMB_IF_RECEIVE_RSP_FC_STD_DATA_SIZE +
OMB_IF_FC6_DATA_LEN
FC7 OMB_IF_RECEIVE_RSP_FC_STD_DATA_SIZE +
OMB_IF_FC7_DATA_LEN
FC15 OMB_IF_RECEIVE_RSP_FC_STD_DATA_SIZE
FC16 OMB_IF_RECEIVE_RSP_FC_STD_DATA_SIZE
FC23 OMB_IF_RECEIVE_RSP_FC23_DATA_SIZE +
OMB_BYTES_OF_REG( unData.tFc23.ulDataCntRead )
Table 22: OMB_IF_RECEIVE_RES - Packet length

Open Modbus/TCP V3 | Protocol API

If the remote station 192.168.10.16 (Client) wants to write one register to our station (FC 6, data
offset = 10, Value = 255), the Open Modbus/TCP stack generates the following indication packet to
the host application. The host application should poll/receive this packet via the driver function
xSysdeviceGetPacket()

Variable Value
ulDest 0
ulSrc Queue handle of OMB task, does not matter in this context
ulDestId Handle from Register AP's ulSrcId (command
OMB_IF_REGISTER_AP_REQ)
ulSrcId Socket number ulSocketNumber of the receiving OMB socket (the allowed range for
socket numbers extends from 0 to 15).
ulLen 26 (24 + 2)
ulId Is generated automatically
ulSta 0
ulCmd 0x3F06 (OMB_IF_RECEIVE_IND)
ulExt Do not change
ulRout Do not change
ulRouting 192.168.10.16 (equivalent to 0xC0A80A10)
ulUnitId Value from client (Node), typically 0
ulFunctionCode 6 (Function code for “Write single register”)
ulException 0
ulDataAdr 10 (“Offset 10”)
ulDataCnt 1 (“1 Register”)
abData[0] 0 (No swap)
abData[1] 255 (No swap)
Table 23: Example: Writing Data via FC6 - Indication

Open Modbus/TCP V3 | Protocol API

DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
The application interface 45/104
The host application responds to the indication packet via the driver function
xSysdevicePutPacket() could for instance should look like:

Variable Value
ulDest Do not change
ulSrc Queue handle of OMB task, does not matter in this context, do not touch
ulDestId Handle from Register AP's ulSrcId (command
OMB_IF_REGISTER_AP_REQ) , do not touch
ulSrcId Socket number ulSocketNumber of the receiving OMB socket. , do not touch
ulLen 26 (24 + 2)
ulSta 0 (if successful, otherwise TLR_E_FAIL)
ulCmd 0x3F07 (OMB_IF_RECEIVE_RES)
ulExt Do not change
ulRout Do not change
ulRouting 192.168.10.16, do not change
ulUnitId Do not change
ulFunctionCode 6 (Function code “Write single register”), do not change in case of error free response
ulDataAdr 10 (“Offset 10”), do not change
ulDataCnt 1 (“1 Register”) , do not change
abData[0] 0 (No swap), do not change
abData[1] 255 (No swap), do not change
Table 24: Example: Writing Data via FC6 – Response

Open Modbus/TCP V3 | Protocol API

4.4.3 OMB_IF_CONNECTION_IND/RES – Connection indication

This indication occurs, whenever a server connection to the stack has been opened or closed. This
indication can be used by the host application to implement an access regulation. E.g., the first
incoming connection is the connection, which is allowed to execute read write operations. The
second incoming connection may be restricted to read operations only.

Note: To receive the OMB_IF_CONNECTION_IND packet the host application must be

registered with HIL_REGISTER_APPLICATION_REQ AND it must be enabled explicitly
in the SET_CONFIGURATION_PACKET with flag:
‚OMB_IF_CFG_FLAG_SERVER_CONNECTION_IND_FORWARDING’.

Figure 9: Sequence diagram OMB_IF_CONNECTION_IND

Packet structure reference

/*! Connect Indication / Response. */
enum OMB_IF_CONNECTION_STATE_Etag
{
OMB_IF_CONNECTION_STATE_DISCONNECTED = 0, /*!< An existing client connection is
terminated. */
OMB_IF_CONNECTION_STATE_CONNECTED = 1, /*!< A new client connection is
established. */
};

/! Connection Indication Data /

typedef struct OMB_IF_CONNECTION_IND_DATA_Ttag
{
uint32_t ulConnectionId; /*!< Unique Connection identifier */
uint8_t bStatus; /*!< Connection status */
uint8_t bType; /*!< Connection type */
uint16_t usReserved; /*!< Reserved */
uint32_t ulIpAddress; /*!< Client IP Address */
} __OMB_IF_CONNECTION_IND_DATA_T;

/! Connection Indication Packet /

typedef struct OMB_IF_CONNECTION_IND_Ttag
{
HIL_PACKET_HEADER_T tHead;
OMB_IF_CONNECTION_IND_DATA_T tData;

} __OMB_IF_CONNECTION_IND_T;

Open Modbus/TCP V3 | Protocol API

Variable Type Value / Range Description

ulLen uint32_t Packet Data Length in bytes
12 OMB_IF_CONNECTION_IND_DATA_SIZE
ulSta uint32_t 0 Packet status, zero for indication
ulCmd uint32_t 0x3F1A OMB_IF_CONNECTION_IND - Command

Structure OMB_IF_CONNECTION_IND_DATA_T
ulConnectionId uint32_t 0 … 15 Connection Identifier (same as packet ulSrcId)
bState uint8_t 0, 1 Connection State:
Bit D0 := 0 -> Not Connected
Bit D0 := 1 -> Connected
Bit D1 … D7 := Reserved

#define
OMB_IF_CONNECTION_STATE_CONNECTED (0x01)
bType uint8_t 1 Connection Type:
1 := Server Connection
usReserved uint16_t 0 Reserved
ulIpAddress uint32_t n Client IpAddress that has been connected or disconnected
Table 25: OMB_IF_CONNECTION_IND – Connection Indication Packet

Open Modbus/TCP V3 | Protocol API

DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
The application interface 48/104
Packet structure reference
typedef struct OMB_IF_CONNECTION_RES_Ttag
{
HIL_PACKET_HEADER_T tHead;

} OMB_IF_CONNECTION_RES_T;

Packet description

Variable Type Value / Range Description

ulDest uint32_t Destination: use value from Indication
ulLen uint32_t 0 Packet Data Length in bytes (header excluded, variable depending on
the transmitted data)
ulSta uint32_t See section Status/Error codes AP task
ulCmd uint32_t 0x3F1B OMB_IF_CONNECTION_RES - Command
Table 26: OMB_IF_CONNECTION_RES – Connection Response Packet

Open Modbus/TCP V3 | Protocol API

4.5 Message mode: Client with packets

4.5.1 Overview
In Message mode, the Open Modbus/TCP stack can run as Modbus/TCP client. In this case, the
user application is the initiator of Open Modbus/TCP requests to any Modbus/TCP server. The user
application has to use the packet OMB_IF_SEND_REQ/CNF - Send data request and send it to the
Open Modbus/TCP stack.

Figure 10: Sequence diagram OMB_IF_SEND_REQ

This mode is the preferred way to implement a fully user specific Modbus/TCP Client data model. It
is in scope of the user application to decide which function codes are requested to which
Modbus/TCP server. The entire Modbus address range is available in this mode.
To operate in this mode, two preconditions need to be fulfilled
 The Open Modbus/TCP stack must be configured in Message mode (ulMode = 0)
 The Open Modbus/TCP stack must have configured some client ports (e.g.
‘ulOpenServerSockets’ = 4; /* 12 are left as client sockets*/)

Open Modbus/TCP V3 | Protocol API

DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
The application interface 50/104
4.5.2 OMB_IF_SEND_REQ/CNF - Send data request
This packet is used by the host application to send a request to a remote station via the Modbus
connection. Thus, the host application can act as an Open Modbus/TCP client, the remote station
acts as an Open Modbus/TCP server. The Modbus answer from the remote station causes a
confirmation packet OMB_IF_SEND_CNF to be sent. The action to take on reception of
OMB_IF_SEND_CNF depends on the function code transmitted along with the request.
The variables of the request and the confirmation packet have the following meaning:
 Variable ulRouting contains the IP-Address of Open Modbus/TCP device/application to
which the request has to be sent or from which the response comes from, accordingly.
 Variable ulUnitId contains the unit identifier, i.e. the identification of a remote slave
connected on a serial line or on other buses. This variable is initialized by the client.
 The variable ulFunctionCode contains the function code that the request sends to the
communication partner at the other end of the Open Modbus/TCP connection:
The following function codes defined by the Open Modbus/TCP specification are supported by
the send data request: FC1, FC2, FC3, FC4, FC5, FC6, FC7, FC15, FC16, FC23
Other values might be allowed in the specification, but will cause an error in ulSta of the
confirmation packet.
For more information about the function codes and their meaning and use, see section Modbus
function codes on page 13.
 The variable ulException contains zero for the request packet. The remote station (server)
can generate an exception in the Modbus response. In this case, the confirmation packet is:
 ulLen = OMB_IF_SEND_CNF_FC_STD_DATA_SIZE (FC1 … FC7, FC15, FC16) /
OMB_IF_SEND_CNF_FC23_DATA_SIZE (FC23)
 ulSta = TLR_E_OMB_IF_ERR_MODBUS
 ulFunctionCode is unchanged, means the one from request packet (no 0x80 added!)
 ulException = Exception code from remote station
 The union variable unData contains various detail information.
The contents of unData is
/*! Maximum user data in bytes (equal to 125 registers or 2000 coils). */
#define OMB_IF_MAX_DATA_BYTESIZE 250

union
{
struct
{
unit32_t ulDataAdr; /* Starting address */
unit32_t ulDataCnt; /* Register- or Bit-Count */

unit8_t abData[OMB_IF_MAX_DATA_BYTESIZE];
} tFcStd; /* Union for FCs 1-6, 15-16 */

Open Modbus/TCP V3 | Protocol API

DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
The application interface 51/104
} unData; /* Data part of PDU */

Union tFcStd for function codes 1-7, 15 and 16

 Variable ulDataAdr contains the register- or bit-offset depending on the function code,
always beginning at offset zero.
 Variable ulDataCnt contains the register- or bit-count depending on the function code.
 The field abData[OMB_MAX_DATA_CNT] contains the user data to be transferred. The field
can contain up to 250 bytes of usable data. This is equivalent to:
 125 16-bit-registers.
 2000 coils
stored at the same location.

Union tFc23 for function code 23

 Variable ulDataAdrRead contains the read register offset, always beginning at offset zero.
 Variable ulDataCntRead contains the read register count.
 Variable ulDataAdrWrite contains the write register offset, always beginning at offset zero.
 Variable ulDataCntWrite contains the write register count.
 The field abData[OMB_MAX_DATA_CNT] contains the user data to be transferred. The field
can contain up to 250 bytes of usable data. These are:
 up to 121 16-bit-registers for the write part (request packet)
 up to 125 16-bit-registers for the read part (confirmation packet).

Packet structure reference

/*! Maximum user data in bytes (equal to 125 registers or 2000 coils). */
#define OMB_IF_MAX_DATA_BYTESIZE 250

typedef struct OMB_IF_MODBUS_DATA_Ttag

{
unit32_t ulRouting; /* IP address */
unit32_t ulUnitId; /* Unit identifier */

unit32_t ulFunctionCode; /* Function code (FC) */

unit32_t ulException; /* Exception code */

union
{
struct
{
unit32_t ulDataAdr; /* Starting address */
unit32_t ulDataCnt; /* Register- or Bit-Count */

unit8_t abData[OMB_IF_MAX_DATA_BYTESIZE];
} tFcStd; /* Union for FCs 1-6, 15-16 */

struct
{
unit32_t ulDataAdrRead; /* Read Starting address */
unit32_t ulDataCntRead; /* Quantity to Read */
unit32_t ulDataAdrWrite; /* Write Starting address */
unit32_t ulDataCntWrite; /* Quantity to Write */
unit8_t abData[OMB_IF_MAX_DATA_BYTESIZE];
Open Modbus/TCP V3 | Protocol API
DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
The application interface 52/104
} tFc23; /* Union for FC 23 */

} unData; /* Data part of PDU */

} OMB_IF_MODBUS_DATA_T;

typedef struct OMB_IF_SEND_REQ_Ttag

{
HIL_PACKET_HEADER_T tHead;
OMB_IF_MODBUS_DATA_T tData;

} OMB_IF_SEND_REQ_T;

Packet description

Variable Type Value / Range Description

ulDest uint32_t 0x20/QUE_OM Destination Queue-Handle
BAPTASK (HIL_PACKET_DEST_DEFAULT_CHANNEL)
ulLen uint32_t Packet Data Length in bytes (header excluded, variable length
depending on the transmitted data)
24+n (FC1 … OMB_IF_SEND_REQ_FC_STD_DATA_SIZE + n
7, 15, 16) OMB_IF_SEND_REQ_FC23_DATA_SIZE + n
32+n (FC23) n is the Application data count of abData[250] in bytes
n = 0 ... OMB_MAX_DATA_CNT (250)*
* The maximum value depends on Function code, see also Table 28:
OMB_IF_SEND_REQ - Packet length for length calculation
ulSta uint32_t 0 Set to 0
ulCmd uint32_t 0x03F08 OMB_IF_SEND_REQ - Command
Data
ulRouting uint32_t IP address of remote station (Modbus server)
ulUnitId uint32_t 0 … 255 Unit identifier
ulFunctionCode uint32_t 1…7, 15, 16, Function code
23
ulException uint32_t 0 Exception code
unData union Contains various data, see above
Table 27: OMB_IF_SEND_REQ - Send Data Request

Open Modbus/TCP V3 | Protocol API

Function code Packet length ulLen

FC1 OMB_IF_SEND_REQ_FC_STD_DATA_SIZE
FC2 OMB_IF_SEND_REQ_FC_STD_DATA_SIZE
FC3 OMB_IF_SEND_REQ_FC_STD_DATA_SIZE
FC4 OMB_IF_SEND_REQ_FC_STD_DATA_SIZE
FC5 OMB_IF_SEND_REQ_FC_STD_DATA_SIZE +
OMB_FC5_PACKET_LEN
FC6 OMB_IF_SEND_REQ_FC_STD_DATA_SIZE +
OMB_FC6_PACKET_LEN
FC7 OMB_IF_SEND_REQ_FC_STD_DATA_SIZE
FC15 OMB_IF_SEND_REQ_FC_STD_DATA_SIZE +
OMB_BYTES_OF_COIL( unData.tFcStd.ulDataCnt )
FC16 OMB_IF_SEND_REQ_FC_STD_DATA_SIZE +
OMB_BYTES_OF_REG(unData.tFcStd.ulDataCnt )
FC23 OMB_IF_SEND_REQ_FC23_DATA_SIZE +
OMB_BYTES_OF_REG( unData.tFc23.ulDataCntWrite )
Table 28: OMB_IF_SEND_REQ - Packet length

Packet structure reference

/*! Maximum user data in bytes (equal to 125 registers or 2000 coils). */
#define OMB_IF_MAX_DATA_BYTESIZE 250

typedef struct OMB_IF_MODBUS_DATA_Ttag

{
unit32_t ulRouting; /* IP address */
unit32_t ulUnitId; /* Unit identifier */

unit32_t ulFunctionCode; /* Function code (FC) */

unit32_t ulException; /* Exception code */

union
{
struct
{
unit32_t ulDataAdr; /* Starting address */
unit32_t ulDataCnt; /* Register- or Bit-Count */

unit8_t abData[OMB_IF_MAX_DATA_BYTESIZE];
} tFcStd; /* Union for FCs 1-6, 15-16 */

} unData; /* Data part of PDU */

} OMB_IF_MODBUS_DATA_T;

typedef struct OMB_IF_SEND_CNF_Ttag

{
HIL_PACKET_HEADER_T tHead;
OMB_IF_MODBUS_DATA_T tData;

} OMB_IF_SEND_CNF_T;
Open Modbus/TCP V3 | Protocol API
DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
The application interface 54/104
Packet description

Variable Type Value / Description

Range
ulLen uint32_t Packet Data Length in bytes (header excluded, variable depending on the
transmitted data)
24+n (FC1 OMB_IF_SEND_CNF_FC_STD_DATA_SIZE+ n
… 7, 15, OMB_IF_SEND_CNF_FC23_DATA_SIZE + n
16)
n is the Application data count of abData[250] in bytes
32+n
(FC23) n = 0 ... OMB_MAX_DATA_CNT (250)*
* The maximum value depends on Function code, see also Table 30:
OMB_IF_SEND_CNF - Packet length
ulSta uint32_t See section Status/Error codes
ulCmd uint32_t 0x3F09 OMB_IF_SEND_CNF- Command

Structure OMB_IF_MODBUS_DATA_T
ulRouting uint32_t IP address of remote station (Modbus server), unchanged
ulUnitId uint32_t 0 … 247 Unit identifier, unchanged
ulFunctionCode uint32_t 1…7, 15, Function code, unchanged - see variable ulException in this chapter
16, 23
ulException uint32_t Exception code - see variable ulException in this chapter
unData union Contains various data, see above
Table 29: OMB_IF_SEND_CNF - Send Data Confirmation

Packet length ulLen

Function code Packet length ulLen

FC1 OMB_IF_SEND_CNF_FC_STD_DATA_SIZE +
OMB_BYTES_OF_COIL( unData.tFcStd.ulDataCnt )
FC2 OMB_IF_SEND_CNF_FC_STD_DATA_SIZE +
OMB_BYTES_OF_COIL( unData.tFcStd.ulDataCnt )
FC3 OMB_IF_SEND_CNF_FC_STD_DATA_SIZE +
OMB_BYTES_OF_REG(unData.tFcStd.ulDataCnt )
FC4 OMB_IF_SEND_CNF_FC_STD_DATA_SIZE +
OMB_BYTES_OF_REG(unData.tFcStd.ulDataCnt )
FC5 OMB_IF_SEND_CNF_FC_STD_DATA_SIZE
FC6 OMB_IF_SEND_CNF_FC_STD_DATA_SIZE
FC7 OMB_IF_SEND_CNF_FC_STD_DATA_SIZE + 1
FC15 OMB_IF_SEND_CNF_FC_STD_DATA_SIZE
FC16 OMB_IF_SEND_CNF_FC_STD_DATA_SIZE
FC23 OMB_IF_SEND_CNF_FC23_DATA_SIZE +
OMB_BYTES_OF_REG( unData.tFc23.ulDataCntRead )
Table 30: OMB_IF_SEND_CNF - Packet length

Open Modbus/TCP V3 | Protocol API

If the host application wants to read one holding register from remote station 192.168.10.16 (FC 3,
data offset = 10, Value = 255), the host application must send the following request packet to the
Open Modbus/TCP stack.
Variable Value
ulDest 0x20 (HIL_PACKET_DEST_DEFAULT_CHANNEL)
ulSrc 0
ulDestId 0
ulSrcId 0 (Source End Point Identifier - could be used from host
application as handle or so)
ulLen 24 (OMB_IF_SEND_REQ_FC_STD_DATA_SIZE)
ulId 0 (Packet identification - could be used from host application)
ulSta 0
ulCmd 0x 3F08 (OMB_IF_SEND_REQ)
ulExt 0 (Set to zero)
ulRout 0
ulRouting 192.168.10.16 (equivalent to 0xC0A80A10)
ulUnitId 0
ulFunctionCode 3 (Function code for “Read holding register”)
ulException 0
ulDataAdr 10 (“Offset 10”)
ulDataCnt 1 (“1 Register”)
Table 31: Example: Reading data via FC3 - Request

The confirmation of the remote station generates a confirmation packet to the host application. The
host application should poll/receive this packet via the driver function.
Variable Value
ulDest 0x20 (HIL_PACKET_DEST_DEFAULT_CHANNEL)
ulSrc 0
ulDestId 0
ulSrcId 0 (Source End Point Identifier - value from request packet)
ulLen 26 (OMB_IF_SEND_CNF_FC_STD_DATA_SIZE + 2)
ulId 0 (Packet identification - value from request packet)
ulSta 0 (Error free case)
ulCmd 0x 3F09 (OMB_IF_SEND_CNF)
ulExt
ulRout
ulRouting 192.168.10.16 (equivalent to 0xC0A80A10)
ulUnitId 0
ulFunctionCode 3 (Function code for “Read holding register”)
ulException 0
ulDataAdr 10 (“Offset 10”)
ulDataCnt 1 (“1 Register”)
abData[0] 0 (No swap)
abData[1] 255 (No swap)
Table 32: Example: Reading data via FC3 - Confirmation

Open Modbus/TCP V3 | Protocol API

4.6 Message mode: Client with command table

4.6.1 Overview
The CMD component is responsible for the execution of the command table. The command table is
a list of configured Open Modbus/TCP function codes, which are executed cyclically. When the
command table is configured, the Modbus/TCP stack operates as client. Depending on the function
code data are either read from a server or written to a remote server. The data that are read or
written to a server are exchanged via the Input and Output area of dual-port memory with the host
application.
The command table can be configured by:
 configuration data base created by Sycon.net
 configuration packets from the host application
The packet API of the CMD task is accessible via the AP – Task of the Open Modbus/TCP stack.
This means, if the host wants to use the configuration packets to configure its own command table,
the host has to send these to the AP – Task of the Open Modbus/TCP stack. The AP – Task will
route these packets then to the CMD – Task.
The following rules apply for creating a command list:
 At startup, the CMDTBL_INIT_REQ must be sent.
 For each server that should be requested from the command list a separate ‘TABLE’ must be
created.
 Each command within a one table must be directed to the same server.
 The default number of addressable remote servers is 12.
 The maximum number of addressable remote servers is 16. Therefore, the parameter
‘ulOpenServerSockets’ must be set 0 to allow the maximum available TCP/IP sockets to be
used as client connections.
 The maximum number of configurable commands over all tables is 256.
The following figure shows a command list with a set of commands, which are directed to 3 servers.
Therefore, the command list has to be created using 3 separate tables.

Figure 11: Example command table

Open Modbus/TCP V3 | Protocol API

DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
The application interface 57/104
The CMD – Task has specified following commands:
Command Value Description Section
CMDTBL_INIT_REQ/CNF 0x0000A300 / 4.6.2
0x0000A301
CMDTBL_ADD_TABLE_REQ/CNF 0x0000A302 / Create a new command table 4.6.3
0x0000A303
CMDTBL_DELETE_TABLE_REQ/CNF 0x0000A304 / Delete a command table 4.6.4
0x0000A305
CMDTBL_ACTIVATE_TABLE_REQ/CNF 0x0000A306 / Activate a command table 4.6.5
0x0000A307
CMDTBL_DEACTIVATE_TABLE_REQ/CNF 0x0000A308 / Deactivate a command table 4.6.6
0x0000A309
CMDTBL_ADD_COMMAND_REQ/CNF 0x0000A30A / Add a command to a table 4.6.7
0x0000A30B
CMDTBL_DELETE_COMMAND_REQ/CNF 0x0000A30C / Delete a command from a table 4.6.8
0x0000A30D
CMDTBL_ACTIVATE_COMMAND_REQ/CNF 0x0000A30E / Activate a command from a table 4.6.9
0x0000A30F
CMDTBL_DEACTIVATE_COMMAND_REQ/CN 0x0000A310 / Deactivate a command from a table 4.6.10
F 0x0000A311
CMDTBL_TRIGGER_COMMAND_REQ/CNF 0x0000A312 / Trigger a command 4.6.11
0x0000A313
CMDTBL_GET_IO_INFO_REQ/CNF 0x0000A314 / Get IO information 4.6.12
0x0000A315
CMDTBL_DEINIT_REQ/CNF 0x0000A316 / Deinit 4.6.13
0x0000A317
CMDTBL_START_STOP_REQ/CNF 0x0000A318 / Table Start/Stop 4.6.14
0x0000A319
Table 33: List of CMD task commands

Open Modbus/TCP V3 | Protocol API

DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
The application interface 58/104
4.6.2 CMDTBL_INIT_REQ/CNF – Init command table task
This command must be sent once at start-up to initialize and provide some basic configuration to the
CMD – Task.

Packet structure reference

typedef struct CMDTBL_INIT_DATA_REQ_Ttag
{
uint32_t ulProtocolType;
uint32_t ulDpmBitFieldOffset;
uint8_t abReserved[16];
} CMDTBL_INIT_DATA_REQ_T;

typedef struct CMDTBL_INIT_REQ_Ttag

{
HIL_PACKET_HEADER_T tHead;
CMDTBL_INIT_DATA_REQ_T tData;
} CMDTBL_INIT_REQ_T;

Packet description

Variable Type Value / Description

Range
ulDest uint32_t 0x20 Destination
QUE_OMBAPTA
SK (HIL_PACKET_DEST_DEFAULT_CHANNEL)

ulLen uint32_t 24 Packet Data Length in bytes

sizeof(CMDTBL_INIT_DATA_REQ_T)
ulSta uint32_t 0 Set to zero
ulCmd uint32_t 0xA300 CMDTBL_INIT_REQ - Command

Structure CMDTBL_INIT_DATA_REQ_T
ulProtocolType uint32_t 0x12 The command table should run as Open Modbus/TCP command table
CMDTBL_PROTOCOL_TYPE_MODBUS_TCP
ulDpmBitFieldOff uint32_t 0 … 5679 Start offset of the diagnostic bitfield in the dual-port memory input
set image. The default position should be dword aligned after the last
input byte in the input image
abReserved[] Uint8_t[16] Reserved array, set to 0
Table 34: CMDTBL_INIT_REQ_T packet

Packet structure reference

typedef struct CMDTBL_INIT_CNF_Ttag
{
HIL_PACKET_HEADER_T tHead;
} CMDTBL_INIT_CNF_T;

Packet description

Variable Type Value / Range Description

ulLen uint32_t 0 Packet Data Length in bytes
ulSta uint32_t x See section Status/Error codes
ulCmd uint32_t 0xA301 CMDTBL_INIT_CNF - Command
Table 35: CMDTBL_INIT_CNF_T packet

Open Modbus/TCP V3 | Protocol API

4.6.3 CMDTBL_ADD_TABLE_REQ/CNF – Add new command table

This packet can be used to add a new command table for processing. To do so, you have to supply
the following time values:
 The cycle time (Variable ulCycleTime)
 The inter command delay time (Variable ulInterCommandDelay)
 The inter scan delay time (Variable ulInterScanDelay)
These time values have to be specified in units of milliseconds.
Furthermore, you can specify whether the table is activated or deactivated (disabled) at the start.
This is done using flag variable ulFlags. If you specify a table as deactivated here, you can activate
it later using the packet CMDTBL_ACTIVATE_TABLE_REQ/CNF – Activate a command table
packet.
The confirmation packet returns a table identifier to be stored for future use as reference to the newly
defined command table.

Packet structure reference

typedef struct CMDTBL_TABLE_Ttag
{
uint32_t ulProtocolType;
uint32_t ulCycleTime;
uint32_t ulInterCommandDelay;
uint32_t ulInterScanDelay;
uint32_t ulFlags;
uint8_t abReserved[16];
} CMDTBL_TABLE_T;

typedef CMDTBL_TABLE_T CMDTBL_ADD_TABLE_DATA_REQ_T;

typedef struct CMDTBL_ADD_TABLE_REQ_Ttag

{
HIL_PACKET_HEADER_T tHead;
CMDTBL_ADD_TABLE_DATA_REQ_T tData;
}
CMDTBL_ADD_TABLE_REQ_T;

Open Modbus/TCP V3 | Protocol API

Variable Type Value / Range Description

ulDest uint32_t 0x20 Destination (HIL_PACKET_DEST_DEFAULT_CHANNEL)
QUE_OMBAPTASK
ulLen uint32_t 36 Packet Data Length in bytes
sizeof(CMDTBL_ADD_TABLE_DATA_REQ_T)
ulSta uint32_t 0 Set to zero
ulCmd uint32_t 0xA302 CMDTBL_ADD_TABLE_REQ - Command

Structure CMDTBL_ADD_TABLE_DATA_REQ_T
ulProtocolType uint32_t 0x12 The command table should run as an Open Modbus/TCP command
table
CMDTBL_PROTOCOL_TYPE_MODBUS_TCP
ulCycleTime uint32_t 0 .. 60.000 Cycle time, in that all commands of this of this shell be executed once.
[ms] The cycle time is given in ms.
Note: If the execution of all commands within the command table takes
longer than this time, the cycle time cannot be respected and the cycle
time will be increased. If the execution of all commands within a
command table takes less than this time, the next execution of the
command table will be started when this time has expired.
The default value is 0 which means the table is executed is fast as
possible. When the last command is finished immediately with the first
command will be started again.
ulInterCommand uint32_t 0 .. 60.000 This delay time specifies a fixed time that is inserted between two
Delay commands of command table. It can be used to delay the execution of
[ms] commands e.g. for a non-performant server that needs a pause on
each request. This time is valid for all commands within one table.
The default value is 0. This means no delay is inserted between each
command.
ulInterScanDelay uint32_t 0 .. 60.000 This delay time can be used to insert a fixed delay time when the last
[ms] command of a table was executed before starting over with the first
command of the table.
The default value is 0. This means no delay time is inserted.
ulFlags uint32_t 0…1 Configuration flag field: Per default all flags are 0
Bit D0 : Table disable bit
If this bit is set, the table (all commands within the table) is excluded
from the execution when the command table is started. The table can
be activated later on explicitly at run time with the
CMDTBL_ACTIVATE_TABLE_REQ Request.
abReserved[16] uint8_t [] 0 Reserved array set to 0
Table 36: CMDTBL_ADD_TABLE_REQ_T packet

Open Modbus/TCP V3 | Protocol API

DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
The application interface 61/104
Packet structure reference
typedef struct CMDTBL_ADD_TABLE_DATA_CNF_Ttag
{
uint32_t ulTableId;
}
CMDTBL_ADD_TABLE_DATA_CNF_T;

typedef struct CMDTBL_ADD_TABLE_CNF_Ttag

{
HIL_PACKET_HEADER_T tHead;
CMDTBL_ADD_TABLE_DATA_CNF_T tData;
}
CMDTBL_ADD_TABLE_CNF_T;

Packet description

Variable Type Value / Range Description

ulLen uint32_t 4 Packet Data Length in bytes
sizeof(CMDTBL_ADD_TABLE_DATA_CNF_T)
ulSta uint32_t x See section Status/Error codes
ulCmd uint32_t 0xA303 CMDTBL_INIT_CNF - Command

Structure CMDTBL_ADD_TABLE_DATA_CNF_T
ulTableId uint32_t n This is the returned table identifier. The host application has to store
this identifier in order to use it later as table reference with other
commands like add a command or activate a table etc.
Table 37: CMDTBL_ADD_TABLE_CNF_T packet

Open Modbus/TCP V3 | Protocol API

DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
The application interface 62/104
4.6.4 CMDTBL_DELETE_TABLE_REQ/CNF – Delete a command table
This packet can be used to delete a command table. The table ID identifying the table to be deleted
has to be specified in variable ulTableId. It is also returned with the confirmation packet.

Packet structure reference

/*******************************************************************
* Delete Table
*******************************************************************/
typedef struct CMDTBL_DELETE_TABLE_DATA_REQ_Ttag
{
uint32_t ulTableId;
}
CMDTBL_DELETE_TABLE_DATA_REQ_T;

typedef struct CMDTBL_DELETE_TABLE_REQ_Ttag

{
HIL_PACKET_HEADER_T tHead;
CMDTBL_DELETE_TABLE_DATA_REQ_T tData;
}
CMDTBL_DELETE_TABLE_REQ_T;

Packet description

Variable Type Value / Range Description

ulDest uint32_t 0x20 Destination (HIL_PACKET_DEST_DEFAULT_CHANNEL)
QUE_OMBAPTASK
ulLen uint32_t 4 Packet Data Length in bytes
sizeof(CMDTBL_DELETE_TABLE_DATA_REQ_T)
ulSta uint32_t 0 Set to zero
ulCmd uint32_t 0xA304 CMDTBL_DELETE_TABLE_DATA_REQ_T - Command

Structure CMDTBL_DELETE_TABLE_DATA_REQ_T
ulTableId uint32_t n ID of the command table that should be deleted.
Table 38: CMDTBL_DELETE_TABLE_REQ_T packet

Open Modbus/TCP V3 | Protocol API

DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
The application interface 63/104
Packet structure reference
/*******************************************************************
* Delete Table
*******************************************************************/
typedef struct CMDTBL_DELETE_TABLE_DATA_REQ_Ttag
{
uint32_t ulTableId;
}
CMDTBL_DELETE_TABLE_DATA_REQ_T;

typedef CMDTBL_DELETE_TABLE_DATA_REQ_T CMDTBL_DELETE_TABLE_DATA_CNF_T;

typedef struct CMDTBL_DELETE_TABLE_CNF_Ttag

{
HIL_PACKET_HEADER_T tHead;
CMDTBL_DELETE_TABLE_DATA_CNF_T tData;
}
CMDTBL_DELETE_TABLE_CNF_T;

Packet description

Variable Type Value / Range Description

ulLen uint32_t 4 Packet Data Length in bytes
sizeof(CMDTBL_DELETE_TABLE_DATA_CNF_T)
ulSta uint32_t x See section Status/Error codes CMD task

ulCmd uint32_t 0xA305 CMDTBL_DELETE_TABLE_CNF - Command

Structure CMDTBL_DELETE_TABLE_DATA_CNF_T
ulTableId uint32_t n Table identifier of the deleted table.
Table 39: CMDTBL_DELETE_TABLE_CNF_T packet

Open Modbus/TCP V3 | Protocol API

4.6.5 CMDTBL_ACTIVATE_TABLE_REQ/CNF – Activate a command

table
This packet can be used to activate either all tables at once or a specific (formerly deactivated)
command table identified by its table ID (Variable ulTableId). Within this context, activating means
including in cyclical processing from now on.
A command table may be deactivated in the following two cases:
 It has been defined as deactivated by setting the table disable bit D0 within variable ulFlags
to 1 during CMDTBL_ADD_TABLE_REQ/CNF – Add new command table, see page 59.
59B

 A CMDTBL_DEACTIVATE_TABLE_REQ/CNF – Deactivate a command table request packet

has already been sent.

Packet structure reference

/*******************************************************************
* Activate Table
*******************************************************************/
typedef struct CMDTBL_ACTIVATE_TABLE_DATA_REQ_Ttag
{
uint32_t ulTableId; /* Table ID returned by the CMDTBL_ADD_TABLE_CNF_T packet
or 0 for all tables created into the database */
}
CMDTBL_ACTIVATE_TABLE_DATA_REQ_T;

typedef struct CMDTBL_ACTIVATE_TABLE_REQ_Ttag

{
HIL_PACKET_HEADER_T tHead;
CMDTBL_ACTIVATE_TABLE_DATA_REQ_T tData;
}
CMDTBL_ACTIVATE_TABLE_REQ_T;

Packet description

Variable Type Value / Range Description

ulDest uint32_t 0x20 Destination (HIL_PACKET_DEST_DEFAULT_CHANNEL)
QUE_OMBAPTASK
ulLen uint32_t 4 Packet Data Length in bytes
sizeof(CMDTBL_ACTIVATE_TABLE_DATA_REQ_T)
ulSta uint32_t 0 Set to zero
ulCmd uint32_t 0xA306 CMDTBL_ACTIVATE_TABLE_REQ - Command

Structure CMDTBL_ACTIVATE_TABLE_DATA_REQ_T
ulTableId uint32_t n Command table that should be activated.
Use 0 to activate all tables at once that are created.
Use table ID returned by the CMDTBL_ADD_TABLE_CNF_T packet
to active a particular table.
Table 40: CMDTBL_ACTIVATE_TABLE_REQ_T packet

Open Modbus/TCP V3 | Protocol API

DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
The application interface 65/104
Packet structure reference
/*******************************************************************
* Activate Table
*******************************************************************/
typedef struct CMDTBL_ACTIVATE_TABLE_DATA_REQ_Ttag
{
uint32_t ulTableId; /* Table ID returned by the CMDTBL_ADD_TABLE_CNF_T packet
or 0 for all tables created into the database */
}
CMDTBL_ACTIVATE_TABLE_DATA_REQ_T;

typedef CMDTBL_ACTIVATE_TABLE_DATA_REQ_T CMDTBL_ACTIVATE_TABLE_DATA_CNF_T;

typedef struct CMDTBL_ACTIVATE_TABLE_CNF_Ttag

{
HIL_PACKET_HEADER_T tHead;
CMDTBL_ACTIVATE_TABLE_DATA_CNF_T tData;
}
CMDTBL_ACTIVATE_TABLE_CNF_T;

Packet description

Variable Type Value / Range Description

ulLen uint32_t 4 Packet Data Length in bytes
sizeof(CMDTBL_ACTIVATE_TABLE_DATA_CNF_T)
ulSta uint32_t x See section Status/Error codes
ulCmd uint32_t 0xA307 CMDTBL_ACTIVATE_TABLE_CNF - Command

Structure CMDTBL_ACTIVATE_TABLE_DATA_CNF_T
ulTableId uint32_t n Table identifier of the activated table.
Table 41: CMDTBL_ACTIVATE_TABLE_CNF_T packet

Open Modbus/TCP V3 | Protocol API

DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
The application interface 66/104
4.6.6 CMDTBL_DEACTIVATE_TABLE_REQ/CNF – Deactivate a
command table
This packet can be used to deactivate either all command tables at once or a specific (formerly
activated) command table identified by its table ID (Variable ulTableId). Within this context,
deactivating means immediately removing from cyclical processing.

Packet structure reference

typedef struct CMDTBL_DEACTIVATE_TABLE_DATA_REQ_Ttag
{
uint32_t ulTableId; /* Table ID returned by the CMDTBL_ADD_TABLE_CNF_T packet
or 0 for all tables created into the database */
}
CMDTBL_DEACTIVATE_TABLE_DATA_REQ_T;

typedef struct CMDTBL_DEACTIVATE_TABLE_REQ_Ttag

{
HIL_PACKET_HEADER_T tHead;
CMDTBL_DEACTIVATE_TABLE_DATA_REQ_T tData;
}
CMDTBL_DEACTIVATE_TABLE_REQ_T;

Packet description
Variable Type Value / Range Description
ulDest uint32_t 0x20 Destination (HIL_PACKET_DEST_DEFAULT_CHANNEL)
QUE_OMBAPTASK
ulLen uint32_t 4 Packet Data Length in bytes
sizeof(CMDTBL_DEACTIVATE_TABLE_DATA_REQ_T)
ulSta uint32_t 0 Set to zero
ulCmd uint32_t 0xA308 CMDTBL_DEACTIVATE_TABLE_REQ - Command

Structure CMDTBL_DEACTIVATE_TABLE_DATA_REQ_T
ulTableId uint32_t n Command table that should be deactivated.
Use 0 to deactivate all tables at once that are created.
Use table ID returned by the CMDTBL_ADD_TABLE_CNF_T packet
to deactivate a particular table.
Table 42: CMDTBL_DEACTIVATE_TABLE_REQ_T packet

Open Modbus/TCP V3 | Protocol API

DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
The application interface 67/104
Packet structure reference
typedef struct CMDTBL_DEACTIVATE_TABLE_DATA_REQ_Ttag
{
uint32_t ulTableId; /* Table ID returned by the CMDTBL_ADD_TABLE_CNF_T packet
or 0 for all tables created into the database */
}
CMDTBL_DEACTIVATE_TABLE_DATA_REQ_T;

typedef CMDTBL_DEACTIVATE_TABLE_DATA_REQ_T CMDTBL_DEACTIVATE_TABLE_DATA_CNF_T;

typedef struct CMDTBL_DEACTIVATE_TABLE_CNF_Ttag

{
HIL_PACKET_HEADER_T tHead;
CMDTBL_DEACTIVATE_TABLE_DATA_CNF_T tData;
}
CMDTBL_DEACTIVATE_TABLE_CNF_T;

Packet description

Variable Type Value / Range Description

ulLen uint32_t 4 Packet Data Length in bytes
sizeof(CMDTBL_DEACTIVATE_TABLE_DATA_CNF_T)
ulSta uint32_t x See section Status/Error codes
ulCmd uint32_t 0xA309 CMDTBL_DEACTIVATE_TABLE_CNF - Command

Structure CMDTBL_DEACTIVATE_TABLE_DATA_CNF_T
ulTableId uint32_t n Table identifier of the deactivated table.
Table 43: CMDTBL_DEACTIVATE_TABLE_CNF_T packet

Open Modbus/TCP V3 | Protocol API

DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
The application interface 68/104
4.6.7 CMDTBL_ADD_COMMAND_REQ/CNF – Add a command to a
table
This packet can be used to add a new command to an existing command table.
To do so, you have to specify the table ID and a structure CMDTBL_COMMAND_T containing a number
of parameters explained below within the packet description.
The first three variables of the request and the confirmation packet are used to define which Modbus
function code will be executed where in the Open Modbus/TCP network:
 Variable ulDeviceAddr contains the IP-Address of the affected Open Modbus/TCP
device/application (remote server).
 Variable ulUnitId contains the unit identifier, i.e. the identification of a remote slave
connected on a serial line for subnetwork addressing.
 The variable ulFunctionCode contains the function code that the request sends to the
communication partner at the other end of the Open Modbus/TCP connection:
The following function codes defined by the Open Modbus/TCP specification are supported by
this packet:
Function code Modbus function
FC1 Read coils
FC2 Read input discretes
FC3 Read multiple registers
FC4 Read input registers
FC5 Write coil
FC6 Write single register
FC15 Force multiple coils
FC16 Write multiple registers
Table 44: Supported function codes in variable ulFunctionCode as defined by the Open Modbus/TCP
specification

For more information about the function codes and their meaning and use, see section Modbus
function codes.
Furthermore, you can specify whether the command is activated or deactivated (disabled) at the
start. This is done using flag variable ulFlags. If you specify a command as deactivated here, you
can activate it later using the CMDTBL_ACTIVATE_COMMAND_REQ/CNF – Activate a command
packet.
The confirmation packet returns a command identifier to be stored for future use as reference to the
newly defined command table.

Open Modbus/TCP V3 | Protocol API

DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
The application interface 69/104
Packet structure reference
typedef struct CMDTBL_COMMAND_Ttag
{
uint32_t ulDeviceAddr;
uint32_t ulUnitId;
uint32_t ulFunctionCode;
uint32_t ulRegisterWriteAddr;
uint32_t ulRegisterWriteCount;
uint32_t ulRegisterReadAddr;
uint32_t ulRegisterReadCount;
uint32_t ulDPMSrcOffset;
uint32_t ulDPMDstOffset;
uint32_t ulTriggerType;
uint32_t ulCyclePeriod;
uint32_t ulFlags;
uint8_t abReserved[16];
} CMDTBL_COMMAND_T;

typedef struct CMDTBL_ADD_COMMAND_DATA_REQ_Ttag

{
uint32_t ulTableId;
CMDTBL_COMMAND_T tCommand;
} CMDTBL_ADD_COMMAND_DATA_REQ_T;

Packet description

Variable Type Value / Range Description

ulDest uint32_t 0x20 Destination (HIL_PACKET_DEST_DEFAULT_CHANNEL)
QUE_OMBAPTASK
ulLen uint32_t 68 Packet Data Length in bytes
sizeof(CMDTBL_ADD_COMMAND_DATA_REQ_T)
ulSta uint32_t 0 Set to zero
ulCmd uint32_t 0xA30A CMDTBL_ADD_COMMAND_REQ - Command

Structure CMDTBL_ADD_COMMAND_DATA_REQ_T
ulTableId uint32_t n Id of the table where to add the command.
Use table ID returned by the CMDTBL_ADD_TABLE_CNF_T packet
to add a particular command.

Structure CMDTBL_COMMAND_T
ulDeviceAddr uint32_t n IP address of the requested remote server
e.g. 0x192.168.10.16 (= 0xC0A80A10)
ulUnitId uint32_t 0 … 255 Sub addressing with the requested remote server.
ulFunctionCode uint32_t 1, 2, 3, 4, 5, Requested function code
6, 15, 16
ulRegisterWriteA uint32_t 0 … 65535 Address within the requested server for writing function codes.
ddr
ulRegisterWriteC uint32_t 0…x Number of Register or Coils that shall be written to the server.
ount 0 – no data is written
ulRegisterReadA uint32_t 0 … 65535 Address within the requested server for reading function codes.
ddr
ulRegisterReadC uint32_t Number of Register or Coils that shall be read from the server.
ount 0 – no data is read.
ulDPMSrcOffset uint32_t Byte offset in dual-port memory “Output area” that holds the data
which shall be written to the server.

Note:
The commands must be added in ascending order in relation to their
offset. It is not possible to add a second command with a smaller
offset then the previous command.

Open Modbus/TCP V3 | Protocol API

Note:
The commands must be added in ascending order in relation to their
offset. It is not possible to add a second command with a smaller
offset then the previous command.
ulTriggerType uint32_t 0,1,2,3 Command Execution
0 := CMDTBL_TRIGGER_TYPE_CYCLIC
-> cyclically depending on a configured interval
1 := CMDTBL_TRIGGER_TYPE_ON_CHANGE
-> only in case of data change
2: = CMDTBL_TRIGGER_TYPE_ON_CHANGE_NON_ZERO
-> only in case of data change to a non-zero value
3 := CMDTBL_TRIGGER_TYPE_ON_REQUEST
-> triggered by external event
CMDTBL_TRIGGER_COMMAND_REQ (see page 78)
ulCyclePeriod uint32_t 0 … 60.000 Each command can be configured with an individual cycle time. This
[ms] time specifies the execution cycle of this command.
The default value is 0. This means that the command is executed
within the configured cycle time of the command table itself.
Note:
This cycle time can be configured only, when the cycle time
‘ulCycleTime ‘and the ‘ulInterScanDelay’ of the command table itself is
set to 0.
ulFlags uint32_t 0…1 Configuration flag field: By default, all flags are set to 0
Bit D0: Command disable bit
If this bit is set, the command is excluded from the execution when the
command table is started. The command can be activated later on
explicitly at run time with the CMDTBL_ACTIVATE_COMMAND_REQ
Request.
abReserved uint8_t [16] 0 Reserved field set to 0
Table 45: CMDTBL_ADD_COMMAND_REQ_T packet

Open Modbus/TCP V3 | Protocol API

DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
The application interface 71/104
Packet structure reference
typedef struct CMDTBL_ADD_COMMAND_DATA_CNF_Ttag
{
uint32_t ulCommandId;
} CMDTBL_ADD_COMMAND_DATA_CNF_T;

typedef struct CMDTBL_ADD_COMMAND_CNF_Ttag

{
HIL_PACKET_HEADER_T tHead;
CMDTBL_ADD_COMMAND_DATA_CNF_T tData;
}
CMDTBL_ADD_COMMAND_CNF_T;

Packet description

Structure CMDTBL_ADD_COMMAND_CNF_T Type: Confirmation

Variable Type Value / Range Description

Structure HIL_PACKET_HEADER_T
ulLen uint32_t 4 Packet Data Length in bytes
sizeof(CMDTBL_ADD_COMMAND_DATA_CNF_T)
ulSta uint32_t x See section Status/Error codes
ulCmd uint32_t 0xA30B CMDTBL_ADD_COMMAND_CNF - Command

Structure CMDTBL_ADD_COMMAND_DATA_CNF_T
ulCommandId uint32_t n Command identifier of the added command. The host application
should hold this handle to use it later by other commands e.g.
CMDTBL_ACTIVATE_COMMAND_REQ
Table 46: CMDTBL_ADD_COMMAND_CNF_T packet

Open Modbus/TCP V3 | Protocol API

DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
The application interface 72/104
4.6.8 CMDTBL_DELETE_COMMAND _REQ/CNF – Delete a command
This packet can be used to delete a specific command from the command table. The command to
be deleted is identified by its command ID (Variable ulCommandId of the request and the
configuration packet).

Packet structure reference

typedef struct CMDTBL_DELETE_COMMAND_DATA_REQ_Ttag
{
uint32_t ulCommandId;
} CMDTBL_DELETE_COMMAND_DATA_REQ_T;

typedef struct CMDTBL_DELETE_COMMAND_REQ_Ttag

{
HIL_PACKET_HEADER_T tHead;
CMDTBL_DELETE_COMMAND_DATA_REQ_T tData;
}
CMDTBL_DELETE_COMMAND_REQ_T;

Packet description

Variable Type Value / Range Description

ulDest uint32_t 0x20 Destination (HIL_PACKET_DEST_DEFAULT_CHANNEL)
QUE_OMBAPTASK
ulLen uint32_t 4 Packet Data Length in bytes
sizeof(CMDTBL_DELETE_COMMAND_DATA_REQ_T)
ulSta uint32_t 0 Set to zero
ulCmd uint32_t 0xA30C CMDTBL_DELETE_COMMAND_REQ - Command

Structure CMDTBL_DELETE_COMMAND_DATA_REQ_T
ulCommandId uint32_t n Command that shall be deleted.
Use the command ID returned by the CMDTBL_ADD_COMMAND
_REQ_T packet to delete a particular command.
Table 47: CMDTBL_DELETE_COMMAND_REQ_T packet

Open Modbus/TCP V3 | Protocol API

DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
The application interface 73/104
Packet structure reference
typedef struct CMDTBL_DELETE_COMMAND_DATA_REQ_Ttag
{
uint32_t ulCommandId;
} CMDTBL_DELETE_COMMAND_DATA_REQ_T;

typedef CMDTBL_DELETE_COMMAND_DATA_REQ_T CMDTBL_DELETE_COMMAND_DATA_CNF_T;

typedef struct CMDTBL_DELETE_COMMAND_CNF_Ttag

{
HIL_PACKET_HEADER_T tHead;
CMDTBL_DELETE_COMMAND_DATA_CNF_T tData;
}
CMDTBL_DELETE_COMMAND_CNF_T;

Packet description

Variable Type Value / Range Description

ulLen uint32_t 4 Packet Data Length in bytes
sizeof(CMDTBL_DEACTIVATE_TABLE_DATA_CNF_T)
ulSta uint32_t x See section Status/Error codes
ulCmd uint32_t 0xA30D CMDTBL_DEACTIVATE_TABLE_CNF - Command

Structure CMDTBL_DELETE_COMMAND_DATA_CNF_T
ulCommandId uint32_t n Command identifier of the deleted command.
Table 48: CMDTBL_DELETE_COMMAND_CNF_T packet

Open Modbus/TCP V3 | Protocol API

DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
The application interface 74/104
4.6.9 CMDTBL_ACTIVATE_COMMAND_REQ/CNF – Activate a
command
This packet can be used to activate a specific (formerly deactivated) command within a command
table. This command is identified by its command ID (Variable ulCommandId of the request and the
configuration packet).
A command may be deactivated in the following two cases:
 It has been defined as deactivated by setting the command disable bit D0 within variable
ulFlags to 1.
 A CMDTBL_DEACTIVATE_COMMAND_REQ/CNF – Deactivate a command request packet
has been processed by the protocol stack earlier.

Packet structure reference

/*******************************************************************
* Activate Command
*******************************************************************/
typedef struct CMDTBL_ACTIVATE_COMMAND_DATA_REQ_Ttag
{
uint32_t ulCommandId;
} CMDTBL_ACTIVATE_COMMAND_DATA_REQ_T;

typedef struct CMDTBL_ACTIVATE_COMMAND_REQ_Ttag

{
HIL_PACKET_HEADER_T tHead;
CMDTBL_ACTIVATE_COMMAND_DATA_REQ_T tData;
} CMDTBL_ACTIVATE_COMMAND_REQ_T;

Packet description

Variable Type Value / Range Description

ulDest uint32_t 0x20 Destination
QUE_OMBAPTASK
(HIL_PACKET_DEST_DEFAULT_CHANNEL)
ulLen uint32_t 4 Packet Data Length in bytes
sizeof(CMDTBL_ACTIVATE_COMMAND_DATA_REQ_T)
ulSta uint32_t 0 Set to zero
ulCmd uint32_t 0xA30E CMDTBL_ACTIVATE_COMMAND_REQ - Command

Structure CMDTBL_ACTIVATE_COMMAND_DATA_REQ_T
ulCommandId uint32_t n Command that shall be activated.
Use the command ID returned by the CMDTBL_ADD_COMMAND
_REQ_T packet to activate a particular command.
Table 49: CMDTBL_ACTIVATE_COMMAND_REQ_T packet

Open Modbus/TCP V3 | Protocol API

DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
The application interface 75/104
Packet structure reference
/*******************************************************************
* Activate Command
*******************************************************************/
typedef struct CMDTBL_ACTIVATE_COMMAND_DATA_REQ_Ttag
{
uint32_t ulCommandId;
} CMDTBL_ACTIVATE_COMMAND_DATA_REQ_T;

typedef CMDTBL_ACTIVATE_COMMAND_DATA_REQ_T CMDTBL_ACTIVATE_COMMAND_DATA_CNF_T;

typedef struct CMDTBL_ACTIVATE_COMMAND_CNF_Ttag

{
HIL_PACKET_HEADER_T tHead;
CMDTBL_ACTIVATE_COMMAND_DATA_CNF_T tData;
} CMDTBL_ACTIVATE_COMMAND_CNF_T;

Packet description

Variable Type Value / Range Description

ulLen uint32_t 4 Packet Data Length in bytes
sizeof(CMDTBL_ACTIVATE_COMMAND_DATA_CNF_T)
ulSta uint32_t x See section Status/Error codes
ulCmd uint32_t 0xA30F CMDTBL_ACTIVATE_COMMAND_CNF - Command

Structure CMDTBL_ACTIVATE_COMMAND_DATA_CNF_T
ulCommandId uint32_t n Command identifier of the activated command.
Table 50: CMDTBL_ACTIVATE_COMMAND_CNF_T packet

Open Modbus/TCP V3 | Protocol API

DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
The application interface 76/104
4.6.10 CMDTBL_DEACTIVATE_COMMAND_REQ/CNF – Deactivate a
command
This packet can be used to deactivate a (formerly activated) command within a command table. This
command is identified by its command ID (Variable ulCommandId of the request and the
configuration packet).

Packet structure reference

/*******************************************************************
* Deactivate Command
*******************************************************************/
typedef struct CMDTBL_DEACTIVATE_COMMAND_DATA_REQ_Ttag
{
uint32_t ulCommandId;
} CMDTBL_DEACTIVATE_COMMAND_DATA_REQ_T;

typedef struct CMDTBL_DEACTIVATE_COMMAND_REQ_Ttag

{
HIL_PACKET_HEADER_T tHead;
CMDTBL_DEACTIVATE_COMMAND_DATA_REQ_T tData;
}
CMDTBL_DEACTIVATE_COMMAND_REQ_T;

Packet description

Variable Type Value / Range Description

ulDest uint32_t 0x20 Destination (HIL_PACKET_DEST_DEFAULT_CHANNEL)
QUE_OMBAPTASK
ulLen uint32_t 4 Packet Data Length in bytes
sizeof(CMDTBL_DEACTIVATE_COMMAND_DATA_REQ_T)
ulSta uint32_t 0 Set to zero
ulCmd uint32_t 0xA310 CMDTBL_DEACTIVATE_COMMAND_REQ - Command

Structure CMDTBL_DEACTIVATE_COMMAND_DATA_REQ_T
ulCommandId uint32_t n Command that shall be activated.
Use the command ID returned by the
CMDTBL_ADD_COMMAND_REQ_T packet to activate a particular
command.
Table 51: CMDTBL_DEACTIVATE_COMMAND_REQ_T packet

Open Modbus/TCP V3 | Protocol API

DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
The application interface 77/104
Packet structure reference
/*******************************************************************
* Deactivate Command
*******************************************************************/
typedef struct CMDTBL_DEACTIVATE_COMMAND_DATA_REQ_Ttag
{
uint32_t ulCommandId;
} CMDTBL_DEACTIVATE_COMMAND_DATA_REQ_T;

typedef CMDTBL_DEACTIVATE_COMMAND_DATA_REQ_T CMDTBL_DEACTIVATE_COMMAND_DATA_CNF_T;

typedef struct CMDTBL_DEACTIVATE_COMMAND_CNF_Ttag

{
HIL_PACKET_HEADER_T tHead;
CMDTBL_DEACTIVATE_COMMAND_DATA_CNF_T tData;
}
CMDTBL_DEACTIVATE_COMMAND_CNF_T;

Packet description

Variable Type Value / Range Description

ulLen uint32_t 4 Packet Data Length in bytes
sizeof(CMDTBL_DEACTIVATE_COMMAND_DATA_CNF_T)
ulSta uint32_t x See section Status/Error codes
ulCmd uint32_t 0xA311 CMDTBL_DEACTIVATE_COMMAND_CNF - Command

Structure CMDTBL_DEACTIVATE_COMMAND_DATA_CNF_T
ulCommandId uint32_t n Command identifier of the activated command.
Table 52: CMDTBL_ACTIVATE_COMMAND_CNF_T packet

Open Modbus/TCP V3 | Protocol API

DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
The application interface 78/104
4.6.11 CMDTBL_TRIGGER_COMMAND_REQ/CNF – Trigger a
command
This packet allows to externally trigger a specific command within a command table. The command
to be triggered is identified by its command ID (Variable ulCommandId).
To do so, the following prerequisites must be fulfilled:
1. The command with the specified command ID must have been added to the command table
using trigger type “CMDTBL_TRIGGER_TYPE_ON_REQUEST”.
2. Neither the command with the specified command ID nor the command table to which it
belongs may be deactivated.

Packet structure reference

/*******************************************************************
* Trigger Command
*******************************************************************/
typedef struct CMDTBL_TRIGGER_COMMAND_DATA_REQ_Ttag
{
uint32_t ulCommandId;
} CMDTBL_TRIGGER_COMMAND_DATA_REQ_T;

typedef struct CMDTBL_TRIGGER_COMMAND_REQ_Ttag

{
HIL_PACKET_HEADER_T tHead;
CMDTBL_TRIGGER_COMMAND_DATA_REQ_T tData;
}
CMDTBL_TRIGGER_COMMAND_REQ_T;

Packet description

Variable Type Value / Range Description

ulDest uint32_t 0x20 Destination (HIL_PACKET_DEST_DEFAULT_CHANNEL)
QUE_OMBAPTASK
ulLen uint32_t 4 Packet Data Length in bytes
sizeof(CMDTBL_TRIGGER_COMMAND_DATA_REQ_T)
ulSta uint32_t 0 Set to zero
ulCmd uint32_t 0xA312 CMDTBL_TRIGGER_COMMAND_REQ - Command

Structure CMDTBL_TRIGGER_COMMAND_DATA_REQ_T
ulCommandId uint32_t n Command that shall be triggered.
Use the command ID returned by the CMDTBL_ADD_COMMAND
_REQ_T packet to trigger a particular command.
Note:
A command can be triggered only if it is configured from trigger type
“CMDTBL_TRIGGER_TYPE_ON_REQUEST” and the command itself
and the command table where it belongs to must not be deactivated.
Table 53: CMDTBL_TRIGGER_COMMAND_REQ_T packet

Open Modbus/TCP V3 | Protocol API

DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
The application interface 79/104
Packet structure reference
/*******************************************************************
* Trigger Command
*******************************************************************/
typedef struct CMDTBL_TRIGGER_COMMAND_DATA_REQ_Ttag
{
uint32_t ulCommandId;
} CMDTBL_TRIGGER_COMMAND_DATA_REQ_T;

typedef CMDTBL_TRIGGER _COMMAND_DATA_REQ_T CMDTBL_TRIGGER_COMMAND_DATA_CNF_T;

typedef struct CMDTBL_TRIGGER_COMMAND_CNF_Ttag

{
HIL_PACKET_HEADER_T tHead;
CMDTBL_TRIGGER_COMMAND_DATA_CNF_T tData;
}
CMDTBL_TRIGGER_COMMAND_CNF_T;

Packet description

Variable Type Value / Range Description

ulLen uint32_t 4 Packet Data Length in bytes
sizeof(CMDTBL_TRIGGER_COMMAND_DATA_CNF_T)
ulSta uint32_t x See section Status/Error codes CMD task

ulCmd uint32_t 0xA313 CMDTBL_TRIGGER_COMMAND_CNF - Command

Structure CMDTBL_TRIGGER_COMMAND_DATA_CNF_T
ulCommandId uint32_t N Command identifier of the activated command.
Table 54: CMDTBL_TRIGGER_COMMAND_CNF_T packet

Open Modbus/TCP V3 | Protocol API

DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
The application interface 80/104
4.6.12 CMDTBL_GET_IO_INFO_REQ/CNF – Get IO Info
This service returns the current input and output byte sizes of the dual-port memory (within the
confirmation packet). It also delivers the start offset of the diagnostic bit field within the dual-port
“Input area”.

Packet structure reference

/*******************************************************************
* IO Size Command
*******************************************************************/
typedef struct CMDTBL_GET_IO_INFO_REQ_Ttag
{
HIL_PACKET_HEADER_T tHead;
}
CMDTBL_GET_IO_INFO_REQ_T;

Packet description

Variable Type Value / Range Description

ulDest uint32_t 0x20 Destination (HIL_PACKET_DEST_DEFAULT_CHANNEL)
QUE_OMBAPTASK
ulLen uint32_t 0 Packet Data Length in bytes
ulSta uint32_t 0 Set to zero
ulCmd uint32_t 0xA314 CMDTBL_GET_IO_INFO_REQ - Command
Table 55: CMDTBL_GET_IO_INFO_REQ_T packet

Open Modbus/TCP V3 | Protocol API

DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
The application interface 81/104
Packet structure reference
typedef struct CMDTBL_GET_IO_INFO_DATA_CNF_Ttag
{
uint32_t ulInputByteSize;
uint32_t ulOutputByteSize;
uint32_t ulDpmBitFieldPosition;
} CMDTBL_GET_IO_INFO_DATA_CNF_T;

typedef struct CMDTBL_GET_IO_INFO_CNF_Ttag

{
HIL_PACKET_HEADER_T tHead;
CMDTBL_GET_IO_INFO_DATA_CNF_T tData;
}
CMDTBL_GET_IO_INFO_CNF_T;

Packet description

Variable Type Value / Range Description

ulLen uint32_t 12 Packet Data Length in bytes
sizeof(CMDTBL_GET_IO_INFO_DATA_CNF_T)
ulSta uint32_t x See section Status/Error codes
ulCmd uint32_t 0xA315 CMDTBL_GET_IO_INFO_CNF - Command

Structure CMDTBL_GET_IO_INFO_DATA_CNF_T
ulInputByteSize uint32_t 0 … 5680 This value defines last byte used in “Input area” of the dual-port
memory.
ulOutputByteSize uint32_t 0 … 5680 This value defines last byte used in “Output area” of the dual-port
memory.
ulDpmBitFieldPos uint32_t 0 … 5680 Start offset of the diagnostic bit field within the dual-port “Input area”.
ition This value reflects the offset that has been configured with the
CMDTBL_INIT_REQ - Command
Table 56: CMDTBL_GET_IO_INFO_CNF_T packet

Open Modbus/TCP V3 | Protocol API

DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
The application interface 82/104
4.6.13 CMDTBL_DEINIT_REQ/CNF – Table Deinitialization
The command table de-initialization can be used to reset the command table task. This command
sets the CMD Task into the Power ON state.

Packet structure reference

/*******************************************************************
* Deinit Request
*******************************************************************/
typedef struct CMDTBL_DEINIT_REQ_Ttag
{
HIL_PACKET_HEADER_T tHead;
}
CMDTBL_DEINIT_REQ_T;

Packet description

Variable Type Value / Range Description

ulDest uint32_t 0x20 Destination (HIL_PACKET_DEST_DEFAULT_CHANNEL)
QUE_OMBAPTASK
ulLen uint32_t 0 Packet Data Length in bytes
ulSta uint32_t 0 Set to zero
ulCmd uint32_t 0xA316 CMDTBL_DEINIT_REQ - Command
Table 57: CMDTBL_DEINIT_REQ packet

Packet structure reference

typedef struct CMDTBL_DEINIT_CNF_Ttag
{
HIL_PACKET_HEADER_T tHead;
}
CMDTBL_DEINIT_CNF_T;

Packet description

Structure CMDTBL_DEINIT_CNF Type: Confirmation

Variable Type Value / Range Description

Structure HIL_PACKET_HEADER_T
ulLen uint32_t 0 Packet Data Length in bytes
ulSta uint32_t x See section Status/Error codes
ulCmd uint32_t 0xA317 CMDTBL_DEINIT_CNF - Command
Table 58: CMDTBL_DEINIT_CNF packet

Open Modbus/TCP V3 | Protocol API

Packet structure reference

/*******************************************************************
* Start/Stop Request
*******************************************************************/
typedef struct CMDTBL_START_STOP_DATA_REQ_Ttag
{
uint32_t ulStartStopCommand;
}
CMDTBL_START_STOP_DATA_REQ_T;

typedef struct CMDTBL_START_STOP_REQ_Ttag

{
HIL_PACKET_HEADER_T tHead;
CMDTBL_START_STOP_DATA_REQ_T tData;
}
CMDTBL_START_STOP_REQ_T;

typedef struct CMDTBL_START_STOP_CNF_Ttag

{
HIL_PACKET_HEADER_T tHead;
}
CMDTBL_START_STOP_CNF_T;

Packet description

Variable Type Value / Range Description

ulDest uint32_t 0x20 Destination (HIL_PACKET_DEST_DEFAULT_CHANNEL)
QUE_OMBAPTASK
ulLen uint32_t 4 Packet Data Length in bytes
ulSta uint32_t 0 Set to zero
ulCmd uint32_t 0xA318 CMDTBL_START_STOP_REQ - Command
Structure CMDTBL_START_STOP_REQ _T
ulStartStopComm uint32_t 0, 1 CMDTBL_STOP_COMMAND = 0x00000000
and CMDTBL_START_COMMAND = 0x00000001
Table 59: CMDTBL_START_STOP_REQ packet

CMDTBL_START_STOP_REQ is intended for a temporary pausing the cyclic execution of all

commands/tables configured. The host could stop the command table execution by sending the
packet with a parameter ulStartStopCommand set to CMDTBL_STOP_COMMAND and then
resume the execution by sending the same packet but with a parameter
CMDTBL_START_COMMAND.
CMDTBL_START_STOP_REQ request is generated internally by the Modbus Stack automatically
anytime the HIL_START_STOP_COMM_REQ is sent regardless of the current state of the
command table.
For example, if the host sends a HIL_START_STOP_COMM_REQ packet in order to activate the
BUS a CMDTBL_START_STOP_REQ will be automatically generated event if the command table
had been previously stopped.
In summary, the HIL_START_STOP_COM_REQ will accordingly change also the state of the
command table along with the state of the stack itself.

Open Modbus/TCP V3 | Protocol API

DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
The application interface 84/104
Packet structure reference
/*******************************************************************
* Start/Stop Request
*******************************************************************/
typedef struct CMDTBL_START_STOP_CNF_Ttag
{
HIL_PACKET_HEADER_T tHead;
}
CMDTBL_START_STOP_CNF_T;

Packet description

Variable Type Value / Range Description

ulLen uint32_t 0 Packet Data Length in bytes
ulSta uint32_t x See section Status/Error codes
ulCmd uint32_t 0xA319 CMDTBL_START_STOP_CNF - Command
Table 60: CMDTBL_START_STOP_CNF packet

Open Modbus/TCP V3 | Protocol API

DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
The application interface 85/104
4.6.15 Command Table diagnostic with Status bit fields
When the Open Modbus/TCP stack is configured in client mode and a “Command Table” is present,
the Open Modbus/TCP stack supports the Hilscher standard bit fields “Configured Slaves”, “Active
Slaves” and “Diagnostic Slaves”. In this case the Open Modbus/TCP stack acts like a master on the
network. Also the Hilscher common diagnostic structure for master stacks
“NETX_MASTER_STATUS_T” is filled.
When the Open Modbus/TCP stack starts, it will parse the command table and assign for each found
IP address one bit in the bit fields. The bit assignment to the IP addresses is done in the same order
like they are configured in the command table. The smallest bit is always assigned to the first
configured IP address in command table the second bit is assigned to the next configured IP address
and so on. If two or more same IP addresses are configured in the command table, then the bit
assignment will be done only for the first IP address.
Additionally, per each configured command the OMB Stack supports a bit field. The assignment of
the command diagnostic flags is in ascending order like they the command sets are defined in the
command table.
unit8_t abConfigSlaves[16]; /* Configured Slave bit filed */
unit8_t abActiveSlaves[16]; /* Active Slave in communication bit field */
unit8_t abDiagSlaves[16]; /* Slaves with diagnostic bit field*/
unit8_t abCommandDiag[32]; /* Diag flags per configured command bit field*/
The bit fields are transferred within the process data input image of the dual port memory. They are
placed 32bit aligned behind the last used input byte of the process data input image. This guarantees
the consistency of process data and status information. The bit field support for configured, active
and diagnostic slaves follows the general implementation for all Hilscher master stacks. That is, why
the mechanism how to get the exact start offset of each bit field is described generally in the “netX
Dual-port Memory Interface” manual. The start offsets and additional information about the bit fields
(size, type etc.) can be read out from the “Extended Status Block” in the dual port memory. Refer to
chapter “Extended Status Block” in the “netX Dual-port Memory Interface” to get detailed information
how to get the bit field offsets.

Open Modbus/TCP V3 | Protocol API

The figure below shows a command table created with SYCON.net.

The command table contains 6 commands. These commands are sent to 3 slave different devices
with:
IPAddress1=192.168.10.22
IPAddress2=192.168.10.11
IPAddress3=192.168.10.33.
The condition is as following IP2 and IP3 are active on the network. IP1 is not connected to the
network. The second command (FC16) of IP2 does not work for any reason. All other commands
are executed successfully.
In this case, the bit fields are filled as follows:

Configured slaves bit field

tBitField.abConfigSlaves[0] = 0b00000111; (bit0 = IP1; bit1 = IP2; bit2 = IP3;)
tBitField.abConfigSlaves[1..15] = 0b00000000;

Active slaves bit field

tBitField.abActiveSlaves[0] = 0b00000110; (bit0 = FALSE because IP1 not active)
tBitField.abActiveSlaves[1..15] = 0b00000000;

Diagnostic slaves bit field

tBitField.abDiagSlaves[0] = 0b00000010; (bit1 = TRUE -> FC16 of IP2 is faulty)
tBitField.abDiagSlaves[1..15] = 0b00000000;

Command bit field

tBitField.abCommandDiag.[0] = 0b00110100; (bit0;1=0 -> IP1 faulty; bit3=0 -> FC16
of IP2 faulty)
tBitField.abCommandDiag.[1..31] = 0b00000000;

Open Modbus/TCP V3 | Protocol API

DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
The application interface 87/104
4.6.16 Command table timing diagram
The following diagrams show the first typical two cases of the command table. In this case, one cycle
time (TCT) is configured for each server command table. This means, all commands shall be
executed once within this cycle tile. The typical use case is to configure an IO cycle. It is possible to
configure an “InterCommandDelay” between each request. This is sometimes required for a slow
server. It is also possible to configure an “InterScanDelay”. This will guarantee a break between the
last and first command of the table. The fastest execution of the command table can be realized if
all timing parameter TCT; ICD and ISD are set to.
The timings are configured with the parameter ulCycleTime (TCT); ulInterCommandDelay (ICD) and
ulInterScanDelay (ISD) of the command CMDTBL_ADD_TABLE_REQ.

Figure 12: Timing diagram for table cyclic time

Open Modbus/TCP V3 | Protocol API

DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
The application interface 88/104
The following diagrams show the second typical use case of the command table. In this case, each
single command is configured with an individual cycle time (CCP).The typical use case is, if some
data of a server shall be requested frequently (e.g. IO data) and some status data from the server
shall be requested rarely.
The timings are configured with the parameter ulInterCommandDelay (ICD of the command
CMDTBL_ADD_TABLE_REQ and ulCyclePeriod of the command
CMDTBL_ADD_COMMAND_REQ.

Figure 13: Timing diagram for command cyclic period

Note: It is not possible to configure a mixed mode of both described timing use cases. This
means it is not allowed to configure a Table Cycle Time ulCycleTime (TCT) to a non 0
value and an individual ulCyclePeriod (CCP). If the command individual ulCyclePeriod
(CCP) is configured then it is not possible to configure an ulInterScanDelay (ISD).

Open Modbus/TCP V3 | Protocol API

5 Status/Error codes
5.1 Status/Error codes OMB task
Hexadecimal value Definition / description
0x00000000 SUCCESS_HIL_OK
Status ok
0xC0000004 ERR_HIL_UNKNOWN_COMMAND
Unknown Command in Packet received
0xC0000007 ERR_HIL_INVALID_PACKET_LEN
Packet length is invalid.
0xC000000C ERR_HIL_WATCHDOG_TIMEOUT
Watchdog error occurred.
0xC000001A ERR_HIL_REQUEST_RUNNING
Request is already running.
0xC0000119 ERR_HIL_NOT_CONFIGURED
Configuration not available
0xC0000200 ERR_HIL_WATCHDOGTIME_INVALID
Watchdog time is out of range.
0xC0600002 ERR_OMB_IF_SEND_IP_SET_CONFIG_FAILED
Failed to forward the SET_CONFIG information to TCP_UDP task (because of a resource
problem).
0xC0600003 ERR_OMB_IF_SYSTEM_FUNCTION_CODE
Wrong function code.
0xC0600004 ERR_OMB_IF_MOD_MEM_MOD_START_ADR
Wrong Modbus start address.
0xC0600005 ERR_OMB_IF_MOD_MEM_LEN
IO mode: Wrong length of Memory map.
0xC0600006 ERR_OMB_IF_MOD_MEM_START_MEM_OFF
IO mode: Wrong Start byte offset in Memory map.
0xC0600007 ERR_OMB_IF_MOD_MEM_SYSTEM_ERROR
IO mode: System error.
0xC0600008 ERR_OMB_IF_INVALID_STARTUP_PARAMETER_QUE_ELEM_CNT
Invalid Startup Parameter ulQueElemCnt.
0xC0600009 ERR_OMB_IF_INVALID_STARTUP_PARAMETER_POOL_ELEM_CNT
Invalid Startup Parameter ulPoolElemCnt.
0xC060000A ERR_OMB_IF_INVALID_STARTUP_PARAMETER_START_FLAGS
Invalid Startup Parameter ulStartFlags.
0xC060000B ERR_OMB_IF_INVALID_STARTUP_PARAMETER_OMB_CYCLE_EVENT
Invalid Startup Parameter ulOmbCycleEvent.
0xC060000C ERR_OMB_IF_APPLICATION_TIMER_CREATE_FAILED
Failed to create an application timer (Timer task).
0xC060000D ERR_OMB_IF_APPLICATION_TIMER_INIT_PACKET_FAILED
Failed to initialize a packet of application timer (Timer task).
0xC060000E ERR_OMB_IF_TCP_UDP_IDENTIFY_FAILED
Failed to identify the TCP_UDP task.
0xC060000F ERR_OMB_IF_TCP_UDP_QUEUE_IDENTIFY_FAILED
The queue identification of TCP_UDP task queue has failed.

Open Modbus/TCP V3 | Protocol API

Hexadecimal value Definition / description

0xC0600010 ERR_OMB_IF_BUFFER_QUEUE_CREATE_FAILED
Creation of buffer queue failed.
0xC0600012 ERR_OMB_IF_FLAGS_VALUE
Invalid parameter ‘Flags’ (ulFlags)
0xC0600034 ERR_OMB_IF_SERVER_CONNECT_VALUE
Invalid configuration data
0xC0600035 ERR_OMB_IF_ANSWER_TIMEOUT_VALUE
Invalid configuration data
0xC0600036 ERR_OMB_IF_OPEN_TIMEOUT_VALUE
Invalid parameter 'Omb Open Time' (ulOmbOpenTime).
0xC0600037 ERR_OMB_IF_MODE_VALUE
Invalid parameter 'Mode' (ulMode).
0xC0600038 ERR_OMB_IF_SEND_TIMEOUT_VALUE
Invalid parameter 'Send Timeout' (ulSendTimeout)
0xC0600039 ERR_OMB_IF_CONNECT_TIMEOUT_VALUE
Invalid parameter 'Connect Timeout' (ulConnectTimeout).
0xC060003A ERR_OMB_IF_CLOSE_TIMEOUT_VALUE
Invalid parameter 'Close Timeout' (ulCloseTimeout).
0xC060003B ERR_OMB_IF_SWAB_VALUE
Invalid parameter 'Swap' (ulSwap).
0xC0600070 ERR_OMB_IF_ERR_ANSWER
TCP_UDP task answered with an error.
0xC0600071 ERR_OMB_IF_ERR_STATE
No socket in specific status found.
0xC0600072 ERR_OMB_IF_ERR_VALUE
Invalid value in command.
0xC0600073 ERR_OMB_IF_ERR_TCP_TASK_STATE
Error in TCP_UDP task state.
0xC0600074 ERR_OMB_IF_ERR_MODBUS
Error in Modbus telegram - for further information, see next section.
0xC0600075 ERR_OMB_IF_ERR_NO_SOCKET
No free and unused socket found.
0xC0600076 ERR_OMB_IF_ERR_UNKNOWN_SOCKET
TCP_UDP command for an unknown socket received.
0xC0600077 ERR_OMB_IF_ERR_TIMEOUT
The timeout for the Client-Job is expired. Timeout-Count starts after target has received
the command.
0xC0600078 ERR_OMB_IF_ERR_UNEXPECTED_CLOSE
Socket was unexpected closed.
0xC0600079 ERR_OMB_IF_USER_NOT_READY
The User is not ready (not registered).
0xC060007A ERR_OMB_IF_NO_SOCKET_AVAILABLE
OMB task is not able to open sockets (TCP_UDP task is not ready).
0xC060007C ERR_OMB_IF_ERR_IP_CONFIG
TCP_UDP task is in configuration status.
0xC060007D ERR_OMB_IF_PLC_TASK_NOT_INITIALIZED
No Dual-port memory access.

Open Modbus/TCP V3 | Protocol API

Hexadecimal value Definition / description

0xC060007E ERR_OMB_IF_SEVER_SOCKET_CLOSED
Server Socket is Closed before Answer is received
0xC06000A1 ERR_OMB_IF_DEVICE_ADR
Invalid device address (IP address).
0xC06000A5 ERR_OMB_IF_DATA_CNT
Invalid Data count.
0xC06000A7 ERR_OMB_IF_FUNCTION
Wrong Function code. Function code is not supported.
0xC0600100 ERR_OMB_IF_MOD_DATA_ADR
IO mode: Wrong Modbus address. Modbus address is outside of Memory map.
0xC0600101 ERR_OMB_IF_MOD_DATA_CNT
IO mode: Wrong Data count in conjunction with the Modbus address. The access area is
outside of Memory map.
0xC0600102 ERR_OMB_IF_MOD_FUNCTION_CODE
IO mode: Wrong Function code. Function code is not supported.
0xC0600103 ERR_OMB_IF_MOD_DATA_TYPE
IO mode: Wrong data type.
0xC0600104 ERR_OMB_IF_MOD_BIT_AREA
IO mode: Addressed coil is outside of the IO area.
0xC0600106 ERR_OMB_IF_SEND_TCP_CONFIG_RELOAD_FAILED
Failed to forward the configuration reload to TCP_UDP task (because of a resource
problem).
0xC0600107 ERR_OMB_IF_WRONG_CONFIG_RELOAD_STS
Wrong configuration reload state.
0xC0600108 ERR_OMB_IF_RESOURCE_OCCUPIED
System error: The requested resource is occupied.
0xC0600109 ERR_OMB_IF_AP_ALREADY_REGISTERED
An application is already registered.
0xC060010A ERR_OMB_IF_AP_NOT_REGISTERED
An application is not registered.
0xC060010B ERR_OMB_IF_START_STOP_MODE
Wrong mode ulMode in command OMB_IF_START_STOP_OMB_REQ.
0xC060010C ERR_OMB_IF_START_STOP_STATE_CHANGE
No senseful state change request (Start/stop) in command
OMB_IF_START_STOP_OMB_REQ.
0xC060010D ERR_OMB_IF_IO_MODE_COMMAND_INVALID
IO mode: Invalid command received
0xC060010E ERR_OMB_IF_STATE_NOT_RUNNING
The OMB stack is not in running state (Info status: ulTaskState is not
OMB_ST_TASK_RUNNING) or the Communication state is not operating
(ulCommunicationState is not HIL_COMM_STATE_OPERATE).
0xC060010F ERR_OMB_IF_MBAP_HEADER
Wrong MBAP header received (Transaction Identifier, Protocol Identifier)
0xC0600110 ERR_OMB_IF_UNIT_ID
Invalid Unit identifier (ulUnitId).
0xC0600111 ERR_OMB_IF_EXCEPTION
Invalid Exception code (ulException).
0xC0600112 ERR_OMB_IF_MBAP_LENGTH
Invalid MBAP header Length value.

Open Modbus/TCP V3 | Protocol API

Hexadecimal value Definition / description

0xC0600113 ERR_OMB_IF_PDU_BYTE_COUNT
Invalid PDU Byte count.
0xC0600114 ERR_OMB_IF_PDU_REF_NUMBER
Invalid PDU Reference Number (Starting Address).
0xC0600115 ERR_OMB_IF_PDU_DATA_CNT
Invalid PDU Data count (Quantity).
0xC0600116 ERR_OMB_IF_PDU_VALUE
Invalid PDU Value.
0xC0600117 ERR_OMB_IF_DATA_ADR
Wrong Modbus address. The Modbus address is outside of the Modbus Data model
(Range 0 ... 65535).
0xC0600118 ERR_OMB_IF_DATA_ADR_CNT
Wrong Data count in conjunction with the Modbus address. The access area is outside of
the Modbus Data model (Range 0 ... 65535).
0xC0600119 ERR_OMB_IF_ERROR_DUE_TO_LIMITED_VERSION
Invalid Startup Parameter ulMaxRegsCnt.
0xC060011A ERR_OMB_IF_INVALID_MAX_REGS_CNT
Invalid Startup Parameter ulMaxCoilsCnt.
0xC060011B ERR_OMB_IF_INVALID_MAX_COILS_CNT
Invalid Function Parameter Supplied.
0xC060011C ERR_OMB_IF_INVALID_FUNCTION_PARAMETERS
Any function has been called with invalid parameter.
0xC060011D ERR_OMB_IF_PROCESS_DATA_WATCHDOG_TIME_EXPIRED
The process data watchdog has expired.
0xC060011E ERR_OMB_IF_INVALID_PROCESS_DATA_WATCHDOG
The process data watchdog not within allowed range.
0xC060011F ERR_OMB_IF_INVALID_INACTIVE_TIMEOUT
The Inactive Timeout value not within allowed range.
0xC0600120 ERR_OMB_IF_INVALID_RESERVED
Reserved field set to value different than 0.
0xC0600121 ERR_OMB_IF_NO_IP_ADDR_CFG
There is no source for an IP address (BOOTP, DHCP, IP address parameter) specified.
0xC0600122 ERR_OMB_IF_INVALID_NETMASK
The configuration parameters contain an invalid subnet mask.
0xC0600123 ERR_OMB_IF_INVALID_IP_ADDR
The configuration parameters contain an invalid IP address.
0xC0600124 ERR_OMB_IF_INVALID_FLAGS_IP_CONFIG
The configuration parameters contain an invalid flag combination for manual IP
configuration.
0xC0600125 ERR_OMB_IF_INVALID_GATEWAY
The configuration parameters contain an invalid gateway IP address.
0xC0600126 ERR_OMB_IF_INVALID_SYSTEM_FLAGS
The configuration parameters contain an invalid System Flags parameter value.
0xC0600127 ERR_OMB_IF_INVALID_WATCHDOG
The Watchdog value not within allowed range.
0xC0600128 ERR_OMB_IF_IO_DATA_IMAGE_OVERLAP
Data overlap in input or output data image.

Open Modbus/TCP V3 | Protocol API

Hexadecimal value Definition / description

0xC0600129 ERR_OMB_IF_IP_CONFLICT
There is a device with the same IP address in the network.
0xC060012A ERR_OMB_IF_AUTO_IP_TIMEOUT
Source for an Auto IP configuration (DHCP, BOOTP) was not found within a specified
time.
0xC060012B ERR_OMB_IF_COMMAND_NOT_ALLOWED_IN_CURRENT_MODE
The packet is not allowed to be sent in current configuration mode.
0xC060012C ERR_OMB_IF_INVALID_FRAME_FRAGMENTATION_TIMEOUT
The Frame Fragmentation Timeout value not within allowed range.
Table 61: Status/Error codes OMB task

Open Modbus/TCP V3 | Protocol API

5.2 Status/Error codes Modbus Core

0xC06E0070 TLR_E_MODBUS_COMMAND_CONFIG_SIZE
Invalid Config Table size, read from the DBM file
0xC06E0071 TLR_E_MODBUS_COMMAND_CONFIG_VERSION
Invalid Config Version, read from the DBM file
0xC06E0072 TLR_E_MODBUS_COMMAND_CONFIG_PROT_CLASS
Invalid Protocol Class, read from the DBM file
0xC06E0073 TLR_E_MODBUS_COMMAND_CONFIG_DELAY
Invalid Delay value, read from the DBM file
0xC06E0074 TLR_E_MODBUS_COMMAND_RESERVED_VALUE
The reserved fields must be zero.
0xC06E0075 TLR_E_MODBUS_COMMAND_CMD_SIZE
Invalid Command Table size
0xC06E0076 TLR_E_MODBUS_COMMAND_CMD_VERSION
Invalid Command Table version
0xC06E0077 TLR_E_MODBUS_COMMAND_CMD_DEVICE
Invalid Device ID
0xC06E0078 TLR_E_MODBUS_COMMAND_CMD_UNIT
Invalid Unit ID, in MBRTU it must be zero
0xC06E0079 TLR_E_MODBUS_COMMAND_CMD_FUNC_CODE
Invalid Function code
0xC06E007A TLR_E_MODBUS_COMMAND_CMD_SUB_ADDR
Invalid values for SubAddress1 & 2, these are reserved
0xC06E007B TLR_E_MODBUS_COMMAND_CMD_CYCLIC_TIME
Invalid Cyclic time
0xC06E007C TLR_E_MODBUS_COMMAND_CMD_DATA_COUNT
Invalid Data Count
0xC06E007D TLR_E_MODBUS_COMMAND_CMD_DATA_ADDR
Invalid Data Address
0xC06E007E TLR_E_MODBUS_COMMAND_CMD_DPM_ADDR
Invalid DPM address
0xC06E007F TLR_E_MODBUS_COMMAND_CMD_TRIGGER
Invalid Trigger
0xC06E0080 TLR_E_MODBUS_COMMAND_NO_CHANGE
The selected task instance is not valid
0xC06E0081 TLR_E_MODBUS_COMMAND_INF_MEMORY
Insufficient Memory
0xC06E0082 TLR_E_MODBUS_COMMAND_INSTANCE
The selected task instance is not valid
0xC06E0083 TLR_E_MODBUS_EMPTY_LIST
The database file from the host is empty
0xC06E0084 TLR_E_MODBUS_COMMAND_CMD_DPM_LIMIT_PASSED
The command table entries are over the DPM Limit
Table 62: Status/Error codes Modbus Core

Open Modbus/TCP V3 | Protocol API

5.3 Status/Error codes CMD task

Hexadecimal value Definition / description
0x00000000 SUCCESS_HIL_OK
Status ok
0xC0E20001 ERR_CMDTBL_COMMAND_INVALID
Invalid command received.
0xC0E20002 ERR_CMDTBL_INVALID_PROTOCOL_TYPE
Not supported protocol.
0xC0E20003 ERR_CMDTBL_INVALID_QUEUE_NAME
The Queue name is invalid.
0xC0E20004 ERR_CMDTBL_UNSUPPORTED_VERSION
The version is not supported.
0xC0E20005 ERR_CMDTBL_TABLE_NOT_AVAILABLE
The table is not configured.
0xC0E20006 ERR_CMDTBL_COMMAND_NOT_AVAILABLE
The command is not configured.
0xC0E20007 ERR_CMDTBL_DEST_QUEUE_NOT_INITED
The destination queue is not initialized.
0xC0E20008 ERR_CMDTBL_COMMAND_DOES_NOT_MATCH_TABLE
The requested command does not exist in the table.
0xC0E20009 ERR_CMDTBL_COMMAND_NOT_TRIGGERABLE
The command is not defined as a triggerable one.
0xC0E2000A ERR_CMDTBL_COMMAND_NOT_ACTIVE
The command is not active or belongs to inactive table.
0xC0E2000B ERR_CMDTBL_UNSUPPORTED_PROTOCOL_TYPE
The command is not active or belongs to inactive table.
0xC0E2000C ERR_CMDTBL_MAX_TABLES_REACHED
The maximum tables number has been reached.
0xC0E2000D ERR_CMDTBL_MAX_COMMANDS_REACHED
The maximum commands number has been reached.
0xC0E2000E ERR_CMDTBL_ALREADY_INITED
The Command Table has already been initialized. Perform a Deinitialization first.
0xC0E2000F ERR_CMDTBL_NOT_INITED
The Command Table has not been initialized. Perform an initialization first.
0xC0E20010 ERR_CMDTBL_REQ_NOT_ALLOWED
The request is not allowed at this state
0xC0E20011 ERR_CMDTBL_INVALID_DEVICE_ADDRESS
An invalid Device Address has been detected.
0xC0E20012 ERR_CMDTBL_INVALID_UNIT_ID
An invalid Unit Identifier has been detected.
0xC0E20013 ERR_CMDTBL_INVALID_FUNCTION_CODE
An invalid Function Code has been detected.
0xC0E20014 ERR_CMDTBL_INVALID_DATA_COUNT
An invalid Data Size has been detected.
0xC0E20015 ERR_CMDTBL_INVALID_COMMAND_OFFSET
An invalid Command Offset has been detected.
0xC0E20016 ERR_CMDTBL_INVALID_TRIGGER_TYPE
An invalid Trigger Type has been detected.
0xC0E20017 ERR_CMDTBL_INVALID_CYCLE_PERIOD
An invalid Cycle Period has been detected.
0xC0E20018 ERR_CMDTBL_INVALID_RESERVED_VALUE
An invalid Reserved Field has been detected.
0xC0E20019 ERR_CMDTBL_ONE_TABLE_PER_DEVICE_ADDR
Each device address can be part of only one table.

Open Modbus/TCP V3 | Protocol API

Hexadecimal value Definition / description

0xC0E2001A ERR_CMDTBL_OFFSET_NOT_ALIGNED
The offset is not 4-byte aligned.
0xC0E2001B ERR_CMDTBL_INVALID_DATA_ADDRESS
An invalid Data Address has been detected.
0xC0E2001C ERR_CMDTBL_INVALID_BITFIELD_OFFSET
An invalid Bitfield Offset has been detected.
0xC0E2001D ERR_CMDTBL_INVALID_COMMAND_DELAY
An invalid Command Delay has been detected.
0xC0E2001E ERR_CMDTBL_INVALID_SCAN_DELAY
An invalid Interscan Delay has been detected.
0xC0E2001F ERR_CMDTBL_CYCLE_PERIOD_MUST_BE_ZERO
The command cycle period and the table cycle period cannot be non-zero values at the
same time.
0xC0E20020 ERR_CMDTBL_INVALID_TABLE_FLAGS
An invalid Flags value has been detected.
Table 63: Status/Error codes command table

Open Modbus/TCP V3 | Protocol API

6 Appendix
6.1 Modbus Exception Codes
The allowed values for packet element Exception Code and their meanings are listed in the following
table according to the MODBUS Application Protocol Specification V1.1b3, April 26, 2012, p.48-49,
which is available at http://www.modbus.org/.
MODBUS Exception Codes

Code Name Meaning

01 ILLEGAL FUNCTION The function code received in the query is not an allowable action for
the server. This may be because the function code is only applicable to
newer devices, and was not implemented in the unit selected. It could
also indicate that the server is in the wrong state to process a request
of this type, for example because it is unconfigured and is being asked
to return register values.
02 ILLEGAL DATA ADDRESS The data address received in the query is not an allowable address for
the server. More specifically, the combination of reference number and
transfer length is invalid. For a controller with 100 registers, the PDU
addresses the first register as 0, and the last one as 99. If a request is
submitted with a starting register address of 96 and a quantity of
registers of 4, then this request will successfully operate (address-wise
at least) on registers 96, 97, 98, 99. If a request is submitted with a
starting register address of 96 and a quantity of registers of 5, then this
request will fail with Exception Code 0x02 “Illegal Data Address” since
it attempts to operate on registers 96, 97, 98, 99 and 100, and there is
no register with address 100.
03 ILLEGAL DATA VALUE A value contained in the query data field is not an allowable value for
server. This indicates a fault in the structure of the remainder of a
complex request, such as that the implied length is incorrect. It
specifically does NOT mean that a data item submitted for storage in a
register has a value outside the expectation of the application program,
since the MODBUS protocol is unaware of the significance of any
particular value of any particular register.
04 SERVER DEVICE FAILURE An unrecoverable error occurred while the server was attempting to
perform the requested action.
05 ACKNOWLEDGE Specialized use in conjunction with programming commands.
The server 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 client. The client can next
issue a Poll Program Complete message to determine if processing is
completed.
06 SERVER DEVICE BUSY Specialized use in conjunction with programming commands.
The server is engaged in processing a long–duration program
command. The client should retransmit the message later when the
server is free.
08 MEMORY PARITY ERROR Specialized use in conjunction with function codes 20 and 21 and
reference type 6, to indicate that the extended file area failed to pass a
consistency check.
The server attempted to read record file, but detected a parity error in
the memory. The client can retry the request, but service may be
required
0A GATEWAY PATH UNAVAILABLE Specialized use in conjunction with gateways, indicates that the
gateway was unable to allocate an internal communication path from
the input port to the output port for processing the request. Usually
means that the gateway is misconfigured or overloaded.
0B GATEWAY TARGET DEVICE Specialized use in conjunction with gateways, indicates that no
FAILED TO RESPOND response was obtained from the target device. Usually means that the
device is not present on the network.
Table 64: MODBUS Exception Codes
Open Modbus/TCP V3 | Protocol API
DOC180702API01EN | Revision 1 | English | 2019-06 | Released | Public © Hilscher, 2018-2019
Appendix 98/104

6.2 List of tables

Table 1: List of revisions...................................................................................................................................................... 4
Table 2: Technical data Open Modbus/TCP ....................................................................................................................... 6
Table 3: Firmware/stack available for netX ......................................................................................................................... 6
Table 4: Configuration ......................................................................................................................................................... 6
Table 5: Additional features................................................................................................................................................. 7
Table 6: Terms, abbreviations and definitions ..................................................................................................................... 8
Table 7: Function codes in detail....................................................................................................................................... 14
Table 8: Configuration sequence ...................................................................................................................................... 18
Table 9: OMB_IF_SET_CONFIGURATION_REQ ............................................................................................................ 22
Table 10: OMB_IF_SET_CONFIGURATION_CNF –Confirmation of Provide Warmstart Parameters Packet.................. 23
Table 11: Basic parameter: Structure OMB_IF_CONFIG_BASIC_T................................................................................. 25
Table 12: TCP/IP Parameter: Structure OMB_IF_CONFIG_IP_T ..................................................................................... 26
Table 13: TCP/IP Parameter – ulFlags ............................................................................................................................. 27
Table 14: Stack Parameter – ulFlags ................................................................................................................................ 29
Table 15: Extended Parameter: Structure OMB_IF_CONFIG_EXT_T .............................................................................. 30
Table 16: Open Modbus/TCP Ident configuration data: Structure OMB_IF_CONFIG_IDENT_T ...................................... 31
Table 17: Common rcX packets ........................................................................................................................................ 33
Table 18: Input and Output Data Images .......................................................................................................................... 34
Table 19: OMB_IF_RECEIVE_IND – Receive Data Indication ......................................................................................... 41
Table 20: OMB_IF_RECEIVE_IND - Packet length .......................................................................................................... 41
Table 21: OMB_IF_RECEIVE_RES– Receive Data Response ........................................................................................ 43
Table 22: OMB_IF_RECEIVE_RES - Packet length ......................................................................................................... 43
Table 23: Example: Writing Data via FC6 - Indication ....................................................................................................... 44
Table 24: Example: Writing Data via FC6 – Response ..................................................................................................... 45
Table 25: OMB_IF_CONNECTION_IND – Connection Indication Packet ........................................................................ 47
Table 26: OMB_IF_CONNECTION_RES – Connection Response Packet ...................................................................... 48
Table 27: OMB_IF_SEND_REQ - Send Data Request ..................................................................................................... 52
Table 28: OMB_IF_SEND_REQ - Packet length .............................................................................................................. 53
Table 29: OMB_IF_SEND_CNF - Send Data Confirmation .............................................................................................. 54
Table 30: OMB_IF_SEND_CNF - Packet length ............................................................................................................... 54
Table 31: Example: Reading data via FC3 - Request ....................................................................................................... 55
Table 32: Example: Reading data via FC3 - Confirmation ................................................................................................ 55
Table 33: List of CMD task commands ............................................................................................................................. 57
Table 34: CMDTBL_INIT_REQ_T packet ......................................................................................................................... 58
Table 35: CMDTBL_INIT_CNF_T packet .......................................................................................................................... 58
Table 36: CMDTBL_ADD_TABLE_REQ_T packet ........................................................................................................... 60
Table 37: CMDTBL_ADD_TABLE_CNF_T packet............................................................................................................ 61
Table 38: CMDTBL_DELETE_TABLE_REQ_T packet ..................................................................................................... 62
Table 39: CMDTBL_DELETE_TABLE_CNF_T packet ..................................................................................................... 63
Table 40: CMDTBL_ACTIVATE_TABLE_REQ_T packet ................................................................................................. 64
Table 41: CMDTBL_ACTIVATE_TABLE_CNF_T packet .................................................................................................. 65
Table 42: CMDTBL_DEACTIVATE_TABLE_REQ_T packet ............................................................................................ 66
Table 43: CMDTBL_DEACTIVATE_TABLE_CNF_T packet ............................................................................................. 67
Table 44: Supported function codes in variable ulFunctionCode as defined by the Open Modbus/TCP specification . 68
Table 45: CMDTBL_ADD_COMMAND_REQ_T packet .................................................................................................... 70
Table 46: CMDTBL_ADD_COMMAND_CNF_T packet .................................................................................................... 71
Table 47: CMDTBL_DELETE_COMMAND_REQ_T packet ............................................................................................. 72
Table 48: CMDTBL_DELETE_COMMAND_CNF_T packet .............................................................................................. 73
Table 49: CMDTBL_ACTIVATE_COMMAND_REQ_T packet .......................................................................................... 74
Table 50: CMDTBL_ACTIVATE_COMMAND_CNF_T packet .......................................................................................... 75
Table 51: CMDTBL_DEACTIVATE_COMMAND_REQ_T packet ..................................................................................... 76
Table 52: CMDTBL_ACTIVATE_COMMAND_CNF_T packet .......................................................................................... 77
Table 53: CMDTBL_TRIGGER_COMMAND_REQ_T packet ........................................................................................... 78
Table 54: CMDTBL_TRIGGER_COMMAND_CNF_T packet ........................................................................................... 79
Table 55: CMDTBL_GET_IO_INFO_REQ_T packet ........................................................................................................ 80
Table 56: CMDTBL_GET_IO_INFO_CNF_T packet ......................................................................................................... 81
Table 57: CMDTBL_DEINIT_REQ packet......................................................................................................................... 82
Table 58: CMDTBL_DEINIT_CNF packet ......................................................................................................................... 82
Table 59: CMDTBL_START_STOP_REQ packet ............................................................................................................. 83
Table 60: CMDTBL_START_STOP_CNF packet ............................................................................................................. 84
Table 61: Status/Error codes OMB task ............................................................................................................................ 93
Table 62: Status/Error codes Modbus Core ...................................................................................................................... 94
Table 63: Status/Error codes command table ................................................................................................................... 96
Table 64: MODBUS Exception Codes .............................................................................................................................. 97

Open Modbus/TCP V3 | Protocol API

6.3 List of figures

Figure 1: Client/Server principle .......................................................................................................................................... 9
Figure 2: Structure of Open Modbus/TCP Firmware ......................................................................................................... 10
Figure 3: Host application accesses the Open Modbus/TCP ............................................................................................ 16
Figure 4: Configuration sequence ..................................................................................................................................... 17
Figure 5: Command table configuration sequence ............................................................................................................ 19
Figure 6: Addressing model of Open Modbus/TCP in IO mode (default mapping)............................................................ 35
Figure 7: Addressing model of Open Modbus/TCP in IO mode (alternative mapping) ...................................................... 36
Figure 8: Sequence diagram OMB_IF_RECEIVE_IND ..................................................................................................... 37
Figure 9: Sequence diagram OMB_IF_CONNECTION_IND............................................................................................. 46
Figure 10: Sequence diagram OMB_IF_SEND_REQ ....................................................................................................... 49
Figure 11: Example command table .................................................................................................................................. 56
Figure 12: Timing diagram for table cyclic time ................................................................................................................. 87
Figure 13: Timing diagram for command cyclic period ...................................................................................................... 88

Open Modbus/TCP V3 | Protocol API

6.4 Legal notes

All rights reserved.
The images, photographs and texts in the accompanying materials (in the form of a user's manual,
operator's manual, Statement of Work document and all other document types, support texts,
documentation, etc.) are protected by German and international copyright and by international trade
and protective provisions. Without the prior written consent, you do not have permission to duplicate
them either in full or in part using technical or mechanical methods (print, photocopy or any other
method), to edit them using electronic systems or to transfer them. You are not permitted to make
changes to copyright notices, markings, trademarks or ownership declarations. Illustrations are
provided without taking the patent situation into account. Any company names and product
designations provided in this document may be brands or trademarks by the corresponding owner
and may be protected under trademark, brand or patent law. Any form of further use shall require
the express consent from the relevant owner of the rights.

Important notes

Utmost care was/is given in the preparation of the documentation at hand consisting of a user's
manual, operating manual and any other document type and accompanying texts. However, errors
cannot be ruled out. Therefore, we cannot assume any guarantee or legal responsibility for
erroneous information or liability of any kind. You are hereby made aware that descriptions found in
the user's manual, the accompanying texts and the documentation neither represent a guarantee
nor any indication on proper use as stipulated in the agreement or a promised attribute. It cannot be
ruled out that the user's manual, the accompanying texts and the documentation do not completely
match the described attributes, standards or any other data for the delivered product. A warranty or
guarantee with respect to the correctness or accuracy of the information is not assumed.
We reserve the right to modify our products and the specifications for such as well as the
corresponding documentation in the form of a user's manual, operating manual and/or any other
document types and accompanying texts at any time and without notice without being required to
notify of said modification. Changes shall be taken into account in future manuals and do not
represent an obligation of any kind, in particular there shall be no right to have delivered documents
revised. The manual delivered with the product shall apply.
Under no circumstances shall Hilscher Gesellschaft für Systemautomation mbH be liable for direct,
indirect, ancillary or subsequent damage, or for any loss of income, which may arise after use of the
information contained herein.

Open Modbus/TCP V3 | Protocol API

The hardware and/or software was created and tested by Hilscher Gesellschaft für
Systemautomation mbH with utmost care and is made available as is. No warranty can be assumed
for the performance or flawlessness of the hardware and/or software under all application conditions
and scenarios and the work results achieved by the user when using the hardware and/or software.
Liability for any damage that may have occurred as a result of using the hardware and/or software
or the corresponding documents shall be limited to an event involving willful intent or a grossly
negligent violation of a fundamental contractual obligation. However, the right to assert damages
due to a violation of a fundamental contractual obligation shall be limited to contract-typical
foreseeable damage.
It is hereby expressly agreed upon in particular that any use or utilization of the hardware and/or
software in connection with
 Flight control systems in aviation and aerospace;
 Nuclear fission processes in nuclear power plants;
 Medical devices used for life support and
 Vehicle control systems used in passenger transport
shall be excluded. Use of the hardware and/or software in any of the following areas is strictly
prohibited:
 For military purposes or in weaponry;
 For designing, engineering, maintaining or operating nuclear systems;
 In flight safety systems, aviation and flight telecommunications systems;
 In life-support systems;
 In systems in which any malfunction in the hardware and/or software may result in physical
injuries or fatalities.
You are hereby made aware that the hardware and/or software was not created for use in hazardous
environments, which require fail-safe control mechanisms. Use of the hardware and/or software in
this kind of environment shall be at your own risk; any liability for damage or loss due to impermissible
use shall be excluded.

Open Modbus/TCP V3 | Protocol API

Hilscher Gesellschaft für Systemautomation mbH hereby guarantees that the software shall run
without errors in accordance with the requirements listed in the specifications and that there were
no defects on the date of acceptance. The warranty period shall be 12 months commencing as of
the date of acceptance or purchase (with express declaration or implied, by customer's conclusive
behavior, e.g. putting into operation permanently).
The warranty obligation for equipment (hardware) we produce is 36 months, calculated as of the
date of delivery ex works. The aforementioned provisions shall not apply if longer warranty periods
are mandatory by law pursuant to Section 438 (1.2) BGB, Section 479 (1) BGB and Section 634a
(1) BGB [Bürgerliches Gesetzbuch; German Civil Code] If, despite of all due care taken, the delivered
product should have a defect, which already existed at the time of the transfer of risk, it shall be at
our discretion to either repair the product or to deliver a replacement product, subject to timely
notification of defect.
The warranty obligation shall not apply if the notification of defect is not asserted promptly, if the
purchaser or third party has tampered with the products, if the defect is the result of natural wear,
was caused by unfavorable operating conditions or is due to violations against our operating
regulations or against rules of good electrical engineering practice, or if our request to return the
defective object is not promptly complied with.

Costs of support, maintenance, customization and product care

Please be advised that any subsequent improvement shall only be free of charge if a defect is found.
Any form of technical support, maintenance and customization is not a warranty service, but instead
shall be charged extra.

Additional guarantees

Although the hardware and software was developed and tested in-depth with greatest care, Hilscher
Gesellschaft für Systemautomation mbH shall not assume any guarantee for the suitability thereof
for any purpose that was not confirmed in writing. No guarantee can be granted whereby the
hardware and software satisfies your requirements, or the use of the hardware and/or software is
uninterruptable or the hardware and/or software is fault-free.
It cannot be guaranteed that patents and/or ownership privileges have not been infringed upon or
violated or that the products are free from third-party influence. No additional guarantees or promises
shall be made as to whether the product is market current, free from deficiency in title, or can be
integrated or is usable for specific purposes, unless such guarantees or promises are required under
existing law and cannot be restricted.

Open Modbus/TCP V3 | Protocol API

The customer hereby expressly acknowledges that this document contains trade secrets,
information protected by copyright and other patent and ownership privileges as well as any related
rights of Hilscher Gesellschaft für Systemautomation mbH. The customer agrees to treat as
confidential all of the information made available to customer by Hilscher Gesellschaft für
Systemautomation mbH and rights, which were disclosed by Hilscher Gesellschaft für
Systemautomation mbH and that were made accessible as well as the terms and conditions of this
agreement itself.
The parties hereby agree to one another that the information that each party receives from the other
party respectively is and shall remain the intellectual property of said other party, unless provided for
otherwise in a contractual agreement.
The customer must not allow any third party to become knowledgeable of this expertise and shall
only provide knowledge thereof to authorized users as appropriate and necessary. Companies
associated with the customer shall not be deemed third parties. The customer must obligate
authorized users to confidentiality. The customer should only use the confidential information in
connection with the performances specified in this agreement.
The customer must not use this confidential information to his own advantage or for his own purposes
or rather to the advantage or for the purpose of a third party, nor must it be used for commercial
purposes and this confidential information must only be used to the extent provided for in this
agreement or otherwise to the extent as expressly authorized by the disclosing party in written form.
The customer has the right, subject to the obligation to confidentiality, to disclose the terms and
conditions of this agreement directly to his legal and financial consultants as would be required for
the customer's normal business operation.

Export provisions

The delivered product (including technical data) is subject to the legal export and/or import laws as
well as any associated regulations of various countries, especially such laws applicable in Germany
and in the United States. The products / hardware / software must not be exported into such countries
for which export is prohibited under US American export control laws and its supplementary
provisions. You hereby agree to strictly follow the regulations and to yourself be responsible for
observing them. You are hereby made aware that you may be required to obtain governmental
approval to export, reexport or import the product.

Open Modbus/TCP V3 | Protocol API

6.5 Contacts

Headquarters

Germany
Hilscher Gesellschaft für
Systemautomation mbH
Rheinstrasse 15
65795 Hattersheim
Phone: +49 (0) 6190 9907-0
Fax: +49 (0) 6190 9907-50
E-Mail: [email protected]
Support
Phone: +49 (0) 6190 9907-99
E-Mail: [email protected]

Subsidiaries

China Japan
Hilscher Systemautomation (Shanghai) Co. Ltd. Hilscher Japan KK
200010 Shanghai Tokyo, 160-0022
Phone: +86 (0) 21-6355-5161 Phone: +81 (0) 3-5362-0521
E-Mail: [email protected] E-Mail: [email protected]
Support Support
Phone: +86 (0) 21-6355-5161 Phone: +81 (0) 3-5362-0521
E-Mail: [email protected] E-Mail: [email protected]

France Korea
Hilscher France S.a.r.l. Hilscher Korea Inc.
69500 Bron Seongnam, Gyeonggi, 463-400
Phone: +33 (0) 4 72 37 98 40 Phone: +82 (0) 31-789-3715
E-Mail: [email protected] E-Mail: [email protected]
Support
Phone: +33 (0) 4 72 37 98 40 Switzerland
E-Mail: [email protected] Hilscher Swiss GmbH
4500 Solothurn
India Phone: +41 (0) 32 623 6633
Hilscher India Pvt. Ltd. E-Mail: [email protected]
Pune, Delhi, Mumbai Support
Phone: +91 8888 750 777 Phone: +49 (0) 6190 9907-99
E-Mail: [email protected] E-Mail: [email protected]

Italy USA
Hilscher Italia S.r.l. Hilscher North America, Inc.
20090 Vimodrone (MI) Lisle, IL 60532
Phone: +39 02 25007068 Phone: +1 630-505-5301
E-Mail: [email protected] E-Mail: [email protected]
Support Support
Phone: +39 02 25007068 Phone: +1 630-505-5301
E-Mail: [email protected] E-Mail: [email protected]

Open Modbus/TCP V3 | Protocol API

Modbus Dokumentation Franka Panda
No ratings yet
Modbus Dokumentation Franka Panda
8 pages
Modbus TCP Specification
No ratings yet
Modbus TCP Specification
26 pages
Open ModbusTCP Standard
No ratings yet
Open ModbusTCP Standard
25 pages
Open ModbusTCP Standard
No ratings yet
Open ModbusTCP Standard
25 pages
AC500_V3_Modbus_TCP_3ADR010226_3_en_US
No ratings yet
AC500_V3_Modbus_TCP_3ADR010226_3_en_US
31 pages
COM600 Modbus TCP Usg 756445 EN
No ratings yet
COM600 Modbus TCP Usg 756445 EN
94 pages
Modbus TCP
No ratings yet
Modbus TCP
16 pages
Open Modbus/tcp Specification
No ratings yet
Open Modbus/tcp Specification
25 pages
COM600 - 3.4 Modbus - TCP - Usg - 756445 - ENd
No ratings yet
COM600 - 3.4 Modbus - TCP - Usg - 756445 - ENd
94 pages
Pymodbustcp Documentation: Release 0.1.10
No ratings yet
Pymodbustcp Documentation: Release 0.1.10
34 pages
Modbus/TCP OPC Server: Technical Description
No ratings yet
Modbus/TCP OPC Server: Technical Description
30 pages
Modbus TCP Server - AOI Based Code For ControlLogix V 2.02.00
No ratings yet
Modbus TCP Server - AOI Based Code For ControlLogix V 2.02.00
16 pages
Modbus 通信協定04
No ratings yet
Modbus 通信協定04
10 pages
Interface Description Modbus
No ratings yet
Interface Description Modbus
120 pages
Modbus TCP 8-20201026073915
No ratings yet
Modbus TCP 8-20201026073915
62 pages
Ah en Modbus TCP 8294 en 03 PDF
No ratings yet
Ah en Modbus TCP 8294 en 03 PDF
32 pages
Modbus TCP Client - AOI Based Code For ControlLogix V 2.02.00
No ratings yet
Modbus TCP Client - AOI Based Code For ControlLogix V 2.02.00
20 pages
cp1w-modtcp61_manual
No ratings yet
cp1w-modtcp61_manual
24 pages
Modbus TCP 9-20210426171633
No ratings yet
Modbus TCP 9-20210426171633
62 pages
FieldTalk Modbus Master C++ Library
No ratings yet
FieldTalk Modbus Master C++ Library
247 pages
ATV32 Modbus TCP EtherNet IP Manual S1A28701 02
No ratings yet
ATV32 Modbus TCP EtherNet IP Manual S1A28701 02
146 pages
Lib M Bus Master
No ratings yet
Lib M Bus Master
283 pages
Master ONE: Modbus TCP/IP Option Instruction Manual
No ratings yet
Master ONE: Modbus TCP/IP Option Instruction Manual
25 pages
Master ONE: Modbus TCP/IP Option Instruction Manual
No ratings yet
Master ONE: Modbus TCP/IP Option Instruction Manual
25 pages
AC500 - V3 - Modbus - RTU - TCP With Third Party Devices
No ratings yet
AC500 - V3 - Modbus - RTU - TCP With Third Party Devices
43 pages
FieldTalk Modbus Master PDF
No ratings yet
FieldTalk Modbus Master PDF
261 pages
Modbus/TCP Client Support: Additional Important Product Information For Release 3.83
No ratings yet
Modbus/TCP Client Support: Additional Important Product Information For Release 3.83
11 pages
CycloneTCP Migration Guide
No ratings yet
CycloneTCP Migration Guide
17 pages
CP1L-EL - EM Modbus TCP Client Socket Services PDF
No ratings yet
CP1L-EL - EM Modbus TCP Client Socket Services PDF
7 pages
Modbus Protocol
No ratings yet
Modbus Protocol
5 pages
Logix AOI For Modbus TCP - The Reynolds Company - Blog
No ratings yet
Logix AOI For Modbus TCP - The Reynolds Company - Blog
3 pages
Technical Document: Niagara Modbus Guide
No ratings yet
Technical Document: Niagara Modbus Guide
74 pages
Moxa Industrial Protocol Users Guide v6.4
No ratings yet
Moxa Industrial Protocol Users Guide v6.4
85 pages
MTCP CP1L Server E
No ratings yet
MTCP CP1L Server E
6 pages
Modbus TCP 13-20230801092526
No ratings yet
Modbus TCP 13-20230801092526
63 pages
Modbus TCP 7
No ratings yet
Modbus TCP 7
50 pages
Intesis Ibox-Mbs-Ocpp Datasheet r1-0
No ratings yet
Intesis Ibox-Mbs-Ocpp Datasheet r1-0
2 pages
Modbus V2 04 TCP 001
No ratings yet
Modbus V2 04 TCP 001
55 pages
Modbus_TCP_IP
No ratings yet
Modbus_TCP_IP
6 pages
Industrial Protocols Users Guide 6e
No ratings yet
Industrial Protocols Users Guide 6e
75 pages
Lantronix Modbus Protocol UsersGuide
No ratings yet
Lantronix Modbus Protocol UsersGuide
28 pages
AC500 Ethernet Modbus TCP Handling Sockets
No ratings yet
AC500 Ethernet Modbus TCP Handling Sockets
15 pages
M340 Serial Link Manual
No ratings yet
M340 Serial Link Manual
296 pages
Modbus TCP 6
No ratings yet
Modbus TCP 6
48 pages
117-4417588-D03 Protocol Manual Modbus Host
No ratings yet
117-4417588-D03 Protocol Manual Modbus Host
68 pages
Dokumen - Tips Tia Portal v13 s7 1200 PLC Modbus TCP Server Amp Modbus
No ratings yet
Dokumen - Tips Tia Portal v13 s7 1200 PLC Modbus TCP Server Amp Modbus
10 pages
98393520_0323_Modbus_for_Dedicated_Controls_IO_GB
No ratings yet
98393520_0323_Modbus_for_Dedicated_Controls_IO_GB
96 pages
COM600 3.5 Modbus TCP Slave OPC Usg 756914 ENb
No ratings yet
COM600 3.5 Modbus TCP Slave OPC Usg 756914 ENb
56 pages
Mdrs
No ratings yet
Mdrs
36 pages
Digital Microwave Radio Systems MDRS 155: OSPF Functions and Commands
No ratings yet
Digital Microwave Radio Systems MDRS 155: OSPF Functions and Commands
36 pages
Open Modbus TCP Specifications
No ratings yet
Open Modbus TCP Specifications
24 pages
1678 Modbus TCP Protocol Guide
No ratings yet
1678 Modbus TCP Protocol Guide
56 pages
Open Modbus/Tcp Specification: Release 1.0, 29 March 1999
No ratings yet
Open Modbus/Tcp Specification: Release 1.0, 29 March 1999
23 pages
Modbusplustoethernet Bridge Schneider GPL
No ratings yet
Modbusplustoethernet Bridge Schneider GPL
87 pages
Niagara AX Modbus Guide
No ratings yet
Niagara AX Modbus Guide
72 pages