模块－modbus模块

Detailed Description详细描述

 #include "mb.h" 

This module defines the 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 eMBInit() first. If the device is ready to answer network requests it must then call eMBEnable() to activate the protocol stack. In the main loop the function eMBPoll() must be called periodically. The time interval between pooling depends on the configured Modbus timeout. If an RTOS is available a separate task should be created and the task should always call the function eMBPoll().

这个模块为应用定义了接口。它包括了使用Modbus协议栈所必须的基本功能函数和类型。一个典型的应用程序将会首先调用eMBInit()函数。如果该设备需要回应网络请求，则其必须调用eMBEnable()函数来激活协议栈。在主循环中，函数eMBPoll()将会被周期性调用。两次调用的时间间隔决定于Modbus的超时时间设置。如果使用了RTOS，用户则必须创建一个独立的任务，并且该任务必须一直调用函数eMBPoll()。

 // Initialize protocol stack in RTU mode for a slave with address 10 = 0x0A

 eMBInit( MB_RTU, 0x0A, 38400, MB_PAR_EVEN );

 // Enable the Modbus Protocol Stack.

 eMBEnable(  );

 for( ;; )

 {

     // Call the main polling loop of the Modbus protocol stack.

     eMBPoll(  );

     ...

 }

Defines定义
#define	MB_TCP_PORT_USE_DEFAULT   0
Enumerations枚举类型
enum	eMBMode { MB_RTU, MB_ASCII, MB_TCP } Modbus协议的模式：RTU ，ASCII 和TCP
enum	eMBRegisterMode { MB_REG_READ, MB_REG_WRITE } Modbus寄存器的模式：READ和WRITE
enum	eMBErrorCode {   MB_ENOERR, MB_ENOREG, MB_EINVAL, MB_EPORTERR,   MB_ENORES, MB_EIO, MB_EILLSTATE, MB_ETIMEDOUT } 错误码：没有错误，没有寄存器，无效，   ，   ，IO错误，无效   ，超时
enum	eMBParity { MB_PAR_NONE, MB_PAR_ODD, MB_PAR_EVEN } Modbus数据帧的校验类型：无校验，偶校验，奇校验
Functions函数
eMBErrorCode	eMBInit (eMBMode eMode, UCHAR ucSlaveAddress, UCHAR ucPort, ULONG ulBaudRate, eMBParity eParity) 协议初始化函数 输入参数： eMBMode eMode, Modubus协议模式 UCHAR ucSlaveAddress, 子模块地址 UCHAR ucPort, 端口 ULONG ulBaudRate, 波特率 eMBParity eParity 串行数据的奇偶校验
eMBErrorCode	eMBTCPInit (USHORT usTCPPort) 如果使用了TCP协议，则用该函数进行初始化
eMBErrorCode	eMBClose (void) 关闭Modbus协议栈
eMBErrorCode	eMBEnable (void) 使能Modbus协议栈
eMBErrorCode	eMBDisable (void) 禁止Modbus协议栈
eMBErrorCode	eMBPoll (void) 周期性调用的协议处理函数
eMBErrorCode	eMBSetSlaveID (UCHAR ucSlaveID, BOOL xIsRunning, UCHAR const *pucAdditional, USHORT usAdditionalLen) 设置子模块ID 输入参数： UCHAR ucSlaveID, 子模块ID BOOL xIsRunning, UCHAR const *pucAdditional, USHORT usAdditionalLen
eMBErrorCode	eMBRegisterCB (UCHAR ucFunctionCode, pxMBFunctionHandler pxHandler) Modbus协议的寄存器回调函数 输入参数： UCHAR ucFunctionCode, 功能码 pxMBFunctionHandler pxHandler功能码对应的处理函数

---

Define Documentation文档

#define MB_TCP_PORT_USE_DEFAULT   0

 

Use the default Modbus TCP port (502). 使用缺省的ModbusTCP移植 Examples: MCF5235TCP/demo.c, STR71XTCP/demo.c, and WIN32TCP/demo.cpp.

---

Enumeration Type Documentation枚举类型定义

enum eMBErrorCode

 

