free-modbus详解.docx

freemodbus之协议模块2007-12-27 10:43:32作者：来源：freemodbus之Modbus协议配置浏览次数：844文字大小：【大】【中】【小】简介：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 ty .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定义#defineMB_TCP_PORT_USE_DEFAULT0Enumerations枚举类型enum eMBModeMB_RTU,MB_ASCII,MB_TCPModbus协议的模式：RTU，ASCII和TCPenum eMBRegisterModeMB_REG_READ,MB_REG_WRITEModbus寄存器的模式：READ和WRITEenum eMBErrorCodeMB_ENOERR,MB_ENOREG,MB_EINVAL,MB_EPORTERR,MB_ENORES,MB_EIO,MB_EILLSTATE,MB_ETIMEDOUT错误码：没有错误，没有寄存器，无效，IO错误，无效，超时enum eMBParityMB_PAR_NONE,MB_PAR_ODD,MB_PAR_EVENModbus数据帧的校验类型：无校验，偶校验，奇校验Functions函数eMBErrorCodeeMBInit(eMBModeeMode, UCHAR ucSlaveAddress, UCHAR ucPort, ULONG ulBaudRate,eMBParityeParity)协议初始化函数输入参数：eMBModeeMode, Modubus协议模式UCHAR ucSlaveAddress,子模块地址UCHAR ucPort,端口ULONG ulBaudRate,波特率eMBParityeParity串行数据的奇偶校验eMBErrorCodeeMBTCPInit(USHORT usTCPPort)如果使用了TCP协议，则用该函数进行初始化eMBErrorCodeeMBClose(void)关闭Modbus协议栈eMBErrorCodeeMBEnable(void)使能Modbus协议栈eMBErrorCodeeMBDisable(void)禁止Modbus协议栈eMBErrorCodeeMBPoll(void)周期性调用的协议处理函数eMBErrorCodeeMBSetSlaveID(UCHAR ucSlaveID, BOOL xIsRunning, UCHAR const *pucAdditional, USHORT usAdditionalLen)设置子模块ID输入参数：UCHAR ucSlaveID,子模块IDBOOL xIsRunning,UCHAR const *pucAdditional,USHORT usAdditionalLeneMBErrorCodeeMBRegisterCB(UCHAR ucFunctionCode, pxMBFunctionHandler pxHandler)Modbus协议的寄存器回调函数输入参数：UCHAR ucFunctionCode,功能码pxMBFunctionHandler pxHandler功能码对应的处理函数Define Documentation文档#define MB_TCP_PORT_USE_DEFAULT0Use the default Modbus TCP port (502).使用缺省的ModbusTCP移植Examples:MCF5235TCP/demo.c,STR71XTCP/demo.c, andWIN32TCP/demo.cpp.Enumeration Type Documentation枚举类型定义enumeMBErrorCodeErrorcodes used by all function in the protocol stack.在协议栈中所有函数使用的错误码Enumeration values:枚举值MB_ENOERRno error.没有错误MB_ENOREGillegal register address.无效的寄存器地址MB_EINVALillegal argument.无效的参数MB_EPORTERRporting layer error.移植层错误MB_ENORESinsufficient resources.资源不足MB_EIOI/O error. I/O错误MB_EILLSTATEprotocol stack in illegal state.协议栈状态错误MB_ETIMEDOUTtimeout 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, andWIN32TCP/demo.cpp.enumeMBModeModbus 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_RTURTU transmission mode. RTU传输模式MB_ASCIIASCII transmission mode. ASCII传输模式MB_TCPTCP mode. TCP模式enumeMBParityParity 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_NONENo parity.无奇偶校验MB_PAR_ODDOdd parity.偶校验MB_PAR_EVENEven parity.奇校验enumeMBRegisterModeIf 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( )andeMBRegInputCB( ).Enumeration values:MB_REG_READRead register values and pass to protocol stack.读寄存器数值并且传给协议栈MB_REG_WRITEUpdate 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, andWIN32TCP/demo.cpp.Function DocumentationeMBErrorCodeeMBClose(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 returneMBErrorCode:MB_ENOERR. If the protocol stack is not in the disabled state it returnseMBErrorCode:MB_EILLSTATE.如果资源释放了，该函数返回eMBErrorCode:MB_ENOERR。如果协议栈不是处于禁止状态，它返回eMBErrorCode:MB_EILLSTATE。Examples:LINUX/demo.c,MCF5235TCP/demo.c,STR71XTCP/demo.c,WIN32/demo.cpp, andWIN32TCP/demo.cpp.eMBErrorCodeeMBDisable(void)Disable the Modbus protocol stack.禁止Modbus协议栈。This function disables processing of Modbus frames.这个函数禁止处理Modbus帧。Returns:返回If the protocol stack has been disabled it returnseMBErrorCode:MB_ENOERR. If it was not in the enabled state it returnseMBErrorCode:MB_EILLSTATE.Examples:LINUX/demo.c,MCF5235TCP/demo.c,STR71XTCP/demo.c,WIN32/demo.cpp, andWIN32TCP/demo.cpp.eMBErrorCodeeMBEnable(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 returnseMBErrorCode:MB_ENOERR. If it was not in the disabled state it returneMBErrorCode: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, andWIN32TCP/demo.cpp.eMBErrorCodeeMBInit(eMBModeeMode,UCHARucSlaveAddress,UCHARucPort,ULONGulBaudRate,eMBParityeParity)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 untileMBEnable( )has been called.该函数初始化为ASCII或者RTU模式，并且调用移植层的初始化函数来准备硬件。需要注意的是，接受依然是禁止的，并且Modbus数据帧都不会得到处理，除非eMBEnable( )被调用。Parameters:eModeIf ASCII or RTU mode should be used. Modbus模式ucSlaveAddressThe slave address. Only frames sent to this address or to the broadcast address are processed.子模块地址。只有发向本模块地址或者广播地址的数据帧能得到处理。ucPortThe port to use. E.g. 1 for COM1 on windows. This value is platform dependent and some ports simply choose to ignore it.使用的端口。该值是硬件相关的，许多移植都会选择忽略该参数。ulBaudRateThe baudrate. E.g. 19200. Supported baudrates depend on the porting layer.波特率，所支持的波特率决定于移植层。eParityParity used for serial transmission.串行传输使用的校验。Returns:If no error occurs the function returnseMBErrorCode:MB_ENOERR. The protocol is then in the disabled state and ready for activation by callingeMBEnable( ). Otherwise one of the following error codes is returned:eMBErrorCode:MB_EINVALIf the slave address was not valid. Valid slave addresses are in the range 1 - 247.eMBErrorCode:MB_EPORTERRIF 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, andWIN32/demo.cpp.eMBErrorCodeeMBPoll(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 returnseMBErrorCode:MB_EILLSTATE. Otherwise it returnseMBErrorCode: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, andWIN32TCP/demo.cpp.eMBErrorCodeeMBRegisterCB(UCHARucFunctionCode,pxMBFunctionHandlerpxHandler)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:参数ucFunctionCodeThe Modbus function code for which this handler should be registers. Valid function codes are in the range 1 to 127.注册的功能码，有效的功能码范围是1到127pxHandlerThe function handler which should be called in case such a frame is received. IfNULLa previously registered function handler for this function code is removed.功能码对应的回调函数。如果为空，一个以前定义功能码回调函数将被去掉。Returns:返回eMBErrorCode:MB_ENOERRif the handler has been installed. If no more resources are available it returnseMBErrorCode:MB_ENORES. In this case the values inmbconfig.hshould be adjusted. If the argument was not valid it returnseMBErrorCode:MB_EINVAL.eMBErrorCode:MB_ENOERR如果回调函数正常安装。如果资源不足，将返回eMBErrorCode:MB_ENORES.在这种情况下，在mbconfig.h中定义的数值必须进行修改。如果参数无效，函数将返回eMBErrorCode:MB_EINVAL.eMBErrorCodeeMBSetSlaveID(UCHARucSlaveID,BOOLxIsRunning,UCHAR const *pucAdditional,USHORTusAdditionalLen)Configure the slave id of the device.设置设备的IDThis function should be called when the Modbus functionReport Slave IDis enabled ( By defining MB_FUNC_OTHER_REP_SLAVEID_ENABLED inmbconfig.h).当使用Modbus的Report Slave ID功能时，这个函数将会被调用（通过在mbconfig.h中定义MB_FUNC_OTHER_REP_SLAVEID_ENABLED）。Parameters:ucSlaveIDValues is returned in theSlave IDbyte of theReport Slave IDresponse.xIsRunningIf TRUE theRun Indicator Statusbyte is set to 0xFF. otherwise theRun Indicator Statusis 0x00.pucAdditionalValues which should be returned in theAdditionalbytes of theReport Slave IDresponse.usAdditionalLenLength of the bufferpucAdditonal.Returns:If the static buffer defined by MB_FUNC_OTHER_REP_SLAVEID_BUF inmbconfig.his to small it returnseMBErrorCode:MB_ENORES. Otherwise it returnseMBErrorCode:MB_ENOERR.Examples:AVR/demo.c,LINUX/demo.c,MCF5235/demo.c, andWIN32/demo.cpp.eMBErrorCodeeMBTCPInit(USHORTusTCPPort)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 untileMBEnable( )is called.该函数初始化Modbus TCP模块。注意，帧处理在eMBEnable()函数调用之前是禁止掉的。Parameters:参数usTCPPortThe TCP port to listen on.监听的TCP端口Returns:返回If the protocol stack has been initialized correctly the function returnseMBErrorCode:MB_ENOERR. Otherwise one of the following error codes is returned:eMBErrorCode:MB_EINVALIf the slave address was not valid. Valid slave addresses are in the range 1 - 247.eMBErrorCode:MB_EPORTERRIF the porting layer returned an error.如果协议栈初始化正确，函数返回MB_ENOERR。否则，函数会返回如下的错误码：eMBErrorCode:MB_EINVAL如果子模块地址无效，有效的子地址范围是1247eMBErrorCode:MB_EPORTERR如果移植层返回一个错误。Examples:MCF5235TCP/demo.c,STR71XTCP/demo.c, andWIN32TCP/demo.cpp.简介：Modbus Registers Modbus的寄存器 Detailed Description 详细描述 #include mb.h The protocol stack does not internally allocate any memory for the registers. This makes the protocol stack .Modbus RegistersModbus的寄存器Detailed Description详细描述#include mb.h The protocol stack does not internally allocate any memory for the registers. This makes the protocol stack very small and also usable on low end targets. In addition the values dont have to be in the memory and could for example be stored in a flash.Whenever the protocol stack requires a value it calls one of the callback function with the register address and the number of registers to read as an argument. The application should then read the actual register values (for example the ADC voltage) and should store the result in the supplied buffer.If the protocol stack wants to update a register value because a write register function was received a buffer with the new register values is passed to the callback function. The function should then use these values to update the application register values.协议栈不在内部为寄存器分配空间。这就使得协议栈非常小并且适用于低端目标应用。并且Modbus寄存器的值不一定存储在内存中，而是可以存储在如flash之类的存储器中。当协议栈需要获取数值是，它通过调用回调函数来实现，该回调函数以寄存器地址和数量作为参数。应用程序将读实际的寄存器数值（如ADC电压），并且存储在特定的缓冲区中。如果协议栈收到了一个写寄存器命令，将会执行寄存器更新操作，一个包含新寄存器数值的缓冲区会传给回调函数。这个回调函数将用这些值来更新应用寄存器数值。Functions功能函数eMBErrorCodeeMBRegInputCB(UCHAR *pucRegBuffer, USHORT usAddress, USHORT usNRegs)输入寄存器回调函数eMBErrorCodeeMBRegHoldingCB(UCHAR *pucRegBuffer, USHORT usAddress, USHORT usNRegs,eMBRegisterModeeMode)保持寄存器回调函数eMBErrorCodeeMBRegCoilsCB(UCHAR *pucRegBuffer, USHORT usAddress, USHORT usNCoils,eMBRegisterModeeMode)线圈状态寄存器回调函数eMBErrorCodeeMBRegDiscreteCB(UCHAR *pucRegBuffer, USHORT usAddress, USHORT usNDiscrete)离散寄存器回调函数Function Documentation功能函数文档eMBErrorCodeeMBRegCoilsCB(UCHAR *pucRegBuffer,USHORTusAddress,USHORTusNCoils,eMBRegisterModeeMode)Callback function used if aCoil Registervalue is read or written by the protocol stack. If you are going to use this function you might use the functionsxMBUtilSetBits( )andxMBUtilGetBits( )for working with bitfields.如果协议栈需要对线圈状态寄存器进行读写，则需要调用回调函数。如果用户用到这个功能，用户可能用到xMBUtilSetBits( )和xMBUtilGetBits( )来处理位域。Parameters:参数pucRegBufferThe bits are packed in bytes where the first coil starting at addressusAddressis stored in the LSB of the first byte in the bufferpucRegBuffer. If the buffer should be written by the callback function unused coil values (I.e. if not a multiple of eight coils is used) should be set to zero.位组成一个字节，起始寄存器对应的位处于该字节pucRegBuffer的最低位LSB。如果回调函数要写这个缓冲区，没有用到的线圈（例如不是8个一组的线圈状态）对应的位的数值必须设置位0。usAddressThe first coil number.第一个线圈地址usNCoilsNumber of coil values requested.请求的线圈个数eModeIfeMBRegisterMode:MB_REG_WRITEthe application values should be updated from the values supplied in the bufferpucRegBuffer. IfeMBRegisterMode:MB_REG_READthe application should store the current values in the bufferpucRegBuffer.如果该参数为eMBRegisterMode:MB_REG_WRITE，用户的应用数值将从pucRegBuffer中得到更新。如果该参数为eMBRegisterMode:MB_REG_READ，用户需要将当前的应用数据存储在pucRegBuffer中。Returns:返回The function must return one of the following error codes:这个函数将返回如下的错误码：eMBErrorCode:MB_ENOERRIf no error occurred. In this case a normal Modbus response is sent.eMBErrorCode:MB_ENOERR如果没有错误发生。在这种情况下，发送一个正常的Modbus应答。eMBErrorCode:MB_ENOREGIf the application does not map an coils within the requested address range. In this case aILLEGAL DATA ADDRESSis sent as a response.eMBErrorCode:MB_ENOREG如果请求的地址范围中没有线圈状态寄存器，在这种情况下，发送一个ILLEGAL DATA ADDRESS应答。eMBErrorCode:MB_ETIMEDOUTIf the requested register block is currently not available and the application dependent response timeout would be violated. In this case aSLAVE DEVICE BUSYexception is sent as a response.eMBErrorCode:MB_ETIMEDOUT如果请求的寄存器区当前无效，并且应用相关的应当超时。这种情况下，发送一个SLAVE DEVICE BUSY应答。eMBErrorCode:MB_EIOIf an unrecoverable error occurred. In this case aSLAVE DEVICE FAILUREexception is sent as a response.eMBErrorCode:MB_EIO如果一个其他错误发生。在这种情况下，发送一个SLAVE DEVICE FAILURE应答。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, andWIN32TCP/demo.