Colway Solutions
Modbus Member Logo

MSPL - C Reference

 

6.1        MSPL-C Data Types

These data types are defined in CSPL_MbDefs.h

MSPL-C Data type

Native definition

CSPL_U8

unsigned char

CSPL_U16

unsigned short int

CSPL_U32

unsigned int

CSPL_I8

char

CSPL_I16

short int

CSPL_I32

int

CSPL_BOOL

typedef enum _CSPL_BOOL

{

CSPL_FALSE,

CSPL_TRUE

}CSPL_BOOL;

 

6.2        MSPL-C Function Reference

6.2.1       MSPL_UserInit

Function name

MSPL_UserInit

Description

This function is called by MSPL_Init() in order to allow any user/application specific initialisation to be done. This is a good place, for instance, to create/link to any synchronisation semaphores, initialise your own application globals or print some start up messages.

Returns

CSPL_BOOL. A status code. This code is passed back by MSPL_Init() to its caller who can take appropriate action on failure.

Possible return values

CSPL_TRUE - All user/application specific initialisation went OK.

CSPL_FALSE - Something went wrong during user de-initialisation.

Arguments

None

Called by

Library

User Implements?

Yes

 

6.2.2       MSPL_UserDeInit

Function name

MSPL_ UserDeInit

Description

This function is called by the MSPL_DeInit() function of the library in order to allow any user/application specific de-initialisation/cleanup to be done. This is a good place, for instance, to close handles to any operating system objects that the application code might be using.

Returns

CSPL_BOOL. A status code. This code is passed back by MSPL_DeInit() to its caller who can take appropriate action on failure.

Possible return values

CSPL_TRUE - All user/application specific de-initialisation went OK.

CSPL_FALSE - Something went wrong during user de-initialisation.

Arguments

None

Called by

Library

User Implements?

Yes

 

6.2.3       MSPL_OpenPort

Function name

MSPL_ OpenPort

Description

This function should open communication port and initialise it so as to get it ready for receiving Modbus packets and sending responses.

This is the place to set all communication parameters like baud rate, parity, port timeouts etc. This function is not internally called by the library but must be called by the user during start up of his application, once for each port that will support Modbus communication.

Returns

CSPL_U8. A value indicating if the specified port was opened and initialised successfully or not.

Possible return values

CSPL_TRUE - The specified port was opened and initialised successfully.

CSPL_FALSE - The specified port could not be opened or initialised.

Arguments

CSPL_U8 networkNo

A number identifying the "port" or channel used for Modbus communication that is to be initialised.

Called by

User application

User Implements?

Yes

 

6.2.4       MSPL_ClosePort

Function name

MSPL_ ClosePort

Description

The implementation of this function should close the specified port and release all resources held by it. This function is not called directly by the library. It must instead be called by the user of the library when Modbus support on a communication port is no longer required.

Returns

CSPL_U8. A value indicating success or failure of the function.

Possible return values

CSPL_TRUE - The port was closed successfully.

CSPL_FALSE - The port could not be closed successfully.

Arguments

CSPL_U8 networkNo

A number identifying the "port" or channel to be closed.

Called by

User application

User Implements?

Yes

 

6.2.5       MSPL_CheckSlaveId

Function name

MSPL_CheckSlaveId

Description

This function is called by the library soon after it reads the Slave ID field from a Modbus ADU in order to know if the Modbus packet is intended for this device or not. The implementation of this function should return a value indicating if the packet is to be processed further or not.

Returns

CSPL_BOOL. A value indicating if the slave ID passed identifies this device or not.

Possible return values

CSPL_TRUE - Slave ID passed identifies this device and so this Modbus ADU may be processed further.

CSPL_FALSE - Slave ID passed does not identify this device.

Arguments

CSPL_U8 slaveID

The slave ID to be validated.

CSPL_U8 networkNo

The network on which this Modbus ADU was received. this parameter may be ignored if the device presents itself on all the networks with the same slave ID.

Called by

Library

User Implements?

Yes

 

6.2.6       MSPL_ValidateAddresses

Function name

MSPL_ ValidateAddresses

Description

