modbus.h

Go to the documentation of this file.

#ifndef MODBUS_H_INCLUDED
#define MODBUS_H_INCLUDED
/**********************************************************************/
/*
 * Copyright (c) 2016, Jetro AS
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without modification,
 * are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright notice,
 *    this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright notice,
 *    this list of conditions and the following disclaimer in the documentation
 *    and/or other materials provided with the distribution.
 * 3. The name of the author may not be used to endorse or promote products
 *    derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONRIBUTORS ``AS IS'' AND ANY EXPRESS
 * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
 * SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
 * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
 * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
 * OF SUCH DAMAGE.
 *
 * This file is part of the EVE platform.
 *
 * The file is partially based on the Christian Walter's FreeModbus Library with
 * the following copyright notice:
 *
 * FreeModbus Libary: A portable Modbus implementation for Modbus ASCII/RTU.
 * Copyright (c) 2006 Christian Walter <wolti@sil.at>
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 * 3. The name of the author may not be used to endorse or promote products
 *    derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
/**
 * \file
 * @brief Main public header file for the Modbus client/server/sniffer over
 *        TCP/UART EVE module.
 *
 * @author SE, Jetro AS
 */ /******************************************************************/

/**
 * \defgroup modbus Modbus driver
 * \ingroup abstract
 * \{
 */

/**
 * This module defines the Modbus driver interface for the application.
 * It contains the basic functions and types required to use the Modbus protocol
 * stack.
 * A typical application will want to call MbInit() first. If the device
 * is ready to answer network requests it must then call MbEnable() to activate
 * the protocol stack.
 */

#include <sys/process.h>
#include <core/uwork.h>
#include <core/mwork.h>

#define MB_SLAVEID_BUF_LEN           32     //!< Number of bytes which should be allocated for the <em>Report Slave ID </em>command.

#define MB_SER_PDU_SIZE_MAX         255     //!< Maximum size of a Modbus RTU frame. 1 byte less than standard because of internal UART limitation.

#define MB_TFILE_TARGET_SIZE         31     //!< Length of bit vector of targets for Transfer File function.
#define MB_TFILE_FNAMELEN_MAX        32     //!< Length of the buffer holding filename for Transfer File function. As file name is null-terminated, actual filenane length cannot exceed 31.
#define MB_TFILE_LAST_PACKET   (1 << 31)    //!< Bit flag in the packet number field of TransferFilePart frame denoting the last packet (file end).
#define MB_TFILE_PART_REGADDR    0xFF00     //!< Server's pseudo-register containing last part number for verification from client (2 registers actually: MB_TFILE_PART_REGADDR and MB_TFILE_PART_REGADDR+1)

/**********************************************************************/
/**
 * @brief Modbus server addresses
 */
#define MB_ADDRESS_BROADCAST       (   0 )   //!< Modbus broadcast address.
#define MB_ADDRESS_MIN             (   1 )   //!< Smallest possible slave address.
#define MB_ADDRESS_MAX             ( 247 )   //!< Biggest possible slave address.
#define MB_TCP_PSEUDO_ADDRESS      ( 255 )   //!< Server address on Modbus over TCP

/**********************************************************************/
/**
 * @brief Modbus function codes
 */
