FreeModbus RTU 移植指南

FreeModbus 简介

FreeModbus 是一个免费的软件协议栈，实现了 Modbus 从机功能：

• 纯 C 语言
• 支持 Modbus RTU/ASCII
• 支持 Modbus TCP

本文介绍 Modbus RTU 移植。

移植环境：

• 裸机
• Keil MDK 编译器
• Cortex-M3 内核芯片（LPC1778/88）

移植概述

1.体系架构相关

项目	描述
INLINE	宏，编译器相关，内联指令或关键字
PR_BEGIN_EXTERN_C PR_END_EXTERN_C	宏，按照 C 代码编译
ENTER_CRITICAL_SECTION( ) EXIT_CRITICAL_SECTION( )	宏，进入临界区和退出临界区
BOOL UCHAR CHAR USHORT SHORT ULONG LONG	数据类型
TRUE FALSE	宏，BOOL 类型变量的值

2.定时器
需要移植的定时器函数

定时器函数	描述
BOOL xMBPortTimersInit( USHORT usTim1Timerout50us )	初始化，由协议栈回调， usTim1Timerout50us 的单位是 50us
void vMBPortTimersEnable( )	使能定时器，协议栈回调 定时器计数器清零，然后开始计数
void vMBPortTimersDisable( )	禁止定时器，由协议栈回调 定时器计数器清零，停止计数
void prvvTIMERExpiredISR( void )	通知协议栈定时器中断发生，需手动安装到定时器中断服务函数中

3.串口
需要移植的函数

定时器函数	描述
BOOL xMBPortSerialInit( UCHAR ucPORT, ULONG ulBaudRate, UCHAR ucDataBits, eMBParity eParity )	初始化串口硬件，由协议栈回调
void vMBPortSerialEnable( BOOL xRxEnable, BOOL xTxEnable )	使能/禁止串口发送和接收，由协议栈回调
BOOL xMBPortSerialPutByte( CHAR ucByte )	通过串口发送一字节数据
BOOL xMBPortSerialGetByte( CHAR * pucByte )	从串口接收一字节数据
void prvvUARTRxISR( void )	通知协议栈串口接收中断发生，协议栈会进行数据接收处理。需手动安装到串口接收中断服务函数中
void prvvUARTTxReadyISR( void )	通知协议栈串口发送中断发生，协议栈会进行数据发送。需手动安装到串口发送中断服务函数中

4.事件
事件相关回调函数需要移植：

事件回调函数	描述
BOOL xMBPortEventInit( void )	初始化
BOOL xMBPortEventPost( eMBEventType eEvent )	事件投递 可以在这个函数中解析事件，并执行自己的事件函数。
BOOL xMBPortEventGet( eMBEventType * eEvent )	获取事件

mb_config.h 文件属于协议栈的一部分，直接修改不合理
assert，直接调用 C 标准库函数， 但这个依赖硬件

移植细节

并不是所有函数都需要重头编写，协议栈 \freemodbus\demo\BARE\port\ 文件夹下给出了移植框架：

port
|---- port.h ：体系架构相关
|---- porttimer.c ：定时器相关
|---- portserial.c ：串口相关
|---- portevent.c ：事件相关

1.体系架构
port.h 文件：

#include <assert.h>
#include <stdint.h>
#include "cmsis_compiler.h"#define	INLINE                      __INLINE
#define PR_BEGIN_EXTERN_C           extern "C" {
#define	PR_END_EXTERN_C             }#ifndef assert
#define assert(ignore) ((void)0)
#endif#define ENTER_CRITICAL_SECTION( )   EnterCriticalSection()
#define EXIT_CRITICAL_SECTION( )    ExitCriticalSection()typedef uint8_t BOOL;typedef unsigned char UCHAR;
typedef char CHAR;typedef uint16_t USHORT;
typedef int16_t SHORT;typedef uint32_t ULONG;
typedef int32_t LONG;#ifndef TRUE
#define TRUE            1
#endif#ifndef FALSE
#define FALSE           0
#endifvoid EnterCriticalSection(void);
void ExitCriticalSection(void);

进入和退出临界区函数，实际上是开关中断，这部分点击这里可以获取详细的信息。我们新建一个 port.c 文件，在这个文件中实现一个可以嵌套使用的进入和退出临界区代码：

#include "cmsis_compiler.h"static uint32_t nesting_count = 0;
static uint32_t old_state;void EnterCriticalSection(void)
{uint32_t cur_state;cur_state = __get_PRIMASK();__disable_irq();if(nesting_count == 0)old_state = cur_state;nesting_count ++;
}void ExitCriticalSection(void)
{nesting_count --;if(0 == nesting_count)__set_PRIMASK(old_state);
}