This function is called by the library to check if the combination of data address range and the function code in the Modbus PDU is valid for this device.

Returns

CSPL_BOOL. A value indicating if the address range is valid or not. If not, the library responds to this ADU with an ILLEGAL DATA ADDRESS (0x02) Exception response.

Possible return values

CSPL_TRUE - The address range is valid.

CSPL_FALSE - The address range is not valid.

Arguments

CSPL_U8 slaveID

A single byte value containing the slave ID of the ADU for which the data addresses are to be validated.

The slave ID is useful in cases where the library is being used to implement a virtual multi slave device where validation of addresses will be different for different slave ID’s. If the device behaviour is independent of the slave ID to which a Modbus request is addressed to, then this parameter may be ignored.

CSPL_U8 networkNo

The network on which this Modbus ADU was received. If the device behaviour is independent of the network on which a Modbus request is received, then this parameter may be ignored.

CSPL_U8 functionCode

A single byte value of the Modbus function code associated with the data addresses to be validated.

CSPL_U16 startAddress

A two-byte value that is the first address in the range to be validated.

CSPL_U16 noOfItems

A two-byte value that is the number of addresses starting from startAddress that are to be validated.

Called by

Library

User Implements?

Yes

 

6.2.7       MSPL_ReadUserData

Function name

MSPL_ ReadUserData

Description

The library calls this function for all PDU's that contain a Modbus "read" service request and expects its implementation to copy the relevant data from the user's database to the buffer it passes as one of the arguments. The buffer passed for holding the data must be filled in a specific format as indicated below, the format itself being data type specific. Helper functions are provided in file CSPL_Utils.c to assist the user in easily filling this buffer in the correct format. The formats have been chosen to keep the usage of memory to the minimum.

Type of data

Format in which data is to be stored in pBuffer

Bit Status

Bit stuffed as 8 status information in one byte

Registers

One register as two consecutive bytes in big endian format

Returns

CSPL_U8. A value indicating if the read request was processed successfully or not.

Possible return values

= 0 - if the service request executed successfully

> 0 - if the service request failed in which case the library sends a SLAVE DEVICE FAILURE Exception response (code 0x04) to the Modbus master.

Arguments

CSPL_U8 slaveID

A single byte value containing the slave ID of the ADU for which the data addresses are to be validated.

The slave ID is useful in cases where the library is being used to implement a virtual multi slave device where validation of addresses will be different for different slave ID's. If the device behaviour is independent of the slave ID to which a Modbus request is addressed to, then this parameter may be ignored.

CSPL_U8 networkNo

The network on which this Modbus ADU was received. If the device behaviour is independent of the network on which a Modbus request is received, then this parameter may be ignored.

CSPL_U8 functionCode

A single byte value of the Modbus function code that defines the Modbus service request. This parameter can be checked to see what kind of data (coil, discrete input, register etc.) is being requested for.

CSPL_U16 startAddress

A two-byte value that is the first address in the range of data being requested for.

CSPL_U16 noOfItems

A two-byte value that is the number of data items starting from startAddress that are being requested for.

CSPL_U8 *pBuffer

Pointer to an array of bytes into which the requested data must be copied into in the correct format.

Appropriate helper functions may be used in stuffing the data in the right format into this buffer.

Called by

Library

User Implements?

Yes

 

6.2.8       MSPL_WriteUserData

Function name

MSPL_ WriteUserData

Description

This function is used transfer data from a Modbus PDU to the user’s database. The library calls this function for all PDU's that contain a Modbus "write" service request and expects its implementation to copy the relevant data from the buffer it passes as one of the arguments to the user’s database. The buffer passed contains the PDU data in a specific format as described below. Helper functions are provided in file CSPL_Utils.c to assist the user in easily decoding and copying data in this buffer to his application's database. The formats have been chosen to keep the usage of memory to the minimum.

Type of data

Format in which data is stored in pBuffer

Bit Status

Bit stuffed as 8 status information in one byte

Registers

One register as two consecutive bytes in big endian format

Returns

CSPL_U8. A value indicating if the write request was processed successfully or not.

Possible return values

= 0 - if the service request executed successfully