#define MB_FUNC_NONE                          (0x00)   //!< Used as "invalid function"
#define MB_FUNC_READ_COILS                    (0x01)   //!< Read Coils
#define MB_FUNC_READ_DISCRETE_INPUTS          (0x02)   //!< Read Discrete Inputs
#define MB_FUNC_READ_HOLDING_REGISTER         (0x03)   //!< Read Holding Registers
#define MB_FUNC_READ_INPUT_REGISTER           (0x04)   //!< Read Input Registers
#define MB_FUNC_WRITE_SINGLE_COIL             (0x05)   //!< Write Single Coil
#define MB_FUNC_WRITE_REGISTER                (0x06)   //!< Write Single Register
#define MB_FUNC_DIAG_READ_EXCEPTION           (0x07)   //!< Read Exception Status (Serial Line only)
#define MB_FUNC_DIAG_DIAGNOSTIC               (0x08)   //!< Diagnostics (Serial Line only)
#define MB_FUNC_DIAG_GET_COM_EVENT_CNT        (0x0B)   //!< Get Comm Event Counter (Serial Line only)
#define MB_FUNC_DIAG_GET_COM_EVENT_LOG        (0x0C)   //!< Get Comm Event Log (Serial Line only)
#define MB_FUNC_WRITE_MULTIPLE_COILS          (0x0F)   //!< Write Multiple Coils
#define MB_FUNC_WRITE_MULTIPLE_REGISTERS      (0x10)   //!< Write Multiple registers
#define MB_FUNC_REPORT_SERVER_ID              (0x11)   //!< Report Server ID (Serial Line only)
#define MB_FUNC_READ_FILE_RECORD              (0x14)   //!< Read File Record
#define MB_FUNC_WRITE_FILE_RECORD             (0x15)   //!< Write File Record
#define MB_FUNC_READWRITE_MULTIPLE_REGISTERS  (0x17)   //!< Read/Write Multiple registers
#define MB_FUNC_TRANSFER_FILE                 (0x64)   //!< Transfer file - Jetro proprietary
#define MB_FUNC_TRANSFER_FILE_COMPLETED       (0x65)   //!< Transfer file complete - Jetro proprietary
#define MB_FUNC_NEW_FILE                      (0x66)   //!< New file arrived - pseudo function, Jetro proprietary
#define MB_FUNC_ERROR                         (0x80)   //!< Error flag for responses (ORed with function code)

struct modbus_t;

/**********************************************************************/
/**
 * @brief Modbus events used in ModbusServerProcess and ModbusClientProcess
 *
 ***********************************************************************/
typedef enum
{
  EV_MB_READY,                   //!< Modbus event: Startup finished.
  EV_MB_FRAME_RECEIVED,          //!< Modbus event: Frame received.
  EV_MB_FRAME_SENT,              //!< Modbus event: Frame sent.
  EV_MB_SEND,                    //!< Modbus event: Request to send frame
  EV_MB_CLOSE_SESSION,           //!< Modbus event: Data exchange ended.
  EVT_MB_T35_TIMEOUT,            //!< 3.5 chars timeout expired
  EV_MB_FT_CONTINUE,             //!< Continue file transfer procedure
  EV_MB__LAST,
} MbEvent_t;


/**********************************************************************/
/**
 * @brief Modbus serial transmission modes (RTU/ASCII/TCP).
 *
 ***********************************************************************/
typedef enum
{
  MB_RTU,   //!< RTU transmission mode.
  MB_ASCII, //!< ASCII transmission mode.
  MB_TCP,   //!< TCP mode.
} MbMode_t;

/**********************************************************************/
/**
 * @brief Modbus device role (MASTER/SLAVE/SNIFFER).
 *
 ***********************************************************************/
typedef enum
{
  MB_SERVER,   //!< Server (slave) role.
  MB_CLIENT,   //!< Client (master) role.
  MB_SNIFFER,  //!< Sniffer role.
} MbRole_t;

/**********************************************************************/
/**
 * @brief Modbus standard exception codes plus internal error codes used
 *  by all function in the protocol stack.
 *
 ***********************************************************************/
typedef enum
{
  MB_EX_NONE = 0x00,                    //!< no error.
  MB_EX_ILLEGAL_FUNCTION = 0x01,        //!< The function code received in the query is not an allowable action for the server.
  MB_EX_ILLEGAL_DATA_ADDRESS = 0x02,    //!< illegal register address.
  MB_EX_ILLEGAL_DATA_VALUE = 0x03,      //!< illegal argument.
  MB_EX_SERVER_DEVICE_FAILURE = 0x04,   //!< An unrecoverable error occurred while the server was attempting to perform the requested action.
  MB_EX_ACKNOWLEDGE = 0x05,             //!< The server has accepted the request and is processing it, but a long duration of time will be required to do so. This response is returned to prevent a timeout error from occurring in the client.
  MB_EX_SERVER_DEVICE_BUSY = 0x06,      //!< The client should retransmit the message later when the server is free
  MB_EX_MEMORY_PARITY_ERROR = 0x08,     //!< In conjunction with function codes 20 and 21: The server attempted to read record file, but detected a parity error in the memory.
  MB_EX_GATEWAY_PATH_FAILED = 0x0A,     //!< In conjunction with gateways: indicates that the gateway was unable to allocate an internal communication path from the input port to the output port
  MB_EX_GATEWAY_TGT_FAILED = 0x0B,      //!< In conjunction with gateways: Specialized use in conjunction with gateways, indicates that no response was obtained from the target device
  MB_EX_BUSY = 0x80,                    //!< ModbusLib INTERNAL exception: Master is busy (awaiting response) or UART is busy (sending/receiving data).
  MB_EX_TIMEOUT = 0x81,                 //!< ModbusLib INTERNAL exception: timeout error occurred.
  MB_EX_ILLEGAL_STATE = 0x83,           //!< ModbusLib INTERNAL exception: protocol stack in illegal state.
  MB_EX_PROTOCOL_ERROR = 0x84,          //!< ModbusLib INTERNAL exception: Communication error (unexpected or invalid frame).
  MB_EX_FT_DONE = 0x86,                 //!< ModbusLib INTERNAL exception: Transfer File function is done.
} MbException_t;

