1. 项目概述ModbusADU 是一个轻量级、零依赖的嵌入式 Modbus 协议数据单元ADU管理库专为资源受限的 MCU 环境设计。它不实现完整的 Modbus 主站或从站逻辑而是聚焦于协议帧的结构化建模、字节级精确操控与校验计算——这是所有 Modbus 实现中最底层、最易出错、也最需严格符合规范的核心环节。该库的核心价值在于将 Modbus RTU 和 TCP 两种物理层之上的 ADU 结构抽象为可编程操作的内存对象。开发者无需手动计算偏移、拼接字节数组、维护 CRC 校验位或处理大小端转换所有这些由ModbusADU类封装完成。其设计哲学是“协议即数据结构帧即内存视图”通过提供多视角的数组访问接口RTU 视图、TCP 视图、PDU 视图、Data 视图使协议解析与构造过程直观、安全、可调试。在实际嵌入式项目中ModbusADU 常作为“胶水层”与以下组件协同工作硬件驱动层UARTRTU、以太网 MAC/PHYTCP传输管理层FreeRTOS 队列缓存接收帧、信号量同步收发、定时器RTU 帧间隔检测应用逻辑层Modbus 主站状态机、从站寄存器映射表、HMI 数据绑定逻辑。它既可独立用于快速原型验证如通过串口助手发送原始帧并解析也可无缝集成进成熟的 Modbus 栈如 FreeMODBUS 的 ADU 层替换具备极高的工程灵活性。2. Modbus 协议 ADU 结构深度解析理解ModbusADU的设计必须首先厘清 Modbus 协议栈中 ADU 的精确定义及其在 RTU 与 TCP 模式下的差异。ADUApplication Data Unit是 Modbus 应用层数据在特定传输层上的完整封装它包含协议头、功能数据和错误校验三部分但具体组成因传输方式而异。2.1 RTU 模式 ADU 结构RTURemote Terminal Unit模式基于串行通信RS-485/RS-232采用二进制编码以静默时间3.5 字符周期界定帧边界。其 ADU 结构如下字段长度描述ModbusADU中对应位置Unit Identifier1 字节从站地址0x00–0xFF。主站用此字段指定目标设备从站用此字段判断是否应答。rtu[0]Function Code1 字节指令类型0x01 读线圈、0x03 读保持寄存器等。rtu[1]或pdu[0]Data0–252 字节功能码相关参数如起始地址、寄存器数量、写入值。长度由功能码决定。rtu[2]开始或pdu[1]开始或data[0]开始Error Check (CRC)2 字节循环冗余校验码覆盖 Unit ID 至 Data 全部字节含 Function Code。低字节在前Little-Endian。rtu[rtu_len - 2]和rtu[rtu_len - 1]关键工程要点RTU 帧无显式长度字段ModbusADU通过setRtuLen()设置的rtu_len仅用于内部计算 CRC 范围并不写入帧中。实际发送时rtu[]数组的length字段索引 2–3不存在这是 RTU 与 TCP 的根本区别。2.2 TCP 模式 ADU 结构TCPTransmission Control Protocol模式运行于以太网上使用标准 TCP/IP 栈以固定长度的 MBAPModbus Application Protocol头标识协议。其 ADU 结构为字段长度描述ModbusADU中对应位置Transaction Identifier2 字节事务标识符用于匹配请求与响应。主站递增从站原样返回。tcp[0]和tcp[1]Protocol Identifier2 字节协议标识符Modbus TCP 固定为0x0000。tcp[2]和tcp[3]Length2 字节后续字节总数Unit ID Function Code Data不含 MBAP 头本身6 字节和错误校验TCP 无 CRC。tcp[4]和tcp[5]Unit Identifier1 字节从站地址同 RTU。tcp[6]Function Code1 字节功能码同 RTU。tcp[7]或pdu[0]Data0–252 字节功能码相关参数同 RTU。tcp[8]开始或pdu[1]开始或data[0]开始关键工程要点TCP ADU无 CRC 字段其可靠性由 TCP 协议栈保证。ModbusADU的updateCrc()和crcGood()方法在 TCP 模式下不生效调用它们不会修改tcp[]数组内容。Length字段是 TCP 模式的核心setLength()、setTcpLen()等方法均围绕此字段计算。2.3 PDU 与 Data 视图跨模式的统一抽象PDUProtocol Data Unit是 Modbus 协议栈中与传输层无关的部分仅包含Function Code和Data字段。ModbusADU通过pdu[]视图提供对此核心协议数据的直接访问实现了 RTU 与 TCP 的逻辑统一pdu[0]恒为Function Codepdu[1]开始为Data字段的首字节pdu视图长度 getPduLen()getFunctionCode()对应的数据长度 1。data[]视图则进一步剥离了Function Code仅暴露纯数据区便于批量读写寄存器值。例如读取 3 个保持寄存器0x03的响应 PDU 为[0x03, 0x06, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06]则pdu[0] 0x03功能码pdu[1] 0x06字节数data[0] 0x01,data[1] 0x02, ...,data[5] 0x066 字节数据。这种分层视图设计使开发者能根据任务粒度选择最合适的操作接口调试时用rtu[]/tcp[]查看全帧协议解析用pdu[]寄存器操作用data[]。3. API 接口详解与工程实践ModbusADU的 API 设计遵循“最小接口、最大控制”原则所有方法均为内联inline无动态内存分配完全适配裸机或 RTOS 环境。以下按功能类别系统梳理核心 API并附带典型工程用例。3.1 构造与基础访问#include ModbusADU.h // 创建 ADU 对象静态分配无构造函数开销 ModbusADU adu; // RTU 视图索引 0 Unit ID索引 1 Function Code... uint8_t unit_id adu.rtu[0]; adu.rtu[1] 0x03; // 设置功能码为读保持寄存器 // TCP 视图索引 0 Transaction ID 高字节索引 1 低字节... adu.tcp[0] 0x12; // Transaction ID 高字节 adu.tcp[1] 0x34; // Transaction ID 低字节 // PDU 视图索引 0 Function Code索引 1 Data[0]... adu.pdu[0] 0x06; // 功能码写单个寄存器 adu.pdu[1] 0x00; // 起始地址高字节 adu.pdu[2] 0x01; // 起始地址低字节 adu.pdu[3] 0x00; // 写入值高字节 adu.pdu[4] 0xFF; // 写入值低字节 // Data 视图索引 0 Data[0]索引 1 Data[1]... adu.data[0] 0x00; // 起始地址高字节同 pdu[1] adu.data[1] 0x01; // 起始地址低字节同 pdu[2] adu.data[2] 0x00; // 写入值高字节同 pdu[3] adu.data[3] 0xFF; // 写入值低字节同 pdu[4]工程提示rtu[]、tcp[]、pdu[]、data[]是同一块内存的不同偏移视图修改任一视图均影响其他视图。例如adu.data[0] 0x00等价于adu.pdu[1] 0x00也等价于adu.tcp[70] 0x00TCP 模式下。3.2 ADU 字段设置与获取方法作用典型用例注意事项setTransactionId(uint16_t tid)/getTransactionId()设置/获取 TCP 事务 IDadu.setTransactionId(0x0001);RTU 模式下无效但调用无害setProtocolId(uint16_t pid)/getProtocolId()设置/获取 TCP 协议 ID恒为 0adu.setProtocolId(0);必须为 0否则非标准 TCP 帧setLength(uint16_t len)/getLength()设置/获取 TCP Length 字段值adu.setLength(6);// Unit ID FC Data 114仅 TCP 有效RTU 模式下getLength()返回 0setUnitId(uint8_t uid)/getUnitId()设置/获取 Unit IDadu.setUnitId(0x01);// 目标从站地址RTU/TCP 通用setFunctionCode(uint8_t fc)/getFunctionCode()设置/获取 Function Codeadu.setFunctionCode(0x03);RTU/TCP 通用setDataRegister(uint8_t index, uint16_t value)/getDataRegister(uint8_t index)以 16 位为单位读写 Data 区adu.setDataRegister(0, 0x1234);// data[0]0x12, data[1]0x34index为字节偏移非寄存器索引需手动处理大小端setDataRegister工程实践示例读取 2 个保持寄存器// 构造读保持寄存器请求FC0x03 adu.setFunctionCode(0x03); adu.setUnitId(0x01); // Data 区[起始地址高, 起始地址低, 寄存器数量高, 寄存器数量低] adu.setDataRegister(0, 0x0000); // 起始地址 0x0000 adu.setDataRegister(2, 0x0002); // 读取 2 个寄存器 // 计算 TCP Length: Unit ID(1) FC(1) Data(4) 6 adu.setLength(6); // 设置 TCP 头 adu.setTransactionId(0x0001); adu.setProtocolId(0); // 此时 tcp[] 数组已就绪可发送 uint8_t *frame adu.tcp; uint16_t frame_len 6 6; // MBAP 头(6) Length 字段值(6) HAL_UART_Transmit(huart1, frame, frame_len, HAL_MAX_DELAY);3.3 长度字段智能计算ModbusADU提供四组长度设置方法自动推导Length字段极大降低出错概率方法输入含义计算逻辑适用场景setRtuLen(uint16_t len)RTU 帧总长度含 Unit ID, FC, Data, CRCLength len - 2减去 CRCRTU 发送前已知完整帧长setTcpLen(uint16_t len)TCP 帧总长度含 MBAP 头 Unit ID FC DataLength len - 6减去 MBAP 头TCP 发送前已知完整帧长setPduLen(uint16_t len)PDU 长度FC DataLength lenTCP或N/ARTU协议解析后已知 PDU 长度setDataLen(uint16_t len)Data 长度Length 1 1 len len 2TCP构造请求时仅知数据长度工程对比示例// 场景向从站 0x01 写入 3 个保持寄存器FC0x10数据为 [0x0001, 0x0002, 0x0003] adu.setUnitId(0x01); adu.setFunctionCode(0x10); // 方式1已知 Data 长度6 字节 adu.setDataLen(6); // 自动设 Length 6 2 8 // 方式2已知 PDU 长度FCData 16 7 字节 adu.setPduLen(7); // TCP 模式下自动设 Length 7 // 方式3已知 TCP 帧总长MBAP头6 UnitID1 FC1 Data6 14 字节 adu.setTcpLen(14); // 自动设 Length 14 - 6 8 // 三种方式结果一致Length 83.4 CRC 校验与异常响应// 更新 RTU 帧的 CRC仅对 rtu[] 视图有效 adu.updateCrc(); // 自动计算 Unit ID 至 Data 末尾的 CRC并写入 rtu[rtu_len-2] 和 rtu[rtu_len-1] // 验证接收到的 RTU 帧 CRC 是否正确 if (adu.crcGood()) { // CRC 正确可安全解析 uint8_t fc adu.getFunctionCode(); if (fc 0x03) { // 解析保持寄存器数据 for (int i 0; i adu.getDataLen(); i 2) { uint16_t reg_val adu.getDataRegister(i); // 处理 reg_val... } } } else { // CRC 错误丢弃帧 } // 准备异常响应如从站收到非法功能码 adu.prepareExceptionResponse(0x01); // 异常码 0x01 Illegal Function // 此时 pdu[0] 0x83 (0x03 | 0x80), pdu[1] 0x01 // 可直接通过 UART 发送 rtu[] 视图关键细节prepareExceptionResponse(exceptionCode)会自动设置Function Code为原功能码OR 0x80并将Data[0]设为exceptionCode。例如对0x03请求的异常响应PDU 为[0x83, 0x01]。4. 在嵌入式系统中的集成实践ModbusADU的真正威力在于其与硬件驱动和 RTOS 的无缝集成。以下以 STM32 FreeRTOS HAL 库为例展示一个典型的从站数据收发循环。4.1 RTU 从站接收与响应流程// FreeRTOS 任务Modbus RTU 从站 void modbus_slave_task(void *argument) { ModbusADU adu; uint8_t rx_buffer[256]; uint16_t rx_len; uint32_t last_rx_time; while (1) { // 1. 等待 UART 接收完成使用 HAL_UART_Receive_IT 或 DMA if (HAL_UART_Receive(huart1, rx_buffer, sizeof(rx_buffer), 100) HAL_OK) { rx_len sizeof(rx_buffer); // 实际长度需由中断/DMA 回调确定 last_rx_time HAL_GetTick(); // 2. 将接收到的字节复制到 adu.rtu[] memcpy(adu.rtu, rx_buffer, rx_len); // 3. 验证 CRC if (adu.crcGood()) { uint8_t uid adu.getUnitId(); uint8_t fc adu.getFunctionCode(); // 4. 检查 Unit ID本从站地址 if (uid SLAVE_ADDRESS) { switch (fc) { case 0x03: // 读保持寄存器 handle_read_holding_registers(adu); break; case 0x10: // 写多个寄存器 handle_write_multiple_registers(adu); break; default: adu.prepareExceptionResponse(0x01); // Illegal Function } } else { // 地址不匹配忽略 continue; } // 5. 发送响应更新 CRC 后发送 adu.updateCrc(); HAL_UART_Transmit(huart1, adu.rtu, adu.getRtuLen(), HAL_MAX_DELAY); } } // 6. RTU 帧间静默检测3.5 字符时间 if (HAL_GetTick() - last_rx_time RTU_SILENCE_MS) { // 清空缓冲区准备下一帧 } osDelay(1); } } // 处理读保持寄存器请求 void handle_read_holding_registers(ModbusADU *adu) { uint16_t start_addr adu-getDataRegister(0); // Data[0-1] 起始地址 uint16_t reg_count adu-getDataRegister(2); // Data[2-3] 寄存器数量 // 7. 校验地址范围假设保持寄存器映射在 hreg_map[] if (start_addr reg_count HREG_COUNT) { adu-prepareExceptionResponse(0x02); // Illegal data address return; } // 8. 构造响应 PDU[FC, Byte Count, Data...] uint8_t byte_count reg_count * 2; adu-setFunctionCode(0x03); adu-data[0] byte_count; // Data[0] 字节数 // 9. 逐个写入寄存器值大端序 for (int i 0; i reg_count; i) { uint16_t val hreg_map[start_addr i]; adu-setDataRegister(1 i*2, val); // Data[1] 开始存放数据 } // 10. 设置 RTU 长度Unit ID FC Data CRC uint16_t rtu_len 1 1 1 byte_count 2; // 111byte_count2 adu-setRtuLen(rtu_len); }4.2 TCP 从站响应流程精简版// TCP 从站响应基于 LwIP socket void modbus_tcp_response(int sock, uint8_t *rx_frame, uint16_t rx_len) { ModbusADU adu; // 1. 复制 TCP 帧到 adu.tcp[] memcpy(adu.tcp, rx_frame, rx_len); // 2. 提取关键字段 uint16_t tid adu.getTransactionId(); uint8_t uid adu.getUnitId(); uint8_t fc adu.getFunctionCode(); // 3. 构造响应复用请求的 TID 和 UID adu.setTransactionId(tid); adu.setUnitId(uid); adu.setFunctionCode(fc); // 4. 填充响应数据同 RTU 逻辑 // ... (handle_read_holding_registers 逻辑) // 5. 设置 TCP Length uint16_t pdu_len adu.getPduLen(); // FC Data 长度 adu.setLength(pdu_len 1); // 1 for Unit ID // 6. 发送MBAP 头已由 tcp[] 视图包含 send(sock, adu.tcp, 6 adu.getLength(), 0); // 6MBAP头, getLength()后续字节数 }5. 常见问题与调试技巧5.1 典型错误场景与解决方案现象根本原因ModbusADU调试方法解决方案主站收不到响应Length字段计算错误TCP或CRC未更新RTU检查adu.getLength()或adu.getRtuLen()返回值用逻辑分析仪捕获实际发送帧使用setTcpLen()或setRtuLen()替代手动计算Length发送前必调adu.updateCrc()从站返回异常响应0x83 0x01功能码不支持、地址越界、数据值非法检查adu.getFunctionCode()和adu.getDataRegister()解析结果在handle_*函数中添加地址/值范围断言使用prepareExceptionResponse()明确返回错误Data 区数据错位setDataRegister(index, value)的index误解为寄存器索引而非字节索引打印adu.data[0],adu.data[1],adu.data[2]等观察实际字节index必须为偶数16 位对齐写入 N 个寄存器index步进为2*NTCP 帧被主站拒绝Protocol Identifier未设为0x0000或Transaction ID未回传检查adu.getProtocolId()和adu.getTransactionId()adu.setProtocolId(0);响应帧中adu.setTransactionId(request_tid);5.2 高效调试技巧内存视图法在调试器中将adu对象的内存地址添加为uint8_t[256]数组实时观察rtu[]、tcp[]、pdu[]视图的同步变化。CRC 交叉验证使用在线 CRC 计算器如 https://www.lammertbies.nl/comm/info/crc-calculation输入adu.rtu中Unit ID到Data末尾的字节比对结果与adu.rtu[rtu_len-2]和adu.rtu[rtu_len-1]。协议一致性检查利用 Wireshark 的 Modbus TCP 解析器或 Modbus Poll 工具捕获ModbusADU生成的帧验证 MBAP 头、PDU 结构是否符合标准。ModbusADU的设计哲学是让协议细节透明化而非隐藏。当一个adu.setFunctionCode(0x03)调用后在内存视图中清晰看到rtu[1]、tcp[7]、pdu[0]同时变为0x03这本身就是最有力的调试证据。