2.定时器
Modbus RTU 使用超时机制判断数据帧结束：串口超过 3.5 个字符传输时间没有收到数据，则认为一帧结束。
这需要一个硬件定时器。
协议栈会根据传入的波特率自动计算 3.5 个字符传输时间是多少，单位是 50us，简化后的代码如下所示：

/* If baudrate > 19200 then we should use the fixed timer values t35 = 1750us. * Otherwise t35 must be 3.5 times the character time.*/
if( ulBaudRate > 19200 )
{usTimerT35_50us = 35;       /* 1800us. */
}
else
{/* The timer reload value for a character is given by:** ChTimeValue = Ticks_per_1s / ( Baudrate / 11 )*             = 11 * Ticks_per_1s / Baudrate*             = 220000 / Baudrate* The reload for t3.5 is 1.5 times this value and similary* for t3.5.*/usTimerT35_50us = ( 7UL * 220000UL ) / ( 2UL * ulBaudRate );
}
xMBPortTimersInit( ( USHORT ) usTimerT35_50us )；

所以就可以根据传入的 3.5 个字符传输时间 usTimerT35_50us 来初始化硬件定时器。我的系统刚好有个 50us 中断一次的定时器，所以我直接使用这个定时器来移植，移植代码在 porttime.c 文件中：

#include <stdbool.h>
/* ----------------------- Platform includes --------------------------------*/
#include "port.h"/* ----------------------- Modbus includes ----------------------------------*/
#include "mb.h"
#include "mbport.h"static bool IsTimerEnable = false;
static USHORT Timerout50usCount = 0;
static USHORT Timerout50usCountCur = 0;/* ----------------------- static functions ---------------------------------*/
static void prvvTIMERExpiredISR( void );/* ----------------------- Start implementation -----------------------------*/
BOOL
xMBPortTimersInit( USHORT usTim1Timerout50us )
{Timerout50usCount = usTim1Timerout50us;IsTimerEnable = false;return TRUE;
}inline void
vMBPortTimersEnable(  )
{/* Enable the timer with the timeout passed to xMBPortTimersInit( ) */IsTimerEnable = true;Timerout50usCountCur = 0;
}inline void
vMBPortTimersDisable(  )
{/* Disable any pending timers. */IsTimerEnable = false;Timerout50usCountCur = 0;
}/*需手动安装到定时器中断服务函数*/
void
vMBPortTimersISR(  )
{if(IsTimerEnable){Timerout50usCountCur ++;if(Timerout50usCountCur >= Timerout50usCount)prvvTIMERExpiredISR();}
}/* Create an ISR which is called whenever the timer has expired. This function* must then call pxMBPortCBTimerExpired( ) to notify the protocol stack that* the timer has expired.*/
static void prvvTIMERExpiredISR( void )
{( void )pxMBPortCBTimerExpired(  );
}

有一点我很好奇， 3.5 个字符传输时间 usTimerT35_50us 为什么要格式化成 50us 的倍数？
我注意到代码 xMBPortTimersInit( ( USHORT ) usTimerT35_50us ) 在传递参数时进行了一次数据强制转换，也就是协议栈使用的 USHORT 数据类型，一般这个数据类型最大值是 65536，如果不转换成 50us 的倍数，低波特率（比如 1200bps ）必然会出现数据溢出现象。
那协议栈为什么又非要使用 USHORT 数据类型呢？
不清楚，大概是当时主流 MCU 还不是 32 位的，USHORT 数据类型可以更快更节省 RAM 。

何时使能定时器？

1. 启动协议栈（eMBRTUStart）
2. 接收到 1 字节数据（xMBRTUReceiveFSM）：复位计数器，重新开始计时

何时关闭定时器？

1. 停止协议栈（eMBRTUStop）
2. 超时发生（3.5 个字符传输时间）：收到新的数据帧，停止计时

定时器与接收关系密切，参与接收状态机的状态迁移：

3.串口
串口用于收发数据。移植代码在 portserial.c 中：

