160 lines
5.3 KiB
Markdown
160 lines
5.3 KiB
Markdown
# 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 是自包含库：
|
||
- 不包含 `<myBase.h>` 或 `<myLog.h>`
|
||
- 通过函数指针回调与上层交互
|
||
- 本项目通过 `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 替代 |
|