> 0 - if the service request failed in which case the library sends a SLAVE DEVICE FAILURE Exception response (code 0x04) to the Modbus master.

Arguments

CSPL_U8 slaveID

A single byte value containing the slave ID of the ADU for which the data addresses are to be validated.

The slave ID is useful in cases where the library is being used to implement a virtual multi slave device where validation of addresses will be different for different slave ID's. If the device behaviour is independent of the slave ID to which a Modbus request is addressed to, then this parameter may be ignored.

CSPL_U8 networkNo

The network on which this Modbus ADU was received. If the device behaviour is independent of the network on which a Modbus request is received, then this parameter may be ignored.

CSPL_U8 functionCode

A single byte value of the Modbus function code that defines the Modbus service request. This parameter can be checked to see what kind of data (coil, discrete input, register etc.) is present in the buffer and which Modbus service is being used to write the data.

CSPL_U16 startAddress

A two-byte value that is the first address in the range of data being written to.

CSPL_U16 noOfItems

A two-byte value indicating the number of data items starting from startAddress that are being written to.

If functionCode is 0x05 or 0x06 then noOfItems will be '1'.

CSPL_U8 *pBuffer

Pointer to an array of bytes containing the data. The library fills this buffer with data from the received PDU.

Called by

Library

User Implements?

Yes

 

6.2.9       MSPL_ReadPort

Function name

MSPL_ ReadPort

Description

This function is called by the library to read a Modbus packet from a communication port.

Returns

CSPL_U8. A value indicating success or failure of the function.

Possible return values

CSPL_TRUE - if the function is able to read at least one byte from the port before a read timeout occurs. The actual number of bytes read should be stored in pNoOfBytesRead.

CSPL_FALSE - if the function is unable to read any byte from the port before a read timeout occurs or if it encounters an error in reading the port. In this case an error code indicating the reason for failure should be stored in pErrorCode argument.

Arguments

CSPL_U8 networkNo

A number identifying the "port" to be read.

CSPL_U16 noOfBytesToRead

The number of bytes to read on this port.

CSPL_U16 *pNoOfBytesRead

A pointer to the variable that receives the actual number of bytes read.

CSPL_U8 *pBuffer

A pointer to the buffer that receives the data read from the port.

CSPL_U8 *pErrorCode

A pointer to the variable that receives an error code in case of failure of this function.

Called by

Library

User Implements?

Yes

 

6.2.10  MSPL_WritePort

Function name

MSPL_ WritePort

Description

This function is called by the library to write a Modbus response packet to a communication port.

Returns

CSPL_U8. A value indicating success or failure of the function.

Possible return values

CSPL_TRUE - if the function is able to write at least one byte to the port before a write timeout occurs. The actual number of bytes written should be stored in pNoOfBytesWritten.

CSPL_FALSE - if the function is unable to write any byte to the port before a write timeout occurs or if it encounters an error in writing to the port. In this case an error code indicating the reason for failure should be stored in pErrorCode argument.

Arguments

CSPL_U8 networkNo

A number identifying the "port" to be read.

CSPL_U16 noOfBytesToWrite

The number of bytes to write to this port.

CSPL_U16 * pNoOfBytesWritten

A pointer to the variable that receives the actual number of bytes written.

CSPL_U8 *pBuffer

A pointer to the buffer containing the data to be written to the port.

CSPL_U8 *pErrorCode

A pointer to the variable that receives an error code in case of failure of this function.

Called by

Library

User Implements?

Yes

 

6.2.11  MSPL_DebugPrint

Function name

MSPL_ DebugPrint

Description

The library calls this function to output a debug message. Users may implement this function to sink the debug message to an output device of their choice (e.g. to a printer, to an LCD, to a file and so on.). This function is called only when debugging is enabled by way of macro DEBUG_LEVEL.

Returns

None

Arguments

CSPL_U8 networkNo

The network on which a Modbus transaction was occurring that caused this debug message. This argument enables redirecting of debug prints from different networks to different sinks so that they do not all get jumbled.

CSPL_U8 eventType

The debug level of this message. Possible values are:

         DEBUG_VERBOSE

         DEBUG_INFORMATION

         DEBUG_WARNING

         DEBUG_ERROR.