#include "port.h"/* ----------------------- Modbus includes ----------------------------------*/
#include "mb.h"
#include "mbport.h"/* ----------------------- static functions ---------------------------------*/
static void prvvUARTTxReadyISR( void );
static void prvvUARTRxISR( void );void down3_set_to_recv(void);
void down3_set_to_send(void);
void down3_put_byte( CHAR data);
void down3_get_byte(CHAR *pucByte);
void init_down3_uart2(UCHAR ucPORT, ULONG ulBaudRate, UCHAR ucDataBits, eMBParity eParity);/* ----------------------- Start implementation -----------------------------*/
void
vMBPortSerialEnable( BOOL xRxEnable, BOOL xTxEnable )
{/* If xRXEnable enable serial receive interrupts. If xTxENable enable* transmitter empty interrupts.*/if(xRxEnable){down3_set_to_recv();}if(xTxEnable){down3_set_to_send();prvvUARTTxReadyISR();}
}BOOL
xMBPortSerialInit( UCHAR ucPORT, ULONG ulBaudRate, UCHAR ucDataBits, eMBParity eParity )
{init_down3_uart2(ucPORT, ulBaudRate, ucDataBits, eParity);return TRUE;
}BOOL
xMBPortSerialPutByte( CHAR ucByte )
{/* Put a byte in the UARTs transmit buffer. This function is called* by the protocol stack if pxMBFrameCBTransmitterEmpty( ) has been* called. */down3_put_byte(ucByte);return TRUE;
}BOOL
xMBPortSerialGetByte( CHAR * pucByte )
{/* Return the byte in the UARTs receive buffer. This function is called* by the protocol stack after pxMBFrameCBByteReceived( ) has been called.*/down3_get_byte(pucByte);return TRUE;
}/*需手动安装到串口接收中断服务函数*/
void
vMBPortSerialRecvISR(void)
{prvvUARTRxISR();
}/*需手动安装到串口发送中断服务函数*/
void
vMBProtSerialSendISR(void)
{prvvUARTTxReadyISR();
}/* Create an interrupt handler for the transmit buffer empty interrupt* (or an equivalent) for your target processor. This function should then* call pxMBFrameCBTransmitterEmpty( ) which tells the protocol stack that* a new character can be sent. The protocol stack will then call * xMBPortSerialPutByte( ) to send the character.*/
static void prvvUARTTxReadyISR( void )
{pxMBFrameCBTransmitterEmpty(  );
}/* Create an interrupt handler for the receive interrupt for your target* processor. This function should then call pxMBFrameCBByteReceived( ). The* protocol stack will then call xMBPortSerialGetByte( ) to retrieve the* character.*/
static void prvvUARTRxISR( void )
{pxMBFrameCBByteReceived(  );
}

4.事件
协议栈使用前后台架构，中断产生 事件 ，主循环处理 事件 。

事件	生产者	消费者	描述
EV_READY	定时器中断 (porttimer.c) prvvTIMERExpiredISR	主循环 (mb.c) eMBPoll	协议栈初始化完毕
EV_FRAME_RECEIVED	定时器中断 (porttimer.c) prvvTIMERExpiredISR	主循环 (mb.c) eMBPoll	接收到一帧数据 如果数据帧校验正确，则产生 EV_EXECUTE 事件
EV_EXECUTE	主循环 (mb.c) eMBPoll	主循环 (mb.c) eMBPoll	解析命令，生成应答数据，添加 CRC ，启动数据发送，数据将由串口发送中断发送
EV_FRAME_SENT	串口发送中断 (portserial.c) prvvUARTTxReadyISR	主循环 (mb.c) eMBPoll	应答数据全部发送完成

事件一般用队列实现，以便消费者来不及处理事件时，暂时保存事件。对于简单应用，如果满足消费者消费事件的速度 大于等于 生产者生产事件的速度，则可以使用协议栈 \freemodbus\demo\BARE\port\portevent.c 文件中的源码，直接使用，不用修改：

#include "mb.h"
#include "mbport.h"/* ----------------------- Variables ----------------------------------------*/
static eMBEventType eQueuedEvent;
static BOOL     xEventInQueue;/* ----------------------- Start implementation -----------------------------*/
BOOL
xMBPortEventInit( void )
{xEventInQueue = FALSE;return TRUE;
}BOOL
xMBPortEventPost( eMBEventType eEvent )
{xEventInQueue = TRUE;eQueuedEvent = eEvent;return TRUE;
}BOOL
xMBPortEventGet( eMBEventType * eEvent )
{BOOL            xEventHappened = FALSE;if( xEventInQueue ){*eEvent = eQueuedEvent;xEventInQueue = FALSE;xEventHappened = TRUE;}return xEventHappened;
}

在发送事件处就可以完成的功能，为什么要绕一圈非得用事件来完成呢？
方便解耦。
对于裸机环境，使用事件将处理过程从中断转移到主循环，从而使中断服务函数简单。
对于有操作系统的应用，事件可以方便的实现操作系统移植层，实现协议栈进程与中断之间的通讯。协议栈进程会因为等待事件而进入阻塞状态。