FreeModbus開源協議棧的移植和詳解(二)
概述
本篇主要介紹main函數以及mb.c文件,通過這兩部分,我們能夠從整體上分析FreeModbus。
一、從main函數說起
打開FreeModbus文件夾中的demo文件夾,該文件夾下是各個平臺下的demo,這裏我們選擇AVR平臺來分析。
打開AVR文件夾下的demo.c文件,main函數代碼如下:
int
main( void )
{
const UCHAR ucSlaveID[] = { 0xAA, 0xBB, 0xCC };
eMBErrorCode eStatus;
eStatus = eMBInit( MB_RTU, 0x0A, 0, 38400, MB_PAR_EVEN );
eStatus = eMBSetSlaveID( 0x34, TRUE, ucSlaveID, 3 );
sei( );
/* Enable the Modbus Protocol Stack. */
eStatus = eMBEnable( );
for( ;; )
{
( void )eMBPoll( );
/* Here we simply count the number of poll cycles. */
usRegInputBuf[0]++;
}
}
要想使用FreeModbus,這裏只要調用三個函數即可,即eMBInit()
、eMBEnable()
、eMBPoll()
三個函數,這三個函數的功能如下:
名稱 | 功能 |
---|---|
eMBInit() | 完成MODBUS的初始化配置 |
eMBEnable() | 使能Modbus協議棧 |
eMBPoll() | 輪詢Modbus的數據接收,並進行數據的處理,這個函數需要循環調用 |
在主函數中調用上面三個函數,即可完成Modbus的使用。是不是很簡單。在系統上電後先初始化協議棧,然後使能協議棧,最後在一個循環中循環調用eMBPoll()
函數即可。其他的函數我們暫時不討論,等到最後移植的時候再來看,我們現在只關注主幹部分。關於這三個函數具體怎麼實現的,我們來看一下mb.c文件。
二、mb.c文件
打開mb.c文件,代碼如下:
/*
* FreeModbus Libary: A portable Modbus implementation for Modbus ASCII/RTU.
* Copyright (c) 2006-2018 Christian Walter <[email protected]>
* 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.
*
*/
/* ----------------------- System includes ----------------------------------*/
#include "stdlib.h"
#include "string.h"
/* ----------------------- Platform includes --------------------------------*/
#include "port.h"
/* ----------------------- Modbus includes ----------------------------------*/
#include "mb.h"
#include "mbconfig.h"
#include "mbframe.h"
#include "mbproto.h"
#include "mbfunc.h"
#include "mbport.h"
#if MB_RTU_ENABLED == 1
#include "mbrtu.h"
#endif
#if MB_ASCII_ENABLED == 1
#include "mbascii.h"
#endif
#if MB_TCP_ENABLED == 1
#include "mbtcp.h"
#endif
#ifndef MB_PORT_HAS_CLOSE
#define MB_PORT_HAS_CLOSE 0
#endif
/* ----------------------- Static variables ---------------------------------*/
static UCHAR ucMBAddress;
static eMBMode eMBCurrentMode;
static enum
{
STATE_ENABLED,
STATE_DISABLED,
STATE_NOT_INITIALIZED
} eMBState = STATE_NOT_INITIALIZED;
/* Functions pointer which are initialized in eMBInit( ). Depending on the
* mode (RTU or ASCII) the are set to the correct implementations.
*/
static peMBFrameSend peMBFrameSendCur;
static pvMBFrameStart pvMBFrameStartCur;
static pvMBFrameStop pvMBFrameStopCur;
static peMBFrameReceive peMBFrameReceiveCur;
static pvMBFrameClose pvMBFrameCloseCur;
/* Callback functions required by the porting layer. They are called when
* an external event has happend which includes a timeout or the reception
* or transmission of a character.
*/
BOOL( *pxMBFrameCBByteReceived ) ( void );
BOOL( *pxMBFrameCBTransmitterEmpty ) ( void );
BOOL( *pxMBPortCBTimerExpired ) ( void );
BOOL( *pxMBFrameCBReceiveFSMCur ) ( void );
BOOL( *pxMBFrameCBTransmitFSMCur ) ( void );
/* An array of Modbus functions handlers which associates Modbus function
* codes with implementing functions.
*/
static xMBFunctionHandler xFuncHandlers[MB_FUNC_HANDLERS_MAX] = {
#if MB_FUNC_OTHER_REP_SLAVEID_ENABLED > 0
{MB_FUNC_OTHER_REPORT_SLAVEID, eMBFuncReportSlaveID},
#endif
#if MB_FUNC_READ_INPUT_ENABLED > 0
{MB_FUNC_READ_INPUT_REGISTER, eMBFuncReadInputRegister},
#endif
#if MB_FUNC_READ_HOLDING_ENABLED > 0
{MB_FUNC_READ_HOLDING_REGISTER, eMBFuncReadHoldingRegister},
#endif
#if MB_FUNC_WRITE_MULTIPLE_HOLDING_ENABLED > 0
{MB_FUNC_WRITE_MULTIPLE_REGISTERS, eMBFuncWriteMultipleHoldingRegister},
#endif
#if MB_FUNC_WRITE_HOLDING_ENABLED > 0
{MB_FUNC_WRITE_REGISTER, eMBFuncWriteHoldingRegister},
#endif
#if MB_FUNC_READWRITE_HOLDING_ENABLED > 0
{MB_FUNC_READWRITE_MULTIPLE_REGISTERS, eMBFuncReadWriteMultipleHoldingRegister},
#endif
#if MB_FUNC_READ_COILS_ENABLED > 0
{MB_FUNC_READ_COILS, eMBFuncReadCoils},
#endif
#if MB_FUNC_WRITE_COIL_ENABLED > 0
{MB_FUNC_WRITE_SINGLE_COIL, eMBFuncWriteCoil},
#endif
#if MB_FUNC_WRITE_MULTIPLE_COILS_ENABLED > 0
{MB_FUNC_WRITE_MULTIPLE_COILS, eMBFuncWriteMultipleCoils},
#endif
#if MB_FUNC_READ_DISCRETE_INPUTS_ENABLED > 0
{MB_FUNC_READ_DISCRETE_INPUTS, eMBFuncReadDiscreteInputs},
#endif
};
/* ----------------------- Start implementation -----------------------------*/
eMBErrorCode
eMBInit( eMBMode eMode, UCHAR ucSlaveAddress, UCHAR ucPort, ULONG ulBaudRate, eMBParity eParity )
{
eMBErrorCode eStatus = MB_ENOERR;
/* check preconditions */
if( ( ucSlaveAddress == MB_ADDRESS_BROADCAST ) ||
( ucSlaveAddress < MB_ADDRESS_MIN ) || ( ucSlaveAddress > MB_ADDRESS_MAX ) )
{
eStatus = MB_EINVAL;
}
else
{
ucMBAddress = ucSlaveAddress;
switch ( eMode )
{
#if MB_RTU_ENABLED > 0
case MB_RTU:
pvMBFrameStartCur = eMBRTUStart;
pvMBFrameStopCur = eMBRTUStop;
peMBFrameSendCur = eMBRTUSend;
peMBFrameReceiveCur = eMBRTUReceive;
pvMBFrameCloseCur = MB_PORT_HAS_CLOSE ? vMBPortClose : NULL;
pxMBFrameCBByteReceived = xMBRTUReceiveFSM;
pxMBFrameCBTransmitterEmpty = xMBRTUTransmitFSM;
pxMBPortCBTimerExpired = xMBRTUTimerT35Expired;
eStatus = eMBRTUInit( ucMBAddress, ucPort, ulBaudRate, eParity );
break;
#endif
#if MB_ASCII_ENABLED > 0
case MB_ASCII:
pvMBFrameStartCur = eMBASCIIStart;
pvMBFrameStopCur = eMBASCIIStop;
peMBFrameSendCur = eMBASCIISend;
peMBFrameReceiveCur = eMBASCIIReceive;
pvMBFrameCloseCur = MB_PORT_HAS_CLOSE ? vMBPortClose : NULL;
pxMBFrameCBByteReceived = xMBASCIIReceiveFSM;
pxMBFrameCBTransmitterEmpty = xMBASCIITransmitFSM;
pxMBPortCBTimerExpired = xMBASCIITimerT1SExpired;
eStatus = eMBASCIIInit( ucMBAddress, ucPort, ulBaudRate, eParity );
break;
#endif
default:
eStatus = MB_EINVAL;
}
if( eStatus == MB_ENOERR )
{
if( !xMBPortEventInit( ) )
{
/* port dependent event module initalization failed. */
eStatus = MB_EPORTERR;
}
else
{
eMBCurrentMode = eMode;
eMBState = STATE_DISABLED;
}
}
}
return eStatus;
}
#if MB_TCP_ENABLED > 0
eMBErrorCode
eMBTCPInit( USHORT ucTCPPort )
{
eMBErrorCode eStatus = MB_ENOERR;
if( ( eStatus = eMBTCPDoInit( ucTCPPort ) ) != MB_ENOERR )
{
eMBState = STATE_DISABLED;
}
else if( !xMBPortEventInit( ) )
{
/* Port dependent event module initalization failed. */
eStatus = MB_EPORTERR;
}
else
{
pvMBFrameStartCur = eMBTCPStart;
pvMBFrameStopCur = eMBTCPStop;
peMBFrameReceiveCur = eMBTCPReceive;
peMBFrameSendCur = eMBTCPSend;
pvMBFrameCloseCur = MB_PORT_HAS_CLOSE ? vMBTCPPortClose : NULL;
ucMBAddress = MB_TCP_PSEUDO_ADDRESS;
eMBCurrentMode = MB_TCP;
eMBState = STATE_DISABLED;
}
return eStatus;
}
#endif
eMBErrorCode
eMBRegisterCB( UCHAR ucFunctionCode, pxMBFunctionHandler pxHandler )
{
int i;
eMBErrorCode eStatus;
if( ( 0 < ucFunctionCode ) && ( ucFunctionCode <= 127 ) )
{
ENTER_CRITICAL_SECTION( );
if( pxHandler != NULL )
{
for( i = 0; i < MB_FUNC_HANDLERS_MAX; i++ )
{
if( ( xFuncHandlers[i].pxHandler == NULL ) ||
( xFuncHandlers[i].pxHandler == pxHandler ) )
{
xFuncHandlers[i].ucFunctionCode = ucFunctionCode;
xFuncHandlers[i].pxHandler = pxHandler;
break;
}
}
eStatus = ( i != MB_FUNC_HANDLERS_MAX ) ? MB_ENOERR : MB_ENORES;
}
else
{
for( i = 0; i < MB_FUNC_HANDLERS_MAX; i++ )
{
if( xFuncHandlers[i].ucFunctionCode == ucFunctionCode )
{
xFuncHandlers[i].ucFunctionCode = 0;
xFuncHandlers[i].pxHandler = NULL;
break;
}
}
/* Remove can't fail. */
eStatus = MB_ENOERR;
}
EXIT_CRITICAL_SECTION( );
}
else
{
eStatus = MB_EINVAL;
}
return eStatus;
}
eMBErrorCode
eMBClose( void )
{
eMBErrorCode eStatus = MB_ENOERR;
if( eMBState == STATE_DISABLED )
{
if( pvMBFrameCloseCur != NULL )
{
pvMBFrameCloseCur( );
}
}
else
{
eStatus = MB_EILLSTATE;
}
return eStatus;
}
eMBErrorCode
eMBEnable( void )
{
eMBErrorCode eStatus = MB_ENOERR;
if( eMBState == STATE_DISABLED )
{
/* Activate the protocol stack. */
pvMBFrameStartCur( );
eMBState = STATE_ENABLED;
}
else
{
eStatus = MB_EILLSTATE;
}
return eStatus;
}
eMBErrorCode
eMBDisable( void )
{
eMBErrorCode eStatus;
if( eMBState == STATE_ENABLED )
{
pvMBFrameStopCur( );
eMBState = STATE_DISABLED;
eStatus = MB_ENOERR;
}
else if( eMBState == STATE_DISABLED )
{
eStatus = MB_ENOERR;
}
else
{
eStatus = MB_EILLSTATE;
}
return eStatus;
}
eMBErrorCode
eMBPoll( void )
{
static UCHAR *ucMBFrame;
static UCHAR ucRcvAddress;
static UCHAR ucFunctionCode;
static USHORT usLength;
static eMBException eException;
int i;
eMBErrorCode eStatus = MB_ENOERR;
eMBEventType eEvent;
/* Check if the protocol stack is ready. */
if( eMBState != STATE_ENABLED )
{
return MB_EILLSTATE;
}
/* Check if there is a event available. If not return control to caller.
* Otherwise we will handle the event. */
if( xMBPortEventGet( &eEvent ) == TRUE )
{
switch ( eEvent )
{
case EV_READY:
break;
case EV_FRAME_RECEIVED:
eStatus = peMBFrameReceiveCur( &ucRcvAddress, &ucMBFrame, &usLength );
if( eStatus == MB_ENOERR )
{
/* Check if the frame is for us. If not ignore the frame. */
if( ( ucRcvAddress == ucMBAddress ) || ( ucRcvAddress == MB_ADDRESS_BROADCAST ) )
{
( void )xMBPortEventPost( EV_EXECUTE );
}
}
break;
case EV_EXECUTE:
ucFunctionCode = ucMBFrame[MB_PDU_FUNC_OFF];
eException = MB_EX_ILLEGAL_FUNCTION;
for( i = 0; i < MB_FUNC_HANDLERS_MAX; i++ )
{
/* No more function handlers registered. Abort. */
if( xFuncHandlers[i].ucFunctionCode == 0 )
{
break;
}
else if( xFuncHandlers[i].ucFunctionCode == ucFunctionCode )
{
eException = xFuncHandlers[i].pxHandler( ucMBFrame, &usLength );
break;
}
}
/* If the request was not sent to the broadcast address we
* return a reply. */
if( ucRcvAddress != MB_ADDRESS_BROADCAST )
{
if( eException != MB_EX_NONE )
{
/* An exception occured. Build an error frame. */
usLength = 0;
ucMBFrame[usLength++] = ( UCHAR )( ucFunctionCode | MB_FUNC_ERROR );
ucMBFrame[usLength++] = eException;
}
if( ( eMBCurrentMode == MB_ASCII ) && MB_ASCII_TIMEOUT_WAIT_BEFORE_SEND_MS )
{
vMBPortTimersDelay( MB_ASCII_TIMEOUT_WAIT_BEFORE_SEND_MS );
}
eStatus = peMBFrameSendCur( ucMBAddress, ucMBFrame, usLength );
}
break;
case EV_FRAME_SENT:
break;
}
}
return MB_ENOERR;
}
下面我們詳細地分析一下這個文件。
1、使用的全局變量和數據結構
1.1 static UCHAR ucMBAddress
ucMBAddress變量存儲了modbus的從機地址,改地址用一個無符號字符型的變量來表示,可以表示的數據範圍爲0~255;
1.2 static eMBMode eMBCurrentMode
eMBCurrentMode用來表示當前modbus協議棧的類型,modbus協議棧的類型有三種,由如下枚舉類型定義,該定義在mb.h文件中。
typedef enum
{
MB_RTU, /*!< RTU transmission mode. */
MB_ASCII, /*!< ASCII transmission mode. */
MB_TCP /*!< TCP mode. */
} eMBMode;
從上面的定義,我們可以看出,FreeModbus協議共支持三種類型的modbus協議,分別是MODBUS-RTU、MODBUS-ASCII和MODBUS-TCP。
1.3 static xMBFunctionHandler xFuncHandlers[MB_FUNC_HANDLERS_MAX]
下面看一下static xMBFunctionHandler xFuncHandlers[MB_FUNC_HANDLERS_MAX]
,這是一個xMBFunctionHandler類型的數組,這個數組共有MB_FUNC_HANDLERS_MAX個元素。先來看一下數據類型xMBFunctionHandler,它的定義在mbproto.h文件中,定義如下:
typedef eMBException( *pxMBFunctionHandler ) ( UCHAR * pucFrame, USHORT * pusLength );
typedef struct
{
UCHAR ucFunctionCode;
pxMBFunctionHandler pxHandler;
} xMBFunctionHandler;
先看上面第一行定義的函數指針,這個函數指針的輸入參數是一個uchar類型的指針和一個ushort類型的指針。通過名字可以判斷出,這兩個指針分別指向modbus接收到的數據幀的首地址和接受到的數據長度,由此可以判斷這個函數指針指向modbus數據幀的處理函數。
下面的結構體有兩個成員,一個是功能碼,另一個就是指向這個功能碼具體處理函數的指針。
因此可以看出,mb.c中定義的數組存儲了一個個功能碼和其相應的處理函數。數組的長度由一個宏來定義,這個宏在mbconfig.h文件中,可以由我們來配置,默認值是16。
1.4其他的函數指針
static peMBFrameSend peMBFrameSendCur; //發送函數
static pvMBFrameStart pvMBFrameStartCur; //開始函數
static pvMBFrameStop pvMBFrameStopCur; //停止函數
static peMBFrameReceive peMBFrameReceiveCur; //接收函數
static pvMBFrameClose pvMBFrameCloseCur; //關閉函數
/* Callback functions required by the porting layer. They are called when
* an external event has happend which includes a timeout or the reception
* or transmission of a character.
*/
BOOL( *pxMBFrameCBByteReceived ) ( void ); //接收回調函數
BOOL( *pxMBFrameCBTransmitterEmpty ) ( void ); //發送回調函數
BOOL( *pxMBPortCBTimerExpired ) ( void ); //定時器超時回調函數
BOOL( *pxMBFrameCBReceiveFSMCur ) ( void ); //接收中斷函數
BOOL( *pxMBFrameCBTransmitFSMCur ) ( void ); //發送中斷函數
上面的五個函數指針的定義在mbframe.h中,定義如下:
/* ----------------------- Prototypes 0-------------------------------------*/
typedef void ( *pvMBFrameStart ) ( void );
typedef void ( *pvMBFrameStop ) ( void );
typedef eMBErrorCode( *peMBFrameReceive ) ( UCHAR * pucRcvAddress,
UCHAR ** pucFrame,
USHORT * pusLength );
typedef eMBErrorCode( *peMBFrameSend ) ( UCHAR slaveAddress,
const UCHAR * pucFrame,
USHORT usLength );
typedef void( *pvMBFrameClose ) ( void );
前面五個函數是在mb.c文件中使用的,這裏爲什麼使用指針而不是直接使用具體的函數的主要原因就是modbus有三種類型的協議,RTU、ASCII和TCP,而mb.c主要是一個框架,包含三種協議,mb.c實現了通用的部分,而把每個協議具體的實現細節交給具體的協議裏面的文件去實現,這樣就把上層和底層分離開了。
下面幾個是回調函數,也是指針,作用和上面相同,這裏就不說了。
2、modbus協議函數
mb.c主要實現了7個函數,先用表格簡單描述一下這幾個函數的功能。
函數名 | 功能 |
---|---|
eMBInit() | 主要實現modbus協議棧的初始化,這裏主要初始化MODBUS-RTU和MODBUS-ASCII,不包括MODBUS-TCP |
eMBTCPInit() | 主要完成MODBUS-TCP的初始化 |
eMBRegisterCB() | 註冊新的功能碼和相應的處理函數到功能碼數組中,便於我們擴展 |
eMBClose() | 關閉modbus協議棧 |
eMBEnable() | 使能modbus協議棧 |
eMBDisable() | 禁止modbus協議棧 |
eMBPoll() | modbus輪詢函數,主要完成事件的查詢和相關處理函數的調用 |
2.1 eMBInit()函數
該函數的接收參數爲modbus的工作模式、從機地址、端口號、波特率、奇偶校驗設置。
函數進來之後首先檢查設置的地址合法性,如果設置的地址爲廣播地址或者不在最小地址和最大地址範圍之內,則返回故障。如果地址正確,則將地址設置到Modbus的地址當中。然後根據Modbus的設置模式,將Modbus的處理函數和RTU或者ASCII的函數關聯起來。然後初始化串口控制器和事件控制器。這裏的串口控制器和事件控制器的具體細節後面再進行討論,先看Modbus的主框架。
2.2 eMBTCPInit()函數
eMBTCPInit()
函數和eMBInit()
函數類似,一個是初始化RTU和ASCII協議,一個是初始化TCP協議。這裏eMBTCPInit()
函數初始化TCP協議棧。過程和RTU與ASCII相同,只是傳遞的參數不同。這裏不再重複說明。簡單瞭解一下即可。
2.3 eMBRegisterCB()函數
這個函數主要是註冊或者取消註冊Modbus協議的功能碼和相應的處理函數的。和上面的xFuncHandlers[]數組息息相關。當傳入的函數指針爲NULL的時候,註銷功能碼和它的處理函數,當傳入的函數指針非NULL的時候,將功能碼和處理函數註冊如xFuncHandlers數組。
2.4 eMBClose()函數
該函數主要是關閉串口傳輸,當不再使用協議的時候,可以關閉。
2.5 eMBEnable()函數
該函數主要是使能UART的接收中斷和開啓定時器。接收中斷用來接收主棧發送過來的數據,定時器用來進行超時檢測。
2.6 eMBDisable()函數
該函數和eMBEnable()
函數功能相反,用來關閉UART接收中斷和發送中斷,關閉定時器。
2.7 eMBPoll()函數
這是modbus協議的最主要的函數,該函數對事件進行輪詢,當接收到數據的時候進行處理。看一下這個函數。
函數首先判斷Modbus協議是否使能,如果沒有使能,則返回故障。接下來查詢Modbus的事件。當系統識別到接收完成事件的時候,進行數據的接收。接受完數據之後,判斷是否需要處理(地址是自己的地址或者是廣播地址),如果需要處理,則發送一個執行事件,否則就不做處理。系統獲取到處理事件的時候,進入數據處理過程。首先從接收到的數據中獲取到功能碼,然後查找功能碼錶(上面說到的xFuncHandlers數組),然後嗲用相應功能碼的處理函數進行數據處理。數據處理完之後,判斷是否需要發送返回幀,如果不是廣播地址就需要返回,如果錯誤,返回的功能碼最高位置1,沒有錯誤,則調用發送函數,將返回幀發送出去。
三、小結
本篇主要簡單介紹了main函數和mb.c文件,介紹的並不是很詳細,本人也是剛接觸FreeModbus,有錯誤之處請見諒。