FreeModbus

FreeModbus 核心概述

FreeModbus 是一款开源、免费、轻量级 的工业级 Modbus 协议栈，完全遵循 Modbus 标准协议规范实现，是嵌入式领域中最主流、应用最广泛的 Modbus 协议解决方案。✅ 核心优势：无商业授权限制、代码精简（适配资源受限的嵌入式设备）、跨平台性极强、支持 Modbus 全核心功能，可快速移植到单片机 / 嵌入式系统中实现工业通信。

✅ 核心支持的通信模式

FreeModbus 原生支持 Modbus 两大主流物理层通信方式，满足绝大多数工业场景需求：

1. Modbus RTU ：基于串口（UART） 的异步串行通信模式（最常用，如 RS485/RS232 物理层），数据帧紧凑、抗干扰性强，适配工业现场有线组网；
2. Modbus TCP ：基于以太网 / TCP/IP 的通信模式，适配工业以太网组网，支持远距离、高带宽的网络通信。

✅ 核心支持的角色（主 / 从站）

协议栈同时实现两种核心通信角色，可按需配置：

• 从站（Slave） ：被动响应设备（如传感器、PLC 从模块、采集终端），等待主站指令并返回对应数据，是嵌入式开发中最常用的角色；
• 主站（Master）：主动发起指令的设备（如工控机、PLC 主站、上位机），主动轮询 / 控制多个从站设备。

FreeModbus 源码结构解析

FreeModbus 源码采用 「分层解耦」 设计，核心协议层与硬件底层完全分离，这是它能跨平台移植的核心原因，源码目录结构规范，各文件职责清晰：

源码根目录核心结构

freemodbus/
├── doc/            # 协议文档、说明文档（含Modbus标准规范）
├── examples/       # 移植示例工程（如STM32、51、Linux）
├── include/        # 所有头文件（.h），含协议层、端口层声明
├── port/           # 硬件端口适配层（核心移植目录，与芯片/系统绑定）
└── src/            # 核心源码（.c），纯协议层实现（与硬件无关）

关键目录 / 文件职责（重点掌握）

✅ 1. src/ ------ 核心协议层（无需修改，跨平台通用）

该目录是 FreeModbus 的核心灵魂 ，实现了 Modbus RTU/TCP 协议的所有逻辑（帧解析、校验、功能码处理），与硬件、操作系统完全无关 ，移植时绝对不需要修改，直接编译即可。核心文件：

• mb.c：Modbus 协议主入口，初始化、主从站切换核心逻辑；
• mbrtu.c：Modbus RTU 协议帧解析、串口收发逻辑；
• mbtcp.c：Modbus TCP 协议帧解析、网络收发逻辑；
• mbfun*.c：各类功能码（01/02/03/04/05/16）的具体实现。

✅ 2. port/ ------ 硬件端口适配层（移植核心，重点修改）

该目录是 FreeModbus 与硬件 / 操作系统 的「桥梁」，也是移植过程中唯一需要修改的目录 ，所有与芯片（如 STM32）、外设（串口、定时器）、系统（裸机、RTOS、Linux）相关的代码都集中在这里。移植的本质 = 修改 port/ 目录下的代码，适配目标硬件的串口、定时器。核心文件（以 Modbus RTU 为例，最常用）：

• portserial.c：串口端口适配（实现串口初始化、发送、接收中断）；
• porttimer.c：定时器端口适配（实现 Modbus RTU 帧间隔超时检测，需 100ms 定时器）；
• port.h：端口层全局配置（定义串口、定时器编号、中断优先级）。

✅3. include/ ------ 头文件目录

存放所有模块的头文件，与 src/、port/ 目录的源码一一对应，移植时只需根据硬件修改 include/port/ 下的端口头文件即可。

✅ 4. examples/ ------ 移植示例（新手友好）

提供主流平台的移植成品示例，包含完整的工程配置、端口适配代码，新手可直接基于示例修改，大幅降低移植难度（如 STM32F103_RTU_Slave 示例）。

