简介这是一份面向嵌入式开发者的STM32 MODBUS主机程序工程包适合需要实现工业设备通信或学习Modbus RTU协议栈移植的读者。工程基于STM32标准外设库完成包含主机读写寄存器、线圈状态等功能码处理逻辑并涉及UART参数配置、CRC校验、中断接收与错误处理等关键环节。压缩包共160个文件整体3.41MB以C源码、头文件、编译生成的目标文件与固件烧录文件为主工程配置和文档辅助材料一并收录结构较完整。目前已有1747人学习下载说明其在该领域具备一定参考价值。通过阅读源码与工程配置可直接掌握在STM32上搭建Modbus主机的框架与排查思路便于迁移到FreeRTOS或实际控制项目中。1. STM32 MODBUS主机程序串口好发总线难调拿 STM32 做 MODBUS 主机程序是一类被严重低估的活儿。网上能下载的例程里十有八九是从机主机程序要么是半成品要么是带延时的阻塞轮询。真正接到现场总线上把七八台仪表、变频器、PLC 挂在一起跑三个月才会明白主机并不是“发一帧请求再收一帧回复”那么简单。它要管的是轮询节奏、超时判定、重试次数、从机掉线识别还要在半双工总线上和每一台从机心照不宣地分时发言。这篇把主机程序从报文结构、硬件接线、串口中断、CRC 校验、485 方向控制到轮询状态机完整拆开直接用可抄的代码和参数说话。适合两类人一类是从机已经写通、想补主机侧的另一类是用了现成协议栈但总觉得是个黑匣子、一旦总线上出现乱码就无从下手的。读完至少能独立把一主多从的轮询跑稳也知道数据链路层之外的坑大概长什么样。2. MODBUS 主机的基础理解与硬件选型把“主机”当一个小型状态机来设计2.1 MODBUS RTU 报文结构主机发什么、从机怎么认MODBUS 在串行链路上最常见的帧格式是 RTU。主机发出的每一帧由四部分组成从机地址1 字节、功能码1 字节、数据段N 字节、CRC16 校验2 字节低字节在前。从机地址决定这个报文是发给谁的功能码决定要做什么操作数据段带寄存器起始地址、数量或写入值CRC 校验保证整帧在传输中没有被噪声改坏。主机程序与从机程序的思维差别就在这从机是“我来处理请求”主机是“我发出请求还要负责确认结果”。同样一个 03 功能码读保持寄存器从机只需要解析地址、功能码、寄存器地址、寄存器数量然后回一堆数据主机要自己组帧、算 CRC、发出去、等回复、验证地址是否一致、验证功能码是否正确、验证 CRC 对不对、验证数据长度是否符合预期。任何一个环节不满足主机都要决定是重试还是认错。这就要求主机程序的接收逻辑不能像从机那样“收到一个完整帧就处理”而是要主动预测一个帧的字节长度。03 功能码的响应长度可以通过请求里的寄存器数量算出来如果请求读 N 个寄存器正常响应帧长度就是 3 2×N 2地址 功能码 寄存器数据字节 CRC。前面加上了从机地址和功能码完整响应应该是 1 1 2N 2 字节。这个长度预期是后面做超时和粘包处理的关键。MODBUS RTU 请求帧03 功能码字节数内容从机地址10x01 ~ 0xF7功能码10x03起始寄存器地址2高字节在前寄存器数量20x0001 ~ 0x007DCRC162低字节在前主机端需要自己实现表里全部字段的组帧。注意 MODBUS 的数据字段是大端高字节在前CRC 校验字段是小端低字节在前这两个方向搞反是最常见的组帧错误。2.2 硬件选型与电气接线RS485 不是串口STM32 的 USART 外设只是数据链路层的物理收发MODBUS 主机大多跑在 RS485 电气层上。RS485 是半双工差分总线A、B 两根线的电压差代表逻辑电平支持多点挂接理论上一条总线能挂 32 台标准负载某些芯片支持 128 或 256。RS232 虽然也是 MODBUS 的物理层之一但只能一对一现场几乎不用。选型时首先确定接口芯片。目前主流方案是 SP3485、MAX485 或带自动收发功能的国产芯片。我的习惯是优先选带独立 DE/RE 控制脚的芯片比如 SP3485原因后面讲方向控制时会说到自动收发芯片在低速长线上偶尔出现发送尾巴被误判为接收数据的问题排查起来比较费劲。隔离方面如果从机是变频器或大功率电机旁边推荐加光耦隔离的 RS485 模块例如用 ISO3082 或 ADI 的磁耦方案成本高一点但至少不会让共模干扰把单片机和烧录口一波带走。接线有几点要落实。A、B 线必须对绞用屏蔽双绞线屏蔽层单端接地。总线两端各接一个 120Ω 终端电阻注意是一头一个不是每个设备都接。如果从机分布很散、走线超过几十米最好在接近总线末端的那台从机上并一个 120Ω 电阻。总线上所有设备的 A、B 必须同名互接出问题时 80% 是 A、B 反了。硬件上还有一个非常容易被忽略的点STM32 的 USART 引脚是 3.3V TTL 电平RS485 芯片的 RO 和 DI 引脚也是 3.3V 电平可以直接连但大多数开发板上的 RS485 芯片是 5V 供电如果输入端没有做电平匹配接 5V 芯片的 DI 引脚可能把 STM32 的 TX 脚反向灌电流。选型时确认一下接口芯片的 VIH/VIL 是否兼容 3.3V或者中间串一个限流电阻。3. 工程搭建到首帧报文跑通串口初始化、CRC 与 485 方向控制3.1 STM32 串口收发初始化中断接收中断发送串口初始化这块需要明确一件事接收用中断发送也用中断一个字节都不在主循环里阻塞。接收侧我们不做空闲中断而是用最朴素的逐字节中断 定时器超时判帧这样移植性最好也不依赖特定型号的库版本。void MODBUS_UART1_Init(void) { // 假设使用 USART1PA9TX, PA10RXPB0RS485 方向控制高电平发送 GPIO_InitTypeDef gpio {0}; __HAL_RCC_USART1_CLK_ENABLE(); __HAL_RCC_GPIOA_CLK_ENABLE(); __HAL_RCC_GPIOB_CLK_ENABLE(); // PA9/PA10 复用为 USART1 gpio.Pin GPIO_PIN_9 | GPIO_PIN_10; gpio.Mode GPIO_MODE_AF_PP; gpio.Pull GPIO_PULLUP; gpio.Speed GPIO_SPEED_FREQ_HIGH; gpio.Alternate GPIO_AF7_USART1; HAL_GPIO_Init(GPIOA, gpio); // PB0 推挽输出作为 DE/RE 控制 gpio.Pin GPIO_PIN_0; gpio.Mode GPIO_MODE_OUTPUT_PP; gpio.Pull GPIO_NOPULL; HAL_GPIO_Init(GPIOB, gpio); HAL_GPIO_WritePin(GPIOB, GPIO_PIN_0, GPIO_PIN_RESET); // 默认接收模式 huart1.Instance USART1; huart1.Init.BaudRate 9600; huart1.Init.WordLength UART_WORDLENGTH_8B; huart1.Init.StopBits UART_STOPBITS_1; huart1.Init.Parity UART_PARITY_NONE; huart1.Init.Mode UART_MODE_TX_RX; huart1.Init.HwFlowCtl UART_HWCONTROL_NONE; huart1.Init.OverSampling UART_OVERSAMPLING_16; HAL_UART_Init(huart1); // 使能接收中断逐字节接收 HAL_UART_Receive_IT(huart1, rx_byte, 1); }代码里的核心设计是把接收设计成“每来一个字节中断一次”然后进我们的状态机去判帧。这里有两个参数要解释。波特率 9600 是工业现场最保险的起跑线一帧 8 字节在 9600 波特率下约需要 10ms超时判帧时间要留够。接收中断优先级建议设成高于发送中断防止接收被发送拖住。如果使用 HAL 库注意HAL_UART_Receive_IT每收到一个字节完成后要重新调用一次否则中断只触发一次。3.2 CRC16 校验与组帧把请求报文拼出来CRC16 MODBUS 是主机的必修课。标准多项式是 0x8005反射多项式 0xA001初始值 0xFFFF。实际工程里用查表法最快但为了把原理讲清楚这里给出按位计算的版本逻辑一目了然代价是速度稍慢。对于 9600 波特率的串口CPU 算这点 CRC 的时间完全可以忽略。uint16_t MODBUS_CRC16(uint8_t *buf, uint16_t len) { uint16_t crc 0xFFFF; for (uint16_t i 0; i len; i) { crc ^ buf[i]; for (uint8_t j 0; j 8; j) { if (crc 0x0001) { crc 1; crc ^ 0xA001; // 反射多项式 } else { crc 1; } } } return crc; }异或 0xA001 这一步本质上是做多项式除法里的借位。计算完成后注意字节序MODBUS 规定 CRC 低字节先发、高字节后发所以组帧时要把 crc 的(uint8_t)(crc 0xFF)放在前面(uint8_t)(crc 8)放在后面。这一步放反了报文发出去从机就会回异常码 03非法数据值。组帧函数直接定义请求的从机地址、功能码、寄存器地址和寄存器数量uint16_t MODBUS_SlaveTxBuf[8]; // 待发送的报文缓冲区 uint8_t MODBUS_BuildReadHoldReg(uint8_t slave, uint16_t reg_addr, uint16_t reg_num, uint8_t *tx_buf) { uint8_t idx 0; uint16_t crc; tx_buf[idx] slave; // 从机地址 tx_buf[idx] 0x03; // 功能码读保持寄存器 tx_buf[idx] (uint8_t)(reg_addr 8); // 寄存器地址高字节 tx_buf[idx] (uint8_t)(reg_addr 0xFF); // 寄存器地址低字节 tx_buf[idx] (uint8_t)(reg_num 8); // 数量高字节 tx_buf[idx] (uint8_t)(reg_num 0xFF); // 数量低字节 crc MODBUS_CRC16(tx_buf, idx); tx_buf[idx] (uint8_t)(crc 0xFF); // CRC 低字节先发 tx_buf[idx] (uint8_t)(crc 8); // CRC 高字节后发 return idx; // 返回总长度 8 字节 }函数返回的报文长度固定是 8 字节但为了通用性里面所有字段都按实际值填充。reg_num在 03 功能码下最多允许 125即一次最多读 125 个寄存器超过 125 从机会回非法数据值。这个上限来自 MODBUS 规范不是从机厂商自己定的。3.3 发送时序控制DE/RE 引脚切换的正确位置485 方向控制是 STM32 MODBUS 主机最容易翻车的地方。SP3485 这类芯片的 DE 和 RE 常常合并成一个引脚控制DE 高电平代表发送模式RE 低电平代表接收模式。如果硬件上把 DE 和 RE 短接在一起那 MCU 只需控制一根脚发时拉高收时拉低。问题的核心在于“何时拉低”。常规误操作是在调用完串口发送函数后立刻把方向脚拉低结果最后一个字节还没移出移位寄存器方向已经切到接收总线上最后一个字节的尾巴被硬生生截断。从机收到的报文 CRC 永远错误或者干脆不响应。正确的位置是在发送完成中断里、串口的移位寄存器完全腾空之后再切方向。用 HAL 库可以借助 UART 的 TCTransmission Complete中断void HAL_UART_TxCpltCallback(UART_HandleTypeDef *huart) { if (huart-Instance USART1) { // 发送完成最后一个字节已经从移位寄存器移出 HAL_GPIO_WritePin(GPIOB, GPIO_PIN_0, GPIO_PIN_RESET); // 切回接收 __HAL_UART_DISABLE_IT(huart1, UART_IT_TC); modbus_tx_done 1; // 置位发送完成标志 } }这个回调里做两件事拉低方向引脚回到接收状态置位发送完成标志。之所以要关闭 TC 中断是因为被置位的 TC 标志如果不清除下次发送一启动就会再次进中断。modbus_tx_done这个标志给轮询状态机用表示“报文已经完整发出可以开始计时等待响应了”。如果你不用中断发送而是轮询发送也可以等待__HAL_UART_GET_FLAG(huart1, UART_FLAG_TC)置位后再拉低方向脚。注意不要用UART_FLAG_TXETXE 只表示数据从 CPU 移交到了发送数据寄存器并不代表移位寄存器已经发完最后一个位。这是一个很典型的翻车点TXE 比 TC 要早不少按 TXE 切方向报文大概率残缺。4. 主机轮询调度与超时容错把请求发出去只是完成了十分之一4.1 非阻塞轮询状态机不用延时用状态推进如果说报文组帧是主机的“手”轮询状态机就是主机的“大脑”。很多初期跑通的主机程序是这么写的发一帧 →HAL_Delay(500)→ 收数据 → 再发下一帧。这在实验室开一台从机、没有干扰的情况下确实能跑但一旦从机掉电、响应时间不固定、或者总线上有多台从机这套写法就完全失控。阻塞延时期间 CPU 干等接收中断来了也没法及时处理从机响应慢一点你的延时时间到了就开始发下一帧两台设备同时在总线上说话报文直接撞车。改成状态机是正解。状态机的核心思想是把“等响应”这件事拆出来用周期时基去驱动。这里规划五个状态空闲IDLE、发送SEND、等待响应WAIT_RESP、重试RETRY、失败延时FAIL_DELAY。typedef enum { MODBUS_IDLE 0, MODBUS_SEND, MODBUS_WAIT_RESP, MODBUS_RETRY, MODBUS_FAIL_DELAY } ModbusState_t; typedef struct { ModbusState_t state; uint8_t slave_addr; // 当前轮询的从机地址 uint16_t reg_addr; // 寄存器起始地址 uint16_t reg_num; // 寄存器数量 uint8_t retry_cnt; // 已重试次数 uint8_t max_retry; // 最大重试次数 uint32_t wait_time; // 超时计时累计值 uint32_t tx_time; // 记录发送时刻 uint8_t resp_buf[256]; // 接收到的响应帧 uint16_t resp_len; // 实际接收到的字节数 } ModbusMaster_t;主循环里每 1ms 调用一次状态机驱动函数用 tick 递增的方式计时替代阻塞延时。void MODBUS_Poll(void) { switch (modbus.state) { case MODBUS_IDLE: // 轮询队列有下一台从机组装报文并发送 modbus.reg_addr next_reg_addr; modbus.reg_num 4; modbus.slave_addr next_slave_addr; modbus.retry_cnt 0; MODBUS_BuildReadHoldReg(modbus.slave_addr, modbus.reg_addr, modbus.reg_num, MODBUS_SlaveTxBuf); MODBUS_UART_Send(MODBUS_SlaveTxBuf, 8); modbus.state MODBUS_SEND; break; case MODBUS_SEND: // 等发送完成回调置位标志 if (modbus_tx_done) { modbus_tx_done 0; modbus.state MODBUS_WAIT_RESP; modbus.wait_time 0; } break; case MODBUS_WAIT_RESP: modbus.wait_time; if (modbus.wait_time MODBUS_TIMEOUT_MS) { // 超时未收到完整帧记一次失败 modbus.retry_cnt; if (modbus.retry_cnt modbus.max_retry) { modbus.state MODBUS_RETRY; // 重新发送 } else { modbus.state MODBUS_FAIL_DELAY; // 标记从机离线 } } else if (modbus.resp_len 0) { if (MODBUS_CheckFrame()) // 校验通过 { MODBUS_HandleResponse(); // 解析数据 modbus.state MODBUS_IDLE; // 继续轮询下一台 } else { // 校验失败也视为一次失败 modbus.retry_cnt; modbus.state MODBUS_RETRY; } } break; case MODBUS_RETRY: MODBUS_BuildReadHoldReg(modbus.slave_addr, modbus.reg_addr, modbus.reg_num, MODBUS_SlaveTxBuf); MODBUS_UART_Send(MODBUS_SlaveTxBuf, 8); modbus.state MODBUS_SEND; modbus.resp_len 0; break; case MODBUS_FAIL_DELAY: // 该从机连续多次失败暂停轮询一段时间避免霸占总线 break; } }注意WAIT_RESP状态里超时计时是从发送完成之后开始算的不是从调用发送函数开始算。因为发送本身需要时间如果算在发送前超时时间会被挤占。另外retry_cnt从 0 开始第一次失败后变成 1如果max_retry设为 2那么第二次失败后变成 3大于max_retry就进FAIL_DELAY实际上总共发了 3 次首次 两次重试逻辑比较顺。4.2 超时重试与从机离线识别三个必调参数超时时间、重试次数、失败后的暂停时间这三个参数决定了主机在真实总线上的表现。超时时间不能拍脑袋取 100ms。它至少应该大于“从机从收到请求到发出响应所需的内部处理时间”加上“帧在总线上的传输时间”。很多仪表内部是 10ms 或 20ms 的循环任务收到主机请求后要等下一个循环才处理响应时间会达到几十毫秒。常见做法是把超时设在 100ms 到 200ms 之间如果从机是 PLC 或专用控制器可能会更长最好先拿逻辑分析仪看几轮实际响应时间再定。重试次数与最大重试次数决定了“从机掉线”的判定灵敏度。重试太多次单台从机掉线会占用总线几十秒重试太少瞬时干扰导致的丢帧就直接判掉线了。一般设置为 2 次重试即最多发 3 遍请求。如果 3 遍都没有响应基本可以认定这台从机有问题主机应该把它标记为离线转而轮询下一台。FAIL_DELAY状态里如果直接跳过该从机就会出现一个悖论如果从机只是临时离线过一会恢复了主机永远不再问它数据就一直停在旧值上。推荐做法是离线从机每 10 秒或 N 次轮询周期尝试一次而不是彻底踢出轮询队列。这就是很多现场里“重启主机后数据恢复”的原因——不是因为程序修好了而是因为重启把失败计数清零了重新从该从机采集了一遍。5. STM32 MODBUS 主机避坑与常见问题排查总线上的血泪经验5.1 现象发送完立刻拉低 DE从机收到的报文被截断现象是逻辑分析仪上能看到 SEND 方波但总线上最后一个字节只有前半段后半段变成电平毛刺从机根本不回任何数据。原因方向切换发生在 TXE 标志之后、TC 标志之前。TXE 表示数据已经进了发送数据寄存器但移位寄存器还在逐位往外送。这个阶段拉低 DE等于把最后一个字节硬切掉。从机的 CRC 校验永远对不上。解决切换 DE 必须在 TCTransmission Complete置位之后。用中断的话放到HAL_UART_TxCpltCallback里用轮询的话等UART_FLAG_TC。不要用UART_FLAG_TXE判断结束。5.2 现象CRC 有校验但主机总是报 CRC 错误现象是主机发出的请求用串口助手抓包看是对的从机也有响应但主机总在MODBUS_CheckFrame()这一步失败。原因最常见的是响应帧的 CRC 字节序判断反了。MODBUS 的 CRC 在帧里是低字节在前如果你的代码里把收到的resp_buf[len-2]当成高字节、resp_buf[len-1]当成低字节去重组 CRC那算出来永远和报文不匹配。解决接收侧重组 CRC 时低字节在前uint16_t recv_crc (uint16_t)resp_buf[resp_len - 2] | ((uint16_t)resp_buf[resp_len - 1] 8);如果重试多次仍然偶发 CRC 错误检查总线上是否缺少终端电阻或 A/B 反接。CRC 错误集中在长报文时多半不是协议问题是电气问题。5.3 现象轮询到第二个从机时总线卡死或乱码现象是单台从机时一切正常挂上多台从机后偶尔出现总线冲突总线上出现两个设备同时发送的叠加信号所有通信全部错乱。原因主机在状态切换时没有给总线留“静默间隔”。MODBUS RTU 规范要求帧与帧之间至少要有 3.5 个字符时间的静默通常按 3.5 × 11 bit 计算。如果主机从收到响应到重新拉高 DE 发出下一帧之间间隔太短某些从机还在收尾总线可能尚未释放。解决在MODBUS_IDLE状态中加入一个最小帧间隔计时。简单做法是在状态机里维护一个last_tx_time每次发送前检查与上一次发送或接收之间是否超过MODBUS_TURNAROUND_MS。按 9600 波特率算3.5 字符约 4ms取 5ms 比较稳妥其他波特率按 11 bit × 3.5 / 波特率换算。5.4 现象用 for 循环延时做轮询CPU 占用率高且逻辑混乱现象是程序编译能过、单次运行正常但加一个 OLED 刷新或按键检测功能后串口响应就变慢偶尔丢帧。原因阻塞延时让整个主循环卡住这段时间里即使串口中断能进应用层也没有及时处理接收缓冲区的数据一旦同时有多个字节进中断缓冲可能被覆盖。解决改状态机结构主循环里只跑非阻塞的MODBUS_Poll()配合一个稳定时基。时基用HAL_GetTick()或你自己的 systick 计数都行但不要在 main 函数里写大段的HAL_Delay。5.5 现象断电重启后主机不轮询要复位一次才恢复现象是现场设备出现过一次通信冲突或掉电后主机彻底“哑火”离线从机不再被重新询问。表面看起来程序死了其实 CPU 还在跑状态机卡在了某个状态里。原因WAIT_RESP或FAIL_DELAY状态里没有超时逃逸逻辑。比如从机响应了一半发了 3 个字节就断了线resp_len停在 3状态机一直处于“等剩下的字节”永远等不到主循环里的轮询队列就停在这一台上了。解决接收判帧必须有整体超时不管当前收到几个字节只要从开始收到响应到现在超过一个完整帧时间就强制把resp_len清零进入失败流程。同时给MODBUS_Poll()的外层套一个看门狗或者状态机自检如果同一个状态持续时间超过 1 秒强制回到MODBUS_IDLE。6. 从能跑到好用合并读寄存器、浮点解析与被动监听技巧6.1 用一条报文读多段寄存器减少总线占用现场常见误区是一台从机上有好几组数据比如一组温度寄存器、一组压力寄存器、一组状态字很多人轮询时写三条报文去读三个地址。这会让总线上多出两倍的帧也增加了碰撞概率。03 功能码允许一次读最多 125 个连续寄存器。如果你的从机寄存器地址是连续的或者厂商把不连续的关键寄存器放在同一个地址段里完全可以一次把整段读回来在主机端做切片解析// 原来读地址10的1个寄存器 读地址50的1个寄存器 // 现在一次读地址10开始共41个寄存器在缓存里取第1个和第40个 MODBUS_BuildReadHoldReg(0x01, 10, 41, MODBUS_SlaveTxBuf);这样报文从两条变一条总线上主机和从机的通信时间直接减半。注意从机寄存器表如果中间地址有空洞读出来可能是 0 或异常需要先查产品手册确认地址范围是连续的。6.2 IEEE754 浮点与字节序从机回的数据怎么解释现场温度、压力这类数据很多从机直接给你 32 位 IEEE754 浮点数分两个寄存器存放。问题出在字节序有的从机寄存器低地址存的是浮点的高 16 位大端模式有的是低 16 位小端模式还有的是寄存器内字节序反的花样很多。举例一个从机返回 0x40490FDB 这个 32 位值表示 3.1415…。如果寄存器地址从 0 开始地址 0 存了 0x4049地址 1 存了 0x0FDB转换方法是uint32_t raw ((uint32_t)regs[0] 16) | (uint32_t)regs[1]; float value; memcpy(value, raw, 4);但另一台从机可能地址 0 存低 16 位地址 1 存高 16 位uint32_t raw ((uint32_t)regs[1] 16) | (uint32_t)regs[0];很多主机程序就死在“手册上写了 IEEE754但没写寄存器顺序”。调这种问题最快的方法是让从机返回一个已知值比如设成 1.00x3F800000看响应帧里的字节排布一帧就能确定正确的组装顺序。我通常会在代码里把字节序定义成宏不同从机型号用不同的宏避免每次都改解析函数。6.3 用 USB 转 485 做被动监听不在现场打断运行主机程序联调时最怕的就是“我发了请求从机到底回没回”靠主机日志判断永远分不清是从机没回还是主机没收到。准备一个 USB 转 485 模块也可以直接 USB 转 TTL 接在 A/B 差分线上用串口助手或逻辑分析仪监听总线上的原始波形。监听设备只挂在总线上不主动发数据不会影响主机和从机的正常通信。监听时要确认监听模块的 A、B 和总线同名互接波特率设成和主机一致。看到的现象分三种总线上有请求帧、无响应帧问题在从机侧有请求、有响应但主机日志显示超时问题在主机接收处理逻辑总线上请求帧本身残缺问题在主机发送或 485 方向控制。被动监听是排查通信故障最快的手段比猜测和打补丁有效得多。做主机程序这几年我最大的体会是MODBUS 主机代码本身不难写难的是把每一次总线故障都当成一次学习机会。一组超时参数、一个 TC 中断、一段总线静默时间这些细节才是真正从“能跑”到“能投产”的差距。希望这些踩过的坑和参数经验能帮到你。本文还有配套的精品资源点击获取