简介：面向 STM32 开发者与嵌入式工程师，该包聚焦 STM32F103ZET6 平台上的 FreeModbus 主机移植与 FreeRTOS 集成，用于解决多任务通信、实时响应和任务调度问题，并配有完整测试工程，适合学习 Modbus 协议栈与 RTOS 结合实践的读者。压缩包共 1254 个文件，以 C 源码（612 个 .c、289 个 .h）为主，辅以工程配置、链接脚本、编译目标文件、文本说明及 PDF 文档等，整体约 24.23MB；内含 STM32F103ZET6_TESTCODE 代码，便于直接定位关键实现。已有 1341 人学习下载，可参考其中串口配置、Modbus RTU 请求处理、FreeRTOS 任务划分与调度器初始化等完整代码。资源附带调试生成文件与编译输出，适合在 STM32CubeMX 基础工程上对照移植步骤逐步验证，既能理解 FreeModbus 主机运行机制，也能掌握 RTOS 下多任务协同开发方法。 做嵌入式这几年，我越来越觉得工业现场最“老而弥坚”的通信协议就是Modbus RTU。电表、温控器、变频器、各类传感器，基本都标配Modbus RTU接口。但反过来，当你想自己做一台主站设备，统一去轮询这些从站设备时，问题就来了：主机协议栈怎么实现？串口收发不能让CPU死等，同时还得兼顾屏幕、按键、上报这些任务怎么办？我最近在STM32F103上完成了一个“STM32 + FreeModbus主机 + FreeRTOS”的项目，把这套组合完整跑通了。这篇文章就是一次实战复盘，从方案选型、底层移植到问题排查，全部摊开讲，适合正在做集中控制器、物联网网关，或者相关毕设的同学参考。
这套方案的本质，就是用FreeModbus协议栈把Modbus RTU主机的报文解析、CRC校验、超时重试这些脏活累活接管过来，把应用层彻底解放；再用FreeRTOS负责任务调度，让Modbus轮询、数据处理、人机交互各自跑在独立任务里，互不阻塞。下面我从选型到移植、从调试到优化，完整过一遍。
1. 项目整体设计与方案选型
1.1 为什么最终选了 FreeModbus + FreeRTOS
先纠正一个很容易踩的选型坑：网上搜“FreeModbus”出来的官方版本，默认只实现了从站，也就是Slave，它只能被动响应请求。我项目里需要的是“主机”，也就是Master，要主动去问别人要数据。官方v1.6源码是不支持主动轮询的。我实际用的是基于官方v1.6扩展出来的主从一体版本，主流维护的是armink分支，把Master侧的功能码补齐了，包括01H、02H、03H、04H、05H、06H、0FH、10H这些常用功能码，RTU和ASCII两种模式也都支持。所以做主机项目时，一定要找主从一体的代码，不能直接拿官方从站代码硬改。
为什么还要上FreeRTOS？Modbus RTU主机天然是个“轮询—等待—超时”的过程：发一帧请求，然后等从站回复，等不到就重发，整个过程可能占用几十到几百毫秒。如果把这些时间全部写在主循环里，MCU在这段时间什么都做不了。用FreeRTOS之后，可以用信号量或者事件组把“等待从站回复”这个动作变成任务阻塞，数据回来再唤醒任务，CPU在等待期间可以去处理显示刷新、按键扫描、数据上报等其它工作。这才是上操作系统的根本意义，不是为了赶时髦。
1.2 主从一体架构与任务规划
我在项目里没有完全抛弃从站功能。现场有些场景需要上位机或触摸屏直接读取我手里这台STM32的数据，所以代码采用“主从一体”架构：既能作为主机主动轮询下级从站模块，也能作为从站响应上位机的读请求。主从一体的版本在协议栈内部已经处理了两种模式的切换，应用层只需要把同一块寄存器数据区同时映射给主机侧和从站侧即可，省心很多。
任务规划上，我整个系统拆成了三个任务：
- Modbus主机轮询任务：负责周期性组帧、发帧、收回复、处理错误重试，优先级最高。
- 数据处理任务：负责把采集回来的寄存器值做换算、越限判断，更新全局数据区。
- 用户交互任务：处理按键、LCD显示、串口打印，优先级最低。
三个任务之间用“全局结构体 + 互斥锁”共享数据，简单稳定，不引入复杂的消息队列也能正常跑。如果后续数据量大、模块多了，再用队列或者共享内存加独立标志位的方案去扩展也完全来得及。这里最重要的是把“串口数据收发”放到底层中断里处理，协议栈只负责解析，任务只处理业务，层级理清楚之后代码会好写很多。
2. 工程搭建与代码准备
2.1 硬件平台与开发环境
硬件我用了STM32F103RCT6，64KB RAM、256KB Flash，串口1外接SP3485 RS485收发器作为Modbus总线，测试时挂了两个从站模块：一个温湿度传感器，一个开关量采集模块。如果你的板子是STM32F407或者H743，移植思路一模一样，只需要换对应的外设驱动。
开发环境我用的Keil MDK5，配STM32标准外设库V3.5。最近不少人都切到VSCode + GCC + CMake，或者STM32CubeMX + HAL库，这个完全看个人习惯。FreeModbus本身平台无关，绝大部分是纯C代码，真正需要改动的只有portserial.c和porttimer.c这两个端口文件。无论底层是标准库还是HAL库，核心工作都集中在这两个文件上。需要提醒的是，标准库环境下新建工程时，记得把芯片的宏定义加对——STM32F103就是STM32F10X_HD，否则外设寄存器地址会出问题，编译能过但跑起来就死机。
2.2 FreeRTOS集成要点
FreeRTOS源码可以直接从官方仓库拿到，V9.0或者V10.0的版本都可以。Keil工程里需要添加tasks.c、queue.c、list.c，以及portable/RVDS/ARM_CM3目录下的port.c，内存管理我用的是heap_4.c，它支持内存合并，对频繁创建信号量、队列的场景非常友好。
FreeRTOSConfig.h里几个关键配置我放在这里：
#define configTOTAL_HEAP_SIZE ( 12 * 1024 ) #define configMAX_PRIORITIES ( 5 ) #define configMINIMAL_STACK_SIZE ( 128 ) #define configUSE_MUTEXES 1 #define configUSE_COUNTING_SEMAPHORES 1 #define configCHECK_FOR_STACK_OVERFLOW 2 #define configMAX_SYSCALL_INTERRUPT_PRIORITY 5这里有个新手容易忽略的问题：STM32F103是Cortex-M3内核，FreeRTOS的port层要选ARM_CM3版本，别选ARM_CM4F（带浮点单元的那个），选错会在编译或运行阶段出一堆莫名其妙的问题。如果你用的是F407，才选ARM_CM4F。另外Total Heap不要贪大，F103只有64KB RAM，分配12KB给FreeRTOS已经够了，剩下的留给全局变量和协议栈缓冲区。
2.3 FreeModbus主站代码的获取与工程文件结构
我用的主从一体FreeModbus代码，在Gitee上搜“FreeModbus master STM32”也能找到很多可用版本，我是从armink的仓库拿到的基础代码。解压之后，重点看这几个文件：
- mbfunc.c：主站功能码处理入口
- mbmaster.c / mbmaster.h：主站核心逻辑
- mbfuncother.c：部分扩展功能码
- portserial.c、porttimer.c：需要自己重写的移植文件
- demo工程里有现成的串口和定时器初始化范例
拿到代码后，先把整个源码目录加进Keil工程的Group里，然后编译。编译报错基本都会集中在portserial.c和porttimer.c上，因为官方例程里这两个文件是针对特定平台写的，我们目标平台不一样，需要按自己的MCU重写。刚开始编译几百个error不用慌，多半是头文件路径没加全，把port文件夹、mb文件夹的路径都加进Include Path就能消掉一大半。
3. 核心移植细节与实现
3.1 串口底层适配与收发实现
portserial.c是整个移植工作的重头戏。需要实现的是串口初始化、发送单个字节、接收单个字节、以及串口中断入口。在RTOS环境下，最核心的是接收中断的处理：每收到一个字节，调用协议栈的接收ISR函数，协议栈内部的RTU状态机会依据字节间隔来拼接报文。
我的USART1中断服务函数是这样的：
void USART1_IRQHandler(void) { if (USART_GetITStatus(USART1, USART_IT_RXNE) != RESET) { uint8_t byte = USART_ReceiveData(USART1); prvvUARTRxISR(byte); // 交给协议栈接收状态机 } if (USART_GetITStatus(USART1, USART_IT_TC) != RESET) { USART_ClearITPendingBit(USART1, USART_IT_TC); pxMBPortEventPost(EV_FRAME_SENT); // 发送完成事件 } }注意，串口中断里我只做了最轻量级的操作：把数据喂给协议栈，然后发事件通知。千万不要在中断里直接做业务逻辑，比如解析数据、更新显示，那会拖垮整个系统的实时性。发送方向控制引脚也很有讲究，RS485半双工模式下，发送完成后要在TC中断里立即把方向引脚拉低，切换到接收状态，否则可能会吃掉从站回复帧的头几个字节，导致超时。
关于DMA——很多人搜“freeModbus DMA”想看DMA怎么配。DMA+IDLE中断确实是单片机串口接收的进阶玩法，能够显著降低CPU负载。UART配置成DMA接收，总线空闲时触发IDLE中断，再配合定时器判断帧与帧之间的间隔，一帧数据就完整收了。但这个方案复杂在“空闲中断 + 超时定时器”的配合上，如果处理不好，RTU 3.5个字符时间的判定容易出问题。我这次没有用DMA接收，而是采用“逐字节中断接收 + 协议栈定时器超时”的方式，简单可靠，调试时还能在示波器上直接看每一字节的时序，更适合工业现场排查问题。如果你是做高波特率、大数据量的项目，再考虑升级成DMA方案。
3.2 定时器与RTU超时处理
RTU模式最关键的参数是3.5个字符时间。Modbus RTU规范规定：帧与帧之间需要至少3.5个字符时间的间隔，超过这个时间没有收到新字节，就认为一帧结束了。这个超时定时的计算要严谨一些。
以9600波特率为例，一个字符在标准11位（起始1位+数据8位+校验1位+停止1位）格式下，时间大约是 1/9600 * 11 ≈ 1.146ms，3.5个字符就是约4.0ms。在实际代码里我留了余量，把定时器配置成1MHz计数值（1us一个tick），T35超时数值设置为4000。也就是说定时器累加到4000us还没收到新字节，就触发超时中断，协议栈认为一帧数据接收完毕。115200波特率下一个字符约95.5us，3.5字符约334us，计数值设为350~400就够。
porttimer.c里需要改动的核心函数是定时器初始化和中断服务函数。我的定时器中断如下：
void TIM2_IRQHandler(void) { if (TIM_GetITStatus(TIM2, TIM_IT_Update) != RESET) { TIM_ClearITPendingBit(TIM2, TIM_IT_Update); (void)pvMBFrameTimeout(); // 通知协议栈：接收超时，帧结束 } }单独说一个容易犯错的地方：定时器中断里调用的pvMBFrameTimeout，在FreeModbus内部会读取当前接收状态、判断是否收到一帧完整报文，然后投递事件。这个函数对时间敏感，所以定时器中断优先级不能太低，否则在高负载下可能延迟几百微秒，导致RTU帧判定错乱。但要记住FreeRTOS的规则：中断优先级必须在configMAX_SYSCALL_INTERRUPT_PRIORITY之上（数字上小于或等于该值），否则中断里调用与系统调度相关的函数会直接崩溃。
3.3 主站功能码调用与轮询流程
主站初始化和从站类似，只是把函数名换成Master前缀。我的主任务里初始化流程是：
void vMBMasterTask(void *param) { eMBMasterInit(MB_RTU, 0x01, 9600, MB_PAR_NONE); eMBMasterEnable(); while (1) { eMBMasterPoll(); vTaskDelay(pdMS_TO_TICKS(20)); } }这里eMBMasterInit的第二个参数是从站地址，对主站来说这个值本身没有意义，但框架里保留了这个参数，保持接口一致即可。
真正读取从站数据时，调用的是：
uint16_t usRegBuf[50]; eMBErrorCode eResult = eMBMasterReadHoldingRegister( 0x02, // 从站地址 0x0000, // 起始寄存器地址 10, // 读取数量 usRegBuf, // 数据缓存 1000); // 超时时间，单位ms这里有个很重要的设计约束：FreeModbus主站在同一时刻只能处理一个未完成的请求。也就是说，调用完ReadHoldingRegister等函数后，必须等待eMBMasterPoll把整个交互过程跑完，才能再发下一个请求。如果不加控制地连续调用读数据函数，后面的请求会被直接丢弃或造成状态错乱。
我在应用层实现了一个简单的请求队列：把“读温湿度从站”、“读IO模块”、“写控制继电器”这些请求排成一个结构体数组，每次eMBMasterPoll处理完一个请求后，从队列里取下一个。伪码逻辑：
static int curReqIdx = 0; while (1) { MBReqItem *item = &reqQueue[curReqIdx]; eMBErrorCode err = item->handler(item); curReqIdx = (curReqIdx + 1) % reqCount; vTaskDelay(pdMS_TO_TICKS(100)); // 间隔100ms发起下一个请求 }这个间隔建议按实际从站数量调整，别太密集。Modbus RTU是半双工总线，一主多从轮询本身就有总线空闲时间要求，如果连续发帧不加间隔，有些从站模块反应不过来，会直接不回复。
4. 调试、问题排查与优化建议
4.1 常见错误与调试记录
调试阶段我遇到的第一个坑就是编译问题：把FreeModbus源码加入Keil工程后，报了一堆“No such file or directory”，尤其是port.h、mb.h这两类头文件。解决方法是把mb、port、demo三个目录全部加进C/C++的Include Paths。如果用了VSCode开发，还要在c_cpp_properties.json或者compile_commands.json里把include路径补齐，否则编辑器的红波浪线会烦死人，而且编译时照样得在Makefile里加对应参数。
第二个坑是ST-Link连接问题。Keil点击下载时报“error: no stm32 target found! if your product embeds debug authentication...”这类错误，我排查了很久。后来发现是目标板供电不足，接口电压被拉低，SWD信号不稳定。把外部供电接上、SWDIO和SWCLK两根线缩短之后问题就消失了。如果你也遇到类似报错，先查三样东西：供电、复位线路、SWD线序。
第三类问题是通信方面的。Modbus数据发过去没反应，先用USB转485调试助手挂到总线上，看主机发出的帧是否正确。如果抓到的帧CRC错误、或者从站回了帧但主机不认，多半是波特率和数据格式没设对。Modbus RTU默认数据格式为8位数据、无校验、1位停止位（8N1），但很多设备出厂是偶校验。我调试时确认了从站手册，把配置统一成8E1之后通信就正常了。还有RS485方向引脚一定要在发送完成后立刻拉低，漏了这一步会出现“自己发完、自己半双工没释放”的情况，导致收不到回复。
4.2 中断优先级与临界区问题
FreeRTOS下的Modbus移植，中断优先级配置是重灾区。Cortex-M3内核里中断优先级数值越小优先级越高。FreeRTOS要求使用了系统API的中断，其抢占优先级必须大于等于configMAX_SYSCALL_INTERRUPT_PRIORITY。我这里的configMAX_SYSCALL_INTERRUPT_PRIORITY设为5，所以串口和定时器中断的抢占优先级都设置成5，而SysTick用FreeRTOS自己管理的优先级。或者更稳妥一点，把串口和定时器中断都设成6，比允许调用FreeRTOS API的门槛低一级，保证不冲突。
NVIC_InitStructure.NVIC_IRQChannel = USART1_IRQn; NVIC_InitStructure.NVIC_IRQChannelPreemptionPriority = 6; NVIC_InitStructure.NVIC_IRQChannelSubPriority = 0; NVIC_InitStructure.NVIC_IRQChannelCmd = ENABLE; NVIC_Init(&NVIC_InitStructure);临界区方面，有个实际案例：我在Modbus主机任务里调用协议栈API前，习惯性地用taskENTER_CRITICAL包了一层，结果发现从站回复的接收事件被挡住了，整个轮询卡死。因为FreeModbus主站API内部本来就有事件等待机制，外面再加临界区会把串口中断收到的字节也挡在临界区外面，导致事件永远到不了协议栈。所以，协议栈调用前后不需要额外加临界区，最多在访问共享数据区时用互斥锁保护。
4.3 堆栈溢出检测与性能优化
FreeRTOS的堆栈溢出检测我强烈建议从一开始就开着。把configCHECK_FOR_STACK_OVERFLOW设置为2，并实现钩子函数：
void vApplicationStackOverflowHook(TaskHandle_t xTask, char *pcTaskName) { // 停在这里，看任务名就知道谁溢出了 while (1); }我实测遇到过一个问题：Modbus轮询任务里加了printf打印调试信息后，任务栈从256字瞬间涨到500多字，直接把栈顶踩穿，系统不定期死机。把printf拆出去单独放一个日志任务，或者把这个任务栈改到512字后问题消失。嵌入式里printf这类可变参数函数非常吃栈，尤其在RTOS环境下，每个任务单独分配栈空间，务必小心。
性能优化方面，如果觉得逐字节中断接收太占CPU，可以升级成DMA+IDLE方式。接收上用DMA把数据搬进缓冲区，IDLE中断标记帧结束，再结合协议栈的超时定时器做兜底。但提醒一句：FreeModbus的RTU状态机是逐字节喂进去的，DMA收满一整帧后再一次性写入协议栈，需要保证写入时所有字节都在，否则状态机会因为字节间隔不够而强行断帧。我在DMA方案中是把DMA接收缓冲区按帧最大长度256字节开辟，IDLE触发后把DMA当前计数减掉起始位置，得到本帧长度，再逐字节调用接收ISR。实测在115200波特率下CPU占用比裸中断低不少，轮询间隔可以进一步缩短。如果只是几十个点的小系统，逐字节中断已经完全够用。
最后再分享一点个人体会
这个项目做完，我最大的感受是：FreeModbus + FreeRTOS的组合，真正把“协议栈”和“应用逻辑”解耦了。以前裸机写Modbus主站，状态机、超时、重试、数据解析全堆在主循环里，加一个功能就要重新理顺全局流程。现在协议栈只管收发和解析，任务只管业务，哪里有问题就定位哪个文件，代码维护起来轻松太多。
另外一个实用小技巧：调试Modbus这类串口协议，别只盯着串口助手，逻辑分析仪才是神器。把RS485收发引脚和方向控制引脚同时挂上去，能看到每一帧的方向切换和时序细节。我在排查RS485方向问题时，就是用逻辑分析仪看到接收方向引脚切换慢了半拍，从而找到了根因。项目后期，我还给协议栈加了简单的错误计数——统计超时次数、CRC错误次数、从站无应答次数，直接通过串口打印出来。这些数据对现场故障定位帮助巨大，尤其是多从站轮询时，哪个站点不稳定一目了然，强烈建议你们也在应用层加一套。
本文还有配套的精品资源，点击获取
