Modbus_RTU_for_Tiva/gfamodbusrtumst/gfambrtumst.h

/*! \file gfambrtumst.h
	\brief Header file of the \b gfambrtumst library.
*/

#if !defined(AGD_GFAMBRTUMST_H__F97088DB_3E1B_4FC8_A313_476634890514__INCLUDED_)
#define AGD_GFAMBRTUMST_H__F97088DB_3E1B_4FC8_A313_476634890514__INCLUDED_

#include <gfautils.h>
#include <gfambrtucom.h>

#ifdef __cplusplus
extern "C" {
#endif	//	__cplusplus

/////////////////////////////////////////////////////////////////////////////
// mbrtumast.h - Declarations:

/*! \typedef HMBRTUMST
 \brief Defines a Handle to a Modbus RTU Master.
*/
typedef void											*HMBRTUMST;

/////////////////////////////////////////////////////////////////////////////
// error codes

/*! \def GFA_MB_MST_ERROR_INVALID_SLAVE_ID
 \brief Invalid Slave ID.
*/
#define GFA_MB_MST_ERROR_INVALID_SLAVE_ID					0x0001

/*! \def GFA_MB_MST_ERROR_INVALID_FUNCTION
 \brief Invalid function code.
*/
#define GFA_MB_MST_ERROR_INVALID_FUNCTION					0x0002

/*! \def GFA_MB_MST_ERROR_SLAVE_ERROR
 \brief The slave has responded with an error-function-code (0x80).
*/
#define GFA_MB_MST_ERROR_SLAVE_ERROR						0x0003

/*! \def GFA_MB_MST_ERROR_SLAVE_RESPONSE_TIMEOUT
 \brief The slave did not respond within a certain time frame (currently 500 milliseconds).
*/
#define GFA_MB_MST_ERROR_SLAVE_RESPONSE_TIMEOUT				0x0004

/*! \def GFA_MB_MST_ERROR_SLAVE_CHAR_TIMEOUT
 \brief The master detected a time interval greater than 1.5 characters between two bytes received.
*/
#define GFA_MB_MST_ERROR_SLAVE_CHAR_TIMEOUT					0x0005

/*! \def GFA_MB_MST_ERROR_SLAVE_INVALID_CRC
 \brief CRC error in response.
*/
#define GFA_MB_MST_ERROR_SLAVE_INVALID_CRC					0x0006

/*! \def GFA_MB_MST_ERROR_SLAVE_INVALID_DATA
 \brief The response contained invalid data.
*/
#define GFA_MB_MST_ERROR_SLAVE_INVALID_DATA					0x0007

/*! \def GFA_MB_MST_ERROR_UNEXPECTED
 \brief An unexpected error occured.
*/
#define GFA_MB_MST_ERROR_UNEXPECTED							0xFFFF

/////////////////////////////////////////////////////////////////////////////

/*! \typedef GFA_MODBUS_RTU_MST_STATES
 \brief Defines the Master's states used in the state machine.
\verbatim
typedef enum _GFA_MODBUS_RTU_MST_STATES
{
	MB_RTU_MST_Void	= -1,
	MB_RTU_MST_Idle,
	MB_RTU_MST_TxStart,
	MB_RTU_MST_TxWaitEnd,
	MB_RTU_MST_TxDone,
	MB_RTU_MST_WaitRxFifo,
	MB_RTU_MST_RxSlvID,
	MB_RTU_MST_RxFunc,
	MB_RTU_MST_RxData,
	MB_RTU_MST_RxError,
	MB_RTU_MST_RxCRC,
	MB_RTU_MST_RxFinalize,
	MB_RTU_MST_ReportError
}GFA_MODBUS_RTU_MST_STATES;
 \endverbatim
 */
typedef enum _GFA_MODBUS_RTU_MST_STATES
{
	MB_RTU_MST_Void	= -1,
	MB_RTU_MST_Idle,
	MB_RTU_MST_TxStart,
	MB_RTU_MST_TxWaitEnd,
	MB_RTU_MST_TxDone,
	MB_RTU_MST_WaitRxFifo,
	MB_RTU_MST_RxSlvID,
	MB_RTU_MST_RxFunc,
	MB_RTU_MST_RxData,
	MB_RTU_MST_RxError,
	MB_RTU_MST_RxCRC,
	MB_RTU_MST_RxFinalize,
	MB_RTU_MST_ReportError
}GFA_MODBUS_RTU_MST_STATES;

/////////////////////////////////////////////////////////////////////////////
/*! \typedef typedef void (*PFN_GFA_MASTER_RAW_REQUEST_COMPLETE)(uint32_t nTID, uint8_t nSlvID, uint16_t err, LPCMODBUS_RTU_ADU padu, size_t nCbData, void *pParam)
 \brief Defines the pointer to a callback function, that is called when a request initiated by \ref GfaModbusRTUMstSendRawRequest has completed.
 \param nTID The transaction id of the request.
 \param nSlvID The slave id of the target of the request.
 \param err The error code, if an error has occured or 0 if successful.
 \param padu A pointer to the \b MODBUS_RTU_ADU (Application Data Unit) structure that on success holds the complete received data. \b MODBUS_RTU_ADU is defined in \b gfambrtucom.h.
 \param nCbData The number of data bytes received not counting the Slave ID, the Function code and the CRC.
 \param pParam The user defined parameter that has been passed to \ref GfaModbusRTUMstSendRawRequest.
 \note The completion routine will be called both on success and on error (or timeout)! Thus the \b err parameter should be evaluated, before performing other tasks!
 In case of an error \b err comprises one of the \b GFA_MB_MST_ERROR_* error codes and \b padu is \b NULL. On success \b err is 0.
*/
typedef void (*PFN_GFA_MASTER_RAW_REQUEST_COMPLETE)				(uint32_t nTID, uint8_t nSlvID, uint16_t err, LPCMODBUS_RTU_ADU padu, size_t nCbData, void *pParam);

/////////////////////////////////////////////////////////////////////////////
/*! \typedef typedef void (*PFN_GFA_MASTER_READ_REGISTERS_COMPLETE)(uint32_t nTID, uint8_t nSlvID, uint16_t err, const uint16_t *pRegs, size_t nRegCount)
 \brief Defines the pointer to a callback function, that is called when a request initiated by \ref GfaModbusRTUMstReadHoldingRegisters or \ref GfaModbusRTUMstReadInputRegisters has completed.
 \param nTID The transaction id of the request.
 \param nSlvID The slave id of the target of the request.
 \param err The error code, if an error has occured or 0 if successful.
 \param pRegs Pointer to an array of registers.
 \param nRegCount Number of elements in \b pRegs.
 \note The completion routine will be called both on success and on error (or timeout)! See \ref PFN_GFA_MASTER_RAW_REQUEST_COMPLETE for details.
*/
typedef void (*PFN_GFA_MASTER_READ_REGISTERS_COMPLETE)			(uint32_t nTID, uint8_t nSlvID, uint16_t err, const uint16_t *pRegs, size_t nRegCount);

/////////////////////////////////////////////////////////////////////////////
/*! \typedef typedef void (*PFN_GFA_MASTER_PRESET_SINGLE_REGISTER_COMPLETE)(uint32_t nTID, uint8_t nSlvID, uint16_t err)
 \brief Defines the pointer to a callback function, that is called when a request initiated by \ref GfaModbusRTUMstPresetSingleRegister has completed.
 \param nTID The transaction id of the request.
 \param nSlvID The slave id of the target of the request.
 \param err The error code, if an error has occured or 0 if successful.
 \note The completion routine will be called both on success and on error (or timeout)! See \ref PFN_GFA_MASTER_RAW_REQUEST_COMPLETE for details.
*/
typedef void (*PFN_GFA_MASTER_PRESET_SINGLE_REGISTER_COMPLETE)	(uint32_t nTID, uint8_t nSlvID, uint16_t err);

/////////////////////////////////////////////////////////////////////////////
/*! \typedef typedef void (*PFN_GFA_MASTER_WRITE_REGISTERS_COMPLETE)(uint32_t nTID, uint8_t nSlvID, uint16_t err, uint16_t nRegStart, uint16_t nRegsWritten)
 \brief Defines the pointer to a callback function, that is called when a request initiated by \ref GfaModbusRTUMstWriteMultipleRegisters has completed.
 \param nTID The transaction id of the request.
 \param nSlvID The slave id of the target of the request.
 \param err The error code, if an error has occured or 0 if successful.
 \param nRegStart Address of the first register that has been written.
 \param nRegsWritten Number of registers written.
 \note The completion routine will be called both on success and on error (or timeout)! See \ref PFN_GFA_MASTER_RAW_REQUEST_COMPLETE for details.
*/
typedef void (*PFN_GFA_MASTER_WRITE_REGISTERS_COMPLETE)			(uint32_t nTID, uint8_t nSlvID, uint16_t err, uint16_t nRegStart, uint16_t nRegsWritten);

/////////////////////////////////////////////////////////////////////////////
/*! \typedef typedef void (*PFN_GFA_MASTER_DIAGNOSIS_COMPLETE)(uint32_t nTID, uint8_t nSlvID, uint16_t err, uint16_t nSubFunc, uint16_t nData)
 \brief Defines the pointer to a callback function, that is called when a request initiated by \ref GfaModbusRTUMstDiagnosis has completed.
 \param nTID The transaction id of the request.
 \param nSlvID The slave id of the target of the request.
 \param err The error code, if an error has occured or 0 if successful.
 \param nSubFunc The requested sub-function code.
 \param nData The result of the request depending on the sub-function.
 \note The completion routine will be called both on success and on error (or timeout)! See \ref PFN_GFA_MASTER_RAW_REQUEST_COMPLETE for details.
*/
typedef void (*PFN_GFA_MASTER_DIAGNOSIS_COMPLETE)				(uint32_t nTID, uint8_t nSlvID, uint16_t err, uint16_t nSubFunc, uint16_t nData);

/////////////////////////////////////////////////////////////////////////////
/*! \typedef typedef void (*PFN_GFA_MASTER_REPORT_SLAVE_ID_COMPLETE)(uint32_t nTID, uint8_t nSlvID, uint16_t err, const void *pData, size_t nCbData)
 \brief Defines the pointer to a callback function, that is called when a request initiated by \ref GfaModbusRTUMstReportSlaveID has completed.
 \param nTID The transaction id of the request.
 \param nSlvID The slave id of the target of the request.
 \param err The error code, if an error has occured or 0 if successful.
 \param pData The slave's response data.
 \param nCbData Number of bytes of the response data.
 \note The completion routine will be called both on success and on error (or timeout)! See \ref PFN_GFA_MASTER_RAW_REQUEST_COMPLETE for details.
*/
typedef void (*PFN_GFA_MASTER_REPORT_SLAVE_ID_COMPLETE)			(uint32_t nTID, uint8_t nSlvID, uint16_t err, const void *pData, size_t nCbData);

/////////////////////////////////////////////////////////////////////////////
/*! \typedef typedef void (*PFN_GFA_MASTER_STATE_CHANGED)(GFA_MODBUS_RTU_MST_STATES newState, GFA_MODBUS_RTU_MST_STATES oldState)
 \brief Defines the pointer to a callback function, that is called after the master's state has changed.
 \param newState The new state of the master.
 \param oldState The previous state of the master.
*/
typedef void (*PFN_GFA_MASTER_STATE_CHANGED)			(GFA_MODBUS_RTU_MST_STATES newState, GFA_MODBUS_RTU_MST_STATES oldState);

/////////////////////////////////////////////////////////////////////////////
/*! \typedef typedef void (*PFN_GFA_MASTER_PRE_TRANSMIT)(uint32_t nTID, uint8_t nSlvID)
 \brief Defines the pointer to a callback function, that is called before the master starts to transmit a request.
 \param nTID The transaction id of the request that is about to be sent.
 \param nSlvID The slave id of the target of the request that is about to be sent.
*/
typedef void (*PFN_GFA_MASTER_PRE_TRANSMIT)				(uint32_t nTID, uint8_t nSlvID);

/////////////////////////////////////////////////////////////////////////////
/*! \typedef typedef void (*PFN_GFA_MASTER_POST_TRANSMIT)(uint32_t nTID, uint8_t nSlvID)
 \brief Defines the pointer to a callback function, that is called when the master has finished transmitting a request and all data has been sent.
 \param nTID The transaction id of the request that has been sent.
 \param nSlvID The slave id of the target of the request that has been sent.
*/
typedef void (*PFN_GFA_MASTER_POST_TRANSMIT)			(uint32_t nTID, uint8_t nSlvID);

/////////////////////////////////////////////////////////////////////////////
/*! \typedef typedef void (*PFN_GFA_MASTER_RECEIVE_START)(uint32_t nTID)
 \brief Defines the pointer to a callback function, that is called before the master starts reading a response from a slave and data is already available.
 \param nTID The transaction id of the request which response is expected.
*/
typedef void (*PFN_GFA_MASTER_RECEIVE_START)			(uint32_t nTID);

/////////////////////////////////////////////////////////////////////////////
/*! \typedef typedef void (*PFN_GFA_MASTER_RECEIVE_END)(uint32_t nTID)
 \brief Defines the pointer to a callback function, that is called after the master has received a response from a slave.
 \param nTID The transaction id of the request which response has been received.
 \note This callback function is actually redundant and will be called right before the completion routine is called, which will provide more info about the response.
*/
typedef void (*PFN_GFA_MASTER_RECEIVE_END)				(uint32_t nTID);

/////////////////////////////////////////////////////////////////////////////
/*! \typedef GFA_MODBUS_MASTER_APP_INTERFACE
 \brief Defines a set of functions to interact with a Modbus application. Any of these function pointers may be NULL, if not needed.
\verbatim
typedef struct _GFA_MODBUS_MASTER_APP_INTERFACE
{
	PFN_GFA_MASTER_STATE_CHANGED	pfnStateChanged;	// called after the master's state has changed
	PFN_GFA_MASTER_PRE_TRANSMIT		pfnPreTx;			// called before the master starts to transmit a request
	PFN_GFA_MASTER_POST_TRANSMIT	pfnPostTx;			// called when the master has finished transmitting a request and all data has been sent
	PFN_GFA_MASTER_RECEIVE_START	pfnRxStart;			// called before the master starts reading a response from a slave and data is already available
	PFN_GFA_MASTER_RECEIVE_END		pfnRxEnd;			// called after the master has received a response from a slave
}GFA_MODBUS_MASTER_APP_INTERFACE, *LPGFA_MODBUS_MASTER_APP_INTERFACE;
typedef const GFA_MODBUS_MASTER_APP_INTERFACE *LPCGFA_MODBUS_MASTER_APP_INTERFACE;
 \endverbatim
 */
typedef struct _GFA_MODBUS_MASTER_APP_INTERFACE
{
	PFN_GFA_MASTER_STATE_CHANGED	pfnStateChanged;
	PFN_GFA_MASTER_PRE_TRANSMIT		pfnPreTx;
	PFN_GFA_MASTER_POST_TRANSMIT	pfnPostTx;
	PFN_GFA_MASTER_RECEIVE_START	pfnRxStart;
	PFN_GFA_MASTER_RECEIVE_END		pfnRxEnd;
}GFA_MODBUS_MASTER_APP_INTERFACE, *LPGFA_MODBUS_MASTER_APP_INTERFACE;
typedef const GFA_MODBUS_MASTER_APP_INTERFACE *LPCGFA_MODBUS_MASTER_APP_INTERFACE;

/////////////////////////////////////////////////////////////////////////////
/*! \typedef GFA_MODBUS_RTU_MASTER_PARAMETERS
 \brief Used to create a Modbus RTU Master
\verbatim
typedef struct _GFA_MODBUS_RTU_MASTER_PARAMETERS
{
	HFIFO hFifoRX;							// handle to the receive fifo buffer
	HFIFO hFifoTX;							// handle to the transmit fifo buffer
	GFA_MODBUS_PROTOCOL_TIMEOUTS mpt;		// modbus protocol timeouts
	GFA_MODBUS_MASTER_APP_INTERFACE appItf;	// app interface
}GFA_MODBUS_RTU_MASTER_PARAMETERS, *LPGFA_MODBUS_RTU_MASTER_PARAMETERS;
typedef const GFA_MODBUS_RTU_MASTER_PARAMETERS *LPCGFA_MODBUS_RTU_MASTER_PARAMETERS;
 \endverbatim
 */
typedef struct _GFA_MODBUS_RTU_MASTER_PARAMETERS
{
	HFIFO hFifoRX;
	HFIFO hFifoTX;
	uint64_t nRxTimeoutUs;
	GFA_MODBUS_PROTOCOL_TIMEOUTS mpt;
	GFA_MODBUS_MASTER_APP_INTERFACE appItf;
}GFA_MODBUS_RTU_MASTER_PARAMETERS, *LPGFA_MODBUS_RTU_MASTER_PARAMETERS;
typedef const GFA_MODBUS_RTU_MASTER_PARAMETERS *LPCGFA_MODBUS_RTU_MASTER_PARAMETERS;

/////////////////////////////////////////////////////////////////////////////
/*! \fn HMBRTUMST GfaModbusRTUMstCreate(LPCGFA_MODBUS_RTU_MASTER_PARAMETERS pmap)
 \brief Creates and initializes a Modbus RTU Master.
 \param pmap A const pointer to a \ref GFA_MODBUS_RTU_MASTER_PARAMETERS structure.
 \return If successful, returns a handle to the newly created master, or NULL in the case of an error.
*/
HMBRTUMST	GfaModbusRTUMstCreate(LPCGFA_MODBUS_RTU_MASTER_PARAMETERS pmap);

/////////////////////////////////////////////////////////////////////////////
/*! \fn void GfaModbusRTUMstRelease(HMBRTUMST hMbMst)
 \brief Releases a modbus master, that was previously created with \ref GfaModbusRTUMstCreate.
 \param hMbMst Handle to the modbus master that has been acquired by a call to \ref GfaModbusRTUMstCreate.
*/
void		GfaModbusRTUMstRelease(HMBRTUMST hMbMst);

/////////////////////////////////////////////////////////////////////////////
/*! \fn bool GfaModbusRTUMstStateMachine(HMBRTUMST hMbMst)
 \brief The modbus master's state machine. This function is the heart beat of the master and must be called repeatedly.
 \param hMbMst Handle to the modbus master that has been acquired by a call to \ref GfaModbusRTUMstCreate.
 \return \b true if successful, or \b false only if hMbMst is NULL or an invalid state was detected.
*/
bool		GfaModbusRTUMstStateMachine(HMBRTUMST hMbMst);

/////////////////////////////////////////////////////////////////////////////
/*! \fn bool GfaModbusRTUMstSendRawRequest(HMBRTUMST hMbMst, uint32_t nTID, uint8_t nSlvID, uint8_t nFunc, const void *pData, size_t nCbData, size_t nCbDataExpected, PFN_GFA_MASTER_RAW_REQUEST_COMPLETE pfnRawReqComplete, void *pParam)
 \brief Creates a generic Modbus RTU Request  and sends it to a Slave.
 \param hMbMst Handle to the modbus master that has been acquired by a call to \ref GfaModbusRTUMstCreate.
 \param nTID User defined transaction id. This id will be passed to the completion routine.
 \param nSlvID ID of the target slave.
 \param nFunc Modbus function code.
 \param pData Pointer to the data payload. May be \b NULL if no additional data is sent.
 \param nCbData Number of bytes of the data payload. May be 0.
 \param nCbDataExpected Number of bytes expected in the response not counting the slave id, the function code and the CRC.
 \param pfnRawReqComplete Pointer to a completion function of type \ref PFN_GFA_MASTER_RAW_REQUEST_COMPLETE that will be called when the response has been received or a timeout occured.
 \param pParam User defined parameter, that will be passed to the completion function.
 \return \b true if successful, \b false if an invalid parameter was passed or the master is not in idle state at the time of the call.
 \note The actual state of the master can be tracked by implementing the \ref PFN_GFA_MASTER_STATE_CHANGED
  callback function or it can be requested on demand by calling \ref GfaModbusRTUMstGetState. \b GfaModbusRTUMstSendRawRequest returns immediately after the request has been sent and thus cannot fail in the case of a
  response error. If the response fails, the completion routine will be called with an according error code.
*/
bool		GfaModbusRTUMstSendRawRequest(HMBRTUMST hMbMst, uint32_t nTID, uint8_t nSlvID, uint8_t nFunc, const void *pData, size_t nCbData, size_t nCbDataExpected, PFN_GFA_MASTER_RAW_REQUEST_COMPLETE pfnRawReqComplete, void *pParam);

/////////////////////////////////////////////////////////////////////////////
/*! \fn bool GfaModbusRTUMstReadHoldingRegisters(HMBRTUMST hMbMst, uint32_t nTID, uint8_t nSlvID, uint16_t nRegStart, uint16_t nRegCount, PFN_GFA_MASTER_READ_REGISTERS_COMPLETE pfnReadRegsComplete)
 \brief Reads registers from a Slave.
 \param hMbMst Handle to the modbus master that has been acquired by a call to \ref GfaModbusRTUMstCreate.
 \param nTID User defined transaction id. This id will be passed to the completion routine.
 \param nSlvID ID of the target slave.
 \param nRegStart Address of the first register to be read.
 \param nRegCount Number of registers to be read.
 \param pfnReadRegsComplete Pointer to a completion function of type \ref PFN_GFA_MASTER_READ_REGISTERS_COMPLETE that will be called when the response has been received or a timeout occured.
 \return \b true if successful, \b false if an invalid parameter was passed or the master is not in idle state at the time of the call.
 \note See \ref GfaModbusRTUMstSendRawRequest for more information on how to track the master's state.
*/
bool		GfaModbusRTUMstReadHoldingRegisters(HMBRTUMST hMbMst, uint32_t nTID, uint8_t nSlvID, uint16_t nRegStart, uint16_t nRegCount, PFN_GFA_MASTER_READ_REGISTERS_COMPLETE pfnReadRegsComplete);

/////////////////////////////////////////////////////////////////////////////
/*! \fn bool GfaModbusRTUMstReadInputRegisters(HMBRTUMST hMbMst, uint32_t nTID, uint8_t nSlvID, uint16_t nRegStart, uint16_t nRegCount, PFN_GFA_MASTER_READ_REGISTERS_COMPLETE pfnReadRegsComplete)
 \brief Reads input registers from a Slave.
 \param hMbMst Handle to the modbus master that has been acquired by a call to \ref GfaModbusRTUMstCreate.
 \param nTID User defined transaction id. This id will be passed to the completion routine.
 \param nSlvID ID of the target slave.
 \param nRegStart Address of the first register to be read.
 \param nRegCount Number of registers to be read.
 \param pfnReadRegsComplete Pointer to a completion function of type \ref PFN_GFA_MASTER_READ_REGISTERS_COMPLETE that will be called when the response has been received or a timeout occured.
 \return \b true if successful, \b false if an invalid parameter was passed or the master is not in idle state at the time of the call.
 \note See \ref GfaModbusRTUMstSendRawRequest for more information on how to track the master's state.
*/
bool		GfaModbusRTUMstReadInputRegisters(HMBRTUMST hMbMst, uint32_t nTID, uint8_t nSlvID, uint16_t nRegStart, uint16_t nRegCount, PFN_GFA_MASTER_READ_REGISTERS_COMPLETE pfnReadRegsComplete);

/////////////////////////////////////////////////////////////////////////////
/*! \fn bool GfaModbusRTUMstWriteMultipleRegisters(HMBRTUMST hMbMst, uint32_t nTID, uint8_t nSlvID, uint16_t nRegStart, uint16_t nRegCount, const void *pRegData, PFN_GFA_MASTER_WRITE_REGISTERS_COMPLETE pfnWriteRegsComplete)
 \brief Writes multiple registers to a Slave.
 \param hMbMst Handle to the modbus master that has been acquired by a call to \ref GfaModbusRTUMstCreate.
 \param nTID User defined transaction id. This id will be passed to the completion routine.
 \param nSlvID ID of the target slave.
 \param nRegStart Address of the first register to to be written to.
 \param nRegCount Number of registers to write.
 \param pRegData Pointer to a buffer that holds the data to be written. The buffer must be at least of size nRegCount * sizeof(uint16_t).
 \param pfnWriteRegsComplete Pointer to a completion function of type \ref PFN_GFA_MASTER_WRITE_REGISTERS_COMPLETE that will be called when the response has been received or a timeout occured.
 \return \b true if successful, \b false if an invalid parameter was passed or the master is not in idle state at the time of the call.
 \note See \ref GfaModbusRTUMstSendRawRequest for more information on how to track the master's state.
*/
bool		GfaModbusRTUMstWriteMultipleRegisters(HMBRTUMST hMbMst, uint32_t nTID, uint8_t nSlvID, uint16_t nRegStart, uint16_t nRegCount, const void *pRegData, PFN_GFA_MASTER_WRITE_REGISTERS_COMPLETE pfnWriteRegsComplete);

/////////////////////////////////////////////////////////////////////////////
/*! \fn bool GfaModbusRTUMstPresetSingleRegister(HMBRTUMST hMbMst, uint32_t nTID, uint8_t nSlvID, uint16_t nRegAddr, uint16_t nRegVal, PFN_GFA_MASTER_PRESET_SINGLE_REGISTER_COMPLETE pfnPresetRegComplete)
 \brief Writes a single register to a Slave.
 \param hMbMst Handle to the modbus master that has been acquired by a call to \ref GfaModbusRTUMstCreate.
 \param nTID User defined transaction id. This id will be passed to the completion routine.
 \param nSlvID ID of the target slave.
 \param nRegAddr Address of the register to to be written to.
 \param nRegVal Value to write.
 \param pfnPresetRegComplete Pointer to a completion function of type \ref PFN_GFA_MASTER_PRESET_SINGLE_REGISTER_COMPLETE that will be called when the response has been received or a timeout occured.
 \return \b true if successful, \b false if an invalid parameter was passed or the master is not in idle state at the time of the call.
 \note See \ref GfaModbusRTUMstSendRawRequest for more information on how to track the master's state.
*/
bool		GfaModbusRTUMstPresetSingleRegister(HMBRTUMST hMbMst, uint32_t nTID, uint8_t nSlvID, uint16_t nRegAddr, uint16_t nRegVal, PFN_GFA_MASTER_PRESET_SINGLE_REGISTER_COMPLETE pfnPresetRegComplete);

/////////////////////////////////////////////////////////////////////////////
/*! \fn bool GfaModbusRTUMstDiagnosis(HMBRTUMST hMbMst, uint32_t nTID, uint8_t nSlvID, uint16_t nSubFunc, uint16_t nData, PFN_GFA_MASTER_DIAGNOSIS_COMPLETE pfnDiagComplete)
 \brief Reads diagnostic information from a Slave.
 \param hMbMst Handle to the modbus master that has been acquired by a call to \ref GfaModbusRTUMstCreate.
 \param nTID User defined transaction id. This id will be passed to the completion routine.
 \param nSlvID ID of the target slave.
 \param nSubFunc Sub function code of the requested diagnostic data as defined in \b gfambrtucom.h.
 \param nData Input value used to send diagnostic data or control information to the slave.
 \param pfnDiagComplete Pointer to a completion function of type \ref PFN_GFA_MASTER_DIAGNOSIS_COMPLETE that will be called when the response has been received or a timeout occured.
 \return \b true if successful, \b false if an invalid parameter was passed or the master is not in idle state at the time of the call.
 \note See \ref GfaModbusRTUMstSendRawRequest for more information on how to track the master's state.
*/
bool		GfaModbusRTUMstDiagnosis(HMBRTUMST hMbMst, uint32_t nTID, uint8_t nSlvID, uint16_t nSubFunc, uint16_t nData, PFN_GFA_MASTER_DIAGNOSIS_COMPLETE pfnDiagComplete);

/////////////////////////////////////////////////////////////////////////////
/*! \fn bool GfaModbusRTUMstReportSlaveID(HMBRTUMST hMbMst, uint32_t nTID, uint8_t nSlvID, size_t nCbDataExpected, PFN_GFA_MASTER_REPORT_SLAVE_ID_COMPLETE pfnRepSlvIDComplete)
 \brief Reads a description of the type of controller present at the slave address, the current status of the slave Run indicator, and other information specific to the slave device.
 \param hMbMst Handle to the modbus master that has been acquired by a call to \ref GfaModbusRTUMstCreate.
 \param nTID User defined transaction id. This id will be passed to the completion routine.
 \param nSlvID ID of the target slave.
 \param nCbDataExpected Number of payload bytes expected in the response, not counting the slave address, the function code and the CRC.
 \param pfnRepSlvIDComplete Pointer to a completion function of type \ref PFN_GFA_MASTER_REPORT_SLAVE_ID_COMPLETE that will be called when the response has been received or a timeout occured.
 \return \b true if successful, \b false if an invalid parameter was passed or the master is not in idle state at the time of the call.
 \note See \ref GfaModbusRTUMstSendRawRequest for more information on how to track the master's state.
*/
bool		GfaModbusRTUMstReportSlaveID(HMBRTUMST hMbMst, uint32_t nTID, uint8_t nSlvID, size_t nCbDataExpected, PFN_GFA_MASTER_REPORT_SLAVE_ID_COMPLETE pfnRepSlvIDComplete);

/*! \fn GFA_MODBUS_RTU_MST_STATES GfaModbusRTUMstGetState(HMBRTUMST hMbMst)
 \brief Returns the current state of the master.
 \param hMbMst Handle to the modbus master that has been acquired by a call to \ref GfaModbusRTUMstCreate.
 \return The master's current state or \b MB_RTU_MST_Void if \b hMbMst is invalid.
*/
GFA_MODBUS_RTU_MST_STATES GfaModbusRTUMstGetState(HMBRTUMST hMbMst);



/////////////////////////////////////////////////////////////////////////////
/////////////////////////////////////////////////////////////////////////////
/////////////////////////////////////////////////////////////////////////////
// Metronik support
/*
 *
 *	ACHTUNG:
 *	Befindet sich der Sensors am Bus mit anderen Teilnehmern führt ein Pollen der Slaves mit einem Frame-Delay < 10 ms zu Timeout-Problemen des Sensors!
 *
 */

#define GFA_MB_ILM_FUNC_READ_UV							((uint8_t)0x41)
#define GFA_MB_ILM_FUNC_READ_TEMP						((uint8_t)0x42)
#define GFA_MB_ILM_FUNC_UNLOCK							((uint8_t)0x43)
#define GFA_MB_ILM_FUNC_NEW_ADDR						((uint8_t)0x44)
#define GFA_MB_ILM_FUNC_READ_RANGE						((uint8_t)0x45)
#define GFA_MB_ILM_FUNC_READ_SERIAL						((uint8_t)0x46)

/////////////////////////////////////////////////////////////////////////////

typedef void (*PFN_GFA_ILM_READ_UV_COMPLETE)			(uint32_t nTID, uint8_t nSlvID, uint16_t err, uint16_t nVal);
typedef void (*PFN_GFA_ILM_READ_TEMP_COMPLETE)			(uint32_t nTID, uint8_t nSlvID, uint16_t err, uint8_t nVal);
typedef void (*PFN_GFA_ILM_READ_UNLOCK_COMPLETE)		(uint32_t nTID, uint8_t nSlvID, uint16_t err, uint8_t nVal);
typedef void (*PFN_GFA_ILM_NEW_ADDR_COMPLETE)			(uint32_t nTID, uint8_t nSlvID, uint16_t err, uint8_t nVal);
typedef void (*PFN_GFA_ILM_READ_RANGE_COMPLETE)			(uint32_t nTID, uint8_t nSlvID, uint16_t err, uint16_t nVal);
typedef void (*PFN_GFA_ILM_READ_SERIAL_COMPLETE)		(uint32_t nTID, uint8_t nSlvID, uint16_t err, const uint8_t *pVal, size_t nCbVal);

/////////////////////////////////////////////////////////////////////////////

bool GfaModbusRTUMstILMReadUV(HMBRTUMST hMbMst, uint32_t nTID, uint8_t nSlvID, PFN_GFA_ILM_READ_UV_COMPLETE pfnReadUvComplete);
bool GfaModbusRTUMstILMReadTemp(HMBRTUMST hMbMst, uint32_t nTID, uint8_t nSlvID, PFN_GFA_ILM_READ_TEMP_COMPLETE pfnReadTempComplete);
bool GfaModbusRTUMstILMUnlock(HMBRTUMST hMbMst, uint32_t nTID, uint8_t nSlvID, PFN_GFA_ILM_READ_UNLOCK_COMPLETE pfnUnlockComplete);
bool GfaModbusRTUMstILMReadRange(HMBRTUMST hMbMst, uint32_t nTID, uint8_t nSlvID, PFN_GFA_ILM_READ_RANGE_COMPLETE pfnReadRangeComplete);
bool GfaModbusRTUMstILMReadSerial(HMBRTUMST hMbMst, uint32_t nTID, uint8_t nSlvID, PFN_GFA_ILM_READ_SERIAL_COMPLETE pfnReadSerialComplete);

/*
 *	GfaModbusRTUMstILMNewAddr: Weist dem Sensor eine neue Slave-Adresse zu.
 *	Achtung: Der Sensor antwortet bei Erfolg bereits mit der neuen Slave-Adresse im Antwort-Frame!!!
 *	Der Master ruft im Anschluss die Completion-Funktion mit dem Fehlercode \ref GFA_MB_MST_ERROR_INVALID_SLAVE_ID auf!
 *	Die neue Slave-Adresse wurde in diesem Fall aber erfolgreich im Slave gesetzt!
 *
 *	Achtung: Der Sensor akzeptiert die Broadcast-Adresse 0 als Slave-ID! Diese sollte niemals gesetzt werden!
 */
bool GfaModbusRTUMstILMNewAddr(HMBRTUMST hMbMst, uint32_t nTID, uint8_t nSlvID, uint8_t nNewAddr, PFN_GFA_ILM_NEW_ADDR_COMPLETE pfnNewAddrComplete);

/////////////////////////////////////////////////////////////////////////////
#ifdef __cplusplus
}
#endif	//	__cplusplus
#endif	//	!defined(AGD_GFAMBRTUMST_H__F97088DB_3E1B_4FC8_A313_476634890514__INCLUDED_)