FreeModbus 移植核心流程

FreeModbus 的移植难度极低，核心遵循 「协议层不动，只改端口层」 的原则，所有平台的移植流程基本一致 ，从裸机（STM32、51）到 RTOS（FreeRTOS、RT-Thread）、Linux，均可复用该流程，核心仅需 3 步，新手也能快速完成：

✅通用移植三步法（核心！必掌握）

第一步：准备工作，工程集成

1. 将 FreeModbus 源码全部拷贝到目标工程中；
2. 在编译器中添加源码路径（src/、port/、include/）；
3. 开启编译，解决头文件路径错误（简单配置，无核心问题）。

第二步：核心移植，适配硬件端口（重中之重）

仅修改 port/ 目录下的 2 个核心文件，完成硬件适配，这是移植的核心工作量（占比 90%）：

✔️适配 1：串口端口（portserial.c）

Modbus RTU 依赖串口实现数据收发，需实现 3 个核心功能：

• 初始化串口：配置波特率（9600/19200，工业常用）、数据位 8、校验位 N/E/O、停止位 1；
• 串口发送：实现单字节 / 多字节数据的串口发送函数；
• 串口接收：开启串口接收中断，将接收到的字节存入协议层缓冲区。

✔️ 适配 2：定时器端口（porttimer.c）

Modbus RTU 协议规定：帧与帧之间的空闲时间 ≥ 3.5 个字符时间（波特率 9600 时约 3.7ms），需定时器实现「帧间隔超时检测」，避免帧粘连，需实现 2 个核心功能：

• 初始化定时器：配置定时时长（推荐 100ms，兼容所有波特率）；
• 定时器中断：超时后触发协议层帧解析，完成一帧数据的处理。

第三步：协议初始化，业务开发（无需修改协议，直接调用 API）

硬件适配完成后，直接调用 FreeModbus 提供的标准化 API，即可完成协议初始化、数据交互，无需关注底层协议细节，开发效率极高。核心初始化代码示例（以 STM32 裸机、Modbus RTU 从站为例，最常用）：

#include "mb.h"
#include "mbport.h"

int main(void)
{
    // 1. 初始化硬件（串口、定时器，已在port层实现）
    HAL_Init();
    SystemClock_Config();
    
    // 2. 初始化FreeModbus，配置为RTU从站模式
    eMBInit(MB_RTU, 0x01, 0, 9600, MB_PAR_NONE);  // 从站地址0x01、串口0、波特率9600、无校验
    
    // 3. 启用Modbus协议栈
    eMBEnable();
    
    while(1)
    {
        // 4. 轮询协议栈，处理串口数据帧（核心循环）
        eMBPoll();
        
        // 5. 业务逻辑（如采集传感器数据、控制外设）
        User_Business_Code();
    }
}

FreeModbus 数据交互开发

嵌入式开发中，99% 的场景是将设备作为 Modbus RTU 从站，实现「上位机（如组态王、PLC、串口助手）读写嵌入式设备的寄存器数据」，核心开发分为「寄存器数据映射」和「业务逻辑绑定」两步，简单高效：

✅核心开发流程（从站模式，必读）

第一步：定义寄存器数据缓冲区（映射硬件数据）

在工程中定义全局数组，作为 Modbus 4 类寄存器的「数据缓冲区」，数组的每一个元素对应寄存器的一个地址，上位机读写寄存器本质 = 读写该数组的元素。示例代码（适配 4 类寄存器，裸机通用）：

#include "mb.h"

// 1. 线圈寄存器（0xxxx）：100个bit位（可自定义长度）
uint8_t ucCoilBuf[100] = {0};
// 2. 离散输入寄存器（1xxxx）：100个bit位
uint8_t ucDiscreteBuf[100] = {0};
// 3. 保持寄存器（4xxxx）：50个16bit字（可存整型/浮点型）
uint16_t usHoldingBuf[50] = {0};
// 4. 输入寄存器（3xxxx）：50个16bit字（采集温湿度等模拟量）
uint16_t usInputBuf[50] = {0};

