RTU_ALL_AI/docs/protocol/lib60870/API-lib60870.md

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，包含：

// 回调函数表（核心架构）
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 字节时标）

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 是自包含库：

• 不包含 <myBase.h> 或 <myLog.h>
• 通过函数指针回调与上层交互
• 本项目通过 cbb_compat.h 提供 u8/u16/u32/f32/BOOL 类型别名

---

6. 构建注意事项

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 替代