/**********************************************************************/
/**
 * @brief Modbus driver state.
 *
 ***********************************************************************/
typedef enum
{
  STATE_NOT_INITIALIZED,   //!< Modbus instance was not initialised. Use MbInit().
  STATE_DISABLED,          //!< Modbus instance was initialised but currently disabled. Use MbEnable().
  STATE_ENABLED,           //!< Modbus instance is listening remote part and ready for transmission
  STATE_BUSY,              //!< Modbus instance is busy with data transfer, or (for client) awaiting reply.
} MbState_t;

/**********************************************************************/
/**
 * @brief Structure for holding variables related to Transfer File function.
 *
 ***********************************************************************/
typedef struct
{
  uint32_t PartNum;                             //!< Last file part transmitted (for client) or received (for server). It is 0 for file header. Highest bit is a flag of the last part, so 0x8000000A is the 10th and last part of the file.
  uint8_t Targets[MB_TFILE_TARGET_SIZE];        //!< Bit vector of targets for file transfer. So f.ex. if bit #0 in byte #1 is 1 - it means file transfers (among others) to server with Id 8.
  uint8_t TargetsTmp[MB_TFILE_TARGET_SIZE];     //!< Temporary copy of targets vector used by client to verify part completion for all targets.
  uint32_t FileSize;                            //!< Total file size
  uint32_t FilePtr;                             //!< Bytes already transmitted. Used by client to determine the size of the last part.
  uint32_t FileCrc32;                           //!< CRC32 of file name (w/o trailing zeroes) + file length + file data. Computed by crc32_compute() function.
  uint8_t FileName[MB_TFILE_FNAMELEN_MAX];  //!< File name is ASCII null-terminated string of 1-31 chars.
  uint32_t CurSize;                             //!< Bytes already received. Used by server to discover possible file size error.
  uint32_t CurCrc32;                            //!< CRC32 of file name + file length + part of data received so far. Used by server to discover possible file CRC error. Computed by crc32_compute() function.
  uint8_t PartLen;                              //!< Current packet file part length.
  uint8_t* PartData;                            //!< Pointer to current part data
  uint8_t  Active;                              //!< Transfer file operation is in progress (even if the actual function is read reg)
  struct mwork_t Mwork;                         //!< Timer for timeouts and transfer abortion. For server: when the next part wasn't arrived. For client: when one of servers still doesn't confirmed part reception.
} mb_transfer_file_t;

/**********************************************************************/
/**
 * @brief Callback specific to the protocol and called on the protocol start.
 *
 * This callback can be implemented in the application for transport layers
 * other than UART if some special processing required and settled to the
 * Virtualfunc member of the modbus_t structure.
 *
 * @param  Mb            Modbus driver instance that should be started
 * @param  Error         Error code occured while command was processed
 * @return MbException_t Error code of the operation (MB_EX_NONE on success)
 *
 ***********************************************************************/
typedef MbException_t (*MbVfuncStart_t)(const struct modbus_t* Mb, void* data);

/**********************************************************************/
/**
 * @brief Callback specific to the protocol and called on the protocol stop.
 *
 * This callback can be implemented in the application for transport layers
 * other than UART if some special processing required and settled to the
 * Virtualfunc member of the modbus_t structure.
 *
 * @param  Mb            Modbus driver instance that should be stopped.
 * @return MbException_t Error code of the operation (MB_EX_NONE on success)
 *
 ***********************************************************************/
typedef MbException_t (*MbVfuncStop_t)(const struct modbus_t* Mb);

