MODBUS Porting Layer (Serial)
[MODBUS Porting Layer]


Typedefs

typedef BOOL(* pbMBPSerialTransmitterEmptyAPIV1CB )(xMBHandle xHdl, UBYTE *pubValue) MB_CDECL_SUFFIX
typedef void(* pvMBPSerialReceiverAPIV1CB )(xMBHandle xHdl, UBYTE ubValue)
typedef BOOL(* pbMBPSerialTransmitterEmptyAPIV2CB )(xMBHandle xHdl, UBYTE *pubBufferOut, USHORT usBufferMax, USHORT *pusBufferWritten) MB_CDECL_SUFFIX
typedef void(* pvMBPSerialReceiverAPIV2CB )(xMBHandle xHdl, const UBYTE *pubBufferIn, USHORT usBufferLen) MB_CDECL_SUFFIX
typedef void * pbMBPSerialTransmitterEmptyCB
typedef void * pvMBPSerialReceiverCB

Functions

eMBErrorCode eMBPSerialInit (xMBPSerialHandle *pxSerialHdl, UCHAR ucPort, ULONG ulBaudRate, UCHAR ucDataBits, eMBSerialParity eParity, UCHAR ucStopBits, xMBHandle xMBHdl)
eMBErrorCode eMBPSerialClose (xMBPSerialHandle xSerialHdl)
eMBErrorCode eMBPSerialTxEnable (xMBPSerialHandle xSerialHdl, pbMBPSerialTransmitterEmptyCB pbMBPTransmitterEmptyFN)
eMBErrorCode eMBPSerialRxEnable (xMBPSerialHandle xSerialHdl, pvMBPSerialReceiverCB pvMBPReceiveFN)

Typedef Documentation

typedef BOOL( * pbMBPSerialTransmitterEmptyAPIV1CB)(xMBHandle xHdl, UBYTE *pubValue) MB_CDECL_SUFFIX
 

This function is called by the porting layer if the transmitter is ready to accept new characters.

The function should either store a new byte in the pointer ubValue and return TRUE indicating that there is a character to transmit or it should return FALSE. If the function returns FALSE the transmitter is automatically disabled by the porting layer.

Parameters:
xHdl The handle passed to the eMBPSerialInit function.
pubValue A pointer where the character to transmit should be stored.
Returns:
TRUE if there are more characters to transmit. Otherwise FALSE and the transmitter should be disabled.

typedef BOOL( * pbMBPSerialTransmitterEmptyAPIV2CB)(xMBHandle xHdl, UBYTE *pubBufferOut, USHORT usBufferMax, USHORT *pusBufferWritten) MB_CDECL_SUFFIX
 

Called by the porting layer if the transmitter can accept new data and APIV2 is enabled.

This function should be called by the porting layer when the transmitter is enabled an new character can be accepted. The MODBUS stack will write up to usBufferMax character into the buffer pubBufferOut. It will store the number of bytes written in the variable pusBufferWritten.

Parameters:
xHdl The handle passed to the eMBPSerialInit function.
pubBufferOut A buffer of usBufferMax bytes.
pusBufferWritten Set by the stack to the number of bytes written.
Returns:
FALSE if no more characters will be sent. In this case the transmitter should be disabled automatically by the porting layer. Otherwise TRUE to indicate that there are more characters waiting.

typedef void* pbMBPSerialTransmitterEmptyCB
 

Abstract type which points either to the API V1 or API V2 functions depending on the setting of MBS_SERIAL_API_VERSION.

If API V1 is enabled a variable of this type holds a function pointer of type pbMBPSerialTransmitterEmptyAPIV1CB. If API V2 is enabled it holds a pointer of type pbMBPSerialTransmitterEmptyAPIV2CB.

typedef void( * pvMBPSerialReceiverAPIV1CB)(xMBHandle xHdl, UBYTE ubValue)
 

This function should be called when a new character has been received by the porting layer.

Parameters:
xHdl The handle passed to the eMBPortSerialInit function.
ubValue The character received. Only valid characters should be passed to the stack.

typedef void( * pvMBPSerialReceiverAPIV2CB)(xMBHandle xHdl, const UBYTE *pubBufferIn, USHORT usBufferLen) MB_CDECL_SUFFIX
 

Called by the porting layer if new data is available and API V2 is enabled.