Errorcodes used by all function in the protocol stack. 在协议栈中所有函数使用的错误码 Enumeration values: 枚举值 MB_ENOERR  no error. 没有错误 MB_ENOREG  illegal register address. 无效的寄存器地址 MB_EINVAL  illegal argument. 无效的参数 MB_EPORTERR  porting layer error. 移植层错误 MB_ENORES  insufficient resources. 资源不足 MB_EIO  I/O error. I/O错误 MB_EILLSTATE  protocol stack in illegal state. 协议栈状态错误 MB_ETIMEDOUT  timeout error occurred. 超时错误 Examples: 例子： AT91SAM7X_ROWLEY/demo.c, AVR/demo.c, LINUX/demo.c, MCF5235/demo.c, MCF5235TCP/demo.c, MSP430/demo.c, STR71X/simple2.c, STR71XTCP/demo.c, WIN32/demo.cpp, and WIN32TCP/demo.cpp.

 

enum eMBMode

 

Modbus serial transmission modes (RTU/ASCII). Modubs串行传输模式 Modbus serial supports two transmission modes. Either ASCII or RTU. RTU is faster but has more hardware requirements and requires a network with a low jitter. ASCII is slower and more reliable on slower links (E.g. modems) Modbus串行传输支持两种模式，ASCII或者是RTU。RTU模式较快但是具有较高的硬件要求并且要求网络延迟要低。ASCII模式较慢，但是在低速连接中更加可靠（如moderms）。 Enumeration values: MB_RTU  RTU transmission mode. RTU传输模式 MB_ASCII  ASCII transmission mode. ASCII传输模式 MB_TCP  TCP mode. TCP模式

 

enum eMBParity

 

Parity used for characters in serial mode. 串行模式中字符的极性 The parity which should be applied to the characters sent over the serial link. Please note that this values are actually passed to the porting layer and therefore not all parity modes might be available. 串行字符传输时应用的校验格式。需要注意，这个值其实是传给移植层，并且不是所有的奇偶模式都能有效。 Enumeration values: MB_PAR_NONE  No parity.  无奇偶校验 MB_PAR_ODD  Odd parity. 偶校验 MB_PAR_EVEN  Even parity. 奇校验

 

enum eMBRegisterMode

 

If register should be written or read. 寄存器是读还是写 This value is passed to the callback functions which support either reading or writing register values. Writing means that the application registers should be updated and reading means that the modbus protocol stack needs to know the current register values. 值将传给支持读或者写寄存器的回调函数。写意味着应用寄存器更新，读表示Modbus协议栈需要知道当前寄存器的数值。 See also: eMBRegHoldingCB( ), eMBRegCoilsCB( ), eMBRegDiscreteCB( ) and eMBRegInputCB( ). Enumeration values: MB_REG_READ  Read register values and pass to protocol stack. 读寄存器数值并且传给协议栈 MB_REG_WRITE  Update register values. 更新寄存器数值 Examples: AT91SAM7X_ROWLEY/demo.c, AVR/demo.c, LINUX/demo.c, MCF5235/demo.c, MCF5235TCP/demo.c, MSP430/demo.c, STR71X/simple2.c, STR71XTCP/demo.c, WIN32/demo.cpp, and WIN32TCP/demo.cpp.

---

Function Documentation

eMBErrorCode eMBClose (  void     )

 

Release resources used by the protocol stack. 释放协议栈使用的资源。 This function disables the Modbus protocol stack and release all hardware resources. It must only be called when the protocol stack is disabled. 该函数禁止Modbus协议栈并且释放所有的硬件资源。只有当协议栈被禁止了，才能调用这个函数。 Note: 注意 Note all ports implement this function. A port which wants to get an callback must define the macro MB_PORT_HAS_CLOSE to 1. 注意所有的移植都要实现这个函数。需要获取回调 Returns: If the resources where released it return eMBErrorCode::MB_ENOERR. If the protocol stack is not in the disabled state it returns eMBErrorCode::MB_EILLSTATE. 如果资源释放了，该函数返回eMBErrorCode::MB_ENOERR。如果协议栈不是处于禁止状态，它返回eMBErrorCode::MB_EILLSTATE。 Examples: LINUX/demo.c, MCF5235TCP/demo.c, STR71XTCP/demo.c, WIN32/demo.cpp, and WIN32TCP/demo.cpp.

 

eMBErrorCode eMBDisable (  void     )

 

Disable the Modbus protocol stack. 禁止Modbus协议栈。 This function disables processing of Modbus frames. 这个函数禁止处理Modbus帧。 Returns: 返回 If the protocol stack has been disabled it returns eMBErrorCode::MB_ENOERR. If it was not in the enabled state it returns eMBErrorCode::MB_EILLSTATE. Examples: LINUX/demo.c, MCF5235TCP/demo.c, STR71XTCP/demo.c, WIN32/demo.cpp, and WIN32TCP/demo.cpp.

 

