docs(lib60870): API 参考文档 + 进度更新
- API-lib60870.md: 模块概述/源文件结构/核心数据结构/API/依赖关系/代码审查 - COMPLETION.md: lib60870 标记完成
This commit is contained in:
parent
a0b85f4bba
commit
7b1bbba325
|
|
@ -36,7 +36,7 @@
|
||||||
| 通讯抽象层 | `libcomm` | ✅ |
|
| 通讯抽象层 | `libcomm` | ✅ |
|
||||||
| 通讯抽象层测试 | `test_comm.cpp`（17项全通过） | ✅ |
|
| 通讯抽象层测试 | `test_comm.cpp`（17项全通过） | ✅ |
|
||||||
| Modbus 协议栈 | `libmodbus`（开源库 v3.1.12，导入+日志适配） | ✅ |
|
| Modbus 协议栈 | `libmodbus`（开源库 v3.1.12，导入+日志适配） | ✅ |
|
||||||
| IEC 60870-5-104 | `lib60870` | ⬜ |
|
| IEC 60870-5-104 | `lib60870`（原工程自研协议栈，导入） | ✅ |
|
||||||
| IEC 点表解析 | `libiec` | ⬜ |
|
| IEC 点表解析 | `libiec` | ⬜ |
|
||||||
| Modbus 主站管理 | `libmodbus_m` | ⬜ |
|
| Modbus 主站管理 | `libmodbus_m` | ⬜ |
|
||||||
| 通讯通道解码 | `libcom_decode` | ⬜ |
|
| 通讯通道解码 | `libcom_decode` | ⬜ |
|
||||||
|
|
|
||||||
|
|
@ -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 是自包含库：
|
||||||
|
- 不包含 `<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 替代 |
|
||||||
Loading…
Reference in New Issue