258 lines
9.6 KiB
Markdown
258 lines
9.6 KiB
Markdown
# API-libiec — IEC 60870-5-104 服务端模块
|
||
|
||
> 版本: v1.0
|
||
> 日期: 2026-07-10
|
||
> 来源: 基于原工程 12 个 IEC 子文件聚合重构
|
||
> 状态: ✅ 已实现，x86 + ARM 双平台编译通过（零警告）
|
||
|
||
---
|
||
|
||
## 1. 模块概述
|
||
|
||
libiec 是 RTU 通讯装置的 **IEC 60870-5-104 服务端（从站）模块**，作为 X-Macro 框架的线程模块运行。通过 `com_router` 的 `bind_app="iec"` 机制接收 TCP :2404 端口的主站连接数据，底层协议栈复用 `lib60870` 自研库。
|
||
|
||
| 功能 | 说明 |
|
||
|------|------|
|
||
| IEC-104 从站协议 | 支持 CS101 / CS104 两种链路类型 |
|
||
| 并发连接管理 | 最多 3 路并发主站连接 (MAX_IEC_NUM=3)，槽位复用 |
|
||
| 超时回收 | 链路 600s 无活动自动回收 slot |
|
||
| XML 点表解析 | 从 `config/IEC60870/iec1014.xml` 解析 St/Mx/Co/Dd/Ao/Param 六类信号 |
|
||
| 数据中心桥接 | 信号变更回调自动写入 SOE/扰动遥测/故障/电度环形缓冲区 |
|
||
| 多主站分发 | 环形缓冲区多出指针 (out_ptrs)，每路连接独立消费位置 |
|
||
| MQ 桥接 | COM_TO_IEC / IEC_TO_COM 双队列，通过 com_router 转发 |
|
||
| 26 个 CS10x 回调 | 完整实现总召、遥测、遥控、电度、参数、定值、文件传输、扰动 |
|
||
|
||
### 架构
|
||
|
||
```
|
||
com_router (bind_app=iec)
|
||
│
|
||
▼ MQ_COM_TO_IEC
|
||
iec104_data_rx()
|
||
│
|
||
▼
|
||
CS10x_104Init / CS10x_DoRecv
|
||
│
|
||
▼ ┌──────────────────────────────────────────┐
|
||
│ │ 26 个回调 (protocol_register_callbacks) │
|
||
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||
│ │ │总召/遥信 │ │遥测/电度 │ │遥控/参数 │ │
|
||
│ │ │定值/对时 │ │故障/扰动 │ │文件传输 │ │
|
||
│ │ └──────────┘ └──────────┘ └──────────┘ │
|
||
│ └──────────────────────────────────────────┘
|
||
│
|
||
▼ MQ_IEC_TO_COM → com_router → TCP → 主站
|
||
```
|
||
|
||
### 与原工程对比
|
||
|
||
| 维度 | 原工程 (12 文件) | 重构后 (3 文件) |
|
||
|------|-----------------|-----------------|
|
||
| 文件数 | 12 | 3 (~75% 减少) |
|
||
| 代码行数 | ~2500+ | 1474 |
|
||
| 槽位管理 | 分散在多文件 | 统一 g_iec[MAX_IEC_NUM] |
|
||
| 环形缓冲区 | 5 个独立结构体 | 4 个模板化 ring_*_t (sem + out_ptrs) |
|
||
| 回调注册 | 分散初始化 | protocol_register_callbacks() 集中 |
|
||
| 命令支持 | 无 | CMD_REGISTER_C 测试命令 |
|
||
| EV_STOP | 无 | 支持优雅退出 |
|
||
|
||
---
|
||
|
||
## 2. 文件结构
|
||
|
||
```
|
||
src/system/libiec/
|
||
├── inc/
|
||
│ ├── iec104.h # 公共头: stru_iec, iec_soe_info_t, iec_yc_info_t, API 声明
|
||
│ └── iec104_cfg.h # 点表配置: stru_iec_sig, stru_iec_cfg
|
||
└── src/
|
||
├── iec104.cpp # CS10x 初始化 + slot 管理 + 26 回调 + 收发桥接 (1252行)
|
||
├── iec104_cfg.cpp # XML 点表解析 (148行)
|
||
└── iec104_point.cpp # 数据中心桥接 — 信号变更回调 → 环形缓冲区 (290行)
|
||
|
||
release/
|
||
└── {x86,arm}/lib/
|
||
└── libiec.a # 编译产物
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 核心数据结构
|
||
|
||
### 3.1 槽位结构 (`stru_iec`)
|
||
|
||
每路并发连接占用一个槽位，全局数组 `g_iec[MAX_IEC_NUM]` (MAX_IEC_NUM=3)：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `is_busy` | `uint8_t` | 槽位占用标志，0=空闲 |
|
||
| `iec_type` | `CS10x_Type` | CS104_TYPE_S / CS101_TYPE_S |
|
||
| `interface` | `uint32_t` | 通道唯一标识 (ch_id<<16 \| fd) |
|
||
| `tm_out` | `uint32_t` | 超时计数器 (ms)，超过 600s 自动回收 |
|
||
| `rx[IEC_BUF_SIZE]` | `uint8_t[1024]` | 接收缓冲区 |
|
||
| `tx[IEC_BUF_SIZE]` | `uint8_t[1024]` | 发送缓冲区 |
|
||
| `pub[IEC_BUF_SIZE]` | `uint8_t[1024]` | 自主上传缓冲区 (总召/扰动) |
|
||
| `bak[IEC_BUF_SIZE]` | `uint8_t[1024]` | 备用缓冲区 |
|
||
| `cs10x` | `CS10x` | lib60870 协议栈句柄 |
|
||
|
||
### 3.2 环形缓冲区
|
||
|
||
4 个环形缓冲区均带独立信号量 (sem_t) 和多出指针 (out_ptrs)，支持多主站并发消费：
|
||
|
||
| 缓冲区 | 容量 | 记录类型 | 用途 |
|
||
|--------|------|---------|------|
|
||
| `g_soe_ring` | 300 | SOE (时标+状态) | 遥信变位事件 |
|
||
| `g_yc_ring` | 200 | 扰动遥测 (idx+val) | 遥测越限扰动 |
|
||
| `g_fault_ring` | 200 | 故障 (SOE+遥测) | 故障录波事件 |
|
||
| `g_dd_ring` | 50 | 电度 (CP56Time2a+val) | 电度累计 |
|
||
|
||
### 3.3 点表配置 (`stru_iec_cfg`)
|
||
|
||
从 `config/IEC60870/iec1014.xml` 解析，6 类信号向量：
|
||
|
||
| 向量 | 信号类型 | IOA 起始 | 默认类型 |
|
||
|------|---------|---------|---------|
|
||
| `vec_st` | 遥信 (St) | 0x0001 | DATA_TYPE_U8 |
|
||
| `vec_mx` | 遥测 (Mx) | 0x4001 | DATA_TYPE_F32 |
|
||
| `vec_co` | 遥控 (Co) | — | DATA_TYPE_U8 |
|
||
| `vec_dd` | 电度 (Dd) | 0x6401 | DATA_TYPE_F32 |
|
||
| `vec_ao` | 参数 (Ao) | — | 无默认 (XML 必须指定) |
|
||
| `vec_param` | 定值 (Param) | — | 无默认 (XML 必须指定) |
|
||
|
||
每条信号 (`stru_iec_sig`) 含: `link` (数据中心路径), `desc` (描述), `inf` (IOA), `type` (数据类型), `invert` (遥信取反), `factor`/`offset` (遥测系数偏移), `p_data` (数据指针)。
|
||
|
||
---
|
||
|
||
## 4. API 参考
|
||
|
||
### 4.1 公共头 API (iec104.h)
|
||
|
||
| 函数 | 功能 | 参数 | 返回值 |
|
||
|------|------|------|--------|
|
||
| `iec104_get_by_interface()` | 按 interface 查找 IEC 实例 | `uint32_t interface` | `stru_iec *` 或 NULL |
|
||
| `iec104_data_rx()` | MQ 数据入口 (从 com_router 接收) | `uint8_t *msg` | 0=成功, -1=失败 |
|
||
| `iec104_task()` | 10ms 定时器处理 | `uint16_t gap` (恒10) | void |
|
||
|
||
### 4.2 线程入口
|
||
|
||
| 函数 | 功能 | 说明 |
|
||
|------|------|------|
|
||
| `app_iec_init1()` | 第一阶段初始化 | 解析 XML 点表 (`iec_cfg_parse`) |
|
||
| `app_iec_init2()` | 第二阶段初始化 | 注册数据中心回调 (`iec104_point_init`) |
|
||
| `app_iec()` | 主循环 | `while(1)` 收 MQ_COM_TO_IEC + 10ms 定时处理 |
|
||
|
||
### 4.3 点表 API (iec104_cfg.h)
|
||
|
||
| 函数 | 功能 | 参数 | 返回值 |
|
||
|------|------|------|--------|
|
||
| `iec_cfg_ptr_get()` | 获取全局配置指针 | void | `stru_iec_cfg *` |
|
||
| `iec_cfg_parse()` | 解析 XML 点表文件 | `const char *xml_path` | 0=成功, -1=失败 |
|
||
|
||
### 4.4 环形缓冲区回调 (iec104_point.cpp → iec104.cpp)
|
||
|
||
| 函数 | 功能 |
|
||
|------|------|
|
||
| `cb_soe_write()` | 写入 SOE 记录 (遥信变位) |
|
||
| `cb_yc_disturb_write()` | 写入扰动遥测记录 |
|
||
| `cb_dd_disturb_write()` | 写入电度记录 |
|
||
| `cb_fault_write()` | 写入故障事件记录 |
|
||
|
||
---
|
||
|
||
## 5. CS10x 回调清单 (26 个)
|
||
|
||
### 5.1 时间 & 初始化 (4)
|
||
|
||
| 回调 | 功能 | CS10x 注册 |
|
||
|------|------|-----------|
|
||
| `cb_get_time` | 获取当前时间 (CP56Time2a) | 时钟回调 |
|
||
| `cb_set_time` | 设置系统时间 (对时) | 时钟回调 |
|
||
| `cb_104init_callback` | 接收 CS104 初始化完成通知 | 104 专用 |
|
||
| `cb_tm_send_result` | 对时报文发送结果通知 | COI 回调 |
|
||
|
||
### 5.2 总召 (3)
|
||
|
||
| 回调 | 功能 |
|
||
|------|------|
|
||
| `cb_st` | 遥信总召 — 遍历 vec_st 打包 SQ=1 报文 |
|
||
| `cb_mx` | 遥测总召 — 遍历 vec_mx 打包浮点报文 |
|
||
| `cb_dd` | 电度总召 — 遍历 vec_dd 打包 CP56Time2a 报文 |
|
||
|
||
### 5.3 遥控 (5)
|
||
|
||
| 回调 | 功能 |
|
||
|------|------|
|
||
| `cb_yk_set` | 遥控选择/执行 — 遍历 vec_co 查找 IOA, 写入 datacenter |
|
||
| `cb_yk_confirm_func` | 遥控确认回调 |
|
||
| `cb_yk_termination_func` | 遥控终止回调 |
|
||
| `cb_yk_order_func` | 遥控命令通知 |
|
||
| `cb_yx_over_time_confirm_func` | 遥信超时确认 |
|
||
|
||
### 5.4 参数 & 定值 (4)
|
||
|
||
| 回调 | 功能 |
|
||
|------|------|
|
||
| `cb_param_get_func` | 参数 (Ao) 读取 — 遍历 vec_ao |
|
||
| `cb_param_set_func` | 参数 (Ao) 设置 — 写 datacenter |
|
||
| `cb_offset_get_func` | 定值 (Param) 读取 — 遍历 vec_param |
|
||
| `cb_offset_set_func` | 定值 (Param) 设置 — 写 datacenter |
|
||
|
||
### 5.5 扰动 & 故障 (5)
|
||
|
||
| 回调 | 功能 |
|
||
|------|------|
|
||
| `cb_dir_num` | 目录数量查询 |
|
||
| `cb_soe_ring_get_one` | 从 SOE 环形缓冲区读取一条 |
|
||
| `cb_yc_ring_get_one` | 从扰动遥测环形缓冲区读取一条 |
|
||
| `cb_fault_ring_get_one` | 从故障环形缓冲区读取一条 |
|
||
| `cb_dd_ring_get_one` | 从电度环形缓冲区读取一条 |
|
||
|
||
### 5.6 文件传输 (5)
|
||
|
||
| 回调 | 功能 |
|
||
|------|------|
|
||
| `cb_file_read` | 文件读回调 |
|
||
| `cb_file_write` | 文件写回调 |
|
||
| `cb_file_wr_finish` | 文件写入完成回调 |
|
||
| `cb_file_call_func` | 文件服务调用 |
|
||
| `cb_dir_num` | 目录服务 (与扰动共用) |
|
||
|
||
---
|
||
|
||
## 6. MQ 消息流
|
||
|
||
```
|
||
主站 → TCP :2404 → com_router (bind_app=iec)
|
||
→ MQ_COM_TO_IEC
|
||
→ app_iec() 主循环收
|
||
→ CS10x_DoRecv()
|
||
→ 对应回调 → datacenter
|
||
|
||
datacenter 信号变更 (St/Mx)
|
||
→ on_st_change / on_mx_change 回调
|
||
→ cb_soe_write / cb_yc_disturb_write → 环形缓冲区
|
||
|
||
总召/扰动触发:
|
||
→ iec104_data_tx() → MQ_IEC_TO_COM
|
||
→ com_router → TCP → 主站
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 配置依赖
|
||
|
||
| 配置文件 | 用途 |
|
||
|----------|------|
|
||
| `config/CHANNEL/channel_cfg.json` | TCP :2404 配置 `bind_app="iec"` |
|
||
| `config/IEC60870/iec1014.xml` | IEC 点表 (St/Mx/Co/Dd/Ao/Param) |
|
||
| `config/SYSTEM/app_config.json` | X-Macro 框架启停控制 |
|
||
|
||
---
|
||
|
||
## 8. 已知限制
|
||
|
||
- 扰动文件 (COMTRADE) 上传/下载: 回调已注册但无实际文件系统实现
|
||
- 遥控执行超时: 使用固定 30s 超时，不支持配置
|
||
- 缓冲区满: 环形缓冲写满后丢弃最早记录 (无 overflow 告警回调)
|
||
- 只有 IEC-104 从站模式，未实现主站模式 (CS10x_Type 预留 CS104_TYPE_M/CS101_TYPE_M)
|