MODBUS interface description

• General description
• FC3 functions
• FC16 functions
• FC23 functions
• Exception code description
• S7 compatibility

Introduction

This document describes the protocol used by the MODBUS server of the module.
The OPEN MODBUS protocol is based on the widely known MODBUS protocol.
OPEN MODBUS is an open protocol and is not manufacturer dependent.
It is mainly used to connect PLC and I/O devices.

Why a MODBUS Server on the MSX-E modules?

Thanks to the MODBUS server, it is possible to manage an MSX-E module with e.g.: a Siemens S7 PLC.
The S7 PLC can start acquisitions and read data from the MSX-E module!

Technical details

Please note that only MODBUS over TCP is standardized. Nonetheless in this present
version the server implements OPEN MODBUS/TCP class 0 and one function of the class 2 even on UDP sockets.

The MODBUS/TCP class 0 defines two types of query: FC3 and FC16.

• FC3 functions read register content from the memory of the remote system
  
• FC16 functions write new register content on the memory of the remote system
  

• FC23 functions read/write registers content from/to the memory of the remote system
  

Characteristics of this communication channel as the standardisation document describes it are:

• The default port used by the server is 512 in both UDP/IP and TCP/IP. You can change this via the web server.
• Data are sent in network order, i.e. big endian (Motorola formata). Use the standard C functions
  atons/atonl and ntohs/ntohl to convert values bigger than 1 bytes.
• Datastructures used to describe parameters that are embedded in on-wire frames must be packed.
  How to do that is compiler-dependant.

The ADDI-DATA MSX-E Modbus server offers the following extension to the standard:

• It is possible to configure the server to accept data sent in little endian (Intel format) (native order)
• In this case, the default port used is 215. You can change this via the web server.

As answer to query a client may receive an acknowledgement (named standard response onward) or an exception.
If an exception or an error occured, you can use the GetLastCommandStatus command to get the real error number (from the remote server).
Real error numbers are described for each command in the "Returns" field.

The chapter below describes the available functions and their parameters.
It also contains the precise description of all frames implied in a given action.

Functions in this group are used to read values on the module.

For new application(s) or automate communication it is recommended to use the function GetLastCommandStatusEx.

Description

Return the result of the last remote function call

Parameters:

[Response frame layout] ReturnValue: The return value of the remote function.

• 0 Always means success
• -100 means you should check Syserrno;
• for other values, check the documentation of the function

[Response frame layout] Syserrno: the value of the libc errno after the call to the remote function

[Response frame layout] Errstr: A nul-terminated string describing the error code Syserrno

Query frame layout

Response frame layout

Exception frame layout

Description

Return the result of the last remote function call

Parameters:

[Response frame layout] ReturnValue: The return value of the remote function.

• 0 Always means success
• -100 means you should check Syserrno;
• for other values, check the documentation of the function

[Response frame layout] Syserrno: the value of the libc errno after the call to the remote function

[Response frame layout] Errstr: A nul-terminated string describing the error code Syserrno

Query frame layout

Response frame layout

Exception frame layout

For new application(s) or automate communication it is recommended to use the function MXCommon__GetModuleTypeEx.

Description

Returns the type of the MSX-E Module

Parameters:

[Response frame layout] str: A 200-characters string

Query frame layout

Response frame layout

Exception frame layout

Description

Returns the type of the MSX-E Module

Parameters:

[Response frame layout] str: A 200-characters string

Query frame layout

Response frame layout

Exception frame layout

For new application(s) or automate communication it is recommended to use the function MXCommon__GetTimeEx.

Description

Get the time on the module

Parameters:

[Response frame layout] tv_sec: Number of seconds since the Epoch

[Response frame layout] tv_usec: Number of microseconds since the begin of the second

Query frame layout

Response frame layout

Exception frame layout

Description

Get the time on the module

Parameters:

[Response frame layout] tv_sec: Number of seconds since the Epoch

[Response frame layout] tv_usec: Number of microseconds since the begin of the second

Query frame layout

Response frame layout

Exception frame layout

For new application(s) or automate communication it is recommended to use the function MXCommon__TestCustomerIDEx.

Description

Permit to test the Customer ID (if the module has the right customer Key )

Parameters:

[Response frame layout] bValueArray: non crypted value array [16 bytes of random data]

[Response frame layout] bCryptedValueArray: Crypted value array [16 bytes of the crypted random data]

Query frame layout

Response frame layout

Exception frame layout

Description

Permit to test the Customer ID (if the module has the right customer Key )

Parameters:

[Response frame layout] bValueArray: non crypted value array [16 bytes of random data]

[Response frame layout] bCryptedValueArray: Crypted value array [16 bytes of the crypted random data]

Query frame layout

Response frame layout

Exception frame layout

Description

Read measured value on all modules.

Parameters:

[Response frame layout] ulValues : Array that contain the measured values, as raw or converted in the selected format.

• ulValues [0] : Module 0 value
• ulValues [1] : Module 1 value
• ulValues [2] : Module 2 value
• ulValues [3] : Module 3 value

[Response frame layout] ulMeasureErrors : Array that contain the measure errors.

• ulMeasureErrors[0] : Module 0

  • 0 : No error.
  • 1 : Amplitude error.
  • 2 : Frequency error (in fast mode is this error not relevant).
  • 3 : Amplitude and frequency error.

• ulMeasureErrors[1] : Module 1

  • 0 : No error.
  • 1 : Amplitude error.
  • 2 : Frequency error (in fast mode is this error not relevant).
  • 3 : Amplitude and frequency error.

• ulMeasureErrors[2] : Module 2

  • 0 : No error.
  • 1 : Amplitude error.
  • 2 : Frequency error (in fast mode is this error not relevant).
  • 3 : Amplitude and frequency error.

• ulMeasureErrors[3] : Module 3

  • 0 : No error.
  • 1 : Amplitude error.
  • 2 : Frequency error (in fast mode is this error not relevant).
  • 3 : Amplitude and frequency error.

Returns:

• Possible return value on the remote system (read them with GetLastCommandStatusEx):
  
  • 0 : No error.
  • -1 : means an system error occured
  • -2 : Multifunction sub module index selection error.
  • -3 : Multifunction sub module is not a SinCos module.
  • -4 : Sinus / Cosinus module not initialised
  • -100 : Read Sinus Cosinus kernel function error (see syserrno).

Query frame layout

Response frame layout

Exception frame layout

Description

Read measured value on the module 0.

Parameters:

[Response frame layout] ulValue : Measured value, as raw or converted in the selected format.

[Response frame layout] ulMeasureError: : Measure error.


• 0 : No error.
• 1 : Amplitude error.
• 2 : Frequency error (in fast mode is this error not relevant).
• 3 : Amplitude and frequency error.

Returns:

• Possible return value on the remote system (read them with GetLastCommandStatusEx):
  
  • 0 : No error.
  • -1 : means an system error occured
  • -2 : Multifunction sub module index selection error.
  • -3 : Multifunction sub module is not a SinCos module.
  • -4 : Sinus / Cosinus module not initialised
  • -100 : Read Sinus Cosinus kernel function error (see syserrno).

Query frame layout

Response frame layout

Exception frame layout

Description

Read measured value on the module 1.

Parameters:

[Response frame layout] ulValue : Measured value, as raw or converted in the selected format.

[Response frame layout] ulMeasureError : Measure error.


• 0 : No error.
• 1 : Amplitude error.
• 2 : Frequency error (in fast mode is this error not relevant).
• 3 : Amplitude and frequency error.

Returns:

• Possible return value on the remote system (read them with GetLastCommandStatusEx):
  
  • 0 : No error.
  • -1 : means an system error occured
  • -2 : Multifunction sub module index selection error.
  • -3 : Multifunction sub module is not a SinCos module.
  • -4 : Sinus / Cosinus module not initialised
  • -100 : Read Sinus Cosinus kernel function error (see syserrno).

Query frame layout

Response frame layout

Exception frame layout

Description

Read measured value on the module 2.

Parameters:

[Response frame layout] ulValue : Measured value, as raw or converted in the selected format.

[Response frame layout] ulMeasureError : Measure error.


• 0 : No error.
• 1 : Amplitude error.
• 2 : Frequency error (in fast mode is this error not relevant).
• 3 : Amplitude and frequency error.

Returns:

