手把手教你把 FreeMODBUS 搞进你的单片机：从零开始打造工业级 Modbus 从机
你有没有遇到过这样的场景？手头的传感器或控制板需要接入 PLC 系统，而对方只认一个协议——Modbus RTU。你翻遍数据手册，发现通信时序复杂、CRC 校验繁琐、帧间隔还得精确到微秒……自己写一套？三天调试两天半，最后还总丢包。
别急，老工程师早就不用“造轮子”了。今天我就带你用开源神器FreeMODBUS，在几天内甚至几小时内，让你的 STM32 或其他 MCU 原地变身标准 Modbus 从机设备。不讲虚的，全程实战拆解，连 T3.5 定时怎么算都给你掰开揉碎。
为什么是 FreeMODBUS？它到底强在哪？
先说结论：如果你要做的是 Modbus 从机（Slave），FreeMODBUS 是目前资源最省、结构最清、社区最稳的选择。
我们来看一组真实数据：在一个 STM32F103C8T6（俗称“蓝丸”，72MHz 主频 + 20KB RAM）上跑 FreeMODBUS RTU 从机，Flash 占用约 6KB，RAM 不到 1KB。这意味着什么？意味着你在一片成本不到 5 块钱的芯片上，就能实现完整的工业通信能力。
更关键的是它的设计哲学——分层解耦。整个协议栈被清晰地划分为三层：
- 协议核心层：处理报文解析、功能码调度、状态机流转；
- 端口层（Port Layer）：对接串口、定时器、中断；
- 应用层：你来定义寄存器怎么读写。
其中只有“端口层”和“应用层”需要你动手改，其余部分几乎可以原封不动移植到任何平台。这种架构让同一套应用逻辑能在 GD32、ESP32、NXP LPC 上无缝切换，简直是嵌入式开发者的福音。
移植第一步：搞定端口层，让协议栈“感知”硬件
串口驱动：别再轮询了，用中断！
很多人一开始喜欢在主循环里不断while(USART_GetFlagStatus(...))轮询接收数据，这在 FreeMODBUS 中行不通。因为它依赖事件驱动模型——每收到一个字节就必须立刻通知协议栈。
怎么做？你需要实现两个回调注册函数，并在中断服务程序中触发它们。
// port.c void vMBPortSerialEnable(BOOL bRxEnable, BOOL bTxEnable) { if (bRxEnable) { __HAL_UART_ENABLE_IT(&huart1, UART_IT_RXNE); pxMBFrameCBByteReceived = prvvUARTRxISR; // 注册接收回调 } else { __HAL_UART_DISABLE_IT(&huart1, UART_IT_RXNE); } if (bTxEnable) { __HAL_UART_DISABLE_IT(&huart1, UART_IT_TXE); // 先关 pxMBFrameCBTransmitterEmpty = prvvUARTTxISR; // 发送启动由协议栈控制，首次发送会自动开启 TXE 中断 } }注意这里的关键点：
- 接收中断始终开启；
- 发送中断由协议栈动态管理（发完一帧就关，有新任务再开）；
-pxMBFrameCBByteReceived和pxMBFrameCBTransmitterEmpty是全局函数指针，指向 FreeMODBUS 内部的状态处理函数。
一旦串口收到数据，进入中断：
void USART1_IRQHandler(void) { if (__HAL_UART_GET_FLAG(&huart1, UART_FLAG_RXNE)) { uint8_t byte = huart1.Instance->DR; prvvUARTRxISR(byte); // 直接交给协议栈处理 } if (__HAL_UART_GET_FLAG(&huart1, UART_FLAG_TXE)) { prvvUARTTxISR(); // 通知协议栈继续发下一个字节 } }这样，协议栈就能实时捕获每一个字节，不会因为主循环卡顿导致丢帧。
定时器配置：T3.5 到底是什么鬼？
这是新手最容易栽跟头的地方。T3.5 是判断一帧结束的关键时间，来源于 Modbus 串行链路规范：当连续 3.5 个字符时间内没有新数据到达，认为当前帧已完整。
计算公式如下：
$$
T_{3.5} = \frac{3.5 \times 11}{\text{波特率}} \quad (\text{单位：秒})
$$
比如 9600bps 下：
- 每位时间 ≈ 104.17μs
- 一个字符（11位）≈ 1.146ms
- T3.5 ≈ 4ms
所以你要配置一个定时器，在每次收到字节后重置并启动，若超时仍未收完，则上报“帧结束”。
void vMBPortTimersEnable(void) { uint32_t timer_ticks = (SystemCoreClock / 1000000) * usT35TimeUs; // 微秒转计数值 htim7.Init.Prescaler = SystemCoreClock / 1000000 - 1; // 1MHz 计频 htim7.Init.CounterMode = TIM_COUNTERMODE_UP; htim7.Init.Period = timer_ticks - 1; HAL_TIM_Base_Start(&htim7); __HAL_TIM_ENABLE_IT(&htim7, TIM_IT_UPDATE); pxMBCallbackTimerExpired = prvvTIMERExpiredISR; // 超时回调 } // 在每次接收到字节时调用此函数复位定时器 void vMBPortTimersReload(void) { __HAL_TIM_SET_COUNTER(&htim7, 0); HAL_TIM_Base_Start(&htim7); }⚠️ 坑点提醒：某些 HAL 库的
HAL_Delay()会影响 SysTick，进而干扰 FreeRTOS 时间基准。建议使用独立定时器或 DWT 周期计数替代。
应用层实现：如何让你的变量“可被 Modbus 访问”
这才是真正体现业务价值的部分。假设你有一个温度传感器值、一组继电器状态、几个 PID 参数要暴露给主站，该怎么组织？
FreeMODBUS 提供四个标准回调函数，分别对应四种寄存器类型：
| 寄存器类型 | 功能码 | 回调函数 |
|---|---|---|
| 线圈（Coils） | 0x01/0x05 | eMBRegCoilsCB() |
| 离散输入 | 0x02 | eMBRegDiscreteCB() |
| 输入寄存器 | 0x04 | eMBRegInputCB() |
| 保持寄存器 | 0x03/0x06/0x10 | eMBRegHoldingCB() |
我们以最常见的保持寄存器读写为例：
#define REG_HOLDING_START 40001 #define REG_HOLDING_NREGS 32 static uint16_t usRegHoldingBuf[REG_HOLDING_NREGS]; eMBErrorCode eMBRegHoldingCB(UCHAR *pucRegBuffer, USHORT usAddress, USHORT usNRegs, eMBRegisterMode eMode) { eMBErrorCode eStatus = MB_ENOERR; int i; // 地址合法性检查 if ((usAddress >= REG_HOLDING_START) && (usAddress + usNRegs <= REG_HOLDING_START + REG_HOLDING_NREGS)) { usAddress -= REG_HOLDING_START; // 转为数组索引偏移 switch (eMode) { case MB_REG_READ: for (i = 0; i < usNRegs; i++) { pucRegBuffer[i*2] = (uint8_t)(usRegHoldingBuf[usAddress + i] >> 8); pucRegBuffer[i*2 + 1] = (uint8_t)(usRegHoldingBuf[usAddress + i]); } break; case MB_REG_WRITE: for (i = 0; i < usNRegs; i++) { usRegHoldingBuf[usAddress + i] = (pucRegBuffer[i*2] << 8) | pucRegBuffer[i*2 + 1]; } break; } } else { eStatus = MB_ENOREG; // 返回地址越界错误 } return eStatus; }这段代码干了三件事：
1. 检查请求地址是否落在允许范围内；
2. 将 Modbus 的大端字节流转换为本地 16 位整数；
3. 支持批量读写，效率高。
你可以把usRegHoldingBuf[0]映射成目标温度设定值，[1]是 PWM 占空比，[2]是运行模式……只要主站知道地址对应关系，就能远程操控你的设备。
主循环怎么写？一句话教会你集成
很多初学者以为 FreeMODBUS 需要复杂的任务调度，其实不然。它采用非阻塞轮询机制，只需在主循环中定期调用一次eMBPoll()函数即可。
int main(void) { HAL_Init(); SystemClock_Config(); MX_GPIO_Init(); MX_USART1_UART_Init(); MX_TIM7_Init(); // 初始化 Modbus 从机 eMBInit(MB_RTU, SLAVE_ADDRESS, 0, BAUD_RATE, MB_PAR_EVEN); eMBEnable(); // 启动串口和定时器 while (1) { eMBPoll(); // 推动协议状态机前进 osDelay(1); // 如果用了 FreeRTOS，可适当延时 } }就这么简单。eMBPoll()内部会检查是否有新帧到来、是否超时、是否需要发送响应等，执行时间通常小于 100μs，完全不影响其他任务运行。
实战避坑指南：那些文档没写的细节
✅ 正确设置 T3.5 时间的方法
不要硬编码#define T35_US 4000！不同波特率下必须动态计算：
static uint32_t usT35TimeUs; void CalculateT35(uint32_t baud) { usT35TimeUs = (35000UL + (baud >> 1)) / baud; // 更精准的四舍五入算法 }这个公式来自 FreeMODBUS 官方推荐，能有效应对浮点误差。
✅ 中断优先级一定要够高！
RS-485 总线通常是多机共享的，主站轮询节奏很快。如果 UART 中断被其他高负载中断抢占，可能导致接收缓冲溢出。
建议设置：
- UART Rx 中断：Preemption Priority ≥ 1
- Timer 超时中断：与 UART 同级或更高
否则你会看到奇怪的现象：偶尔能通，大部分时间无响应。
❌ 绝对不能在回调里加 delay！
新手常犯的错误是在eMBRegHoldingCB()里操作 GPIO 时加延时：
case MB_REG_WRITE: relay_state = pucRegBuffer[0]; HAL_GPIO_WritePin(Relay_GPIO_Port, Relay_Pin, relay_state); HAL_Delay(10); // 错！会导致协议卡死！ break;eMBPoll()是非阻塞的，但如果你在里面阻塞了，整个协议状态机就会停滞，无法处理下一帧。正确做法是：只做数据搬运，不执行耗时动作。真正的控制逻辑放在主循环或其他任务中轮询执行。
✅ 加个看门狗，防止协议锁死
虽然 FreeMODBUS 很稳定，但在极端电磁干扰环境下仍可能出现异常。建议在eMBPoll()外围喂狗：
while (1) { eMBPoll(); HAL_IWDG_Refresh(&hiwdg); // 每毫秒左右喂一次 osDelay(1); }确保系统即使卡在协议层也能自动重启恢复。
进阶玩法：让设备更聪明一点
动态修改设备地址
默认地址是编译时固定的，但你可以留一个寄存器（如 40001）专门用来保存当前从机地址：
if (usAddress == 40001 && eMode == MB_REG_WRITE) { SLAVE_ADDRESS = usRegHoldingBuf[0]; // 更新全局地址 eMBSetSlaveID(SLAVE_ADDRESS, TRUE); // 通知协议栈 }这样主站就可以在组网时统一配置所有节点地址，无需重新烧录固件。
结合 FreeRTOS 做多任务协同
如果你的项目较复杂，可以把 Modbus 单独放在一个低优先级任务中：
void ModbusTask(void *pvParameters) { eMBInit(MB_RTU, 1, 0, 9600, MB_PAR_NONE); eMBEnable(); for (;;) { eMBPoll(); vTaskDelay(pdMS_TO_TICKS(1)); } }其他任务负责采集、控制、网络上传，彼此互不干扰。
写在最后：FreeMODBUS 的真正价值不只是通信
当你成功跑通第一个 Modbus 从机后，你会发现它带来的远不止“能联网”这么简单。
它是你通往工业自动化世界的第一张通行证。从此以后，你的设备不再是孤岛，而是可以被 SCADA 系统监控、被 HMI 触摸屏操作、被 PLC 联动控制的标准单元。
更重要的是，通过这次移植，你会深刻理解：
- 如何将协议与硬件解耦；
- 如何设计可复用的软件模块；
- 如何在资源受限系统中优化性能。
这些经验，远比学会 Modbus 本身更有价值。
如果你也正在做一个智能仪表、远程 IO 模块或者定制化传感器，不妨试试 FreeMODBUS。我已经把它用在光伏汇流箱、水处理控制器、楼宇温控终端等多个项目中，稳定运行超过两年。
有什么具体问题？欢迎留言交流，我们一起踩坑、填坑、绕坑。
