From 854319a500ff07662510ba6251b49c3023f52bcc Mon Sep 17 00:00:00 2001
From: ypc <15051963820@163.com>
Date: Wed, 8 Jul 2026 16:00:24 +0800
Subject: [PATCH] =?UTF-8?q?docs(libmodbus=5Fm):=20API=20=E5=8F=82=E8=80=83?=
 =?UTF-8?q?=E6=96=87=E6=A1=A3=20+=20=E8=BF=9B=E5=BA=A6=E6=9B=B4=E6=96=B0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- API-libmodbus_m.md: 模块概述/数据结构/API/依赖/适配说明
- COMPLETION.md: libmodbus_m 标记完成
---
 COMPLETION.md                              |   2 +-
 docs/system/libmodbus_m/API-libmodbus_m.md | 149 +++++++++++++++++++++
 2 files changed, 150 insertions(+), 1 deletion(-)
 create mode 100644 docs/system/libmodbus_m/API-libmodbus_m.md

diff --git a/COMPLETION.md b/COMPLETION.md
index c8b6898..0a003e3 100644
--- a/COMPLETION.md
+++ b/COMPLETION.md
@@ -38,7 +38,7 @@
 | Modbus 协议栈 | `libmodbus`（开源库 v3.1.12，导入+日志适配） | ✅ |
 | IEC 60870-5-104 | `lib60870`（原工程自研协议栈，导入） | ✅ |
 | IEC 点表解析 | `libiec` | ⬜ |
-| Modbus 主站管理 | `libmodbus_m` | ⬜ |
+| Modbus 主站管理 | `libmodbus_m`（原工程自研模块，导入+适配） | ✅ |
 | 通讯通道解码 | `libcom_decode` | ⬜ |
 | Web 管理服务 | `libweb_server` | ⬜ |
 | 主程序入口 | `RTU` | ⬜ |
diff --git a/docs/system/libmodbus_m/API-libmodbus_m.md b/docs/system/libmodbus_m/API-libmodbus_m.md
new file mode 100644
index 0000000..05a7b57
--- /dev/null
+++ b/docs/system/libmodbus_m/API-libmodbus_m.md
@@ -0,0 +1,149 @@
+# 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 通讯通道配置
+
+```c
+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 点表条目
+
+```c
+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` | 任务上下文结构体 |