eMBErrorCode eMBEnable (  void     )

 

Enable the Modbus protocol stack. 使能Modbus协议栈 This function enables processing of Modbus frames. Enabling the protocol stack is only possible if it is in the disabled state. 本函数使能Modbus帧的处理。 Returns: If the protocol stack is now in the state enabled it returns eMBErrorCode::MB_ENOERR. If it was not in the disabled state it return eMBErrorCode::MB_EILLSTATE. Examples: AT91SAM7X_ROWLEY/demo.c, AVR/demo.c, LINUX/demo.c, MCF5235/demo.c, MCF5235TCP/demo.c, MSP430/demo.c, STR71X/simple2.c, STR71XTCP/demo.c, WIN32/demo.cpp, and WIN32TCP/demo.cpp.

 

eMBErrorCode eMBInit (  eMBMode  eMode,     UCHAR  ucSlaveAddress,     UCHAR  ucPort,     ULONG  ulBaudRate,     eMBParity  eParity   )

 

Initialize the Modbus protocol stack. 初始化Modbus协议栈 This functions initializes the ASCII or RTU module and calls the init functions of the porting layer to prepare the hardware. Please note that the receiver is still disabled and no Modbus frames are processed until eMBEnable( ) has been called. 该函数初始化为ASCII或者RTU模式，并且调用移植层的初始化函数来准备硬件。需要注意的是，接受依然是禁止的，并且Modbus数据帧都不会得到处理，除非eMBEnable( )被调用。 Parameters:   eMode  If ASCII or RTU mode should be used. Modbus模式   ucSlaveAddress  The slave address. Only frames sent to this address or to the broadcast address are processed. 子模块地址。只有发向本模块地址或者广播地址的数据帧能得到处理。   ucPort  The port to use. E.g. 1 for COM1 on windows. This value is platform dependent and some ports simply choose to ignore it. 使用的端口。该值是硬件相关的，许多移植都会选择忽略该参数。   ulBaudRate  The baudrate. E.g. 19200. Supported baudrates depend on the porting layer. 波特率，所支持的波特率决定于移植层。   eParity  Parity used for serial transmission.串行传输使用的校验。 Returns: If no error occurs the function returns eMBErrorCode::MB_ENOERR. The protocol is then in the disabled state and ready for activation by calling eMBEnable( ). Otherwise one of the following error codes is returned: ·   eMBErrorCode::MB_EINVAL If the slave address was not valid. Valid slave addresses are in the range 1 - 247. ·   eMBErrorCode::MB_EPORTERR IF the porting layer returned an error. 如果没有错误，这个函数返回eMBErrorCode::MB_ENOERR。协议栈将处于禁止状态，可以通过调用eMBEnable( )来激活。否则，将返回下列的一个错误： ·   eMBErrorCode::MB_EINVAL 如果子模块地址无效。 ·   eMBErrorCode::MB_EPORTERR 如果移植层返回一个错误。 Examples: AT91SAM7X_ROWLEY/demo.c, AVR/demo.c, LINUX/demo.c, MCF5235/demo.c, MSP430/demo.c, STR71X/simple2.c, and WIN32/demo.cpp.

 

eMBErrorCode eMBPoll (  void     )

 

The main pooling loop of the Modbus protocol stack. Modbus协议栈的主轮询函数。 This function must be called periodically. The timer interval required is given by the application dependent Modbus slave timeout. Internally the function calls xMBPortEventGet() and waits for an event from the receiver or transmitter state machines. 该函数必须被周期性调用。两次调用的时间间隔决定于Modbus的超时时间设置。在函数内部调用了xMBPortEventGet()函数来等待接受或者发送状态机发出的事件。 Returns: If the protocol stack is not in the enabled state the function returns eMBErrorCode::MB_EILLSTATE. Otherwise it returns eMBErrorCode::MB_ENOERR. 如果协议栈没有被使能，这个函数返回eMBErrorCode::MB_EILLSTATE.，否则返回eMBErrorCode::MB_ENOERR. Examples: AT91SAM7X_ROWLEY/demo.c, AVR/demo.c, LINUX/demo.c, MCF5235/demo.c, MCF5235TCP/demo.c, MSP430/demo.c, STR71X/simple2.c, STR71XTCP/demo.c, WIN32/demo.cpp, and WIN32TCP/demo.cpp.

 

