简介FreeModbus v1.6的源码包提供了一套完整的Modbus协议栈实现主要面向嵌入式开发者和自动化工程师解决工业设备通信中的协议接入问题支持RTU、ASCII和TCP三种传输模式。压缩包共1103个文件大小仅4.78MB包含492个头文件、418个C语言源文件以及txt文档、链接脚本、makefile/批处理脚本、demo示例等多种类型按modules、demo、doc、tools等目录清晰组织方便检索与二次开发。包内同时附有GPL/LGPL/BSD许可证文本和Changelog更新记录便于开发者根据项目属性选择合适的授权方式并追踪v1.6版本的改动细节。已有1191人学习下载对于需要在MCU上快速集成Modbus通信或深入理解协议栈内部机制的开发者来说这份资源提供了可直接编译参考的例程与完整源码能够显著降低协议栈的移植和调试成本。 前阵子给一台 STM32F103 的老设备补 Modbus 从站功能工程还停在标准库 V3.5翻了不少资料最后选了 FreeModbus。这个开源协议栈在工业通信里几乎是事实标准v1.6 版本虽然年头不短但做 Modbus RTU 从站该有的东西一样不缺常见功能码齐全、代码量小、结构清晰。移植它不需要你精通 Modbus 协议细节真正要做的只有四件事把串口收发接到协议栈、做好 3.5T 帧间隔定时器、实现事件队列、写好寄存器回调。这篇文章以 stm32f103 标准库 RS232 为例把 FreeModbus v1.6 的完整移植过程和调试心得分享出来适合手里有老工程、想快速接入 Modbus 总线的开发者参考。1. 从解压到建工程FreeModbus v1.6 的文件取舍与移植边界1.1 解压之后先别急着往工程里拖freemodbus-v1.6.zip 解压出来有doc、demo、modbus、tools几个目录真正要用的只有modbus下面的东西。很多新手会把整个目录塞进 Keil 工程结果编译报一堆文件重定义或者找不到头文件其实只需要添加这几类文件协议栈核心mb.c、mb.h、mbrtu.c、mbrtu.h、mbproto.c、mbproto.h功能码实现mbfuncholding.c、mbfunccoils.c、mbfundiscrete.c、mbfuncinput.c工具函数mbutils.c、mbutils.h移植层port.h、portserial.c、porttimer.c、portevent.c配置与用户回调mbconfig.h、自己新建的user_mb_app.c文件对应的作用我整理了一张表文件作用mb.c协议栈总入口eMBInit、eMBPoll、eMBEnable 都在这里mbrtu.cModbus RTU 模式实现包含 3.5T 帧超时计算与状态机mbproto.c通用协议处理、功能码分发mbfuncholding.c保持寄存器功能码 03/06/16mbfunccoils.c线圈功能码 01/05/15mbfundiscrete.c离散输入功能码 02mbfuncinput.c输入寄存器功能码 04mbutils.cCRC16、字节序等工具函数demo目录下的参考工程可以看但别直接抄因为不同开发板的时钟和外设差异很大。头文件包含路径至少要把modbus/include和modbus/port加上这个漏了的话编译直接挂在第一个mb.h。1.2 协议栈层和移植层的边界画在哪FreeModbus 设计得很干净协议栈层只负责解析字节流、判断帧完整性、按功能码分发请求完全不碰具体硬件。它需要底层提供的三种能力是串口收发一个字节、定时器产生帧间隔超时、事件队列传递协议栈状态。所以移植的本质是重写portserial.c、porttimer.c、portevent.c这三个文件而不是去改mbrtu.c里的协议逻辑。我见过有人在mbrtu.c里改 CRC 或者改帧判断逻辑最后查错查到崩溃就是没搞清边界。mbconfig.h是协议栈的功能开关默认所有功能码都使能如果只做只读数据的从站可以关掉写线圈、写多寄存器这些功能减小代码体积但初期建议保持默认调通再裁剪。2. 串口层移植USART 中断与协议栈字节流怎么对接2.1 串口初始化只开 RXNE先别开 TXE基于标准库 V3.5GPIO 和 USART1 的初始化很常规。有一个关键点初始化阶段只打开接收中断RXNE不要开发送中断TXE。因为 FreeModbus 的发送是逐字节驱动的发送中断什么时候开由协议栈通过vMBPortSerialEnable(xRxEnable, xTxEnable)来控制移植层不要自己提前开。BOOL xMBPortSerialInit(UCHAR ucPort, ULONG ulBaudRate, UCHAR ucDataBits, eMBParity eParity) { GPIO_InitTypeDef GPIO_InitStructure; USART_InitTypeDef USART_InitStructure; NVIC_InitTypeDef NVIC_InitStructure; if(ucPort 0) /* 0 映射到 USART1 */ { RCC_APB2PeriphClockCmd(RCC_APB2Periph_GPIOA | RCC_APB2Periph_USART1, ENABLE); GPIO_InitStructure.GPIO_Pin GPIO_Pin_9; /* TX */ GPIO_InitStructure.GPIO_Mode GPIO_Mode_AF_PP; GPIO_InitStructure.GPIO_Speed GPIO_Speed_50MHz; GPIO_Init(GPIOA, GPIO_InitStructure); GPIO_InitStructure.GPIO_Pin GPIO_Pin_10; /* RX */ GPIO_InitStructure.GPIO_Mode GPIO_Mode_IN_FLOATING; GPIO_Init(GPIOA, GPIO_InitStructure); USART_InitStructure.USART_BaudRate ulBaudRate; USART_InitStructure.USART_WordLength USART_WordLength_8b; USART_InitStructure.USART_StopBits USART_StopBits_1; USART_InitStructure.USART_Parity USART_Parity_No; USART_InitStructure.USART_HardwareFlowControl USART_HardwareFlowControl_None; USART_InitStructure.USART_Mode USART_Mode_Rx | USART_Mode_Tx; USART_Init(USART1, USART_InitStructure); NVIC_InitStructure.NVIC_IRQChannel USART1_IRQn; NVIC_InitStructure.NVIC_IRQChannelPreemptionPriority 1; NVIC_InitStructure.NVIC_IRQChannelSubPriority 0; NVIC_InitStructure.NVIC_IRQChannelCmd ENABLE; NVIC_Init(NVIC_InitStructure); USART_ITConfig(USART1, USART_IT_RXNE, ENABLE); USART_Cmd(USART1, ENABLE); } return TRUE; }注意ucDataBits和eParity这两个参数。如果你在eMBInit里配置了偶校验或者奇校验USART 的字长要改成 9 位校验位对应设置成USART_Parity_Even或USART_Parity_Odd。上面这段只演示了最常用的 8N1实际项目按需补全判断就好。2.2 ISR 里的两个关键回调一个收、一个发USART1 中断处理函数是串口层和协议栈之间的桥梁。接收侧逻辑很简单RXNE 置位说明收到了一个字节用xMBPortSerialGetByte读出来然后立刻喂给pxMBFrameCBByteReceived。这个函数是协议栈内部函数你不用管它怎么处理只要保证每个字节都不丢就行。发送侧的机制稍微绕一点。FreeModbus 不会一次性把整帧数据塞给串口而是一个字节一个字节往外发每发完一个字节触发 TXE 中断在中断里调用pxMBFrameCBTransmitFinished()协议栈收到这个信号后会决定是继续发下一个字节还是收尾关闭发送。完整的 ISR 写法如下void USART1_IRQHandler(void) { if(USART_GetITStatus(USART1, USART_IT_RXNE) ! RESET) { CHAR ucByte; xMBPortSerialGetByte(ucByte); pxMBFrameCBByteReceived(ucByte); } if(USART_GetITStatus(USART1, USART_IT_TXE) ! RESET) { USART_ClearITPendingBit(USART1, USART_IT_TXE); vMBPortSerialEnable(TRUE, FALSE); /* 先关掉 TXE 中断 */ pxMBFrameCBTransmitFinished(); } }这里有个特别容易踩的坑TXE 是发送数据寄存器空不是发送完成。FreeModbus 用的是 TXE 中断因为它在逐字节发送时需要一个“当前字节已经从 DR 寄存器拿走”的信号TC发送完成是等移位寄存器全部发完才置位时序上慢了半拍。如果你误开成 TC 中断整帧发完后才会通知协议栈表现出的现象就是响应异常缓慢甚至卡死。2.3 vMBPortSerialEnableRS485 方向控制的天然切入点vMBPortSerialEnable(xRxEnable, xTxEnable)的参数含义是“打开还是关闭接收中断、发送中断”而不是“使能串口”。新手最容易把它写成USART_Cmd(USART1, ENABLE)或者USART_Cmd(USART1, DISABLE)那样会把整个串口关掉接收路径直接瘫痪。如果是 RS485 硬件这个函数是做方向控制的绝佳位置xTxEnable 为 TRUE 时拉高 DE 引脚进入发送模式为 FALSE 时拉低 DE回到接收模式。FreeModbus 在响应帧发送前会调用vMBPortSerialEnable(TRUE, TRUE)发送完再调用vMBPortSerialEnable(TRUE, FALSE)正好和 RS485 收发方向切换的节奏完全吻合。void vMBPortSerialEnable(BOOL xRxEnable, BOOL xTxEnable) { if(xRxEnable) { USART_ITConfig(USART1, USART_IT_RXNE, ENABLE); } else { USART_ITConfig(USART1, USART_IT_RXNE, DISABLE); } if(xTxEnable) { GPIO_SetBits(GPIOB, GPIO_Pin_12); /* RS485 方向控制 DE */ USART_ITConfig(USART1, USART_IT_TXE, ENABLE); } else { GPIO_ResetBits(GPIOB, GPIO_Pin_12); USART_ITConfig(USART1, USART_IT_TXE, DISABLE); } }3. 3.5T 帧间隔定时器Modbus RTU 最容易被忽略的成败点3.1 为什么一个定时器能决定一帧数据是否完整Modbus RTU 没有像帧头、帧尾这样的固定标记收发双方靠“总线静默时间”来切分帧接收端如果超过 3.5 个字符时间没有收到新字节就认为当前这帧结束了。一个字符按 10 个 bit 计算9600 波特率下 3.5T 大约是 3.65ms如果有校验位按 11 个 bit 算大约是 4.01ms。这个时间窗口非常短主循环里计数根本来不及必须用硬件定时器。FreeModbus 的做法是每收到一个字节就重置定时器如果 3.5T 内没有新字节到来定时器溢出协议栈就判定一帧结束开始解析数据。这也是为什么很多移植版接收偶尔出现“半帧”或者“两帧粘一起”的怪问题基本都是这个定时器没调对。3.2 用 TIM3 做单脉冲定时器别用自动重载标准库工程里我习惯用 TIM3因为 USART1 和 TIM3 的中断优先级可以分开管理。配置思路系统时钟 72MHzAPB1 预分频后定时器时钟 72MHz预分频设 71得到 1MHz 计数频率也就是一个 tick 等于 1us。FreeModbus 的xMBPortTimersInit传入参数的单位是 50us所以重载值就是usTim1Timerout50us * 50 - 1。关键在定时器模式要选单脉冲模式TIM_OPMode_Single。这样定时器溢出一次后自动停下来等下一个字节触发vMBPortTimersEnable再重新启动。如果用自动重载模式定时器每 3.5T 就中断一次一帧数据会被切得七零八落协议栈永远不会认为是完整帧。BOOL xMBPortTimersInit(USHORT usTim1Timerout50us) { TIM_TimeBaseInitTypeDef TIM_TimeBaseStructure; NVIC_InitTypeDef NVIC_InitStructure; RCC_APB1PeriphClockCmd(RCC_APB1Periph_TIM3, ENABLE); TIM_TimeBaseStructure.TIM_Period (usTim1Timerout50us * 50) - 1; TIM_TimeBaseStructure.TIM_Prescaler 72 - 1; TIM_TimeBaseStructure.TIM_ClockDivision 0; TIM_TimeBaseStructure.TIM_CounterMode TIM_CounterMode_Up; TIM_TimeBaseInit(TIM3, TIM_TimeBaseStructure); TIM_SelectOnePulseMode(TIM3, TIM_OPMode_Single); NVIC_InitStructure.NVIC_IRQChannel TIM3_IRQn; NVIC_InitStructure.NVIC_IRQChannelPreemptionPriority 2; NVIC_InitStructure.NVIC_IRQChannelSubPriority 0; NVIC_InitStructure.NVIC_IRQChannelCmd ENABLE; NVIC_Init(NVIC_InitStructure); TIM_ITConfig(TIM3, TIM_IT_Update, ENABLE); return TRUE; } void vMBPortTimersEnable(void) { TIM_SetCounter(TIM3, 0); TIM_Cmd(TIM3, ENABLE); } void vMBPortTimersDisable(void) { TIM_Cmd(TIM3, DISABLE); }usTim1Timerout50us这个值不需要你自己算eMBInit传入波特率之后协议栈内部会算好再调xMBPortTimersInit。但调试时要心里有数9600 波特率大概对应 70~80 个 tick115200 波特率大概只有 6~7 个 tick差距很大如果换了波特率没有重新初始化协议栈就会出现超时时间不对导致的断帧。3.3 定时器溢出中断里只做一件事TIM3 更新中断里要第一时间清标志然后调用pxMBPortTimersTicks()这是协议栈判断帧超时的入口。可以顺手调一次vMBPortTimersDisable()虽然单脉冲模式已经自动停止了但多加这一句能防止某些芯片标志位异常导致定时器没有完全停住。void TIM3_IRQHandler(void) { if(TIM_GetITStatus(TIM3, TIM_IT_Update) ! RESET) { TIM_ClearITPendingBit(TIM3, TIM_IT_Update); vMBPortTimersDisable(); pxMBPortTimersTicks(); } }这里有个经验USART 接收中断的优先级要高于 TIM3 中断或者至少不低于。如果定时器中断把串口中断打断太久在高波特率下很容易丢字节一丢字节 CRC 就不对整个帧被协议栈丢弃现象就是“偶发不应答”。4. 四个寄存器回调把设备数据映射成 Modbus 地址空间4.1 四张数据表对应四个函数Modbus 从站的核心是维护四张数据表线圈、离散输入、输入寄存器、保持寄存器。FreeModbus 通过四个回调函数让用户把这四张表和自己的数据区对接起来数据模型常见地址范围典型功能码对应回调线圈 Coils0x01/05/15eMBRegCoilsCB离散输入 Discrete Inputs1x02eMBRegDiscreteCB输入寄存器 Input Registers3x04eMBRegInputCB保持寄存器 Holding Registers4x03/06/16eMBRegHoldingCB从站收到主站请求后协议栈会解析出功能码、地址和数量然后调用对应的回调函数。回调函数内部只需要做一个翻译工作把请求里的数据从协议栈缓冲区搬到实际变量区或者反过来把变量区数据搬到协议栈缓冲区。Modbus 协议细节、CRC 校验、异常码生成全部由协议栈处理回调里不用管。4.2 保持寄存器回调的读写实现保持寄存器是项目中用得最多的一个完整的eMBRegHoldingCB写法如下eMBErrorCode eMBRegHoldingCB(UCHAR *pucRegBuffer, USHORT usAddress, USHORT usNRegs, eMBRegisterMode eMode) { eMBErrorCode eStatus MB_ENOERR; int iRegIndex; if((usAddress usNRegs) REG_HOLDING_NREGS) { for(iRegIndex 0; iRegIndex usNRegs; iRegIndex) { if(eMode REG_READ) { /* 读高字节在前低字节在后 */ pucRegBuffer[2 * iRegIndex] (UCHAR)(usRegHolding[usAddress iRegIndex] 8); pucRegBuffer[2 * iRegIndex 1] (UCHAR)(usRegHolding[usAddress iRegIndex] 0xFF); } else { /* 写从缓冲区拼出 16 位数据 */ usRegHolding[usAddress iRegIndex] (USHORT)((pucRegBuffer[2 * iRegIndex] 8) | pucRegBuffer[2 * iRegIndex 1]); } } } else { eStatus MB_ENOREG; } return eStatus; }有两个点要解释清楚。第一usAddress是相对这块数据表起始地址的偏移量。比如主站读取地址 40001协议栈传入的usAddress就是 0读取 40010传入就是 9。所以你的映射表从哪个地址开始决定了数组下标和实际 Modbus 地址之间要减多少。第二Modbus 寄存器是 16 位且大端传输读时先高字节后低字节写时要把两个字节拼回一个 16 位数这个顺序错了读出来的数据就是乘以 256 再取模之类的乱值。4.3 越界一定要返回 MB_ENOREG回调函数里最容易忽略的是地址越界处理。如果主站访问的寄存器数量超出了数组范围一定要返回MB_ENOREG协议栈会自动回一个 Modbus 异常码给主站。如果硬着头皮继续读写轻则读到越界地址的垃圾值重则把数组后面的内容覆盖造成内存踩踏。线圈、离散输入、输入寄存器这三个回调的结构完全一样只是数据类型从 16 位变成 1 位处理时用位运算即可。5. 主循环初始化与联调排错eMBPoll 这个函数不能省5.1 初始化流程和 eMBPoll 的调用位置main 函数里协议栈的初始化流程很固定先eMBInit配置模式、从站地址、串口号、波特率和校验位然后eMBEnable启动协议栈最后在 while 主循环里高频调用eMBPoll。eMBPoll负责处理事件队列中的状态比如帧接收完成、执行请求、帧发送完成它决定整个从站能否正确响应主站。int main(void) { /* 系统时钟、GPIO、USART、TIM3 初始化 */ SysTick_Init(); vUARTInit(); eMBErrorCode eStatus eMBInit(MB_RTU, 0x01, 0, 9600, MB_PAR_NONE); if(eStatus ! MB_ENOERR) { /* 初始化失败一般是参数不合法 */ } eMBEnable(); while(1) { eMBPoll(); /* 其他用户任务 */ } }这里有个很实际的建议eMBPoll不要放在某个大循环的末尾也不要被长延时阻塞。实测下来一个 20ms 以上的阻塞延时就会明显影响响应速度因为协议栈可能在延时期间收到完整请求但来不及处理。最好把eMBPoll放在 while 循环开头其他任务见缝插针。5.2 用 Modbus Poll 联调问题排查表PC 端用 Modbus Poll设置从站地址 1、功能码 03、起始地址 0、数量 10地址 40001 开始读保持寄存器。如果没有任何反应按下面的顺序排查现象最可能原因排查方法串口收不到数据接线错误、RXNE 中断没开先看接线和共地再进 ISR 打断点收到请求但不应答从站地址不匹配核对 eMBInit 第二参数应答乱码波特率/校验位不一致确认双方参数一致偶发不响应3.5T 定时器不准或中断优先级低检查 TIM3 单脉冲配置提高 USART 中断优先级通信几次后卡死TXE 中断没有按协议栈开关检查 vMBPortSerialEnable 是否严格按 xTxEnable 控制RS232 调试时还有一个很容易忽视的问题有些 USB 转 RS232 线的 TX、RX 是交叉好的有些是直连的遇到收不到数据先试一下交换 TX/RX。RS485 同样要注意 A/B 线别接反并且主站和从站之间必须共地否则通信极不稳定问号一堆。6. 关于 freemodbus dma 移植高速通信的进阶方向6.1 为什么有人一搜就是 freemodbus dmaFreeModbus 默认的收发方式是每收到一个字节进一次 RXNE 中断每发出一个字节进一次 TXE 中断。9600、19200 波特率下这个频率还能接受但到了 115200 以上一个字节的时间只有 87us 左右CPU 频繁进出中断处理其他实时任务的时间就被严重挤压。搜freemodbus dma的人基本都是想把收发的中断次数降下来。这个思路本身没错但 FreeModbus 的原生架构是逐字节事件驱动直接上 DMA 并不是简单替换一个函数就行改造前要理解它内部状态机是怎么流转的。6.2 可行的改造方向和我踩过坑后的建议发送侧的理想方案是把“逐字节写 DR 寄存器 TXE 中断”改成“协议栈把整帧准备好后一次性交给 DMA传输完成中断里再调pxMBFrameCBTransmitFinished()”。麻烦在于 FreeModbus 的发送状态机是每发一个字节就等待 TXE 中断来推进的要改成 DMA 方式必须修改mbrtu.c里发送状态机那一段或者换一种思路在xMBPortSerialPutByte里先把字节写进自己的发送缓冲区等协议栈把所有字节都“发”完、调用vMBPortSerialEnable关闭 TXE 时再启动一次 DMA 把缓冲区内容搬出去。这种做法改动小一些但对缓冲区生命周期和发送完成时序要求比较高。接收侧相对可控一点用 USART 空闲中断IDLE DMA 循环接收一帧数据到达后整段搬走再交给协议栈解析。但要注意 FreeModbus 内部通过 3.5T 定时器判断帧结束如果你用空闲中断来定帧边界必须保证空闲中断的触发时机和 3.5T 匹配否则高波特率下会把连续的多帧误判成一帧。我的建议是第一版先用中断版跑通功能确认 Modbus 通信稳定无误后再考虑 DMA。如果只是偶尔通信量不大根本不用上 DMA如果确实高速通信 CPU 吃紧优先改接收侧的空闲 DMA发送状态机动刀成本高、风险大改之前一定先把代码理解透或者找别人验证过的 freemodbus dma 移植版参考别上来就抄。最后说点个人体会FreeModbus v1.6 代码确实老但在 Modbus 从站这个场景下非常能打。我最初也动过自己写协议栈的念头试了一版就放弃了光 3.5T 和 CRC 的边界情况就够喝一壶。如果你用的是 STM32F0 或者 HAL 库移植思路完全一样只是时钟和外设 API 换一下。新板子建议先用 9600 波特率调通再逐步往上提速率能少踩很多通信时序的坑。本文还有配套的精品资源点击获取
简介FreeModbus v1.6的源码包提供了一套完整的Modbus协议栈实现主要面向嵌入式开发者和自动化工程师解决工业设备通信中的协议接入问题支持RTU、ASCII和TCP三种传输模式。压缩包共1103个文件大小仅4.78MB包含492个头文件、418个C语言源文件以及txt文档、链接脚本、makefile/批处理脚本、demo示例等多种类型按modules、demo、doc、tools等目录清晰组织方便检索与二次开发。包内同时附有GPL/LGPL/BSD许可证文本和Changelog更新记录便于开发者根据项目属性选择合适的授权方式并追踪v1.6版本的改动细节。已有1191人学习下载对于需要在MCU上快速集成Modbus通信或深入理解协议栈内部机制的开发者来说这份资源提供了可直接编译参考的例程与完整源码能够显著降低协议栈的移植和调试成本。 前阵子给一台 STM32F103 的老设备补 Modbus 从站功能工程还停在标准库 V3.5翻了不少资料最后选了 FreeModbus。这个开源协议栈在工业通信里几乎是事实标准v1.6 版本虽然年头不短但做 Modbus RTU 从站该有的东西一样不缺常见功能码齐全、代码量小、结构清晰。移植它不需要你精通 Modbus 协议细节真正要做的只有四件事把串口收发接到协议栈、做好 3.5T 帧间隔定时器、实现事件队列、写好寄存器回调。这篇文章以 stm32f103 标准库 RS232 为例把 FreeModbus v1.6 的完整移植过程和调试心得分享出来适合手里有老工程、想快速接入 Modbus 总线的开发者参考。1. 从解压到建工程FreeModbus v1.6 的文件取舍与移植边界1.1 解压之后先别急着往工程里拖freemodbus-v1.6.zip 解压出来有doc、demo、modbus、tools几个目录真正要用的只有modbus下面的东西。很多新手会把整个目录塞进 Keil 工程结果编译报一堆文件重定义或者找不到头文件其实只需要添加这几类文件协议栈核心mb.c、mb.h、mbrtu.c、mbrtu.h、mbproto.c、mbproto.h功能码实现mbfuncholding.c、mbfunccoils.c、mbfundiscrete.c、mbfuncinput.c工具函数mbutils.c、mbutils.h移植层port.h、portserial.c、porttimer.c、portevent.c配置与用户回调mbconfig.h、自己新建的user_mb_app.c文件对应的作用我整理了一张表文件作用mb.c协议栈总入口eMBInit、eMBPoll、eMBEnable 都在这里mbrtu.cModbus RTU 模式实现包含 3.5T 帧超时计算与状态机mbproto.c通用协议处理、功能码分发mbfuncholding.c保持寄存器功能码 03/06/16mbfunccoils.c线圈功能码 01/05/15mbfundiscrete.c离散输入功能码 02mbfuncinput.c输入寄存器功能码 04mbutils.cCRC16、字节序等工具函数demo目录下的参考工程可以看但别直接抄因为不同开发板的时钟和外设差异很大。头文件包含路径至少要把modbus/include和modbus/port加上这个漏了的话编译直接挂在第一个mb.h。1.2 协议栈层和移植层的边界画在哪FreeModbus 设计得很干净协议栈层只负责解析字节流、判断帧完整性、按功能码分发请求完全不碰具体硬件。它需要底层提供的三种能力是串口收发一个字节、定时器产生帧间隔超时、事件队列传递协议栈状态。所以移植的本质是重写portserial.c、porttimer.c、portevent.c这三个文件而不是去改mbrtu.c里的协议逻辑。我见过有人在mbrtu.c里改 CRC 或者改帧判断逻辑最后查错查到崩溃就是没搞清边界。mbconfig.h是协议栈的功能开关默认所有功能码都使能如果只做只读数据的从站可以关掉写线圈、写多寄存器这些功能减小代码体积但初期建议保持默认调通再裁剪。2. 串口层移植USART 中断与协议栈字节流怎么对接2.1 串口初始化只开 RXNE先别开 TXE基于标准库 V3.5GPIO 和 USART1 的初始化很常规。有一个关键点初始化阶段只打开接收中断RXNE不要开发送中断TXE。因为 FreeModbus 的发送是逐字节驱动的发送中断什么时候开由协议栈通过vMBPortSerialEnable(xRxEnable, xTxEnable)来控制移植层不要自己提前开。BOOL xMBPortSerialInit(UCHAR ucPort, ULONG ulBaudRate, UCHAR ucDataBits, eMBParity eParity) { GPIO_InitTypeDef GPIO_InitStructure; USART_InitTypeDef USART_InitStructure; NVIC_InitTypeDef NVIC_InitStructure; if(ucPort 0) /* 0 映射到 USART1 */ { RCC_APB2PeriphClockCmd(RCC_APB2Periph_GPIOA | RCC_APB2Periph_USART1, ENABLE); GPIO_InitStructure.GPIO_Pin GPIO_Pin_9; /* TX */ GPIO_InitStructure.GPIO_Mode GPIO_Mode_AF_PP; GPIO_InitStructure.GPIO_Speed GPIO_Speed_50MHz; GPIO_Init(GPIOA, GPIO_InitStructure); GPIO_InitStructure.GPIO_Pin GPIO_Pin_10; /* RX */ GPIO_InitStructure.GPIO_Mode GPIO_Mode_IN_FLOATING; GPIO_Init(GPIOA, GPIO_InitStructure); USART_InitStructure.USART_BaudRate ulBaudRate; USART_InitStructure.USART_WordLength USART_WordLength_8b; USART_InitStructure.USART_StopBits USART_StopBits_1; USART_InitStructure.USART_Parity USART_Parity_No; USART_InitStructure.USART_HardwareFlowControl USART_HardwareFlowControl_None; USART_InitStructure.USART_Mode USART_Mode_Rx | USART_Mode_Tx; USART_Init(USART1, USART_InitStructure); NVIC_InitStructure.NVIC_IRQChannel USART1_IRQn; NVIC_InitStructure.NVIC_IRQChannelPreemptionPriority 1; NVIC_InitStructure.NVIC_IRQChannelSubPriority 0; NVIC_InitStructure.NVIC_IRQChannelCmd ENABLE; NVIC_Init(NVIC_InitStructure); USART_ITConfig(USART1, USART_IT_RXNE, ENABLE); USART_Cmd(USART1, ENABLE); } return TRUE; }注意ucDataBits和eParity这两个参数。如果你在eMBInit里配置了偶校验或者奇校验USART 的字长要改成 9 位校验位对应设置成USART_Parity_Even或USART_Parity_Odd。上面这段只演示了最常用的 8N1实际项目按需补全判断就好。2.2 ISR 里的两个关键回调一个收、一个发USART1 中断处理函数是串口层和协议栈之间的桥梁。接收侧逻辑很简单RXNE 置位说明收到了一个字节用xMBPortSerialGetByte读出来然后立刻喂给pxMBFrameCBByteReceived。这个函数是协议栈内部函数你不用管它怎么处理只要保证每个字节都不丢就行。发送侧的机制稍微绕一点。FreeModbus 不会一次性把整帧数据塞给串口而是一个字节一个字节往外发每发完一个字节触发 TXE 中断在中断里调用pxMBFrameCBTransmitFinished()协议栈收到这个信号后会决定是继续发下一个字节还是收尾关闭发送。完整的 ISR 写法如下void USART1_IRQHandler(void) { if(USART_GetITStatus(USART1, USART_IT_RXNE) ! RESET) { CHAR ucByte; xMBPortSerialGetByte(ucByte); pxMBFrameCBByteReceived(ucByte); } if(USART_GetITStatus(USART1, USART_IT_TXE) ! RESET) { USART_ClearITPendingBit(USART1, USART_IT_TXE); vMBPortSerialEnable(TRUE, FALSE); /* 先关掉 TXE 中断 */ pxMBFrameCBTransmitFinished(); } }这里有个特别容易踩的坑TXE 是发送数据寄存器空不是发送完成。FreeModbus 用的是 TXE 中断因为它在逐字节发送时需要一个“当前字节已经从 DR 寄存器拿走”的信号TC发送完成是等移位寄存器全部发完才置位时序上慢了半拍。如果你误开成 TC 中断整帧发完后才会通知协议栈表现出的现象就是响应异常缓慢甚至卡死。2.3 vMBPortSerialEnableRS485 方向控制的天然切入点vMBPortSerialEnable(xRxEnable, xTxEnable)的参数含义是“打开还是关闭接收中断、发送中断”而不是“使能串口”。新手最容易把它写成USART_Cmd(USART1, ENABLE)或者USART_Cmd(USART1, DISABLE)那样会把整个串口关掉接收路径直接瘫痪。如果是 RS485 硬件这个函数是做方向控制的绝佳位置xTxEnable 为 TRUE 时拉高 DE 引脚进入发送模式为 FALSE 时拉低 DE回到接收模式。FreeModbus 在响应帧发送前会调用vMBPortSerialEnable(TRUE, TRUE)发送完再调用vMBPortSerialEnable(TRUE, FALSE)正好和 RS485 收发方向切换的节奏完全吻合。void vMBPortSerialEnable(BOOL xRxEnable, BOOL xTxEnable) { if(xRxEnable) { USART_ITConfig(USART1, USART_IT_RXNE, ENABLE); } else { USART_ITConfig(USART1, USART_IT_RXNE, DISABLE); } if(xTxEnable) { GPIO_SetBits(GPIOB, GPIO_Pin_12); /* RS485 方向控制 DE */ USART_ITConfig(USART1, USART_IT_TXE, ENABLE); } else { GPIO_ResetBits(GPIOB, GPIO_Pin_12); USART_ITConfig(USART1, USART_IT_TXE, DISABLE); } }3. 3.5T 帧间隔定时器Modbus RTU 最容易被忽略的成败点3.1 为什么一个定时器能决定一帧数据是否完整Modbus RTU 没有像帧头、帧尾这样的固定标记收发双方靠“总线静默时间”来切分帧接收端如果超过 3.5 个字符时间没有收到新字节就认为当前这帧结束了。一个字符按 10 个 bit 计算9600 波特率下 3.5T 大约是 3.65ms如果有校验位按 11 个 bit 算大约是 4.01ms。这个时间窗口非常短主循环里计数根本来不及必须用硬件定时器。FreeModbus 的做法是每收到一个字节就重置定时器如果 3.5T 内没有新字节到来定时器溢出协议栈就判定一帧结束开始解析数据。这也是为什么很多移植版接收偶尔出现“半帧”或者“两帧粘一起”的怪问题基本都是这个定时器没调对。3.2 用 TIM3 做单脉冲定时器别用自动重载标准库工程里我习惯用 TIM3因为 USART1 和 TIM3 的中断优先级可以分开管理。配置思路系统时钟 72MHzAPB1 预分频后定时器时钟 72MHz预分频设 71得到 1MHz 计数频率也就是一个 tick 等于 1us。FreeModbus 的xMBPortTimersInit传入参数的单位是 50us所以重载值就是usTim1Timerout50us * 50 - 1。关键在定时器模式要选单脉冲模式TIM_OPMode_Single。这样定时器溢出一次后自动停下来等下一个字节触发vMBPortTimersEnable再重新启动。如果用自动重载模式定时器每 3.5T 就中断一次一帧数据会被切得七零八落协议栈永远不会认为是完整帧。BOOL xMBPortTimersInit(USHORT usTim1Timerout50us) { TIM_TimeBaseInitTypeDef TIM_TimeBaseStructure; NVIC_InitTypeDef NVIC_InitStructure; RCC_APB1PeriphClockCmd(RCC_APB1Periph_TIM3, ENABLE); TIM_TimeBaseStructure.TIM_Period (usTim1Timerout50us * 50) - 1; TIM_TimeBaseStructure.TIM_Prescaler 72 - 1; TIM_TimeBaseStructure.TIM_ClockDivision 0; TIM_TimeBaseStructure.TIM_CounterMode TIM_CounterMode_Up; TIM_TimeBaseInit(TIM3, TIM_TimeBaseStructure); TIM_SelectOnePulseMode(TIM3, TIM_OPMode_Single); NVIC_InitStructure.NVIC_IRQChannel TIM3_IRQn; NVIC_InitStructure.NVIC_IRQChannelPreemptionPriority 2; NVIC_InitStructure.NVIC_IRQChannelSubPriority 0; NVIC_InitStructure.NVIC_IRQChannelCmd ENABLE; NVIC_Init(NVIC_InitStructure); TIM_ITConfig(TIM3, TIM_IT_Update, ENABLE); return TRUE; } void vMBPortTimersEnable(void) { TIM_SetCounter(TIM3, 0); TIM_Cmd(TIM3, ENABLE); } void vMBPortTimersDisable(void) { TIM_Cmd(TIM3, DISABLE); }usTim1Timerout50us这个值不需要你自己算eMBInit传入波特率之后协议栈内部会算好再调xMBPortTimersInit。但调试时要心里有数9600 波特率大概对应 70~80 个 tick115200 波特率大概只有 6~7 个 tick差距很大如果换了波特率没有重新初始化协议栈就会出现超时时间不对导致的断帧。3.3 定时器溢出中断里只做一件事TIM3 更新中断里要第一时间清标志然后调用pxMBPortTimersTicks()这是协议栈判断帧超时的入口。可以顺手调一次vMBPortTimersDisable()虽然单脉冲模式已经自动停止了但多加这一句能防止某些芯片标志位异常导致定时器没有完全停住。void TIM3_IRQHandler(void) { if(TIM_GetITStatus(TIM3, TIM_IT_Update) ! RESET) { TIM_ClearITPendingBit(TIM3, TIM_IT_Update); vMBPortTimersDisable(); pxMBPortTimersTicks(); } }这里有个经验USART 接收中断的优先级要高于 TIM3 中断或者至少不低于。如果定时器中断把串口中断打断太久在高波特率下很容易丢字节一丢字节 CRC 就不对整个帧被协议栈丢弃现象就是“偶发不应答”。4. 四个寄存器回调把设备数据映射成 Modbus 地址空间4.1 四张数据表对应四个函数Modbus 从站的核心是维护四张数据表线圈、离散输入、输入寄存器、保持寄存器。FreeModbus 通过四个回调函数让用户把这四张表和自己的数据区对接起来数据模型常见地址范围典型功能码对应回调线圈 Coils0x01/05/15eMBRegCoilsCB离散输入 Discrete Inputs1x02eMBRegDiscreteCB输入寄存器 Input Registers3x04eMBRegInputCB保持寄存器 Holding Registers4x03/06/16eMBRegHoldingCB从站收到主站请求后协议栈会解析出功能码、地址和数量然后调用对应的回调函数。回调函数内部只需要做一个翻译工作把请求里的数据从协议栈缓冲区搬到实际变量区或者反过来把变量区数据搬到协议栈缓冲区。Modbus 协议细节、CRC 校验、异常码生成全部由协议栈处理回调里不用管。4.2 保持寄存器回调的读写实现保持寄存器是项目中用得最多的一个完整的eMBRegHoldingCB写法如下eMBErrorCode eMBRegHoldingCB(UCHAR *pucRegBuffer, USHORT usAddress, USHORT usNRegs, eMBRegisterMode eMode) { eMBErrorCode eStatus MB_ENOERR; int iRegIndex; if((usAddress usNRegs) REG_HOLDING_NREGS) { for(iRegIndex 0; iRegIndex usNRegs; iRegIndex) { if(eMode REG_READ) { /* 读高字节在前低字节在后 */ pucRegBuffer[2 * iRegIndex] (UCHAR)(usRegHolding[usAddress iRegIndex] 8); pucRegBuffer[2 * iRegIndex 1] (UCHAR)(usRegHolding[usAddress iRegIndex] 0xFF); } else { /* 写从缓冲区拼出 16 位数据 */ usRegHolding[usAddress iRegIndex] (USHORT)((pucRegBuffer[2 * iRegIndex] 8) | pucRegBuffer[2 * iRegIndex 1]); } } } else { eStatus MB_ENOREG; } return eStatus; }有两个点要解释清楚。第一usAddress是相对这块数据表起始地址的偏移量。比如主站读取地址 40001协议栈传入的usAddress就是 0读取 40010传入就是 9。所以你的映射表从哪个地址开始决定了数组下标和实际 Modbus 地址之间要减多少。第二Modbus 寄存器是 16 位且大端传输读时先高字节后低字节写时要把两个字节拼回一个 16 位数这个顺序错了读出来的数据就是乘以 256 再取模之类的乱值。4.3 越界一定要返回 MB_ENOREG回调函数里最容易忽略的是地址越界处理。如果主站访问的寄存器数量超出了数组范围一定要返回MB_ENOREG协议栈会自动回一个 Modbus 异常码给主站。如果硬着头皮继续读写轻则读到越界地址的垃圾值重则把数组后面的内容覆盖造成内存踩踏。线圈、离散输入、输入寄存器这三个回调的结构完全一样只是数据类型从 16 位变成 1 位处理时用位运算即可。5. 主循环初始化与联调排错eMBPoll 这个函数不能省5.1 初始化流程和 eMBPoll 的调用位置main 函数里协议栈的初始化流程很固定先eMBInit配置模式、从站地址、串口号、波特率和校验位然后eMBEnable启动协议栈最后在 while 主循环里高频调用eMBPoll。eMBPoll负责处理事件队列中的状态比如帧接收完成、执行请求、帧发送完成它决定整个从站能否正确响应主站。int main(void) { /* 系统时钟、GPIO、USART、TIM3 初始化 */ SysTick_Init(); vUARTInit(); eMBErrorCode eStatus eMBInit(MB_RTU, 0x01, 0, 9600, MB_PAR_NONE); if(eStatus ! MB_ENOERR) { /* 初始化失败一般是参数不合法 */ } eMBEnable(); while(1) { eMBPoll(); /* 其他用户任务 */ } }这里有个很实际的建议eMBPoll不要放在某个大循环的末尾也不要被长延时阻塞。实测下来一个 20ms 以上的阻塞延时就会明显影响响应速度因为协议栈可能在延时期间收到完整请求但来不及处理。最好把eMBPoll放在 while 循环开头其他任务见缝插针。5.2 用 Modbus Poll 联调问题排查表PC 端用 Modbus Poll设置从站地址 1、功能码 03、起始地址 0、数量 10地址 40001 开始读保持寄存器。如果没有任何反应按下面的顺序排查现象最可能原因排查方法串口收不到数据接线错误、RXNE 中断没开先看接线和共地再进 ISR 打断点收到请求但不应答从站地址不匹配核对 eMBInit 第二参数应答乱码波特率/校验位不一致确认双方参数一致偶发不响应3.5T 定时器不准或中断优先级低检查 TIM3 单脉冲配置提高 USART 中断优先级通信几次后卡死TXE 中断没有按协议栈开关检查 vMBPortSerialEnable 是否严格按 xTxEnable 控制RS232 调试时还有一个很容易忽视的问题有些 USB 转 RS232 线的 TX、RX 是交叉好的有些是直连的遇到收不到数据先试一下交换 TX/RX。RS485 同样要注意 A/B 线别接反并且主站和从站之间必须共地否则通信极不稳定问号一堆。6. 关于 freemodbus dma 移植高速通信的进阶方向6.1 为什么有人一搜就是 freemodbus dmaFreeModbus 默认的收发方式是每收到一个字节进一次 RXNE 中断每发出一个字节进一次 TXE 中断。9600、19200 波特率下这个频率还能接受但到了 115200 以上一个字节的时间只有 87us 左右CPU 频繁进出中断处理其他实时任务的时间就被严重挤压。搜freemodbus dma的人基本都是想把收发的中断次数降下来。这个思路本身没错但 FreeModbus 的原生架构是逐字节事件驱动直接上 DMA 并不是简单替换一个函数就行改造前要理解它内部状态机是怎么流转的。6.2 可行的改造方向和我踩过坑后的建议发送侧的理想方案是把“逐字节写 DR 寄存器 TXE 中断”改成“协议栈把整帧准备好后一次性交给 DMA传输完成中断里再调pxMBFrameCBTransmitFinished()”。麻烦在于 FreeModbus 的发送状态机是每发一个字节就等待 TXE 中断来推进的要改成 DMA 方式必须修改mbrtu.c里发送状态机那一段或者换一种思路在xMBPortSerialPutByte里先把字节写进自己的发送缓冲区等协议栈把所有字节都“发”完、调用vMBPortSerialEnable关闭 TXE 时再启动一次 DMA 把缓冲区内容搬出去。这种做法改动小一些但对缓冲区生命周期和发送完成时序要求比较高。接收侧相对可控一点用 USART 空闲中断IDLE DMA 循环接收一帧数据到达后整段搬走再交给协议栈解析。但要注意 FreeModbus 内部通过 3.5T 定时器判断帧结束如果你用空闲中断来定帧边界必须保证空闲中断的触发时机和 3.5T 匹配否则高波特率下会把连续的多帧误判成一帧。我的建议是第一版先用中断版跑通功能确认 Modbus 通信稳定无误后再考虑 DMA。如果只是偶尔通信量不大根本不用上 DMA如果确实高速通信 CPU 吃紧优先改接收侧的空闲 DMA发送状态机动刀成本高、风险大改之前一定先把代码理解透或者找别人验证过的 freemodbus dma 移植版参考别上来就抄。最后说点个人体会FreeModbus v1.6 代码确实老但在 Modbus 从站这个场景下非常能打。我最初也动过自己写协议栈的念头试了一版就放弃了光 3.5T 和 CRC 的边界情况就够喝一壶。如果你用的是 STM32F0 或者 HAL 库移植思路完全一样只是时钟和外设 API 换一下。新板子建议先用 9600 波特率调通再逐步往上提速率能少踩很多通信时序的坑。本文还有配套的精品资源点击获取