/**********************************************************************/
/**
 * @brief Callbacks specific to the protocol and called when the driver
 *        wants to send data.
 *
 * This callback must be implemented in the application for transport layers
 * other than UART and settled to the Virtualfunc member of the modbus_t
 * structure.
 *
 * Implementation must write Mb->State->MbFrameLen bytes from the
 * Mb->State->MbFrame pointer to the callback specific interface.
 *
 * @param  Mb            Modbus driver instance which called the callback
 * @return MbException_t MB_EX_NONE on success, MB_EX_PROTOCOL_ERROR on error
 *
 ***********************************************************************/
typedef MbException_t (*MbVfuncSend_t)(const struct modbus_t* Mb);

/**********************************************************************/
/**
 * @brief Callbacks specific to the protocol and called when the driver
 *        wants to receive data.
 *
 * This callback must be implemented in the application for transport layers
 * other than UART and settled to the Virtualfunc member of the modbus_t
 * structure.
 *
 * Implementation must read all available bytes from the callback specific
 * interface to the Mb->State->MbFrame pointer.
 * Mb->State->MbFrameLen must be settled to the received data length.
 *
 * @param  Mb            Modbus driver instance which called the callback
 * @return MbException_t MB_EX_NONE on success (even if nothing to read,
 *                       MB_EX_PROTOCOL_ERROR on error.
 *
 ***********************************************************************/
typedef MbException_t (*MbVfuncReceive_t)(const struct modbus_t* Mb);

/**********************************************************************/
/**
 * @brief Callbacks specific to the Read/Write Holding Register(s) command.
 *        They're called when Modbus command or response requires to read or
 *        write specific register. It could be both command request on the
 *        server side, or command response on the client side.
 *
 * These callbacks must be implemented in the application for Read Holding
 * Register, Write Holding Register, Write Multiple Registers command support
 * and settled via the FuncHandlers member of the modbus_t structure.
 *
 * Implementation must read or write one register.
 *
 * @param  Mb            Modbus driver instance which called the callback
 * @param  SlaveAddr     Slave address from the Modbus request/response frame
 * @param  RegAddr       Register address to read or write
 * @param  Value         Pointer to the value to set / buffer for output value
 * @return MbException_t MB_EX_NONE on success, MB_EX_PROTOCOL_ERROR on error.
 *
 ***********************************************************************/
typedef MbException_t (*MbHoldingHandler_t)(const struct modbus_t* Mb, uint16_t SlaveAddr, uint16_t RegAddr, uint16_t* Value);

/**********************************************************************/
/**
 * @brief Callback specific to the Transfer File command.
 *        It is called when Modbus command requests to write a file.
 *
 * This callback must be implemented in the application for Transfer File
 * command support and settled via the FuncHandlers member of the modbus_t
 * structure.
 *
 * @param  Mb            Modbus driver instance which called the callback
 * @param  SlaveAddr     Slave address from the Modbus request/response frame
 * @param  TransferFile  Structure with information about the file and current part
 * @return MbException_t MB_EX_NONE on success, MB_EX_PROTOCOL_ERROR on error.
 *
 ***********************************************************************/
typedef MbException_t (*MbTransferFileHandler_t)(const struct modbus_t* Mb, uint16_t SlaveAddr, mb_transfer_file_t* TransferFile);

/**********************************************************************/
/**
 * @brief Callback specific to the Transfer File Completed command.

 * @param  Mb            Modbus driver instance which called the callback
 * @param  SlaveAddr     Slave address from the Modbus request/response frame
 * @param  PartNumber    Reported file part number completed
 * @return MbException_t MB_EX_NONE on success, MB_EX_PROTOCOL_ERROR on error.
 *
 ***********************************************************************/
typedef MbException_t (*MbTransferFileCompletedHandler_t)(const struct modbus_t* Mb, uint16_t SlaveAddr, uint32_t PartNumber);

/**********************************************************************/
/**
 * @brief Callback specific to the Transfer File command. It is called after
 *  a new file arrives to server or sniffer.
 *
 * @param  Mb            Modbus driver instance which called the callback
 * @param  FileName      Name of the new file in file system.
 *
 ***********************************************************************/
typedef void (*MbNewFileHandler_t)(const struct modbus_t* Mb, uint8_t* FileName);