• Possible return value on the remote system (read them with GetLastCommandStatusEx):
  
  • 0 : No error.
  • -1 : means an system error occured
  • -2 : Multifunction sub module index selection error.
  • -3 : Multifunction sub module is not a SinCos module.
  • -4 : Sinus / Cosinus module not initialised
  • -100 : Read Sinus Cosinus kernel function error (see syserrno).

Query frame layout

Response frame layout

Exception frame layout

Description

Read measured value on the module 3.

Parameters:

[Response frame layout] ulValue : Measured value, as raw or converted in the selected format.

[Response frame layout] ulMeasureError : Measure error.


• 0 : No error.
• 1 : Amplitude error.
• 2 : Frequency error (in fast mode is this error not relevant).
• 3 : Amplitude and frequency error.

Returns:

• Possible return value on the remote system (read them with GetLastCommandStatusEx):
  
  • 0 : No error.
  • -1 : means an system error occured
  • -2 : Multifunction sub module index selection error.
  • -3 : Multifunction sub module is not a SinCos module.
  • -4 : Sinus / Cosinus module not initialised
  • -100 : Read Sinus Cosinus kernel function error (see syserrno).

Query frame layout

Response frame layout

Exception frame layout

Description

Read measured value and abosolut position on the module 0.

Parameters:

[Response frame layout] ulValue : Measured value, as raw or converted in the selected format.

[Response frame layout] ulAbsPos : Measured absolut position value, as raw or converted in the selected format and only if ulAbsPosStatus = 1.

[Response frame layout] ulAbsPosStatus : 0 if absolut position not available. 1 if absolut position available

[Response frame layout] ulMeasureError: : Measure error.


• 0 : No error.
• 1 : Amplitude error.
• 2 : Frequency error (in fast mode is this error not relevant).
• 3 : Amplitude and frequency error.

Returns:

• Possible return value on the remote system (read them with GetLastCommandStatusEx):
  
  • 0 : No error.
  • -1 : means an system error occured
  • -2 : Multifunction sub module index selection error.
  • -3 : Multifunction sub module is not a SinCos module.
  • -4 : Sinus / Cosinus module not initialised
  • -100 : Read Sinus Cosinus kernel function error (see syserrno).

Query frame layout

Response frame layout

Exception frame layout

Description

Read measured value and abosolut position on the module 1.

Parameters:

[Response frame layout] ulValue : Measured value, as raw or converted in the selected format.

[Response frame layout] ulAbsPos : Measured absolut position value, as raw or converted in the selected format and only if ulAbsPosStatus = 1.

[Response frame layout] ulAbsPosStatus : 0 if absolut position not available. 1 if absolut position available

[Response frame layout] ulMeasureError: : Measure error.


• 0 : No error.
• 1 : Amplitude error.
• 2 : Frequency error (in fast mode is this error not relevant).
• 3 : Amplitude and frequency error.

Returns:

• Possible return value on the remote system (read them with GetLastCommandStatusEx):
  
  • 0 : No error.
  • -1 : means an system error occured
  • -2 : Multifunction sub module index selection error.
  • -3 : Multifunction sub module is not a SinCos module.
  • -4 : Sinus / Cosinus module not initialised
  • -100 : Read Sinus Cosinus kernel function error (see syserrno).

Query frame layout

Response frame layout

Exception frame layout

Description

Read measured value and abosolut position on the module 2.

Parameters:

[Response frame layout] ulValue : Measured value, as raw or converted in the selected format.

[Response frame layout] ulAbsPos : Measured absolut position value, as raw or converted in the selected format and only if ulAbsPosStatus = 1.

[Response frame layout] ulAbsPosStatus : 0 if absolut position not available. 1 if absolut position available

[Response frame layout] ulMeasureError: : Measure error.


• 0 : No error.
• 1 : Amplitude error.
• 2 : Frequency error (in fast mode is this error not relevant).
• 3 : Amplitude and frequency error.

Returns:

• Possible return value on the remote system (read them with GetLastCommandStatusEx):
  
  • 0 : No error.
  • -1 : means an system error occured
  • -2 : Multifunction sub module index selection error.
  • -3 : Multifunction sub module is not a SinCos module.
  • -4 : Sinus / Cosinus module not initialised
  • -100 : Read Sinus Cosinus kernel function error (see syserrno).

