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