/**********************************************************************/
/**
 * @brief Callback called on the command processing end (reporting
 *        overall success/error)
 *
 * This callback should be implemented in the application and settled to the
 * MbSessionClosedCb member of the modbus_t structure.
 *
 * @param  Mb            Modbus driver instance which called the callback
 * @param  Error         Error code occured while command was processed
 * @return MbException_t Error code to return to the client in the Modbus reply
 *                       frame (MB_EX_NONE on success)
 *
 ***********************************************************************/
typedef MbException_t (*MbSessionClosed_t)(const struct modbus_t* Mb, MbException_t Error);

/**********************************************************************/
/**
 * @brief Structure for holding a callback serving one of Modbus commands.
 *        A pointer of array of these structures must be settled as the
 *        FuncHandlers member of the modbus_t structure.
 *
 ***********************************************************************/
struct MbFunctionDescriptor_t
{
  uint8_t FunctionCode;    //!< Modbus command code as per Modbus spec
  void* FunctionHandler;   //!< Function to call. Function type must follow the driver plugin specification for the command. F.ex. MbHoldingHandler_t for Holding Register commands.
};

/**********************************************************************/
/**
 * @brief Structure for holding a number of protocol specific virtual functions.
 *        UART related functions are the part of Modbus driver. Other protocols
 *        must be implemented on the application level.
 *        It is not necessary to implement MbStart and/or MbStop functions,
 *        if there is nothing to do. Thus functions can be settlet to NULL in
 *        the structure.
 *        However MbSendData/MbReceiveData functions are mandatory.
 *        A pointer of array of these structures must be settled as the
 *        Virtualfunc member of the modbus_t structure.
 *
 ***********************************************************************/
struct MbVirtualfunc_t
{
  MbVfuncStart_t MbStart;         //!< Function to call on the protocol start
  MbVfuncStop_t MbStop;           //!< Function to call on the protocol stop
  MbVfuncSend_t MbSendData;       //!< Function to call in order to send data (see MbVfuncSend_t)
  MbVfuncReceive_t MbReceiveData; //!< Function to call in order to send data (see MbVfuncReceive_t)
};

/**********************************************************************/
/**
 * @brief modbus_state_t structure holds internal state of the Modbus driver.
 *
 ***********************************************************************/
struct modbus_state_t {
  const struct modbus_t* Module;             //!< Pointer to the Modbus driver instance structure
  struct process Process;                    //!< Process running the instance (it starts during the MbInit() function call)
  struct mwork_t RespTOwork;                 //!< Client' timeout counter
  uint32_t RespTO;                           //!< Client' timeout value in ms
  struct uwork_t T35work;                    //!< UART 3.5 chars timeout timer
  uint32_t TimerT35;                         //!< UART 3.5 chars timeout value in us
  MbException_t Exception;                   //!< Last communication status
  MbState_t MbState;                         //!< State of the instance (disables/enabled/busy)
  uint8_t MyAddress;                         //!< Slave address of the interface on the Modbus (semistatic, assigned in MbInit() function call)
  uint8_t RcvAddress;                        //!< Slave address of the currently processing Modbus frame
  uint8_t DestAddress;                       //!< Slave address of the last sent Modbus frame (client only)
  uint16_t DestReg;                          //!< First destination register of the last sent Read command (client only)
  uint8_t* MbFrame;                          //!< Current pointer to the processing/assembling Modbus frame
  uint16_t MbFrameLen;                       //!< Current length of the processing/assembling Modbus frame
  void* Transport;                           //!< Pointer to the structure holding transport instance (UART, TCP, TLS...)
  uint8_t SlaveIdBuf[MB_SLAVEID_BUF_LEN];    //!< Buffer holding the Slave ID string
  uint16_t SlaveIdLen;                       //!< Length of the Slave ID string
  uint8_t SndState;                          //!< UART send state for RTU and ASCII
  uint8_t RcvState;                          //!< UART receive state for RTU and ASCII
  uint8_t UartBuf[MB_SER_PDU_SIZE_MAX];      //!< Main buffer for assembling the receiving/transmitting Modbus frame
  uint8_t* UartSndBufCur;                    //!< Current sending pointer in the UartBuf
  uint16_t UartSndBufCount;                  //!< Counter of bytes sent from the UartBuf
  uint16_t UartRcvBufPos;                    //!< Counter of bytes received to the UartBuf