If the receiver is enabled the porting layer should call this function whenever there is new data available. The number of bytes available is passed in usBufferLen.

Parameters:
pubBufferIn Buffer holding usBufferLen bytes.
usBufferLen Length of the buffer.

typedef void* pvMBPSerialReceiverCB
 

Abstract type which points either to the API V1 or API V2 functions depending on the setting of MBS_SERIAL_API_VERSION.

If API V1 is enabled a variable of this type holds a function pointer of type pvMBPSerialReceiverAPIV1CB. If API V2 is enabled it holds a pointer of type pvMBPSerialReceiverAPIV2CB.

Function Documentation

eMBErrorCode eMBPSerialClose (  xMBPSerialHandle  xSerialHdl  ) 
 

Close a serial port.

This function should release all resources used by this instance such that it can be used again.

Parameters:
xSerialHdl A valid handle for a serial port.
Returns:
eMBErrorCode::MB_ENOERR If the port has been released. eMBErrorCode::MB_EAGAIN if the function should be called again because a shutdown is not possible right now. eMBErrorCode::MB_EINVAL if the handle is not valid. All other errors should be mapped to eMBErrorCode::MB_EPORTERR.

eMBErrorCode eMBPSerialInit (  xMBPSerialHandle *  pxSerialHdl,
UCHAR  ucPort,
ULONG  ulBaudRate,
UCHAR  ucDataBits,
eMBSerialParity  eParity,
UCHAR  ucStopBits,
xMBHandle  xMBHdl
) 
 

This function should initialize a new serial port and return a handle to it.

Note:
The serial port should start in the disabled mode. I.e. it should behave the same as if the transmitter and the receiver has been disabled by the appropriate calls.
Parameters:
pxSerialHdl A pointer to a serial handle. If the function returns MBP_ENOERR this value must hold a valid handle.
ucPort A porting layer dependent number to distinguish between different serial ports.
ulBaudRate The baudrate. For example 38400.
ucDataBits Number of databits. Values used are 8 and 7.
eParity The parity.
ucStopBits Either one or two stopbits.
xMBHdl A MODBUS stack handle. This should be passed in every callbacks made by the serial porting layer.
bFrameTimeoutFN If MBP_SERIAL_PORT_DETECTS_TIMEOUT is active and this argument is not equal to NULL the porting layer needs to detect the timeouts. See the documentation of MBP_SERIAL_PORT_DETECTS_TIMEOUT.
eMode If the serial port detects the timeout the argument includes wheter ASCII or RTU is used.
Returns:
eMBErrorCode::MB_ENOERR if a new serial port instances has been created. If pxSerialHdl equals NULL or one of the arguments is not valid it should return eMBErrorCode::MB_EINVAL. All other errors should be mapped to eMBErrorCode::MB_EPORTERR.

eMBErrorCode eMBPSerialRxEnable (  xMBPSerialHandle  xSerialHdl,
pvMBPSerialReceiverCB  pvMBPReceiveFN
) 
 

Enables the receiver and registers a callback or disables it.

After the receiver has been enabled the callback function should be called for every new character. Only valid characters should be passed to the stack.

Parameters:
xSerialHdl A valid handle for a serial port.
pvMBPReceiveFN A pointer to the callback function or NULL if the receiver should be disabled.
Returns:
eMBErrorCode::MB_ENOERR is the receiver has been disabled. eMBErrorCode::MB_EINVAL if the handle is not valid. All other errors should be mapped to eMBErrorCode::MB_EPORTERR.

eMBErrorCode eMBPSerialTxEnable (  xMBPSerialHandle  xSerialHdl,
pbMBPSerialTransmitterEmptyCB  pbMBPTransmitterEmptyFN
) 
 

Enables the transmitter and registers a callback or disables it.

After the transmitter has been enabled the callback function should be called until it returns FALSE indicating that no more characters should be transmitted.

Parameters:
xSerialHdl A valid handle for a serial port.
pbMBPTransmitterEmptyFN A pointer to the callback function or NULL if the transmitter should be disabled.
Returns:
eMBErrorCode::MB_ENOERR is the transmitter has been enabled. eMBErrorCode::MB_EINVAL if the handle is not valid. All other errors should be mapped to eMBErrorCode::MB_EPORTERR.

(C) 2007 Embedded Solutions. Last updated on 14 Jun 2015.