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)