  uint8_t LastFunction;                      //!< For client only: function of last sent packet
  mb_transfer_file_t TransferFile;           //!< Variables related to Transfer File function
};

/**********************************************************************/
/**
 * @brief modbus_t structure is used for configuration of Modbus instance.
 *   The structure must be initialized before the Modbus driver may be used.
 ***********************************************************************/
struct modbus_t {
  struct modbus_state_t* State;                        //!< Pointer to the Modbus driver instance state structure
  MbMode_t Protocol;                                   //!< Protocol type for the instance: TCP, RTU or ASCII
  MbRole_t Role;                                       //!< Instance role on the Modbus: Client, Server or Sniffer
  uint32_t RespTODefault;                              //!< Default client' timeout value in ms (can overrides in each command)
  const struct MbVirtualfunc_t* Virtualfunc;           //!< Callbacks specific to the protocol to start/stop the protocol, receive/send data. For UART these functions are embedded in the Modbus driver (const struct MbVirtualfunc_t MbVirtualFuncRtu). For other carriers such as TLS they must be implemented on the application level.
  const struct MbFunctionDescriptor_t* FuncHandlers;   //!< Callbacks specific to the command and being called during the command processing  to perform command/unit specific task
  MbSessionClosed_t MbSessionClosedCb;                 //!< Callback being called on the command processing end (reporting overall success/error)
  const struct modbus_t* MbClient;                     //!< For sniffer only. Modbus client instance on the same device (for confirmations sending)
};

/**********************************************************************/
/**
 * @brief Virtual functions for the UART protocol. Included in the driver and
 *        ready to be included in modbus_t as an address of this structure.
 *
 ***********************************************************************/
extern const struct MbVirtualfunc_t MbVirtualFuncRtu;

/**********************************************************************/
/**
 * @brief Virtual functions for the standard unsecured TCP protocol (using
 *        socket API). Included in the driver and ready to be included in
 *         modbus_t as an address of this structure.
 *
 ***********************************************************************/
extern const struct MbVirtualfunc_t MbVirtualFuncTcp;

/**********************************************************************/
/**
 * @brief Initialise resources used by the protocol stack instance.
 *
 * This function initialises Modbus instance' state (modbus_state_t)
 * and starts a new OS process for the instance. MbInit() does not allow to
 * use the instance, MbEnable() call is required after initialisation in order
 * to send/receive frames.
 *
 * @note NB: The function can be called only if the instance is not initialised
 *       (first time after reset, or after had been closed by MbClose()).
 *
 * @param  Mb            Modbus driver instance which called the callback
 * @param  MbAddress     Slave address for the instance (ignored for Client role and for TCP protocol)
 * @return MbException_t MB_EX_NONE on success, some other exception on error.
 *
 ***********************************************************************/
MbException_t MbInit(const struct modbus_t* Mb, uint8_t MbAddress);

/**********************************************************************/
/**
 * @brief Release resources used by the protocol stack instance.
 *
 * This function releases all the resources and stops the OS process for
 * the instance.
 *
 * @note NB: The function can be called only if the instance is initialised by
 *       MbInit() and either not yet enabled by MbEnable(), or disabled by
 *       MbDisable().
 *
 * @param  Mb            Modbus driver instance which called the callback
 * @return MbException_t MB_EX_NONE on success, some other exception on error.
 *
 ***********************************************************************/
MbException_t MbClose(const struct modbus_t* Mb);

/**********************************************************************/
/**
 * @brief Enable the Modbus protocol stack instance.
 *
 * This function enables processing of Modbus frames. Enabling the protocol
 * stack is only possible if it is in the disabled state: after MbInit() or
 * MbDisable().
 *
 * @note NB: Mb->Virtualfunc->MbStart callback is called from within this
 *           function if not NULL.
 *
 * @param  Mb            Modbus driver instance which called the callback
 * @param  Data          Pointer to the transport level instance descriptor (uart_t for UART, tls_conn_t for TLS).
 * @return MbException_t MB_EX_NONE on success, some other exception on error.
 *
 ***********************************************************************/
MbException_t MbEnable(const struct modbus_t* Mb, void* Data);

