RTU_ALL_AI/docs/system/libmodbus_m/API-libmodbus_m.md

API-libmodbus_m — Modbus 主站管理模块

版本: v1.0
日期: 2026-07-08
来源: 原工程自研模块（科大智能）
状态: 导入完成，适配编译通过

---

1. 模块概述

libmodbus_m 是 RTU 通讯装置的 Modbus 主站管理模块，负责：

功能	说明
XML 配置解析	解析 modbus_m.xml 中的通道（TCP/RTU）和点表（ST/MX/CO/AO）
通道管理	TCP/RTU 多通道，自动连接/断开
轮询读取	按 (channel, slave, fc) 三元组分组，批量读取 Modbus 从站数据
异步写入	遥控/遥调通过写队列异步执行
数据发布	读取到的数据通过 dc_set_out_signal_val() 写入 datacenter

架构

modbus_m.xml → libxml(tinyxml2) 解析
    ↓
stru_modbus_m_cfg { channels, point }
    ↓
app_modbus_m() 主循环（独立线程）
    ├── 事件等待 (EV_TIMER1=轮询, EV_TIMER2/3=写队列)
    ├── poll_groups() — 按分组批量读取
    └── process_writes() — 异步写入
    ↓
libmodbus (modbus.h) — 实际 Modbus 协议收发
    ↓
libdatacenter (dc_set_out_signal_val) — 数据发布

---

2. 源文件结构

libmodbus_m/
├── inc/
│   ├── myModbusM.h     # 聚合入口
│   └── modbus_m.h      # 数据结构 + API 声明
└── src/
    └── modbus_m.cpp    # 实现 (~1000 行)

---

3. 核心数据结构

3.1 通讯通道配置

typedef struct {
    uint32_t id;              // 通道 ID
    std::string mode;         // "tcp" 或 "rtu"
    std::string host;         // TCP 目标 IP
    uint16_t port;            // TCP 目标端口
    std::string device;       // RTU 串口设备
    int baud;                 // RTU 波特率
    char parity;              // RTU 校验位
    int data_bit;             // RTU 数据位
    int stop_bit;             // RTU 停止位
    int timeout_ms;           // 请求超时
    int retry_cnt;            // 失败重试次数
    modbus_t *ctx;            // libmodbus 上下文
    bool connected;           // 连接状态
} stru_modbus_m_channel;

3.2 点表条目

typedef struct {
    uint16_t no;              // 序号
    uint8_t type;             // 2=bit, 4=uint16, 6=float32, 7=uint32, 13=string
    uint32_t channel;         // 归属通道 ID
    uint8_t slave;            // 从站地址
    uint8_t fc;               // 功能码
    uint16_t addr;            // 寄存器/线圈起始地址
    uint16_t count;           // 连续读取数量
    uint8_t bit;              // 位位置 (type=2 且 fc=03/04 时有效)
    float factor;             // 遥测系数
    float offset;             // 遥测偏移
    std::string saddr;        // datacenter 信号地址
    std::string desc;         // 描述
    void *p_val;              // 数据指针
} stru_modbus_m_item;

3.3 数据类型映射

type	datacenter 类型	说明
2	DATA_TYPE_B	位 / 线圈
4	DATA_TYPE_U16	uint16
6	DATA_TYPE_F32	float32（2 寄存器）
7	DATA_TYPE_U32	uint32（2 寄存器）
13	DATA_TYPE_STR	字符串

---

4. 公共 API

函数	说明
modbus_m_init()	初始化 Modbus 通道连接
modbus_m_cfg_parse(path)	解析 XML 配置文件
modbus_m_show_info()	打印配置信息
app_modbus_m_init1(arg)	应用初始化阶段 1（datacenter 注册后）
app_modbus_m_init2(arg)	应用初始化阶段 2
app_modbus_m(arg)	主循环（独立线程）

---

5. 依赖关系

libmodbus_m → libmodbus (myModbus.h)    — Modbus 协议收发
            → libxml (tinyxml2.h)        — XML 解析
            → libdatacenter (myDatacenter.h) — 数据发布
            → liblog (myLog.h)           — 日志
            → libfunc (myFunc.h)         — 进程路径
            → libcmd (myCmd.h)           — 调试命令注册
            → libtask (myTask.h)         — 事件等待
            → mySystem.h                 — stru_app 任务上下文

---

6. 适配说明

本项目对原工程代码做了以下适配（不修改核心逻辑）：

修改	原因
SIGNAL_CTRL_STEP → dc_ctrl_step_t	本项目 datacenter 的命名
SIGNAL_CTRL_TYPE → dc_ctrl_type_t	同上
DIRECT_NORMAL → DC_CTRL_DIRECT	同上
EV_TIMER1/2/3 → 0x01/0x02/0x04	原工程事件常量不兼容
func_get_process_self_dir → func_proc_self_dir	本项目 libfunc 的命名
dc_create_data_ptr_by_type → dc_create_data	本项目 datacenter 的命名
回调签名 std::string → const char*	本项目 datacenter 的接口
stru_app → src/system/inc/mySystem.h	任务上下文结构体