# 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` | 任务上下文结构体 |