/***********************************************************************/
/**
 * @brief Disable the Modbus protocol stack instance.
 *
 * Enabling the protocol
 * stack is only possible if it is in the enabled state: after MbEnable().
 *
 * @note NB: Mb->Virtualfunc->MbStop callback is called from within this
 *           function if not NULL.
 *
 * @param  Mb            Modbus driver instance which called the callback
 * @return MbException_t MB_EX_NONE on success, some other exception on error.
 *
 ************************************************************************/
MbException_t MbDisable(const struct modbus_t* Mb);

/**********************************************************************/
/**
 * @brief Request to write holding register.
 *
 * Send Modbus command "write holding register" to the bus and set the response
 * timer. It is impossible to send another request before the current one is
 * finished (with success, error or timeout): in such case MB_EX_BUSY is
 * returned.
 * In the end of command execution the callback Mb->MbSessionClosedCb will be
 * called with the result.
 *
 * @note NB: This function is valid for instances having Client role only.
 *
 * @param  Mb            Modbus driver instance which called the callback
 * @param  DestAddr      Slave address to send to (can be MB_ADDRESS_BROADCAST)
 * @param  RegAddr       Register to write to
 * @param  RegData       Data to write
 * @param  TimeOut       Command timeout in ms (if 0, the default for modbus_t is used).
 * @return MbException_t MB_EX_NONE on success, some other exception on error.
 *
 ************************************************************************/
MbException_t MbReqWriteHolding(const struct modbus_t* Mb, uint8_t DestAddr,
                                uint16_t RegAddr, uint16_t RegData, int32_t TimeOut);

/**********************************************************************/
/**
 * @brief Request to write multiple holding registers.
 *
 * Send Modbus command "write multiple registers" to the bus and set the response
 * timer. It is impossible to send another request before the current one is
 * finished (with success, error or timeout): in such case MB_EX_BUSY is
 * returned.
 * In the end of command execution the callback Mb->MbSessionClosedCb will be
 * called with the result.
 *
 * @note NB: This function is valid for instances having Client role only.
 *
 * @param  Mb            Modbus driver instance which called the callback
 * @param  DestAddr      Slave address to send to (can be MB_ADDRESS_BROADCAST)
 * @param  RegAddr       First register to write to
 * @param  NRegs         Number of registers to write
 * @param  DataBuffer    Pointer to the data to write (must be NRegs*2 bytes long).
 * @param  TimeOut       Command timeout in ms (if 0, the default for modbus_t is used).
 * @return MbException_t MB_EX_NONE on success, some other exception on error.
 *
 ************************************************************************/
MbException_t MbReqWriteMultiple(const struct modbus_t* Mb, uint8_t DestAddr,
                                 uint16_t RegAddr, uint16_t NRegs,
                                 uint16_t* DataBuffer, int32_t TimeOut);

/**********************************************************************/
/**
 * @brief Request to read holding registers.
 *
 * Send Modbus command "read holding registers" to the bus and set the response
 * timer. It is impossible to send another request before the current one is
 * finished (with success, error or timeout): in such case MB_EX_BUSY is
 * returned.
 * In the end of command execution the callback Mb->MbSessionClosedCb will be
 * called with the result.
 *
 * @note NB: This function is valid for instances having Client role only.
 *
 * @param  Mb            Modbus driver instance which called the callback
 * @param  DestAddr      Slave address to send to
 * @param  RegAddr       First register to read from
 * @param  NRegs         Number of registers to read
 * @param  TimeOut       Command timeout in ms (if 0, the default for modbus_t is used).
 * @return MbException_t MB_EX_NONE on success, some other exception on error.
 *
 ************************************************************************/
MbException_t MbReqReadHolding(const struct modbus_t* Mb, uint8_t DestAddr,
                               uint16_t RegAddr, uint16_t NRegs, int32_t TimeOut);

/**********************************************************************/
/**
 * @brief Request to write file.
 *
 * Send Modbus command "write file record" to the bus and set the response
 * timer. It is impossible to send another request before the current one is
 * finished (with success, error or timeout): in such case MB_EX_BUSY is
 * returned.
 * In the end of command execution the callback Mb->MbSessionClosedCb will be
 * called with the result.
 *
 * @note NB: This function is valid for instances having Client role only.
 *
 * @param  Mb            Modbus driver instance which called the callback
 * @param  DestAddr      Slave address to send to (can be MB_ADDRESS_BROADCAST)
 * @param  FileNum       File number to write to
 * @param  RecNum        Record number to write
 * @param  Data          Pointer to the data to write.
 * @param  DataLen       Data length in bytes.
 * @param  TimeOut       Command timeout in ms (if 0, the default for modbus_t is used).
 * @return MbException_t MB_EX_NONE on success, some other exception on error.
 *
 ************************************************************************/
