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

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

Description

Return the number of transducer channels on the module (4,8 or 16)

Parameters:

[Response frame layout]ChannelNumber: Number of channels

Query frame layout

Response frame layout

Exception frame layout

Description

Return the number of transducer channels on the module (4,8 or 16)

Parameters:

[Response frame layout]ChannelNumber: Number of channels

Query frame layout

Response frame layout

Exception frame layout

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

Description

This function get the auto refresh counter value an the channels values

Parameters:

[Response frame layout]Value: Array that contain the counter and channels values

• Values [0]: Auto refresh counter value
  
• Values [1]: Channel 0 value
  
• ...
  
• Values [16]: Channel 15 value
  

Returns:

Possible return value on the remote system (read them with GetLastCommandStatus)
• 0 : means the remote function performed OK
  
• -100 : GetAutoRefreshAllValues kernel function error
  

Query frame layout

Response frame layout

Exception frame layout

Description

This function get the auto refresh counter value an the channels values

Parameters:

[Response frame layout]Value: Array that contain the counter and channels values

• Values [0]: Auto refresh counter value
  
• Values [1]: Channel 0 value
  
• ...
  
• Values [16]: Channel 15 value
  

Returns:

Possible return value on the remote system (read them with GetLastCommandStatusEx)
• 0 : means the remote function performed OK
  
• -100 : GetAutoRefreshAllValues kernel function error
  

Query frame layout

Response frame layout

Exception frame layout

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

Description

Read the external temperature

Parameters:

[Response frame layout] Value: External temperature value. Format depend from the initialisation

[Response frame layout] TimeStampLow: Time stamp low dword (us)

[Response frame layout] TimeStampHigh: Time stamp high dword (s)

Returns:

Possible return value on the remote system (read them with GetLastCommandStatus)

• 0: means the remote function performed OK
  
• -1: means an system error occured
  
• -2: Power save enabled and no transducer acquisition started
  
• -3: Power save enabled and transducer acquisition started but hardware trigger used
• -100: Read external temperature kernel function error
  

Query frame layout

Response frame layout

Exception frame layout

Description

Read the external temperature

Parameters:

[Response frame layout] Value: External temperature value. Format depend from the initialisation

[Response frame layout] TimeStampLow: Time stamp low dword (us)

[Response frame layout] TimeStampHigh: Time stamp high dword (s)

Returns:

Possible return value on the remote system (read them with GetLastCommandStatusEx)

• 0: means the remote function performed OK
  
• -1: means an system error occured
  
• -2: Power save enabled and no transducer acquisition started
  
• -3: Power save enabled and transducer acquisition started but hardware trigger used
• -100: Read external temperature kernel function error
  

Query frame layout

Response frame layout

Exception frame layout

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

Description

Returns the number of transducer types currently defined in the database.

Parameters:

[Query frame layout] NumberOfTransducerTypes: number of transducer types currently defined.

Returns:

• 0 : success
  
• otherwise : internal error
  

Query frame layout

Response frame layout

Exception frame layout

Description

Returns the number of transducer types currently defined in the database.

Parameters:

[Query frame layout] NumberOfTransducerTypes: number of transducer types currently defined.

Returns:

• 0 : success
  
• otherwise : internal error
  

Query frame layout

Response frame layout

Exception frame layout

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

Description

Returns the current cursor of the transducer database.

Parameters:

[Query frame layout] TransducerDatabaseCursor: Current cursor. This is an integer from 0 .. (NumberOfTransducerTypes-1)

Returns:

• 0 : success
  
• otherwise : internal error
  

Query frame layout

Response frame layout

Exception frame layout

Description

Returns the current cursor of the transducer database.

Parameters:

[Query frame layout] TransducerDatabaseCursor: Current cursor. This is an integer from 0 .. (NumberOfTransducerTypes-1)

Returns:

• 0 : success
  
• otherwise : internal error
  

Query frame layout

Response frame layout

Exception frame layout

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

Description

Returns the information stored in the database about the type selected by the current TransducerDatabaseCursor.

Parameters:

Returns:

• 0 : success
  
• otherwise : internal error
  

Query frame layout

Response frame layout

Exception frame layout

Description

Returns the information stored in the database about the type selected by the current TransducerDatabaseCursor.

Parameters:

Returns:

• 0 : success
  
• otherwise : internal error
  

Query frame layout

Response frame layout

Exception frame layout

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

Description

Initialise the primary connection test

• 0: success
  
• -1: otherwise : internal error
  
• -100> Primary connection test initialization kernel function error

Query frame layout

Response frame layout

Exception frame layout

Description

Initialise the primary connection test

• 0: success
  
• -1: otherwise : internal error
  
• -100> Primary connection test initialization kernel function error

Query frame layout

Response frame layout

Exception frame layout

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

Description

Test primary connection

Parameters:

[Response frame layout] ulValue: Connection status

• 0: connection error
  
• 1: connection ok
  

Returns:

Possible return value on the remote system (read them with GetLastCommandStatus)
• 0: success
  
• -1: otherwise : internal error
  

Query frame layout

Response frame layout

Exception frame layout

Description

Test primary connection

Parameters:

[Response frame layout] ulValue: Connection status

• 0: connection error
  
• 1: connection ok
  

Returns:

Possible return value on the remote system (read them with GetLastCommandStatusEx)
• 0: success
  
• -1: otherwise : internal error
  

Query frame layout

Response frame layout

Exception frame layout

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

Description

Test primary short circuit

Parameters:

[Response frame layout] ulValue: Connection status

• 0: connection error
  