第二步：实现寄存器读写回调函数（协议层绑定缓冲区）

FreeModbus 提供标准化的回调函数接口，需实现这些函数，将协议层的寄存器操作「映射」到第一步定义的全局数组，协议栈会自动调用这些函数完成数据交互。核心回调函数（仅需实现，无需主动调用）：

// 读线圈寄存器（01功能码）
eMBErrorCode eMBRegCoilsCB( UCHAR *pucRegBuffer, USHORT usAddress, USHORT usNCoils, eMBRegisterMode eMode )
{
    // 实现：将ucCoilBuf中对应地址的数据，拷贝到pucRegBuffer
    return MB_ENOERR; // 无错误
}

// 读离散输入寄存器（02功能码）
eMBErrorCode eMBRegDiscreteCB( UCHAR *pucRegBuffer, USHORT usAddress, USHORT usNDiscrete, eMBRegisterMode eMode )
{
    // 实现：将ucDiscreteBuf中对应地址的数据，拷贝到pucRegBuffer
    return MB_ENOERR;
}

// 读/写保持寄存器（03/06/16功能码）
eMBErrorCode eMBRegHoldingCB( UCHAR *pucRegBuffer, USHORT usAddress, USHORT usNRegs, eMBRegisterMode eMode )
{
    if(eMode == MB_REG_READ) {
        // 读：将usHoldingBuf数据拷贝到pucRegBuffer
    } else {
        // 写：将pucRegBuffer数据拷贝到usHoldingBuf，更新硬件参数
    }
    return MB_ENOERR;
}

// 读输入寄存器（04功能码）
eMBErrorCode eMBRegInputCB( UCHAR *pucRegBuffer, USHORT usAddress, USHORT usNRegs, eMBRegisterMode eMode )
{
    // 实现：将usInputBuf中采集的模拟量数据，拷贝到pucRegBuffer
    return MB_ENOERR;
}

第三步：业务逻辑绑定（硬件数据 ↔ 寄存器缓冲区）

在主循环 / 中断中，完成「硬件数据」与「寄存器缓冲区」的双向同步，这是实现实际功能的核心：

• ✅ 采集数据：将传感器（温湿度、电压）、开关量的采集结果，写入 usInputBuf、ucDiscreteBuf；
• ✅ 控制硬件：检测 ucCoilBuf、usHoldingBuf 的值变化，控制继电器、电机、指示灯等外设。

示例代码（主循环中同步）：

void User_Business_Code(void)
{
    // 1. 采集温湿度 → 写入输入寄存器30001、30002
    usInputBuf[0] = DHT11_Read_Temp();  // 30001 = 温度值
    usInputBuf[1] = DHT11_Read_Humi();  // 30002 = 湿度值
    
    // 2. 采集按钮状态 → 写入离散输入寄存器10001
    ucDiscreteBuf[0] = HAL_GPIO_ReadPin(GPIOA, GPIO_PIN_0); // 10001 = 按钮状态
    
    // 3. 检测线圈寄存器00001 → 控制继电器
    if(ucCoilBuf[0] == 1) {
        HAL_GPIO_WritePin(GPIOB, GPIO_PIN_1, GPIO_PIN_SET); // 继电器吸合
    } else {
        HAL_GPIO_WritePin(GPIOB, GPIO_PIN_1, GPIO_PIN_RESET); // 继电器断开
    }
    
    // 4. 检测保持寄存器40001 → 设置报警阈值
    g_alarm_temp = usHoldingBuf[0]; // 40001 = 温度报警阈值
}

FreeModbus 移植与开发常见问题

整理了嵌入式开发中使用 FreeModbus 最常见的问题及解决方案，覆盖移植、通信、功能开发全场景，帮你快速避坑：