MbException_t MbReqWriteFile(const struct modbus_t* Mb, uint8_t DestAddr,
                             uint16_t FileNum, uint16_t RecNum,
                             uint8_t* Data, uint16_t DataLen,
                             int32_t TimeOut);

/**********************************************************************/
/**
 * @brief Request to transfer file header.
 *
 * Send Jetro proprietary Modbus command "transfer file" with file header
 * information (the first PDU in file transfer procedure) to the bus and set
 * the response timer. It is impossible to send another request before the
 * current one is finished (with success, error or timeout): in such case
 * MB_EX_BUSY is returned.
 * In the end of command execution the callback Mb->MbSessionClosedCb will be
 * called with the result.
 *
 * @note NB: This function is valid for instances having Client role only.
 *
 * @param  Mb            Modbus driver instance which called the callback
 * @param  Targets       uint8_t[31] is actually 248 bit array of Modbus device addresses the file transfers to.
 * @param  FileSize      File size in bytes
 * @param  Crc32         File Crc calculated by crc32_compute() from nRF SDK from 1) file name, 2) file size (4 bytes), 3) file content.
 * @param  FileName      Pointer to an ASCII null-terminated string containing file name.
 * @param  TimeOut       Command timeout in ms (if 0, the default for modbus_t is used).
 * @return MbException_t MB_EX_NONE on success, some other exception on error.
 *
 ************************************************************************/
MbException_t MbReqTransferFile(const struct modbus_t* Mb, uint8_t* Targets,
                                uint32_t FileSize, uint32_t Crc32,
                                uint8_t* FileName, int32_t TimeOut);

/**********************************************************************/
/**
 * @brief Request to transfer file data.
 *
 * Send Jetro proprietary Modbus command "transfer file" with file data
 * (all but the first PDU in file transfer procedure) to the bus and set
 * the response timer. It is impossible to send another request before the
 * current one is finished (with success, error or timeout): in such case
 * MB_EX_BUSY is returned.
 * In the end of command execution the callback Mb->MbSessionClosedCb will be
 * called with the result.
 *
 * @note NB: This function is valid for instances having Client role only.
 *
 * @param  Mb            Modbus driver instance which called the callback
 * @param  PartNumber    File part number (1-0x7FFFFFFF). Can't be 0 as 0th part
 *                       transfers with MbReqTransferFileHeader() function.\n
 *                       Highest bit denotes last part.
 * @param  PartSize      Part size in bytes (247 bytes max)
 * @param  Data          Pointer to the data to transfer.
 * @param  TimeOut       Command timeout in ms (if 0, the default for modbus_t is used).
 * @return MbException_t MB_EX_NONE on success, some other exception on error.
 *
 ************************************************************************/
MbException_t MbReqTransferFileData(const struct modbus_t* Mb,
                                    uint32_t PartNumber, uint8_t PartSize,
                                    uint8_t* Data, int32_t TimeOut);

/**********************************************************************/
/**
 * @brief Request to send "transfer file complete" message.
 *
 * Send Jetro proprietary Modbus command "transfer file complete" to the bus
 * and set the response timer. It is impossible to send another request before
 * the current one is finished (with success, error or timeout): in such case
 * MB_EX_BUSY is returned.
 * In the end of command execution the callback Mb->MbSessionClosedCb will be
 * called with the result.
 *
 * @note NB: This function is valid for instances having Client role only.
 *
 * @param  Mb            Modbus driver instance which called the callback
 * @param  MyAddress     Modbus own sniffer address of the device
 * @param  PartNumber    Part number received
 * @param  TimeOut       Command timeout in ms (if 0, the default for modbus_t is used).
 * @return MbException_t MB_EX_NONE on success, some other exception on error.
 *
 ************************************************************************/
MbException_t MbReqTransferFileCompleted(const struct modbus_t* Mb, uint8_t MyAddress,
                                         uint32_t PartNumber, int32_t TimeOut);

/** @} modbus */

#endif // MODBUS_H_INCLUDED