Colway Solutions
Modbus Member Logo

MMPL - C Reference

 

4.1        MMPL-C Data Types

These data types are defined in MMPL_Defs.h

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

 

4.2        MMPL-C Function Reference

 

4.2.1       MMPL_OpenPort

Function name

MMPL_ 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

 

4.2.2       MMPL_ClosePort

Function name

MMPL_ 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

 

4.2.3       MMPL_ReadPort

Function name

MMPL_ 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

 

4.2.4  MMPL_WritePort

Function name

MMPL_ 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

 

4.2.5  MMPL_DebugPrint

Function name

MMPL_ 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_CHAR* debugMessage

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

Called by

Library

User Implements?

Yes

 

4.2.6  MMPL_SendRequest

Function name

MMPL_SendRequest

Description

MMPL_SendRequest function constructs and sends Modbus request

Returns

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

Arguments

MMPL_MB_REQ_ADU *pMbReqAdu

Used to hold the Modbus request ADU to be sent to the slave.

MMPL_MB_RSP_ADU *pMbRspAdu

Used to hold the Modbus response ADU received from the slave.

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.

CSPL_U8 slaveNo

A single byte value containing the slave ID of the device from which data is being requested.

CSPL_U8 functionfode

A single byte value of the Modbus function code that defines the Modbus service request.

CSPL_U16 startAddress

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

CSPL_U16 numItems

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

CSPL_U8 *dataBuffer

-> (OUT): Pointer to an array of bytes into which the requested data must be copied into in the correct format for 'Read' FCs.

-> (IN): Pointer to an array of bytes containing the data that has to be 'written' to slave.

Called by

User application

User Implements?

No

 

4.2.7  MMPL_RecvAndProcessResp

Function name

MMPL_RecvAndProcessResp

Description

MMPL_RecvAndProcessResp function receives and processes slave response

Returns

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

Arguments

MMPL_MB_REQ_ADU *pMbReqAdu

Used to hold the Modbus request ADU to be sent to the slave.

MMPL_MB_RSP_ADU *pMbRspAdu

Used to hold the Modbus response ADU received from the slave.

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.

CSPL_U8 slaveNo

A single byte value containing the slave ID of the device from which data is being requested.

CSPL_U8 functionfode

A single byte value of the Modbus function code that defines the Modbus service request.

CSPL_U16 startAddress

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

CSPL_U16 numItems

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

CSPL_U8 *dataBuffer

-> (OUT): Pointer to an array of bytes into which the requested data must be copied into in the correct format for 'Read' FCs.

-> (IN): Pointer to an array of bytes containing the data that has to be 'written' to slave.

Called by

User application

User Implements?

No

 

4.2.8  DoModbusTransaction

Function name

DoModbusTransaction

Description

This method is the main function that drives Modbus communication on a network.

Returns

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

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.

CSPL_U8 slaveNo

A single byte value containing the slave ID of the device from which data is being requested.

CSPL_U8 functionfode

A single byte value of the Modbus function code that defines the Modbus service request.

CSPL_U16 startAddress

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

CSPL_U16 numItems

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

CSPL_U8 *dataBuffer

-> (OUT): Pointer to an array of bytes into which the requested data must be copied into in the correct format for 'Read' FCs.

-> (IN): Pointer to an array of bytes containing the data that has to be 'written' to slave.

CSPL_U8 numRetries

The number of times to retry communication with slave.

Called by

User application

User Implements?

No

 

4.2.7   Status codes returned by function DoModbusTransaction, MMPL_SendRequest and MMPL_RecvAndProcessResp "

The following error codes may be returned by the main entry point function DoModbusTransaction, MMPL_SendRequest and MMPL_RecvAndProcessResp. They are defined in MMPL_Defs.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 MMPL_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 MMPL_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.

TXID_MISMATCH

0x0B

The Transaction ID of the Modbus request does not match the response's Transaction ID.

INVALID_PROTCODE

0x0C

Invalid Protocol code in the response.

EXCEPTION_RESPONSE

0x0D

Exception response from slave.

FC_MISMATCH

0x0E

The function code of the Modbus request does not match the response's function code.

INVALID_BYTECNT

0x0F

Invalid Byte count in the response.

INVALID_DATA_VALUE

0x10

Invalid Data Value.

INVALID_PKTLEN

0x12

Invalid Packet Length in the response.

INVALID_SLAVE_ADDR

0x13

Invalid Slave ID.

INVALID_NUM_ITEMS

0x14

Invalid number of items.


Back to Index


Privacy Policy Site Map FAQ Contact Us