A possible use of this information is to print debug messages of different levels in different colours.

CSPL_CHAR* debugMessage

A null-terminated 'C' string containing the debug message.

Called by

Library

User Implements?

Yes

 

6.2.12  MSPL_RunModbus

Function name

MSPL_RunModbus

Description

This is the entry point function into the library which must be run periodically to execute the Modbus stack. When called, it reads the channel (passed as an argument) to check if any data has been received. If so, it attempts to process the packet received as a Modbus frame and if required sends out a response.

Returns

CSPL_U8. A status code as shown in section below titled "Status codes returned by function MSPL_RunModbus"

Arguments

CSPL_U8 networkNo

The channel on which this function must look for a Modbus packet. The library passes this parameter to every hook function that it calls from MSPL_UserIf.h. Since this function processes one channel at a time, it must be called once for every channel configured for Modbus in your system.

Called by

User application

User Implements?

No

 

6.2.13   Status codes returned by function MSPL_RunModbus

The following error codes may be returned by the main entry point function MSPL_RunModbus. They are defined in CSPL_MbDefs.h

 

Error

Code

Remarks

MSPL_NO_ERROR

0x00

No error was encountered and the function executed successfully

UNKNOWN_ERROR

0x01

An unknown error occurred reading / writing to port. This indicates that the underlying device driver API for read/write returned an unknown code when invoked.

INVALID_HANDLE

0x02

An invalid handle or path ID was used to read from / write to the port.

INVALID_NETWORKNUM

0x03

An uninitialized network number was passed as a parameter. Indicates that an attempt was made to use a channel that has not been initialised with a call to MSPL_OpenPort().

READ_WRITE_FAIL

0x04

Device failure reading / writing to port. Indicates that the underlying device driver API for read/write returned an error code.

READ_WRITE_TIMEOUT

0x05

Timeout occurred reading / writing bytes. Indicates that the library called MSPL_ReadPort which returned with no data but a timeout.

ID_MISMATCH

0x06

The slave ID found in the Modbus request does not match this device. Indicates that the library encountered a message that was directed to a different slave. In case of Modbus RTU, this could occur frequently when using a shared bus like RS485 whereas in case of Modbus TCP, this error code indicates a true errpr.

CRC_ERR

0x07

The message contained incorrect CRC Bytes. Indicates a corrupt message. Modbus RTU only.

BUFFER_TOO_SMALL

0x08

The request message has more bytes than the available size of buffer. Indicates that the master is trying to read or write too many Modbus data units that the block sizes configured for the library.

PORT_CLOSED

0x09

The communication port was closed when trying to read or write on it. This error commonly occurs when a TCP connection is closed just when the library was trying to read from the channel.

INVALID_FC

0x0A

An invalid/unsupported function code was requested to be serviced.

 

6.2.14  MSPL_GetMessageCounters

Function name

MSPL_GetMessageCounters

Description

This function provides the value of various message counters maintained by the stack.

Returns

MSPL_MB_MSG_CTRS. A structure containing the counters maintained by the stack. See section below titled "Structure MSPL_MB_MSG_CTRS" for details of these counters.

Arguments

CSPL_U8 networkNo

The channel whose counters are being requested. The stack maintains an exclusive set of counters for each channel.

Called by

User application

User Implements?

No

 

6.2.14.1  Structure MSPL_MB_MSG_CTRS

Member

Data Type

Description of the counter

busMsgCnt

CSPL_U32

Quantity of messages that the remote device has detected on the communication channel since its last restart, clear counters operation or power-up.

busCommErrCnt

CSPL_U32

Quantity of CRC errors encountered by the remote device on this channel since its last restart, clear counters operation or power-up. This member is present only in Modbus RTU mode.

busExcpErrCnt

CSPL_U32

Quantity of MODBUS exception responses returned by the remote device since its last restart, clear counters operation or power-up.

slvMsgCnt

CSPL_U32

Quantity of messages addressed to the remote device, or broadcast on this channel, that the remote device has processed since its last restart, clear counters operation, or power-up.

 

Back to Index

Privacy Policy Site Map FAQ Contact Us