Query frame layout

Response frame layout

Exception frame layout

Description

Read measured value and abosolut position on the module 3.

Parameters:

[Response frame layout] ulValue : Measured value, as raw or converted in the selected format.

[Response frame layout] ulAbsPos : Measured absolut position value, as raw or converted in the selected format and only if ulAbsPosStatus = 1.

[Response frame layout] ulAbsPosStatus : 0 if absolut position not available. 1 if absolut position available

[Response frame layout] ulMeasureError: : Measure error.


• 0 : No error.
• 1 : Amplitude error.
• 2 : Frequency error (in fast mode is this error not relevant).
• 3 : Amplitude and frequency error.

Returns:

• Possible return value on the remote system (read them with GetLastCommandStatusEx):
  
  • 0 : No error.
  • -1 : means an system error occured
  • -2 : Multifunction sub module index selection error.
  • -3 : Multifunction sub module is not a SinCos module.
  • -4 : Sinus / Cosinus module not initialised
  • -100 : Read Sinus Cosinus kernel function error (see syserrno).

Query frame layout

Response frame layout

Exception frame layout

Description

Read measured value and abosolut position on the all the modules

Parameters:

[Response frame layout] ulValues : Array that contain the measured values, as raw or converted in the selected format.

• ulValues [0] : Module 0 value
• ulValues [1] : Module 1 value
• ulValues [2] : Module 2 value
• ulValues [3] : Module 3 value

[Response frame layout] ulAbsPos : Array that contain measured absolut position value, as raw or converted in the selected format and only if ulAbsPosStatus = 1.

• ulAbsPos [0] : Module 0 absolut position value
• ulAbsPos [1] : Module 1 absolut position value
• ulAbsPos [2] : Module 2 absolut position value
• ulAbsPos [3] : Module 3 absolut position value

[Response frame layout] ulAbsPosStatus :Array that contain measured absolut position status

• ulAbsPosStatus[0] : Module 0

  • 0 : Absolut position not available.
  • 1 : Absolut position available

• ulAbsPosStatus[1] : Module 1

  • 0 : Absolut position not available.
  • 1 : Absolut position available

• ulAbsPosStatus[2] : Module 2

  • 0 : Absolut position not available.
  • 1 : Absolut position available

• ulAbsPosStatus[3] : Module 3

  • 0 : Absolut position not available.
  • 1 : Absolut position available

[Response frame layout] ulMeasureErrors : Array that contain the measure errors.

• ulMeasureErrors[0] : Module 0

  • 0 : No error.
  • 1 : Amplitude error.
  • 2 : Frequency error (in fast mode is this error not relevant).
  • 3 : Amplitude and frequency error.

• ulMeasureErrors[1] : Module 1

  • 0 : No error.
  • 1 : Amplitude error.
  • 2 : Frequency error (in fast mode is this error not relevant).
  • 3 : Amplitude and frequency error.

• ulMeasureErrors[2] : Module 2

  • 0 : No error.
  • 1 : Amplitude error.
  • 2 : Frequency error (in fast mode is this error not relevant).
  • 3 : Amplitude and frequency error.

• ulMeasureErrors[3] : Module 3

  • 0 : No error.
  • 1 : Amplitude error.
  • 2 : Frequency error (in fast mode is this error not relevant).
  • 3 : Amplitude and frequency error.

Returns:

• Possible return value on the remote system (read them with GetLastCommandStatusEx):
  
  • 0 : No error.
  • -1 : means an system error occured
  • -2 : Multifunction sub module index selection error.
  • -3 : Multifunction sub module is not a SinCos module.
  • -4 : Sinus / Cosinus module not initialised
  • -100 : Read Sinus Cosinus kernel function error (see syserrno).

Query frame layout

Response frame layout

Exception frame layout

Description

Read all the digital I/O channel value. If channel is configured as output, then this function return the status of the output

Parameters:

[Response frame layout]ulChannelsValue : Channels value

Returns:

• Possible return value on the remote system (read them with GetLastCommandStatusEx):
  • 0 : No error.
  • -1 : Means an system error occured
  • -100 : Kernel function error (see syserrno).

Query frame layout

Response frame layout

Exception frame layout

Description