简介这是一份面向嵌入式开发者的FreeModbus移植资源核心目标是将开源Modbus协议栈移植到FreeRTOS实时操作系统上实现与西门子组态屏等主站设备的稳定通信。资源完整覆盖主库与从库两种角色适合需要掌握Modbus RTU/ASCII/TCP通信、实时任务调度与串口驱动集成的中高级开发者。压缩包共含50个文件其中35个C源码与15个头文件按port、functions、include及用户接口层组织。移植所需的portserial.c、porttimer.c、portevent.c等底层适配文件均在包内可直接基于FreeRTOS任务、软件定时器与事件标志组改造modbus_user.c/h则提供寄存器映射和回调函数的自定义框架便于快速对接实际设备。资源大小仅110KB代码结构精炼、学习路径清晰。目前已有2326人学习下载是理解FreeRTOS与Modbus协议结合、提升嵌入式通信开发能力的实用参考资料。 前段时间把一个跑了很久的裸机Modbus从站程序往 FreeRTOS 上搬原以为就是官方文档里那几句话的事结果真动起手来串口中断动不动进 HardFault上位机一读寄存器主控就卡死光是排查“为什么发一帧命令就挂在中断里”就花了一整天。网上关于 FreeModbus 移植的教程不少但大多数只给结论不给原因抄过来能编译一接真实设备就露馅。这篇把我这次移植的完整思路、改写的每个接口、以及踩过的坑都记录下来给打算在 STM32 或者其它 M 内核单片机上把 FreeModbus 移植到 FreeRTOS 的朋友做个参考。1. 移植前先弄明白FreeModbus 这套代码在裸机下是怎么转起来的很多人拿到 FreeModbus 源码第一件事就是找 serial 和 timer 的 port 文件觉得把这几个函数填满就完事了。其实这恰恰是最容易翻车的地方。FreeModbus 不是“一个协议栈库”而是一台由事件驱动的状态机它在裸机上怎么跑、在 RTOS 上该怎么跑完全取决于你理不理解这套事件循环。1.1 裸机版的核心运转方式先看裸机下的典型调用int main(void) { eMBInit(MB_RTU, 0x01, 1, 9600, MB_PAR_NONE); eMBEnable(); while (1) { eMBPoll(); } }eMBPoll()不是简单的轮询它内部会从事件队列里取事件然后驱动 RTU 状态机完成“收帧 → 校验 → 分发功能码 → 组响应帧 → 发送”这一整套流程。串口中断负责把字节收进缓冲区定时器中断负责判断帧与帧之间的时间间隔RTU 模式下是 3.5 个字符时间两者都通过xMBPortEventPost()往事件层丢事件eMBPoll()再消费这些事件。这就像一个小型消息循环外设中断是生产者eMBPoll()是消费者事件是它们之间的唯一纽带。裸机下跑这个循环没有任何问题因为 CPU 永远在这个 while 里转。1.2 RTOS 下要改的协作模型移植到 FreeRTOS 之后不能简单地把eMBPoll()扔进一个 while 任务里就撒手不管。关键区别在于裸机下eMBPoll()是主循环里的常驻函数它一直活着但在 FreeRTOS 里串口中断仍然还是中断可协议栈却变成了一个任务。正确做法是把eMBPoll()放进一个独立任务优先级根据项目需求定然后让eMBPoll()在事件到来之前阻塞住不要空转。同时xMBPortEventGet()这个接口必须从“查一个标志位”改成“阻塞等待事件”这样 Modbus 任务在空闲时完全不占 CPU等串口中断或定时器中断通过事件把它唤醒。简单说移植的核心就是两件事让串口和定时器中断继续高效地生产事件让 Modbus 任务在收到事件时立刻被唤醒去消费事件。把这个模型理清了后续所有代码都是在往这个骨架上填肉。2. 动手前把配置改对少踩一半的坑很多新手一上来就埋头改 port 层代码结果发现跑起来各种怪问题。我这次的经验是配置文件的坑远比代码代码的坑多尤其是mbconfig.h和FreeRTOSConfig.h这两个文件改错一个宏够你查好几天。2.1 mbconfig.h 里的功能开关和功能码数量FreeModbus 的mbconfig.h是裁剪协议栈的入口。以常见的从站实现为例以下几个宏要特别注意#define MB_RTU_ENABLED 1 #define MB_ASCII_ENABLED 0 #define MB_FUNC_HANDLERS_MAX 8 #define MB_FUNC_READ_INPUT_ENABLED 1 #define MB_FUNC_READ_HOLDING_ENABLED 1 #define MB_FUNC_WRITE_HOLDING_ENABLED 1 #define MB_FUNC_READ_COILS_ENABLED 0 #define MB_FUNC_WRITE_COILS_ENABLED 0 #define MB_FUNC_READ_DISCRETE_INPUTS_ENABLED 0MB_FUNC_HANDLERS_MAX这个宏很容易被忽略。它决定协议栈内部功能码处理函数数组的大小如果你启用了 8 个功能码这里还写 3那部分功能码注册就会失败而且eMBInit()不一定报错运行时就是“有几个功能码没反应”。我的习惯是第一版全功能打开把它调到 8调通之后再根据实际需求裁剪。另外MB_ASCII_ENABLED在 FreeRTOS 下建议直接关掉ASCII 模式在嵌入式里用得少而且开启后会多占一部分内存和事件类型没必要给系统添负担。2.2 FreeRTOSConfig.h 的中断优先级红线和栈检测FreeRTOS 对中断优先级有一套严格约束凡是中断里调用了 FreeRTOS API比如任务通知、信号量、队列该中断的优先级数值必须大于等于configMAX_SYSCALL_INTERRUPT_PRIORITY。STM32 的数值越小优先级越高所以如果你把串口中断优先级设为 0 到 4而configMAX_SYSCALL_INTERRUPT_PRIORITY是 5那么中断里调xTaskNotifyFromISR()就会触发断言或 HardFault。我这次把串口和定时器中断都设在 6configMAX_SYSCALL_INTERRUPT_PRIORITY保持 5既不影响实时性又能在中断里安全地调用 FreeRTOS 的 API。configCHECK_FOR_STACK_OVERFLOW建议设为 2配合vApplicationStackOverflowHook()打印任务名。FreeModbus 在协议栈处理期间寄存器回调、CRC 校验、状态机跳转都会用栈尤其如果你的寄存器回调不小心调了printf()之类的东西栈很容易爆。没有栈溢出检测任务死了你都不知道去哪查。2.3 顶层调用时序初始化顺序也容易踩坑。我的推荐顺序是外设初始化时钟、串口、定时器、GPIO创建 Modbus 任务在 Modbus 任务入口里调用eMBInit()和eMBEnable()进入eMBPoll()循环。为什么不在main()里初始化因为如果你把xMBPortEventInit()改成了基于任务通知的实现它需要拿到当前任务的句柄而调用 eMBInit 时如果还不在 Modbus 任务上下文里拿到的句柄就是错的。这件事后面第 3 章讲事件层时会展开。3. 改 port 层三件套串口、定时器、临界区FreeModbus 的 port 层文件一般有portserial.c、porttimer.c、portevent.c、portother.c。其中前三个基本决定了移植成败临界区接口一般放在portother.c里。3.1 串口搞清楚发送完成和接收缓冲区就够了FreeModbus 对串口的要求其实很简单四个接口void vMBPortSerialEnable(BOOL xRxEnable, BOOL xTxEnable); BOOL xMBPortSerialPutByte(CHAR ucByte); BOOL xMBPortSerialGetByte(CHAR *pucByte);vMBPortSerialEnable()用来切换收发状态。发送时关接收、开发送发送完成后关发送、开接收。用 STM32 HAL 库时这个函数里主要控制串口中断的开关和收发模式切换。发送函数直接往串口数据寄存器写一个字节接收函数从自己的缓冲区或数据寄存器读一个字节。这里有一个细节接收缓冲的溢出标志要处理好。Modbus 一帧最多 256 字节如果你的接收缓冲区只有几十字节主站发一个比较大的写寄存器帧缓冲区就爆了数据会被丢弃从站毫无反应。我的习惯是把接收缓冲区大小直接设成MB_RTU_MAX_ADU_LENGTH即 256宁可费一点 RAM也不在这种地方找 bug。3.2 定时器RTU 模式的灵魂是 3.5T 字符间隔RTU 模式是靠“字节间静默时间”来分帧的一帧内字节间隔不能超过 1.5 个字符时间帧与帧之间必须超过 3.5 个字符时间。实际移植时我们主要实现 3.5T串口每收到一个字节就重置定时器定时器溢出说明这一帧结束了。3.5T 的计算方法以 9600 波特率、8 数据位、无校验、1 停止位为例一个字符是 10 bit1 起始 8 数据 1 停止那么 3.5 个字符时间就是3.5 * 10 / 9600 ≈ 3.645 ms如果用 72 MHz 的定时器时钟预分频 71 得到 1 MHz 计数频率自动重装载值就是 3645。对 115200 波特率这个值大约是 304用定时器实现一点问题都没有。这里再说一个经验严格按理论值算出来的 3.5T在真实设备上偶尔会把正常的一帧拆成两帧因为串口中断响应、任务调度都会带来额外延迟。我的做法是把定时器溢出时间在理论值基础上乘 1.5 到 2 倍作为帧结束的判定阈值测试下来比死扣理论值稳定得多。定时器接口就两个void vMBPortTimersEnable(void); void vMBPortTimersDisable(void);Enable里设置自动重装载值、清计数、启动定时器中断Disable里停止定时器。在定时器中断服务函数里做一件事void TIM_IRQHandler(void) { if (__HAL_TIM_GET_FLAG(htim, TIM_FLAG_UPDATE)) { __HAL_TIM_CLEAR_IT(htim, TIM_FLAG_UPDATE); vMBPortTimersDisable(); xMBPortEventPost(EV_FRAME_RECEIVED); } }定时器溢出后必须立刻禁用定时器否则它会持续触发中断Modbus 任务会被大量无效事件淹没。这个细节很多移植教程不会提。3.3 临界区从关全局中断到关调度器FreeModbus 协议栈内部在访问共享缓冲区时会调用临界区接口void vMBPortEnterCritical(void); void vMBPortExitCritical(void);裸机环境下可以直接关全局中断但 FreeRTOS 里关中断会导致系统 tick 中断被延迟影响调度。正确做法是用 FreeRTOS 的临界区 APIvoid vMBPortEnterCritical(void) { taskENTER_CRITICAL(); } void vMBPortExitCritical(void) { taskEXIT_CRITICAL(); }需要注意临界区里面绝对不能调用任何阻塞或可能引起任务切换的 API。FreeModbus 自身的临界区代码都很短所以这个要求一般能满足。你在写寄存器回调时也尽量不要在里面做耗时操作否则临界区会拉长影响系统实时性。4. 串口中断里最容易被忽视的细节串口中断是 FreeModbus 在 FreeRTOS 下最容易出问题的地方三个问题占了故障原因的 90% 以上优先级配置错误、事件没有正确投递、缓冲区处理不当。4.1 中断优先级与 FreeRTOS API 的调用红线串口接收中断和定时器中断中都要调用xMBPortEventPost()如果你按我前面说的用任务通知实现那事件投递函数内部就是xTaskNotifyFromISR()。这个 API 只能在优先级数值大于等于configMAX_SYSCALL_INTERRUPT_PRIORITY的中断里调用。STM32 上还有一个隐藏坑中断优先级分组必须是 Group 4。如果工程默认用了 Group 2抢占优先级只有 2 位FreeRTOS 判断中断优先级时会乱套。在HAL_Init()之后显式调用HAL_NVIC_SetPriorityGrouping(NVIC_PRIORITYGROUP_4);这是很多从标准库工程移植过来的人最容易忽略的一步。4.2 帧接收事件必须投递到 Modbus 任务串口收到每个字节时我们只需要做两件事把字节存入缓冲区重置 3.5T 定时器。等定时器溢出才说明一帧完整到达此时在定时器中断里投递EV_FRAME_RECEIVED事件。为什么不能在收到一个字节时就投递因为一个完整请求帧可能有 8 个字节你收到第一个字节就唤醒任务任务开始解析数据还没收全必然出错。协议栈的状态机是靠“帧结束”驱动的不是靠“字节到达”驱动的。部分移植教程直接在串口字节中断里投递事件表面看也能响应但长帧数据一多就出乱子帧错率极高就是这个原因。4.3 接收缓冲区的类型和溢出判断FreeModbus 内部有自己的 RTU 接收缓冲串口中断只负责往这个缓冲里写。但这里有个容易犯的错FreeModbus 接收数据的接口是eMBRTUReceive()它在 RTU 状态机里被调用而串口中断往哪个缓冲写、写多少必须和这个接口配合好。我的建议是串口中断里保存原始字节流长度超过MB_RTU_MAX_ADU_LENGTH就直接丢弃并复位接收状态不要用环形缓冲做无界接收。Modbus RTU 是请求-响应式协议帧长度本来就有上限做无界缓冲反而增加复杂度。5. 实测排障实录从“不响应”到“偶发卡死”的排查链路移植完成之后我实际遇到的故障现象非常典型几乎每个移植 FreeModbus 的人都会碰到。我按排查顺序记录一下。5.1 现象 A一上电就 HardFault第一次上电主站发一帧请求从站直接进 HardFault。排查链路先看栈溢出钩子有没有触发结果没有单步调试发现在xTaskNotifyFromISR()中断言检查串口中断优先级是 3而configMAX_SYSCALL_INTERRUPT_PRIORITY是 5中断优先级数值比允许值小意味着这个中断的优先级高于 FreeRTOS 可管理范围不能调 API把串口和定时器中断优先级改成 6HardFault 消失。这个问题本质上就是 FreeRTOS 中断优先级红线如果你的工程是从别处复制过来的一定要检查中断优先级分组和具体数值。5.2 现象 B能收到请求但从站不回帧主站能发请求从站也收到了但就是没有响应。排查链路在eMBPoll()里加打印发现事件一直没来再查定时器中断发现 3.5T 溢出后只清了标志没有调用xMBPortEventPost(EV_FRAME_RECEIVED)补上事件投递发现还是没响应查vMBPortSerialEnable()发送完成中断里关闭了发送使能但接收使能一直没有重新打开在发送完成中断里恢复接收使能问题解决。这个案例说明串口收发方向切换和事件投递是 FreeModbus 移植的三个命门之二任何一个没打通从站都像个哑巴。5.3 现象 C偶发帧错误通信一阵好一阵坏主站连续读写时偶尔会出现EV_FRAME_RECEIVED事件到了但协议栈校验失败。排查链路打印接收到的原始字节发现帧的最后一个字节偶尔丢失检查定时器时间理论 3.5T 太短在 115200 波特率下只有 304us任务调度或者其它中断稍一延迟就会在最后一字节还没被串口数据寄存器读走之前触发超时把 3.5T 乘系数放宽到 800us帧错误明显减少同时检查接收缓冲确认没有溢出。这种问题在 115200 甚至更高波特率下很常见。理论值可以作为起点但最终一定要根据实际设备调优。稳定的通信比算出一个教科书级的 3.5T 值更重要。6. 稳定跑通后值得做的几个优化通信跑通只是第一步让它在工程里真正好用下面这几件事我认为值得做。6.1 用任务通知实现事件层最轻量FreeModbus 裸机版本的portevent.c一般是用一个静态变量做标志位xMBPortEventGet()只查标志。在 FreeRTOS 里我建议改成基于任务通知的实现static TaskHandle_t xModbusTaskHandle; void vMBPortSetTaskHandle( TaskHandle_t xTask ) { xModbusTaskHandle xTask; } BOOL xMBPortEventInit( void ) { return TRUE; } BOOL xMBPortEventPost( eMBEventType eEvent ) { BaseType_t xHigherPriorityTaskWoken pdFALSE; xTaskNotifyFromISR( xModbusTaskHandle, (uint32_t)eEvent, eSetBits, xHigherPriorityTaskWoken ); portYIELD_FROM_ISR( xHigherPriorityTaskWoken ); return TRUE; } BOOL xMBPortEventGet( eMBEventType * eEvent ) { uint32_t ulNotificationValue 0; xTaskNotifyWait( 0, 0xFFFFFFFF, ulNotificationValue, portMAX_DELAY ); *eEvent (eMBEventType)( ulNotificationValue 0xFF ); return TRUE; }注意我在前面专门提到的坑xMBPortEventGet()阻塞前必须确保xModbusTaskHandle已经被设置成当前 Modbus 任务的句柄。所以在 Modbus 任务入口处先调用一次vMBPortSetTaskHandle(xTaskGetCurrentTaskHandle())再执行eMBInit()和eMBEnable()。否则事件层根本不知道往哪个任务发通知。6.2 寄存器回调函数里不要做重活eMBRegHoldingCB()、eMBRegInputCB()这些回调是直接在协议栈任务上下文中执行的。如果你在回调里读 Flash、驱动传感器、调用延时函数Modbus 任务会被卡住下一帧请求来了也无法及时处理。我的做法是回调里只读写 RAM 映射区。需要持久化的数据先把更新标记置位由专门的存储任务在主循环的合适时机批量写入。这样既保证了 Modbus 响应速度又避免频繁擦写 Flash 导致寿命问题。6.3 DMA 串口空闲中断的方案要慎重很多朋友喜欢把串口改成 DMA 接收释放 CPU。但 FreeModbus 原生的 RTU 分帧逻辑是基于“逐个字节喂 3.5T 定时器”的一旦开启 DMA 和 FIFO字节中断没了3.5T 定时器无法按预期刷新协议栈就会把正常帧拆散或合并。如果确实想用 DMA一个可行的思路是串口空闲中断来判定一帧结束DMA 收到完整一帧后一次性投递事件关掉原来的 3.5T 定时器逻辑。但这相当于重写 FreeModbus 的接收状态机工作量比移植大不少。我个人建议第一版先老老实实用逐字节中断把整个链路跑稳再考虑 DMA 优化。绝大多数从站应用115200 波特率下逐字节中断占用的 CPU 完全可接受。本文还有配套的精品资源点击获取
