简介：基于STM32F103ZET6的FreeModbus主机与FreeRTOS移植资源，面向嵌入式通信与物联网开发者，提供一套可对照实践的完整工程。压缩包共1254个文件，约24.23MB，涵盖612个C源文件、289个头文件以及汇编文件、目标文件、静态库、Keil工程配置和hex/bin烧录文件，便于直接编译、烧录与二次开发。资源以STM32F103ZET6_TESTCODE工程为核心，融合Modbus RTU主站协议栈与FreeRTOS任务调度，展示了在多任务环境下如何拆分通信与业务逻辑，提升系统实时性。已有1341人学习下载，适合正在研究STM32通信协议栈移植或希望将FreeRTOS集成到实际项目中的开发者参考。 做了大半年工业设备数据采集，终于把“STM32移植FreeModbus主机 + FreeRTOS”这套组合完整跑通了。这个需求在产线数据上报、PLC网关、智能传感器集中管理这些场景里太常见了，但网上能搜到的资料，九成都是讲FreeModbus从机怎么移植，真正把主机功能做出来、还要在FreeRTOS下稳定跑的教程少之又少。我这篇文章就把整个过程的思路、关键代码和踩过的坑一次说清，给正在搞STM32 + Modbus RTU主站项目的朋友一个可以直接抄作业的参考。
1. 项目背景与整体方案选型
1.1 FreeModbus官方版本的“先天不足”
FreeModbus v1.6是网上流传非常广的开源Modbus协议栈，结构清晰、代码量小，非常适合MCU环境。但有一个问题很多人移植完了才发现：官方版本只实现了从机（Slave）功能。也就是说，它默认是等在外面，接收主站的请求帧，解析功能码，回数据。整套状态机都是围绕“被动响应”设计的。
而实际项目里，我的需求恰恰相反：STM32要作为主站（Master），主动去轮询下位机设备，读寄存器、写参数。比如去读一台温控仪的当前温度、去写一台变频器的运行频率。这就需要把FreeModbus从底子上改一套主机状态机出来，工作量说大不大，但关键是要把协议栈的代码结构吃透，改对了能省很多事。
1.2 为什么选FreeModbus而不是libmodbus
可能有人会问，Linux下libmodbus不是现成的主站库吗？没错，但libmodbus依赖Linux的文件操作和系统调用，代码相对庞大，在STM32这种裸金属环境下移植成本高、资源占用大。FreeModbus虽然官方只做从机，但它的分层做得很好——协议无关的核心层和具体的移植层分得清晰，改造成主机是顺着框架加东西，不是推翻重来。再加上网上FreeModbus的参考资料多，遇到问题好查。
另一个替代方案是用商业协议栈，比如各种收费的Modbus主从库，稳定性和功能都没话说，但成本和授权限制在这个项目里不划算。自己扩展FreeModbus，一是代码完全可控，二是能学到协议栈内部的状态机设计思路，后面要增加自定义功能码、做广播帧支持，都顺手很多。
1.3 主机功能扩展的整体思路
我的做法是：保留FreeModbus原有的从机框架不动，在其之上新增一套主机状态机和主机功能码处理逻辑。通过一个编译宏来切换设备角色，主站和从站功能放同一份代码里。这样以后如果产品既要当主站去采集数据，又要当从站被别人读取状态，切换起来非常方便。
整体架构从上到下大致是这样：
- 应用层：业务任务，生成“读哪个设备的哪个寄存器”的请求列表
- 协议栈层：FreeModbus核心，新增主机状态机、主机功能码处理
- 移植层：串口收发、定时器、RTOS信号量/事件组通知
- 硬件层：STM32串口 + RS485收发器 + 方向控制GPIO
2. FreeModbus协议栈剖析与主机扩展设计
2.1 协议栈源码结构梳理
FreeModbus的源码结构其实很清晰。核心部分和移植部分分开，移植部分放在port文件夹里。我把关键文件的职责列一下，方便还没上手的朋友快速建立地图：
| 文件 | 职责 |
|---|---|
| mb.c | 协议栈初始化、主循环调度入口 |
| mbrtu.c | RTU模式状态机（官方版为从机服务） |
| mbfunc.c | 功能码处理函数入口（读线圈、读寄存器等） |
| mbport.h | 移植层接口声明，串口、定时器、事件回调都在这 |
| portevent.c | 事件机制，裸机和RTOS版本差异主要在这里 |
| portserial.c | 串口底层收发实现 |
| porttimer.c | 定时器时基（T3.5字符静默超时） |
官方从机状态机是：RTU模式下，串口收到帧之后，通过一个T3.5定时器来判断一帧是否结束。如果两个字符之间的时间间隔超过3.5个字符时间，就认为这一帧接收完成，然后把帧交给上层解析。这个T3.5是整个RTU模式的基础，主机模式同样依赖它来分帧。
2.2 主机关键功能模块的设计
官方框架里没有主机功能，所以我额外抽象了一个主机状态机，核心状态如下：
typedef enum { STATE_MB_MASTER_IDLE, // 空闲，可以发送下一帧 STATE_MB_MASTER_WAIT, // 已发送请求，等待从机响应 STATE_MB_MASTER_ERROR // 等待超时或出现帧错误，准备恢复 } eMBMasterState;主机发送一帧请求之后，状态切到WAIT，同时启动一个超时定时器。在超时时间内如果收不到合法响应帧，就认为从机无应答，状态回到IDLE，然后轮询下一台设备。这个超时时间的设置很有讲究，我一般根据波特率来算：9600波特率下，一帧最长256字节，按Modbus协议规范，主站至少要等够从机处理的时间，同时也不能太心软导致轮询周期被拖长。实测下来，响应超时设置在50ms到200ms之间比较合理，具体看从机设备的处理速度。
主机需要支持的功能码也不多，我实现了最常用的三个：
- 0x03：读保持寄存器，读取从机的运行数据
- 0x06：写单个寄存器，比如启停控制、参数修改
- 0x10：写多个寄存器，批量下发参数表
每个功能码对应的请求帧构造和响应帧解析，都在独立函数里完成。这里有个细节：从机如果返回0x83、0x86、0x90这类异常码，主站不能照样当正常数据去解析。我封装了一个统一的响应判断函数，先检查功能码最高位是否为1，是的话直接提取异常码，记录下来方便调试。
2.3 与FreeRTOS的接口层设计
裸机环境下，FreeModbus靠轮询 + 中断跑，但在FreeRTOS里，我选择让Modbus协议栈跑在一个专门的任务里，串口中断只负责搬运数据，处理完一帧之后通过事件组通知任务去解析。
这里有几个设计原则，是从实际工程里总结出来的：
- 中断里不用阻塞函数，所有RTOS通信都带FromISR后缀
- 串口DMA接收 + 空闲中断决定帧边界，T3.5定时器做兜底
- Modbus任务优先级不要设太高，毕竟是通信任务，给数据处理任务留出CPU
- 事件组比二值信号量好用，因为可以区分“收到帧”“发完帧”“超时”等多个事件
事件组的定义大致是这个样子：
#define EVT_RX_FRAME (1 << 0) #define EVT_TX_DONE (1 << 1) #define EVT_TIMEOUT (1 << 2)3. 基于STM32的完整移植实操
3.1 串口底层与DMA收发的实现
我用的STM32F103，HAL库，串口1接RS485。接收部分没有用传统的中断逐字节接收，而是用了UART空闲中断 + DMA环形搬运。这样MCU不需要在每个字节都进中断，CPU占用率能降一个量级。
初始化部分核心代码如下：
#define MODBUS_RX_BUF_SIZE 256 uint8_t xRxBuffer[MODBUS_RX_BUF_SIZE]; void ModbusUartInit(void) { __HAL_UART_ENABLE_IT(&huart1, UART_IT_IDLE); HAL_UART_Receive_DMA(&huart1, xRxBuffer, MODBUS_RX_BUF_SIZE); }在串口中断处理函数里，检测到IDLE标志就说明DMA接收停止了一段空闲，这时读取DMA剩余计数，就能算出这一帧实际收了多少字节：
void USART1_IRQHandler(void) { BaseType_t xHigherPriorityTaskWoken = pdFALSE; if (__HAL_UART_GET_FLAG(&huart1, UART_FLAG_IDLE) != RESET) { __HAL_UART_CLEAR_IDLEFLAG(&huart1); HAL_UART_DMAStop(&huart1); uint16_t usLen = MODBUS_RX_BUF_SIZE - __HAL_DMA_GET_COUNTER(&hdma_usart1_rx); if (usLen > 0) { xRxFrameLen = usLen; xEventGroupSetBitsFromISR(xModbusEventGroup, EVT_RX_FRAME, &xHigherPriorityTaskWoken); } HAL_UART_Receive_DMA(&huart1, xRxBuffer, MODBUS_RX_BUF_SIZE); } portYIELD_FROM_ISR(xHigherPriorityTaskWoken); }这里有个排坑经验：DMA停止之后再重新启动前，务必清掉接收标志。否则连续两帧之间的空闲中断可能偶发丢失，导致从机响应丢帧、主机误判超时。
3.2 定时器时基与超时控制
T3.5定时器是从机分帧的关键，主机端也需要一个超时定时器来等从机响应。我用了TIM3做1ms时基，直接在定时器中断里对超时计数变量做累加，没有额外加RTOS定时器，省资源而且实时性更好。
T3.5时间怎么算？Modbus RTU规定，两个字符之间的最大静默时间不能超过1.5个字符时间，一帧结束时必须有3.5个字符时间的静默。一个字符在串口上占11位（1起始 + 8数据 + 1校验 + 1停止，无校验则少1位）。最常见配置是无校验 + 1停止位，所以：
1字符时间 = 10bit / 波特率 T3.5 = 3.5 × 10 / 波特率以9600波特率计算：T3.5 = 3.5 × 10 / 9600 ≈ 3.65ms。代码里向上取整，设为4ms。对于115200波特率，T3.5只有约0.3ms，这种情况下定时器中断要做成0.1ms级别的时基才能保证精度。所以我把时基定成1ms，同时用硬件定时器捕获来做更精细的静默时间判断，比单纯靠RTOS tick准得多。
3.3 FreeRTOS任务划分与信号量交互
整个系统的任务划分，我按轻重缓急拆成了三个：
- ModbusTask（优先级5，栈512字）：轮询下位机，发送请求、处理响应
- DataProcessTask（优先级3，栈256字）：拿到数据之后做业务处理、存数据库、刷新显示
- WatchdogTask（优先级6，栈128字）：喂独立看门狗，系统异常时快速复位
ModbusTask 的核心循环代码如下：
void ModbusTask(void *pvParameters) { TickType_t xLastWakeTime = xTaskGetTickCount(); const TickType_t xFrequency = pdMS_TO_TICKS(200); for (;;) { ModbusMasterPoll(); // 轮询所有设备的请求列表 vTaskDelayUntil(&xLastWakeTime, xFrequency); } }任务里我只做了轮询和解析，真正的串口收发全部由中断和DMA完成。中断收完一帧后置位事件，ModbusTask等待事件组时如果有EVT_RX_FRAME，就去解析这帧数据。这样串口数据处理和请求发送在时间上解耦，不会出现RS485半双工下“发送还没结束就乱收数据”的尴尬。
3.4 主机请求发送与数据接收解析流程
一帧主机请求的发送过程，我封装成公共函数。以读保持寄存器为例：
eMBMasterErrorCode eMBMasterReadHoldingRegisters(USHRT usAddr, USHRT usRegAddr, USHRT usRegNum) { // 组装请求帧：从机地址 + 功能码0x03 + 寄存器起始地址 + 寄存器数量 + CRC // 调用 xMBMasterUtilSendFrame() 发送 // 状态机切到 WAIT，启动超时定时器 }发送时RS485方向控制是关键。STM32的串口发送是异步的，调用HAL_UART_Transmit返回时，数据可能还在移位寄存器里。如果在发送函数返回后立刻把RS485的DE引脚拉低，就会把帧尾截断。我的做法是等发送完成标志TC置位后再切方向：
HAL_GPIO_WritePin(RS485_DE_GPIO_Port, RS485_DE_Pin, GPIO_PIN_SET); if (HAL_UART_Transmit(&huart1, pFrame, usLen, 100) == HAL_OK) { while (__HAL_UART_GET_FLAG(&huart1, UART_FLAG_TC) == RESET); } HAL_GPIO_WritePin(RS485_DE_GPIO_Port, RS485_DE_Pin, GPIO_PIN_RESET);接收解析同样在协议栈内部完成。收到一帧后，先校验从机地址是否匹配、CRC是否正确，再判断功能码会不会是异常响应，最后缓存响应数据供业务层读取。这套流程下来，ModbusTask 在200ms轮询周期内可以稳定搞定4到6台从机的数据采集。
4. 调试、踩坑与常见问题实录
4.1 堆栈溢出检测，一个让人头疼的问题
FreeRTOS接手之后，最隐蔽的坑就是任务栈溢出。ModbusTask里如果定义了大的局部数组，比如uint8_t ucFrameBuf[256]，再加上函数调用链里的其他局部变量，栈低于256字很容易溢出。常见表现是：系统运行一段时间后，任务突然跑飞、HardFault，或者某些变量值莫名其妙被改写。
我的调试方法分两步。第一步，开启FreeRTOS的栈溢出检测：
#define configCHECK_FOR_STACK_OVERFLOW 2把这项设成2后，FreeRTOS每次任务切换都会主动检查栈指针是否越界。第二步，使用uxTaskGetStackHighWaterMark()在任务循环里打印最小剩余栈：
UBaseType_t uxRemain = uxTaskGetStackHighWaterMark(NULL); printf("ModbusTask stack remain: %u\n", uxRemain);实测下来，ModbusTask 稳定运行时剩余栈最好保持在100字以上。如果低于50字，就要加栈了。我把ModbusTask初始栈设成512字，四台设备轮询的压力测试下剩余栈约180字，算安全。
4.2 延时函数卡死，十有八九是SysTick冲突
这个坑太经典了。项目里原本有裸机时代的delay_ms()函数，不确定是不是基于SysTick做的延时。如果裸机延时函数依赖SysTick中断，而FreeRTOS接管SysTick之后，中断优先级和中断处理函数已经被RTOS改写了，直接调用裸机延时就会卡死或者时间不准。表现就是程序跑到一半死掉，debugger暂停发现卡在delay函数里。
解决方案很简单：FreeRTOS环境下，任务内一律用vTaskDelay()或vTaskDelayUntil()。如果确实需要us级别的短延时应答，我用的是HAL_Delay()也只适合50ms以上，短延时则关掉调度器切回裸延时，或者用DWT时钟计数器：
static void DWT_Delay_us(uint32_t us) { DWT->CYCCNT = 0; DWT->CTRL |= DWT_CTRL_CYCCNTENA_Msk; while (DWT->CYCCNT < us * (SystemCoreClock / 1000000)); }这个函数在临界区外调用，不会阻塞RTOS调度，实测在Modbus发送间隔控制中很好用。
4.3 RS485收发切换的时序坑
RS485是半双工总线，收发方向切换如果处理不当，轻则丢帧，重则整个总线冲突。我最早用延时法控制方向，延时时间不好把握：延时太短会截断最后一位，延时太长又浪费总线吞吐。后来改成上文说的等TC标志，问题彻底解决。
另外还有一个很多人忽略的点：发送完切回接收之后，不要立刻开始准备收下一帧。RS485总线在方向切换瞬间会有电平毛刺，如果串口此时正好开启了接收，会把毛刺当成0x00字节接收进来，扰乱状态机。我在切换方向后加了一个极短的稳定延时（用DWT实现，约0.2ms），实测效果很好。
4.4 常见问题速查表
| 问题现象 | 可能原因 | 解决方法 |
|---|---|---|
| 从机始终无响应 | A/B线接反、总线无终端电阻 | 调换A/B线，120欧电阻并入总线两端 |
| 偶发性响应超时 | DMA接收未清标志导致丢帧 | 每次停止DMA后重新使能，中断里清IDLE标志 |
| 收到0x83类异常码 | 功能码不支持或寄存器地址非法 | 查看从机文档，确认寄存器范围和功能码支持情况 |
| 程序跑飞、HardFault | 任务栈溢出 | 开启栈溢出检测，降低任务内局部数组大小 |
| 串口发出乱码 | 波特率不匹配、晶振精度不够 | 核对从机波特率，检查时钟配置 |
| 轮询周期比预期长很多 | 响应超时时间设置过大 | 把超时时间合理缩小，按从机最慢响应时间定 |
除了表里的内容，还有两个容易忽略的点。一是任务优先级倒置问题：如果项目里还有显示任务、存储任务，优先级设置不当会导致Modbus任务长时间得不到运行，轮询周期抖动很大，我建议Modbus任务优先级不要低于大部分业务任务，但也不能高于看门狗。另一个是CRC校验表的存放位置，放在const区而不是RAM区，省内存还提速，代码里顺手就改了。
5. 关于这套方案的一点个人体会
把FreeModbus从机改成主机，再把FreeRTOS集成进去，整个过程最大的体会是：
协议栈移植的难点从来不在跑通官方例程，而在搞懂它的状态机设计逻辑，然后在此基础上做扩展。FreeModbus的代码组织方式不复杂，但每一层该干什么分得很清楚，我花了两三天通读源码之后，再改主机功能就有一种“顺着作者的思路继续写”的感觉。FreeRTOS那边，重点是把中断和任务之间的数据流设计干净，能用事件组就用事件组，别在中断里处理太多逻辑。
最后再分享一个实用小技巧：调试Modbus通信这种强时序的协议，我强烈建议在代码里预留一个DUMP_FRAME宏开关，开了之后把所有收发帧以十六进制格式打印出来。这个习惯帮我无数次快速定位到是地址不匹配、CRC算错、还是从机异常应答，尤其是在现场调试被业主盯着的时候，能少很多焦虑。
这套方案后续还可以继续扩展：比如增加对广播地址0xFF的支持、把轮询列表做成可动态配置、甚至加上MODBUS TCP网关功能。基础架构对了，这些功能都是搭积木的事。
本文还有配套的精品资源，点击获取
