docs(libmodbus_m): API 参考文档 + 进度更新
- API-libmodbus_m.md: 模块概述/数据结构/API/依赖/适配说明 - COMPLETION.md: libmodbus_m 标记完成
This commit is contained in:
parent
78d48e537e
commit
854319a500
|
|
@ -38,7 +38,7 @@
|
||||||
| Modbus 协议栈 | `libmodbus`（开源库 v3.1.12，导入+日志适配） | ✅ |
|
| Modbus 协议栈 | `libmodbus`（开源库 v3.1.12，导入+日志适配） | ✅ |
|
||||||
| IEC 60870-5-104 | `lib60870`（原工程自研协议栈，导入） | ✅ |
|
| IEC 60870-5-104 | `lib60870`（原工程自研协议栈，导入） | ✅ |
|
||||||
| IEC 点表解析 | `libiec` | ⬜ |
|
| IEC 点表解析 | `libiec` | ⬜ |
|
||||||
| Modbus 主站管理 | `libmodbus_m` | ⬜ |
|
| Modbus 主站管理 | `libmodbus_m`（原工程自研模块，导入+适配） | ✅ |
|
||||||
| 通讯通道解码 | `libcom_decode` | ⬜ |
|
| 通讯通道解码 | `libcom_decode` | ⬜ |
|
||||||
| Web 管理服务 | `libweb_server` | ⬜ |
|
| Web 管理服务 | `libweb_server` | ⬜ |
|
||||||
| 主程序入口 | `RTU` | ⬜ |
|
| 主程序入口 | `RTU` | ⬜ |
|
||||||
|
|
|
||||||
|
|
@ -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` | 任务上下文结构体 |
|
||||||
Loading…
Reference in New Issue