✅ 问题 1：串口收发异常，上位机无法通信

• 现象：上位机发送指令，设备无响应；或数据收发乱码；
• 原因：① 串口参数不匹配（波特率、校验位、停止位）；② 串口中断未开启；③ RS485 收发方向未切换（最常见！）；
• 解决方案：
  1. 确保串口配置为「8N1」（8 数据位、无校验、1 停止位），波特率与上位机一致；
  2. 开启串口接收 / 发送中断，确保 portserial.c 中中断回调函数正确；
  3. Modbus RTU 多采用 RS485，需在 portserial.c 中添加RS485 方向控制（发送数据时置 DE=RE=1，接收时置 0）。

✅ 问题 2：Modbus RTU 帧解析失败，频繁报校验错误

• 现象：上位机指令发送后，设备返回错误码；或协议栈无法识别完整帧；
• 原因：① 定时器超时时间配置错误（未满足 3.5 字符间隔）；② 串口接收缓冲区溢出；③ 波特率误差过大；
• 解决方案：
  1. 定时器定时时长配置为100ms （兼容所有波特率，推荐值），确保 porttimer.c 中定时器中断正常；
  2. 增大串口接收缓冲区，避免数据溢出；
  3. 确保硬件串口波特率误差 ≤1%（晶振选 8MHz/12MHz/25MHz，减少误差）。

✅ 问题 3：上位机读写寄存器时，地址偏移错误

• 现象：上位机读 30001，实际读到的是 30002 的数据；或地址越界报错；

• 原因：Modbus 协议寄存器地址是 1 起始 ，而 C 语言数组是0 起始，未做地址偏移处理；

• 解决方案：在回调函数中，将上位机传入的 usAddress 减 1，再访问数组：

  usAddress--; // 关键：1起始 → 0起始，匹配数组索引

✅ 问题 4：浮点型数据读写异常（如温湿度浮点值）

• 现象：上位机读到的浮点值与实际不符，数据乱码；
• 原因：Modbus 寄存器是 16bit 字，浮点型（32bit）需高低字拼接，字节序未统一；
• 解决方案：
  1. 嵌入式端：将 float 型数据拆分为 2 个 uint16_t（高 16 位、低 16 位），存入相邻的保持 / 输入寄存器；
  2. 上位机端：读取相邻 2 个寄存器，按「大端 / 小端」拼接为 float 型（与嵌入式端一致）。

✅ 问题 5：FreeRTOS/RTOS 中移植后，通信卡顿 / 死锁

• 现象：协议栈运行卡顿，或系统死机；
• 原因：① 串口 / 定时器中断优先级高于 RTOS 内核优先级；② 协议栈临界区未加互斥保护；
• 解决方案：
  1. 配置中断优先级 ≤ RTOS 内核的最低抢占优先级；
  2. 在 portserial.c、porttimer.c 中，用 RTOS 的互斥锁 / 临界区函数保护共享数据。

总结

1. FreeModbus 是开源免费、轻量级、跨平台的 Modbus 协议栈，支持 RTU/TCP、主 / 从站，是嵌入式工业通信首选；
2. 源码分层解耦 ：src/（协议层，不动） + port/（端口层，修改），移植本质是适配串口 + 定时器；
3. 核心支持 4 类寄存器：线圈（0xxxx）、离散输入（1xxxx）、保持（4xxxx）、输入（3xxxx），覆盖所有工业读写场景；
4. 从站开发核心：定义寄存器缓冲区 → 实现回调函数 → 绑定业务逻辑，上位机读写寄存器即操作缓冲区；
5. 高频坑点：RS485 方向切换、地址偏移、浮点型拼接、中断优先级配置，规避后可快速实现稳定通信。

通过以上内容，你可以快速掌握 FreeModbus 的核心原理、移植方法和开发技巧，轻松在 STM32/51/Linux 等平台实现 Modbus 工业通信！