Freemodbus文档1：模块

转自 http://blog.sina.com.cn/s/blog_4935209001012eb5.html

文档：模块

这个模块为应用定义了接口。它包括了使用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(  );

     ...

}

 

 

定义

#define 

MB_TCP_PORT_USE_DEFAULT   0

 

枚举类型

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数据帧的校验类型：无校验，偶校验，奇校验

 

函数

eMBErrorCode 

eMBInit (eMBMode eMode,UCHAR ucSlaveAddress, UCHAR ucPort, ULONGulBaudRate, eMBParityeParity)

协议初始化函数

输入参数：

eMBMode eMode,Modubus协议模式

UCHAR ucSlaveAddress, 子模块地址

UCHAR ucPort, 端口

ULONG ulBaudRate, 波特率

eMBParity eParity 串行数据的奇偶校验

eMBErrorCode 

eMBTCPInit (USHORTusTCPPort)

如果使用了TCP协议，则用该函数进行初始化

eMBErrorCode 

eMBClose (void)

关闭Modbus协议栈

eMBErrorCode 

eMBEnable (void)

使能Modbus协议栈

eMBErrorCode 

eMBDisable (void)

禁止Modbus协议栈

eMBErrorCode 

eMBPoll (void)

周期性调用的协议处理函数

eMBErrorCode 

eMBSetSlaveID (UCHARucSlaveID, BOOL xIsRunning, UCHAR const *pucAdditional, USHORTusAdditionalLen)

设置子模块ID

输入参数：

UCHAR ucSlaveID, 子模块ID

BOOL xIsRunning,

UCHAR const *pucAdditional,

USHORT usAdditionalLen

eMBErrorCode 

eMBRegisterCB (UCHARucFunctionCode, pxMBFunctionHandler pxHandler)

Modbus协议的寄存器回调函数

输入参数：

UCHAR ucFunctionCode, 功能码

pxMBFunctionHandler pxHandler功能码对应的处理函数

---

DefineDocumentation文档

#defineMB_TCP_PORT_USE_DEFAULT   0

 

Use the defaultModbus TCP port (502).

使用缺省的ModbusTCP移植

Examples:

MCF5235TCP/demo.c, STR71XTCP/demo.c,and WIN32TCP/demo.cpp.

---

枚举类型定义

 

• enum eMBErrorCode

 

在协议栈中所有函数使用的错误码

枚举值: 

MB_ENOERR 

 没有错误

MB_ENOREG 

无效的寄存器地址

MB_EINVAL 

无效的参数

MB_EPORTERR 

 移植层错误

MB_ENORES 

资源不足

MB_EIO 

I/O错误

MB_EILLSTATE 

协议栈状态错误

MB_ETIMEDOUT 

超时错误

例子：

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 serialtransmission modes (RTU/ASCII).

Modubs串行传输模式

Modbus串行传输支持两种模式，ASCII或者是RTU。RTU模式较快但是具有较高的硬件要求并且要求网络延迟要低。ASCII模式较慢，但是在低速连接中更加可靠（如moderms）。

枚举值:

MB_RTU 

RTU传输模式

MB_ASCII 

ASCII传输模式

MB_TCP 

TCP模式

• enum eMBParity

 

串行模式中字符的极性

串行字符传输时应用的校验格式。需要注意，这个值其实是传给移植层，并且不是所有的奇偶模式都能有效。

Enumeration values:

MB_PAR_NONE 

无奇偶校验

MB_PAR_ODD 

偶校验

MB_PAR_EVEN 

奇校验

 

• enum eMBRegisterMode

 

寄存器是读还是写

值将传给支持读或者写寄存器的回调函数。写意味着应用寄存器更新，读表示Modbus协议栈需要知道当前寄存器的数值。

See also:

eMBRegHoldingCB(), eMBRegCoilsCB(), eMBRegDiscreteCB() and eMBRegInputCB().

枚举值:

MB_REG_READ 

读寄存器数值并且传给协议栈

MB_REG_WRITE 

更新寄存器数值

例子:

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 eMBClose(void )

 

 

释放协议栈使用的资源。

该函数禁止Modbus协议栈并且释放所有的硬件资源。只有当协议栈被禁止了，才能调用这个函数。

注意: 

Note all ports implement this function. A port which wantsto get an callback must define the macro MB_PORT_HAS_CLOSE to1.

注意所有的移植都要实现这个函数。需要获取回调

返回:

如果资源释放了，该函数返回eMBErrorCode::MB_ENOERR。如果协议栈不是处于禁止状态，它返回eMBErrorCode::MB_EILLSTATE。

 

例子:

LINUX/demo.c, MCF5235TCP/demo.c, STR71XTCP/demo.c, WIN32/demo.cpp,andWIN32TCP/demo.cpp.

  eMBErrorCode eMBDisable(void )

 

 

 

 

禁止Modbus协议栈。

这个函数禁止处理Modbus帧。

返回: 

If the protocol stack has been disabled itreturns eMBErrorCode::MB_ENOERR.If it was not in the enabled state itreturns eMBErrorCode::MB_EILLSTATE.

