From 7b1bbba325b65fa61440853ddeb0bae48ef376a2 Mon Sep 17 00:00:00 2001 From: ypc <15051963820@163.com> Date: Wed, 8 Jul 2026 15:45:57 +0800 Subject: [PATCH] =?UTF-8?q?docs(lib60870):=20API=20=E5=8F=82=E8=80=83?= =?UTF-8?q?=E6=96=87=E6=A1=A3=20+=20=E8=BF=9B=E5=BA=A6=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - API-lib60870.md: 模块概述/源文件结构/核心数据结构/API/依赖关系/代码审查 - COMPLETION.md: lib60870 标记完成 --- COMPLETION.md | 2 +- docs/protocol/lib60870/API-lib60870.md | 159 +++++++++++++++++++++++++ 2 files changed, 160 insertions(+), 1 deletion(-) create mode 100644 docs/protocol/lib60870/API-lib60870.md diff --git a/COMPLETION.md b/COMPLETION.md index 30eb8fd..c8b6898 100644 --- a/COMPLETION.md +++ b/COMPLETION.md @@ -36,7 +36,7 @@ | 通讯抽象层 | `libcomm` | ✅ | | 通讯抽象层测试 | `test_comm.cpp`（17项全通过） | ✅ | | Modbus 协议栈 | `libmodbus`（开源库 v3.1.12，导入+日志适配） | ✅ | -| IEC 60870-5-104 | `lib60870` | ⬜ | +| IEC 60870-5-104 | `lib60870`（原工程自研协议栈，导入） | ✅ | | IEC 点表解析 | `libiec` | ⬜ | | Modbus 主站管理 | `libmodbus_m` | ⬜ | | 通讯通道解码 | `libcom_decode` | ⬜ | diff --git a/docs/protocol/lib60870/API-lib60870.md b/docs/protocol/lib60870/API-lib60870.md new file mode 100644 index 0000000..69be7a6 --- /dev/null +++ b/docs/protocol/lib60870/API-lib60870.md @@ -0,0 +1,159 @@ +# API-lib60870 — IEC 60870-5 协议栈模块 + +> 版本: v1.0 +> 日期: 2026-07-08 +> 来源: 原工程自研协议栈（科大智能，2022） +> 状态: 导入完成（专有代码，未重构） + +--- + +## 1. 模块概述 + +lib60870 是 RTU 通讯装置的 **IEC 60870-5 协议栈**，支持三种子协议： + +| 协议 | GB 标准 | 说明 | +|------|------|------| +| IEC 60870-5-101 | GB/T 18657.5 | 串行链路（RS-232 / RS-485），平衡/非平衡模式 | +| IEC 60870-5-103 | GB/T 14598.3 | 保护设备信息接口，继电保护通讯 | +| IEC 60870-5-104 | GB/T 18657.6 | 网络访问（TCP/IP），RTU 最常见的上行协议 | + +### 设计思想 + +- **回调驱动架构**：协议栈通过函数指针回调与上层交互（CS10xHandle_t 包含 30+ 回调函数） +- **独立线程运行**：每个协议链路在独立线程中运行 `CS104_RunTask()` / `CS101_RunTask()` +- **ASDU 编解码**：`Asdu.c` 提供 30+ 种 ASDU 类型的编解码函数 + +--- + +## 2. 源文件结构 + +``` +lib60870/ +├── inc/ +│ ├── myIec60870.h # 聚合入口（本项目新增） +│ ├── lib60870_common.h # 公共数据结构 + 回调函数表（2000+ 行） +│ ├── lib60870_public.h # 任务管理、校验、CP56Time2a +│ ├── lib60870_process.h # 协议处理主流程 +│ ├── lib60870_inc.h # 内部宏（LOBYTE/HIBYTE/IEC_PRINT） +│ ├── Asdu.h # ASDU 域编解码 +│ ├── gb104.h # IEC 104 帧处理（I/S/U 帧） +│ ├── gb101.h # IEC 101 帧处理 +│ ├── gb103.h # IEC 103 帧处理 +│ ├── md5.h # MD5 辅助 +│ └── cbb_compat.h # u8/u16/u32 类型别名（本项目新增） +└── src/ + ├── lib60870_common.c # 公共函数实现 + ├── lib60870_public.c # 任务管理 + 校验 + ├── lib60870_process.c # 协议流程 + ├── Asdu.c # ASDU 编解码 + ├── gb104.c # IEC 104 实现（~4000 行） + ├── gb101.c # IEC 101 实现 + ├── gb103.c # IEC 103 实现 + └── md5.c # MD5 实现 +``` + +--- + +## 3. 核心数据结构 + +### 3.1 CS10xHandle_t（协议上下文句柄） + +不透明句柄，指向 `struct CS10x_t`，包含： + +```c +// 回调函数表（核心架构） +CS10x_GetTime cb_get_time; // 获取设备时间 +CS10x_SetTime cb_set_time; // 对时 +CS10x_SetValue cb_set_value; // 遥控/遥调执行 +CS10x_YkVerify cb_yk_verify; // 遥控返校 +CS10x_GetYcCountByGroup cb_get_yc_count; // 按组获取遥测数量 +CS10x_GetYcValueByGroup cb_get_yc_value; // 按组获取遥测值 +CS10x_SendSoeEnent cb_send_soe; // SOE 事件上报 +CS10x_SendDiturbYc cb_send_disturb_yc; // 扰动遥测 +CS10x_CheckParamRWSt cb_param_rw; // 定值读写 +CS10x_CheckFileTransferSt cb_file_transfer; // 文件传输 +// ... 30+ 回调函数 +``` + +### 3.2 104 帧格式 + +``` +启动字符 0x68 +APDU 长度（1 字节，≤ 253） +控制域 (I/S/U 帧) ++ ASDU（应用服务数据单元） +``` + +| 帧类型 | 说明 | +|------|------| +| I 帧 | 信息传输（ASDU 数据） | +| S 帧 | 编号监视（确认） | +| U 帧 | 控制功能（STARTDT/STOPDT/TESTFR） | + +### 3.3 CP56Time2a（7 字节时标） + +```c +typedef struct { + unsigned char hour; // 时 + unsigned char min; // 分 + unsigned short ms; // 毫秒 + unsigned char day; // 日 + unsigned char month; // 月 + unsigned char year; // 年（低 7 位） +} __CP56Time2a; +``` + +--- + +## 4. 公共 API（lib60870_public.h 导出） + +| 函数 | 说明 | +|------|------| +| `CS10x_SendTask(handle)` | 发送任务调度 | +| `SetSendTask(handle, flag, low, hig)` | 设置发送任务标志 | +| `SetTaskFlag/ClearTaskFlag/GetTaskFlag` | 任务标志位操作 | +| `CP56Time2a_Pack2Buf/GetFromBuf` | 7 字节时标编解码 | +| `IntBytes_Pack2Buf/GetFromBuf` | 多字节整数编解码 | +| `Float_Pack2Buf/GetFromBuf` | 浮点数编解码 | +| `U16_Pack2Buf/GetFromBuf` | uint16 编解码 | +| `checksum_8(buf, len)` | 8 位校验和 | +| `CheckParamTagAndLen(tag, len)` | 参数标记与长度校验 | + +--- + +## 5. 依赖关系 + +``` +lib60870 → (运行时回调接入 libdatacenter) + → (无编译时依赖，自包含) +``` + +lib60870 是自包含库： +- 不包含 `` 或 `` +- 通过函数指针回调与上层交互 +- 本项目通过 `cbb_compat.h` 提供 `u8/u16/u32/f32/BOOL` 类型别名 + +--- + +## 6. 构建注意事项 + +**makefile** 添加两条特殊编译选项： + +```makefile +F += -include cbb_compat.h # 注入 u8/u16/u32 类型定义 +F += -Wno-implicit-function-declaration # gb103.c 存在跨文件函数声明 +``` + +这两处是原工程代码的已知问题，本项目不修改源文件，通过编译选项规避。 + +--- + +## 7. 代码审查要点 + +| 项 | 状态 | 说明 | +|------|:--:|------| +| 来源 | 科大智能 | 原工程自研协议栈 | +| 代码规模 | ~16K 行 | 8 个头文件 + 8 个源文件 | +| 架构 | 回调驱动 | 30+ 函数指针回调，独立线程 | +| 103 协议 | 部分未实现 | gb103.c 中 CS103_CmdFixedData/CS103_CmdYK 等函数引用缺失 | +| 类型别名 | 外部依赖 | 原工程依赖 ostype.h，本项目用 cbb_compat.h 替代 |