eMBErrorCode eMBRegisterCB (  UCHAR  ucFunctionCode,     pxMBFunctionHandler  pxHandler   )

 

Registers a callback handler for a given function code. 为给定的功能码注册一个回调处理函数。 This function registers a new callback handler for a given function code. The callback handler supplied is responsible for interpreting the Modbus PDU and the creation of an appropriate response. In case of an error it should return one of the possible Modbus exceptions which results in a Modbus exception frame sent by the protocol stack. 这个函数为一个给定的功能代码注册一个新的回调函数。提供的回调函数负责解释Modbus PDU并且创建一个合适的应答。当错误发生时，这个函数会返回一个Modbus异常，该异常是由协议栈发送的Modbus异常。 Parameters: 参数   ucFunctionCode  The Modbus function code for which this handler should be registers. Valid function codes are in the range 1 to 127. 注册的功能码，有效的功能码范围是1到127   pxHandler  The function handler which should be called in case such a frame is received. If NULL a previously registered function handler for this function code is removed. 功能码对应的回调函数。如果为空，一个以前定义功能码回调函数将被去掉。 Returns: 返回 eMBErrorCode::MB_ENOERR if the handler has been installed. If no more resources are available it returns eMBErrorCode::MB_ENORES. In this case the values in mbconfig.h should be adjusted. If the argument was not valid it returns eMBErrorCode::MB_EINVAL. eMBErrorCode::MB_ENOERR 如果回调函数正常安装。如果资源不足，将返回 eMBErrorCode::MB_ENORES. 在这种情况下，在 mbconfig.h 中定义的数值必须进行修改。如果参数无效，函数将返回 eMBErrorCode::MB_EINVAL.

 

eMBErrorCode eMBSetSlaveID (  UCHAR  ucSlaveID,     BOOL  xIsRunning,     UCHAR const *  pucAdditional,     USHORT  usAdditionalLen   )

 

Configure the slave id of the device. 设置设备的ID This function should be called when the Modbus function Report Slave ID is enabled ( By defining MB_FUNC_OTHER_REP_SLAVEID_ENABLED in mbconfig.h ). 当使用Modbus的Report Slave ID 功能时，这个函数将会被调用（通过在mbconfig.h 中定义MB_FUNC_OTHER_REP_SLAVEID_ENABLED）。 Parameters:   ucSlaveID  Values is returned in the Slave ID byte of the Report Slave ID response.   xIsRunning  If TRUE the Run Indicator Status byte is set to 0xFF. otherwise the Run Indicator Status is 0x00.   pucAdditional  Values which should be returned in the Additional bytes of the Report Slave ID response.   usAdditionalLen  Length of the buffer pucAdditonal. Returns: If the static buffer defined by MB_FUNC_OTHER_REP_SLAVEID_BUF in mbconfig.h is to small it returns eMBErrorCode::MB_ENORES. Otherwise it returns eMBErrorCode::MB_ENOERR. Examples: AVR/demo.c, LINUX/demo.c, MCF5235/demo.c, and WIN32/demo.cpp.

 

eMBErrorCode eMBTCPInit (  USHORT  usTCPPort  )

 

Initialize the Modbus protocol stack for Modbus TCP. Modbus TCP的协议初始化 This function initializes the Modbus TCP Module. Please note that frame processing is still disabled until eMBEnable( ) is called. 该函数初始化Modbus TCP 模块。注意，帧处理在eMBEnable()函数调用之前是禁止掉的。 Parameters: 参数   usTCPPort  The TCP port to listen on. 监听的TCP端口 Returns: 返回 If the protocol stack has been initialized correctly the function returns eMBErrorCode::MB_ENOERR. Otherwise one of the following error codes is returned: ·   eMBErrorCode::MB_EINVAL If the slave address was not valid. Valid slave addresses are in the range 1 - 247. ·   eMBErrorCode::MB_EPORTERR IF the porting layer returned an error. 如果协议栈初始化正确，函数返回MB_ENOERR。否则，函数会返回如下的错误码： ·   eMBErrorCode::MB_EINVAL如果子模块地址无效，有效的子地址范围是1－247 ·   eMBErrorCode::MB_EPORTERR如果移植层返回一个错误。 Examples: MCF5235TCP/demo.c, STR71XTCP/demo.c, and WIN32TCP/demo.cpp.