例子:

LINUX/demo.c, MCF5235TCP/demo.c, STR71XTCP/demo.c, WIN32/demo.cpp,andWIN32TCP/demo.cpp.

 

• eMBErrorCode eMBEnable(void )

 

 

 

使能Modbus协议栈

本函数使能Modbus帧的处理。

返回:

If the protocol stack is now in the state enabled itreturns eMBErrorCode::MB_ENOERR.If it was not in the disabled state itreturn eMBErrorCode::MB_EILLSTATE.

例子:

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

 

) 

 

 

初始化Modbus协议栈

该函数初始化为ASCII或者RTU模式，并且调用移植层的初始化函数来准备硬件。需要注意的是，接受依然是禁止的，并且Modbus数据帧都不会得到处理，除非eMBEnable()被调用。

参数:

 

eMode 

Modbus模式：ASCII或RTU

 

ucSlaveAddress 

子模块地址。只有发向本模块地址或者广播地址的数据帧能得到处理。

 

ucPort 

The port to use. E.g. 1 for COM1 on windows. Thisvalue is platform dependent and some ports simply choose to ignoreit.

使用的端口。该值是硬件相关的，许多移植都会选择忽略该参数。

 

ulBaudRate 

The baudrate. E.g. 19200. Supported baudratesdepend on the porting layer. 波特率，所支持的波特率决定于移植层。

 

eParity 

串行传输使用的校验。

返回:

如果没有错误，这个函数返回eMBErrorCode::MB_ENOERR。协议栈将处于禁止状态，可以通过调用eMBEnable( )来激活。否则，将返回下列的一个错误：

·   eMBErrorCode::MB_EINVAL 如果子模块地址无效。

·   eMBErrorCode::MB_EPORTERR 如果移植层返回一个错误。

例子:

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  )

 

Modbus协议栈的主轮询函数。

该函数必须被周期性调用。两次调用的时间间隔决定于Modbus的超时时间设置。在函数内部调用了xMBPortEventGet()函数来等待接受或者发送状态机发出的事件。

返回:

如果协议栈没有被使能，这个函数返回eMBErrorCode::MB_EILLSTATE.，否则返回eMBErrorCode::MB_ENOERR.

例子:

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

   

  ) 

   

为给定的功能码注册一个回调处理函数。

这个函数为一个给定的功能代码注册一个新的回调函数。提供的回调函数负责解释ModbusPDU并且创建一个合适的应答。当错误发生时，这个函数会返回一个Modbus异常，该异常是由协议栈发送的Modbus异常。

参数: 

 

ucFunctionCode 

注册的功能码，有效的功能码范围是1到127

 

pxHandler 

功能码对应的回调函数。如果为空，一个以前定义功能码回调函数将被去掉。

 

返回: 

eMBErrorCode::MB_ENOERR 如果回调函数正常安装。如果资源不足，将返回eMBErrorCode::MB_ENORES. 在这种情况下，在 mbconfig.h 中定义的数值必须进行修改。如果参数无效，函数将返回 eMBErrorCode::MB_EINVAL.

 

 

• eMBErrorCode eMBSetSlaveID

( 

UCHAR 

ucSlaveID,

 

 

BOOL 

xIsRunning,

 

 

UCHAR const* 

pucAdditional,

 

 

USHORT 

usAdditionalLen

 

)

 

 

设置设备的ID

当使用Modbus的Report Slave ID 功能时，这个函数将会被调用（通过在mbconfig.h 中定义MB_FUNC_OTHER_REP_SLAVEID_ENABLED）。

参数:

 

ucSlaveID 

Values is returned inthe SlaveID byte ofthe ReportSlave ID response.

 

xIsRunning 

If TRUE the Run IndicatorStatus byte is set to 0xFF. otherwisethe RunIndicator Statusis 0x00.

 

pucAdditional 

Values which should be returned inthe Additional bytesof the Report SlaveID response.

 

usAdditionalLen 

Length of thebuffer pucAdditonal.

返回:

If the static buffer defined byMB_FUNC_OTHER_REP_SLAVEID_BUF in mbconfig.h isto small it returnseMBErrorCode::MB_ENORES.Otherwise it returns eMBErrorCode::MB_ENOERR.

例子:

AVR/demo.c, LINUX/demo.c, MCF5235/demo.c,and WIN32/demo.cpp.

•  eMBErrorCode eMBTCPInit

( 

USHORT 

usTCPPort

 )

 

ModbusTCP的协议初始化

该函数初始化ModbusTCP 模块。注意，帧处理在eMBEnable()函数调用之前是禁止掉的。

参数: 

 

usTCPPort 

 监听的TCP端口

返回: 

如果协议栈初始化正确，函数返回MB_ENOERR。否则，函数会返回如下的错误码：

 

·   eMBErrorCode::MB_EINVAL如果子模块地址无效，有效的子地址范围是1－247

·   eMBErrorCode::MB_EPORTERR如果移植层返回一个错误。

Examples:

MCF5235TCP/demo.c, STR71XTCP/demo.c,and WIN32TCP/demo.cpp.