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，导入+日志适配） | ✅ |
|
||||
| IEC 60870-5-104 | `lib60870`（原工程自研协议栈，导入） | ✅ |
|
||||
| IEC 点表解析 | `libiec` | ⬜ |
|
||||
| Modbus 主站管理 | `libmodbus_m` | ⬜ |
|
||||
| Modbus 主站管理 | `libmodbus_m`（原工程自研模块，导入+适配） | ✅ |
|
||||
| 通讯通道解码 | `libcom_decode` | ⬜ |
|
||||
| Web 管理服务 | `libweb_server` | ⬜ |
|
||||
| 主程序入口 | `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