• 1: connection ok
  

Returns:

Possible return value on the remote system (read them with GetLastCommandStatus)
• 0: success
  
• -1: otherwise : internal error
  

Query frame layout

Response frame layout

Exception frame layout

Description

Test primary short circuit

Parameters:

[Response frame layout] ulValue: Connection status

• 0: connection error
  
• 1: connection ok
  

Returns:

Possible return value on the remote system (read them with GetLastCommandStatusEx)
• 0: success
  
• -1: otherwise : internal error
  

Query frame layout

Response frame layout

Exception frame layout

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

Description

Rearm primary

Parameters:

[Response frame layout] ulValue: Rearm status

• 0: Rearm not ok
  
• 1: Rearm ok
  

Returns:

Possible return value on the remote system (read them with GetLastCommandStatus)
• 0: success
  
• -1: otherwise : internal error
  

Query frame layout

Response frame layout

Exception frame layout

Description

Rearm primary

Parameters:

[Response frame layout] ulValue: Rearm status

• 0: Rearm not ok
  
• 1: Rearm ok
  

Returns:

Possible return value on the remote system (read them with GetLastCommandStatusEx)
• 0: success
  
• -1: otherwise : internal error
  

Query frame layout

Response frame layout

Exception frame layout

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

Description

Test the secondary connection for channel 0 (you must call the MX371X__TransducerSelectChannel function before to select the channel you want to use )

Parameters:

[Response frame layout] ulValue: Connection status

• 0: connection error
  
• 1: connection ok
  

Returns:

Possible return value on the remote system (read them with GetLastCommandStatus)
• 0: success
  
• -1: otherwise : internal error
  

Query frame layout

Response frame layout

Exception frame layout

Description

Test the secondary connection for channel 0 (you must call the MX371X__TransducerSelectChannel function before to select the channel you want to use )

Parameters:

[Response frame layout] ulValue: Connection status

• 0: connection error
  
• 1: connection ok
  

Returns:

Possible return value on the remote system (read them with GetLastCommandStatusEx)
• 0: success
  
• -1: otherwise : internal error
  

Query frame layout

Response frame layout

Exception frame layout

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

Description

Test the secondary connection for channel 1(you must call the MX371X__TransducerSelectChannel function before to select the channel you want to use )

Parameters:

[Response frame layout] ulValue: Connection status

• 0: connection error
  
• 1: connection ok
  

Returns:

Possible return value on the remote system (read them with GetLastCommandStatus)
• 0: success
  
• -1: otherwise : internal error
  

Query frame layout

Response frame layout

Exception frame layout

Description

Test the secondary connection for channel 1(you must call the MX371X__TransducerSelectChannel function before to select the channel you want to use )

Parameters:

[Response frame layout] ulValue: Connection status

• 0: connection error
  
• 1: connection ok
  

Returns:

Possible return value on the remote system (read them with GetLastCommandStatusEx)
• 0: success
  
• -1: otherwise : internal error
  

Query frame layout

Response frame layout

Exception frame layout

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

Description

Test the secondary connection for channel 2(you must call the MX371X__TransducerSelectChannel function before to select the channel you want to use )

Parameters:

[Response frame layout] ulValue: Connection status

• 0: connection error
  
• 1: connection ok
  

Returns:

Possible return value on the remote system (read them with GetLastCommandStatus)
• 0: success
  
• -1: otherwise : internal error
  

Query frame layout

Response frame layout

Exception frame layout

Description

Test the secondary connection for channel 2(you must call the MX371X__TransducerSelectChannel function before to select the channel you want to use )

Parameters:

[Response frame layout] ulValue: Connection status

• 0: connection error
  
• 1: connection ok
  

Returns:

Possible return value on the remote system (read them with GetLastCommandStatusEx)
• 0: success
  
• -1: otherwise : internal error
  

Query frame layout

Response frame layout

Exception frame layout

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

Description

Test the secondary connection for channel 3(you must call the MX371X__TransducerSelectChannel function before to select the channel you want to use )

Parameters:

[Response frame layout] ulValue: Connection status

• 0: connection error
  
• 1: connection ok
  

Returns:

Possible return value on the remote system (read them with GetLastCommandStatus)
• 0: success
  
• -1: otherwise : internal error
  

Query frame layout

Response frame layout

Exception frame layout

Description

Test the secondary connection for channel 3(you must call the MX371X__TransducerSelectChannel function before to select the channel you want to use )

Parameters:

[Response frame layout] ulValue: Connection status

• 0: connection error
  
• 1: connection ok
  

Returns:

Possible return value on the remote system (read them with GetLastCommandStatusEx)
• 0: success
  
• -1: otherwise : internal error
  

Query frame layout

Response frame layout

Exception frame layout

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

Description

Test the secondary connection for channel 4(you must call the MX371X__TransducerSelectChannel function before to select the channel you want to use )

Parameters:

[Response frame layout] ulValue: Connection status

• 0: connection error
  
• 1: connection ok
  

Returns:

Possible return value on the remote system (read them with GetLastCommandStatus)
• 0: success
  
• -1: otherwise : internal error
  

Query frame layout

Response frame layout

Exception frame layout

Description

Test the secondary connection for channel 4(you must call the MX371X__TransducerSelectChannel function before to select the channel you want to use )

Parameters:

[Response frame layout] ulValue: Connection status

• 0: connection error
  
• 1: connection ok
  

Returns:

Possible return value on the remote system (read them with GetLastCommandStatusEx)
• 0: success
  
• -1: otherwise : internal error
  

Query frame layout

Response frame layout