693 lines
27 KiB
Markdown
693 lines
27 KiB
Markdown
# lib60870 CBB 库详细解析
|
||
|
||
> **库版本**: IECVer2.01.059_260202 (2026-02-02)
|
||
> **厂家**: 科大智能电气有限公司 (2013-2026)
|
||
> **用途**: IEC 60870-5-101 / 60870-5-104 / 60870-5-103 电力远动规约协议栈
|
||
> **源码路径**: [src/protocol/lib60870/](../../src/protocol/lib60870/)
|
||
> **编译兼容头**: [cbb_compat.h](../../release/inc/cbb_compat.h) (通过 gcc `-include` 注入，不修改库文件)
|
||
|
||
---
|
||
|
||
## 1. 模块总览
|
||
|
||
### 1.1 文件清单
|
||
|
||
```
|
||
src/protocol/lib60870/
|
||
├── ChangeList.md # 版本变更记录 (V2.01.035 → V2.01.059)
|
||
├── 规约参数说明.md # 参数配置字典 (必读)
|
||
├── 规约库默认参数.md # 初始化的默认值
|
||
├── inc/ # 头文件目录
|
||
│ ├── lib60870_inc.h # 基础包含 (stdint/stdio) + 字节序宏
|
||
│ ├── lib60870_common.h # ★ 核心头文件: CS10x 结构体 + 全部 API 声明 + 常量
|
||
│ ├── lib60870_public.h # 公共工具: TaskFlag/checksum/CP56Time 编解码
|
||
│ ├── lib60870_process.h # 公共流程: SOE/故障/扰动检查与调度
|
||
│ ├── Asdu.h # ASDU 数据域解析: 品质描述词 + 发送/解码函数
|
||
│ ├── gb101.h # ★ IEC 101 链路层: 帧编解码/重发/链路状态
|
||
│ ├── gb104.h # ★ IEC 104 APCI 层: I/S/U帧/计时器
|
||
│ ├── gb103.h # IEC 103 规约: 保护通信/通用分类服务
|
||
│ └── md5.h # MD5 校验
|
||
└── src/ # 源文件目录
|
||
├── lib60870_common.c # CS10x 公共接口实现 + 回调注册
|
||
├── lib60870_public.c # 工具函数实现
|
||
├── lib60870_process.c # 公共流程实现
|
||
├── Asdu.c # ASDU 编解码 + 业务数据发送
|
||
├── gb101.c # 101 链路层实现
|
||
├── gb104.c # 104 APCI 层实现
|
||
├── gb103.c # 103 规约实现
|
||
└── md5.c # MD5 实现
|
||
```
|
||
|
||
### 1.2 头文件依赖关系
|
||
|
||
```mermaid
|
||
graph TD
|
||
A[lib60870_inc.h] --> B[lib60870_common.h]
|
||
B --> C[lib60870_public.h]
|
||
B --> D[lib60870_process.h]
|
||
B --> E[Asdu.h]
|
||
B --> F[gb101.h]
|
||
B --> G[gb104.h]
|
||
B --> H[gb103.h]
|
||
C --> E
|
||
D --> E
|
||
E --> F
|
||
E --> G
|
||
```
|
||
|
||
`lib60870_common.h` 是所有模块的**单一依赖入口**。外部只需 `#include "lib60870_common.h"` 即可获得全部类型和 API。
|
||
|
||
---
|
||
|
||
## 2. 核心数据结构
|
||
|
||
### 2.1 协议类型枚举 `CS10x_Type`
|
||
|
||
```c
|
||
typedef enum {
|
||
CS101_TYPE_S = 0, // CS101 从站 (被控站/终端)
|
||
CS101_TYPE_M, // CS101 主站
|
||
CS104_TYPE_S, // CS104 从站 (被控站/终端)
|
||
CS104_TYPE_M, // CS104 主站
|
||
} CS10x_Type;
|
||
```
|
||
|
||
**理解要点**：
|
||
- `_S` = slave/从站 = 终端侧 = **本项目 RTU 使用的模式**
|
||
- `_M` = master/主站 = 调度侧
|
||
- 101 和 104 共用同一个 `CS10x` 结构体，通过类型枚举区分行为
|
||
|
||
### 2.2 核心结构体 `CS10x`（约 300 行，[源码](src/protocol/lib60870/inc/lib60870_common.h#L1300-L1599)）
|
||
|
||
```c
|
||
struct CS10x_t { ... } CS10x; // 结构体定义 + typedef
|
||
typedef struct CS10x_t *CS10xHandle_t; // 句柄指针
|
||
```
|
||
|
||
**关键成员分类**：
|
||
|
||
| 分类 | 成员 | 说明 |
|
||
|------|------|------|
|
||
| **协议标识** | `CS10x_Type eCS10x_Type` | 当前协议类型 (101/104 + 主/从) |
|
||
| **101 链路** | `ucAddr`, `ucReSend_Num`, `usReSend_Gap` | 链路地址、重发次数、重发间隔 |
|
||
| | `uc101InitFlag`, `uc101LinkState` | 101 链路初始化状态 |
|
||
| | `CONTROL101 stControl101Up/Down` | 101 控制域位域 |
|
||
| **104 链路** | `usSendNum/usRecvNum`, `usAckSendNum/usAckRecvNum` | 104 发送/接收序号 |
|
||
| | `VIec104Timer stM_vTimer[4]` | T0/T1/T2/T3 定时器 |
|
||
| **数据缓冲** | `VCommBuf stRecvBuf/SendBuf` | 接收/发送环形缓冲区 |
|
||
| **ASDU 参数** | `CS10x_AppLayerParameters stParam` | ASDU 字节长度配置 |
|
||
| | `CS104_APCIParameters st104Param` | 104 K/W/T 参数 |
|
||
| **任务标志** | `VFLAGS stTaskFlags` | 128 位任务位图 |
|
||
| **回调函数** | `pfnSend`, `pfnGetTime`, `pfnSetTime` | ★ 核心回调接口（见 3.1） |
|
||
| | `pfnGetYcCountByGroup` / `pfnGetYcValueByGroup` | 遥测回调 |
|
||
| | `pfnGetYxCountByGroup` / `pfnGetYxStatusByGroup` | 遥信回调 |
|
||
| | `pfnGetSOE` / `pfnUpdata_SOE_Pout` / `pfnGetSOE_SendNum` | SOE 回调 |
|
||
| | `pfnGetFaultEvent` / `pfnUpdata_FaultEvent_Pout` | 故障事件回调 |
|
||
| | `pfnFcYkVerify` | 遥控校验回调 |
|
||
| | `pfnGetDdCountByGroup` / `pfnGetDdValueByGroup` | 电度回调 |
|
||
| | `pfnGetDiturbYc` / `pfnGetTimeDdu` | 扰动遥测/电度时标回调 |
|
||
| **参数读写** | `pfnGetParamArea` / `pfnSetParamArea` | 定值区切换 |
|
||
| | `pfnAddIECParam` / `pfnRunReadIECParam` / `pfnRunWriteIECParam` | 参数读写 |
|
||
| | `pfnGetParamCount` / `pfnGetParamInfoByIndx` | 参数信息查询 |
|
||
| **文件传输** | `pfnGetProDirFile` / `pfnReadFile` / `pfnWrite` 等 | 文件服务回调（*已废弃旧接口，新接口为 `CS10x_S_FileReadOprtHandler`*） |
|
||
| **软件升级** | `pfnOnlineProg` / `pfnUpdateOprt` | 在线升级回调 |
|
||
| **配置参数** | `usYcType(0/1/2)` / `usYxType(0/1)` / `usDdType(0/1)` | 数据类型选择 |
|
||
| | `ucSOEEn`, `ucCOSEn`, `ucYkEndFrameEn` | SOE/COS/遥控结束帧使能 |
|
||
| | `ucMutilFrameEn` | 104 多帧发送使能 |
|
||
| | `ulSummon_Gap`, `ulHeart_Gap`, `ulSyn_Gap` | 定时器间隔(ms) |
|
||
| | `ucInitType`, `ucFileAckType` | 初始化类型/文件确认类型 |
|
||
|
||
### 2.3 ASDU 信息体数据结构
|
||
|
||
```c
|
||
// 遥信—库发出给应用层填充数据
|
||
typedef struct {
|
||
unsigned int uiInfoAddr; // 信息体地址 (点号)
|
||
unsigned char ucStatus; // 状态 (0=分/1=合)
|
||
unsigned char ucStateType; // 0=单点 / 1=双点
|
||
} Yx_Info;
|
||
|
||
// 遥测—库发出给应用层填充数据
|
||
typedef struct {
|
||
unsigned int uiInfoAddr; // 信息体地址
|
||
float fVal; // 遥测值 (浮点)
|
||
unsigned char ucQds; // 品质描述词
|
||
} Yc_Info;
|
||
|
||
// SOE—事件顺序记录
|
||
typedef struct {
|
||
unsigned int uiInfoAddr; // 信息体地址
|
||
unsigned char ucStatus; // 状态
|
||
unsigned char ucStateType; // 单点/双点
|
||
__CP56Time2a stCTime; // 时标 (7字节 CP56 格式)
|
||
} SOE_Info;
|
||
|
||
// 遥控—库传递给应用层校验
|
||
typedef struct {
|
||
unsigned int uiInfoAddr; // 信息体地址
|
||
unsigned char ucStatus; // 命令值 (0=分/1=合)
|
||
unsigned char ucStateType; // 单点遥控/双点遥控
|
||
unsigned char ucYkType; // 选择/执行
|
||
} Yk_Info;
|
||
|
||
// 电度
|
||
typedef struct { unsigned int uiInfoAddr; float fVal; } Dd_Info;
|
||
|
||
// 带时标电度
|
||
typedef struct { unsigned int uiInfoAddr; float fVal; __CP56Time2a stCTime; } TimeDd_Info;
|
||
|
||
// 故障事件
|
||
typedef struct {
|
||
unsigned short usSoeNum;
|
||
SOE_Info staSoe[MAX_FAULT_EVENT_SOE_SIZE];
|
||
unsigned short usYcNum;
|
||
Yc_Info staYc[MAX_FAULT_EVENT_YC_SIZE];
|
||
} FAULT_EVENT_Info;
|
||
|
||
// 参数/定值
|
||
typedef struct {
|
||
unsigned char ucType; // TAG_TYPE_xxx
|
||
unsigned char ucLen; // 数据长度
|
||
union { ... } unVal; // 值 (支持多种类型)
|
||
unsigned int uiInfoAddr; // 信息体地址
|
||
} IECPARAM_T;
|
||
```
|
||
|
||
### 2.4 CP56Time2a 时间格式
|
||
|
||
```c
|
||
typedef struct {
|
||
unsigned char ucLMs; // 毫秒低位
|
||
unsigned char ucHMs; // 毫秒高位 (含 IV 标志位)
|
||
unsigned char ucMin; // 分钟 (含 IV 标志)
|
||
unsigned char ucHour; // 小时 (含 SU 夏令时标志)
|
||
unsigned char ucWeek; // 星期 (0=未用)
|
||
unsigned char ucMonth; // 月
|
||
unsigned char ucYear; // 年 (0-99)
|
||
} __CP56Time2a;
|
||
|
||
// 编解码工具函数
|
||
unsigned char CP56Time2a_Pack2Buf(unsigned char *out, const __CP56Time2a *cp56);
|
||
unsigned char CP56Time2a_GetFromBuf(const unsigned char *in, __CP56Time2a *cp56);
|
||
```
|
||
|
||
### 2.5 帧格式定义
|
||
|
||
```c
|
||
// 104 帧
|
||
typedef struct {
|
||
unsigned char byStartCode; // 0x68
|
||
unsigned char byAPDULen; // APDU 长度
|
||
unsigned char byControl1..4; // 控制域 (4字节)
|
||
unsigned char byASDU[249]; // ASDU 数据
|
||
} VIec104Frame;
|
||
|
||
// 101 帧—联合体：短帧(单字节地址/双字节地址) / 长帧
|
||
typedef union {
|
||
VFrame10 stFrame10; // 双字节地址短帧
|
||
VFrame10_S stFrame10_S; // 单字节地址短帧
|
||
VFrame68 stFrame68; // 长帧
|
||
} VIec101Frame;
|
||
```
|
||
|
||
---
|
||
|
||
## 3. API 体系
|
||
|
||
### 3.1 生命周期 API（必须调用）
|
||
|
||
| 函数 | 说明 |
|
||
|------|------|
|
||
| **`CS10x_101Init(pstSelf, cbSend, arg, CS101_TYPE_S/M)`** | ★ 101 从站初始化 |
|
||
| **`CS10x_104Init(pstSelf, cbSend, arg, CS104_TYPE_S/M)`** | ★ 104 从站初始化 |
|
||
| **`CS10x_DoRecv(pstSelf, pBuf, usLen)`** | ★ 接收数据入口 (每收到一包调用一次) |
|
||
| **`CS10x_TimerHandle(pstSelf, usGap)`** | ★ 定时器驱动入口 (每 usGap ms 调用一次) |
|
||
|
||
> `cbSend` 类型: `int (*)(unsigned char *buf, unsigned short len, void *arg)`
|
||
> 库通过此回调将编码好的报文交给应用层发送。
|
||
|
||
### 3.2 参数配置 API（初始化后、运行前调用）
|
||
|
||
```c
|
||
// ★ 核心 ASDU 参数
|
||
void CS10x_SetAppParameters(CS10xHandle_t pstSelf, CS10x_AppLayerParameters *param);
|
||
// → 链路地址字节数(1-2)、传输原因字节数(1-2)、公共地址字节数(1-2)、
|
||
// 信息体地址字节数(2-3)、链路地址、公共地址
|
||
|
||
// ★ 104 APCI 参数
|
||
void CS10x_SetAPCIParameters(CS10xHandle_t pstSelf, CS104_APCIParameters *param);
|
||
// → K(0-600)、W(1-60)、T0/T1/T2/T3(2-120s)
|
||
|
||
// 数据类型
|
||
void CS10x_SetYcType(pstSelf, usType); // 0=整形 1=标度化 2=浮点
|
||
void CS10x_SetYxType(pstSelf, usType); // 0=单点 1=双点
|
||
void CS10x_SetDdType(pstSelf, usType); // 0=不带时标 1=带时标
|
||
|
||
// 时间间隔 (ms)
|
||
void CS10x_SetSummonGap(pstSelf, uiGap); // 总召间隔 (默认300s)
|
||
void CS10x_SetESummonGap(pstSelf, uiGap); // 电度总召间隔 (默认60s)
|
||
void CS10x_SetHeartTimeGap(pstSelf, uiGap); // 心跳间隔 (默认90s)
|
||
void CS10x_FrameGap(pstSelf, uiGap); // 发送帧间隔 (默认100ms)
|
||
|
||
// 101 特殊
|
||
void CS10x_ResendGap(pstSelf, uiGap); // 重发超时 (默认5s)
|
||
void CS10x_ResendCnt(pstSelf, ucCnt); // 重发次数 (默认5)
|
||
void CS10x_SetInitType(pstSelf, bType); // 简单初始化投退 (1=投入)
|
||
void CS10x_SetFileAckType(pstSelf, ucType); // 文件需确认帧 (0=需要, 1=不需要)
|
||
|
||
// 功能使能
|
||
void CS10x_SetMultFrameEn(pstSelf, ucEn); // 104 多帧发送 (0=关闭 1=开启)
|
||
void CS10x_FaultEventEn(pstSelf, ucEn); // 故障事件 (0=关, 1/2/3=开)
|
||
void CS10x_SetSendSoe(pstSelf, ucEn); // SOE 发送 (0/1)
|
||
void CS10x_SetSendCos(pstSelf, ucEn); // COS 发送 (0/1)
|
||
void CS10x_SetYKEendFrame(pstSelf, ucEn); // 遥控结束帧 (0/1)
|
||
void CS10x_SetReadFileVSQ(pstSelf, ucEn); // 文件传输VSQ状态值
|
||
void CS10x_SetPresetContType(pstSelf, ucEn); // 参数预置忽略后续帧 (淮北主站=1)
|
||
```
|
||
|
||
### 3.3 回调注册 API（按业务域分组）
|
||
|
||
> **约定**: 以 `CS10x_S_` 为前缀的新接口是**推荐使用**的从站回调注册 API。旧的无前缀接口（如 `CS10x_GetYcValueByGroupHandler`）已标记为"待删除"。
|
||
|
||
```c
|
||
// ===== 遥测 (YC) =====
|
||
void CS10x_S_GetYcByGroupHandler(pstSelf,
|
||
CS10x_GetYcCountByGroup cbGetYcCount, // → 返回该组遥测数量
|
||
CS10x_GetYcValueByGroup cbGetYcValue); // → 填充特定遥测值 (Yc_Info*)
|
||
|
||
// ===== 遥信 (YX) =====
|
||
void CS10x_S_GetYxByGroupHandler(pstSelf,
|
||
CS10x_GetYxCountByGroup cbGetYxCount, // → 返回该组遥信数量
|
||
CS10x_GetYxStatusByGroup cbGetYxStatus); // → 填充特定遥信状态 (Yx_Info*)
|
||
|
||
// ===== SOE (事件顺序记录) =====
|
||
void CS10x_S_SOEHandler(pstSelf,
|
||
CS10x_GetSOE cbGetSOE, // → 获取SOE数据
|
||
CS10x_GET_SOE_SendNum cbSendNum, // → 返回待发送SOE条数
|
||
CS10x_Updata_SOE_Pout cbUpdataSOEPout); // → 更新已发送指针
|
||
|
||
// ===== 遥控 (YK) =====
|
||
void CS10x_S_YkVerifyHandler(pstSelf,
|
||
CS10x_YkVerify cbYkVerify); // → 校验遥控命令合法性
|
||
|
||
// ===== 电度 (DD) =====
|
||
void CS10x_S_GetDdByGroupHandler(pstSelf,
|
||
CS10x_GetDdCountByGroup cbGetDdCount,
|
||
CS10x_GetDdValueByGroup cbGetDdValue);
|
||
|
||
// ===== 扰动遥测 (Disturb YC) =====
|
||
void CS10x_S_DiturbYcHandler(pstSelf,
|
||
CS10x_GetDiturbYc cbGetDiturbYc,
|
||
CS10x_GET_DiturbYc_SendNum cbSendNum,
|
||
CS10x_Updata_DiturbYc_Pout cbUpdataPout);
|
||
|
||
// ===== 时标电度 =====
|
||
void CS10x_S_DiturbDduHandler(pstSelf,
|
||
CS10x_GetTimeDdu cbGetTimeDdu,
|
||
CS10x_GetTimeDdu_SendNum cbSendNum,
|
||
CS10x_Updata_TimeDdu_Pout cbUpdataPout);
|
||
|
||
// ===== 故障事件 =====
|
||
void CS10x_S_FaultEventHandler(pstSelf,
|
||
CS10x_GET_Event_SendNum cbSendNum,
|
||
CS10x_GetFaultEvent cbGetFaultEvent,
|
||
CS10x_Updata_FaultEvent_Pout cbUpdataPout);
|
||
|
||
// ===== 参数/定值 =====
|
||
void CS10x_S_ParamAreaHandler(pstSelf,
|
||
CS10x_GetParamArea cbGetParamArea, // 读取当前定值区号
|
||
CS10x_SetParamArea cbSetParamArea); // 切换定值区
|
||
|
||
void CS10x_S_IECParamHandler(pstSelf,
|
||
CS10x_AddIECParam cbAddIECParam, // 添加参数项
|
||
CS10x_RunReadIECParam cbReadIECParam, // 读参数执行
|
||
CS10x_RunWriteIECParam cbWriteIECParam); // 写参数执行
|
||
|
||
void CS10x_S_GetParamInfoHandler(pstSelf,
|
||
CS10x_GetParamCount cbGetParamCount, // 参数总数
|
||
CS10x_GetParamInfoByIndx cbGetParamInfo); // 按索引获取参数信息
|
||
|
||
// ===== 时间 (对时) =====
|
||
void CS10x_TimeRWHandler(pstSelf,
|
||
CS10x_GetTime cbGetTime, // → 获取当前时间 (填充 __CP56Time2a)
|
||
CS10x_SetTime cbSetTime); // → 设置时间 (解析 __CP56Time2a)
|
||
|
||
// ===== 文件服务 =====
|
||
void CS10x_S_FileReadOprtHandler(pstSelf, cbGetPro, cbGetNum, cbRead, pvParam);
|
||
void CS10x_S_FileWriteOprtHandler(pstSelf, cbWrite, cbCheck, cbFinish, pvParam);
|
||
void CS10x_S_UpdateProcHandler(pstSelf, cbUpdateProc); // 软件升级
|
||
```
|
||
|
||
### 3.4 主动发送 API（应用层调用，库提供）
|
||
|
||
```c
|
||
// 任务类
|
||
unsigned char CS10x_SendTask(pstSelf); // 调度所有待发送任务
|
||
|
||
// 遥控主动下发（主站模式使用）
|
||
void CS10x_SetYkTask(pstSelf, usInfoAddr, ucSE, ucCmd, ucDcs, ucQU, bEncrypt);
|
||
```
|
||
|
||
### 3.5 公共工具函数
|
||
|
||
```c
|
||
// TaskFlag 操作
|
||
void SetTaskFlag(VFLAGS *flags, unsigned int flagNo);
|
||
unsigned int GetTaskFlag(VFLAGS *flags, unsigned int flagNo);
|
||
void ClearTaskFlag(VFLAGS *flags, unsigned int flagNo);
|
||
|
||
// 字节序编解码
|
||
unsigned char IntBytes_Pack2Buf(unsigned char *out, unsigned int val, unsigned char size);
|
||
unsigned int IntBytes_GetFromBuf(const unsigned char *in, unsigned char size);
|
||
unsigned char Float_Pack2Buf(unsigned char *out, float val);
|
||
float Float_GetFromBuf(const unsigned char *in);
|
||
unsigned char U16_Pack2Buf(unsigned char *out, unsigned short val);
|
||
unsigned short U16_GetFromBuf(const unsigned char *in);
|
||
|
||
// 校验
|
||
unsigned char checksum_8(unsigned char *buf, unsigned char len);
|
||
```
|
||
|
||
|
||
## 4. 典型使用流程
|
||
|
||
### 4.1 IEC 104 从站完整流程
|
||
|
||
```c
|
||
// ============ 步骤 1: 创建规约实例并初始化 ============
|
||
CS10x cs10x;
|
||
memset(&cs10x, 0, sizeof(CS10x));
|
||
CS10x_104Init(&cs10x, MySendCallback, myAppData, CS104_TYPE_S);
|
||
|
||
// ============ 步骤 2: 配置 ASDU 参数 ============
|
||
CS10x_AppLayerParameters appParam = {
|
||
.iSzOfLinkAddr = 0, // 104 无链路地址
|
||
.iSzOfTypeId = 1,
|
||
.iSzOfVSQ = 1,
|
||
.iSzOfCOT = 2, // 传输原因 2 字节
|
||
.iSzOfCA = 2, // 公共地址 2 字节
|
||
.iSzOfIOA = 3, // 信息体地址 3 字节
|
||
.iLinkAddr = 0,
|
||
.iPublicAddr = 1,
|
||
.iMaxSzOfAsduLen = 249
|
||
};
|
||
CS10x_SetAppParameters(&cs10x, &appParam);
|
||
|
||
// ============ 步骤 3: 配置 104 APCI 参数 ============
|
||
CS104_APCIParameters apciParam = {
|
||
.iK = 12,
|
||
.iW = 8,
|
||
.iT0 = 10, // 连接建立超时 10s
|
||
.iT1 = 12, // 发送超时 12s
|
||
.iT2 = 8, // 确认超时 8s
|
||
.iT3 = 15 // 空闲测试超时 15s
|
||
};
|
||
CS10x_SetAPCIParameters(&cs10x, &apciParam);
|
||
|
||
// ============ 步骤 4: 配置数据类型 ============
|
||
CS10x_SetYcType(&cs10x, 2); // 浮点遥测
|
||
CS10x_SetYxType(&cs10x, 0); // 单点遥信
|
||
CS10x_SetDdType(&cs10x, 1); // 带时标电度
|
||
CS10x_FrameGap(&cs10x, 10); // 10ms 帧间隔
|
||
CS10x_SetSummonGap(&cs10x, 300000); // 300s 总召
|
||
|
||
// ============ 步骤 5: 注册回调 ============
|
||
CS10x_S_GetYcByGroupHandler(&cs10x, MyGetYcCount, MyGetYcValue);
|
||
CS10x_S_GetYxByGroupHandler(&cs10x, MyGetYxCount, MyGetYxStatus);
|
||
CS10x_S_SOEHandler(&cs10x, MyGetSOE, MySOESendNum, MyUpdateSOEPout);
|
||
CS10x_S_YkVerifyHandler(&cs10x, MyYkVerify);
|
||
CS10x_TimeRWHandler(&cs10x, MyGetTime, MySetTime);
|
||
|
||
// ============ 步骤 6: 主循环驱动 ============
|
||
while(running) {
|
||
// 接收数据
|
||
int len = recv(sock, buf, sizeof(buf), 0);
|
||
if(len > 0) {
|
||
CS10x_DoRecv(&cs10x, buf, len); // ★ 喂给规约栈
|
||
}
|
||
|
||
// 定时器驱动 (每 10ms 调用一次)
|
||
CS10x_TimerHandle(&cs10x, 10); // ★ 驱动所有定时任务
|
||
}
|
||
```
|
||
|
||
### 4.2 回调函数签名参考
|
||
|
||
```c
|
||
// 发送回调 → 库将编码好的帧传给此函数
|
||
int MySendCallback(unsigned char *buf, unsigned short len, void *arg) {
|
||
return send(mySock, buf, len, 0);
|
||
}
|
||
|
||
// 获取遥测数量 (uiParam=组号)
|
||
int MyGetYcCount(void *param, unsigned int uiParam) {
|
||
return (uiParam == 1) ? g_ycCount : 0;
|
||
}
|
||
|
||
// 获取特定遥测值 (usPos=组内偏移)
|
||
int MyGetYcValue(Yc_Info *info, void *param, unsigned int usPos) {
|
||
info->uiInfoAddr = g_ycTable[usPos].addr; // 信息体地址
|
||
info->fVal = g_ycTable[usPos].value; // 遥测值
|
||
info->ucQds = 0x00; // 品质: 有效
|
||
return 0;
|
||
}
|
||
|
||
// 获取时间 (对时使用)
|
||
int MyGetTime(__CP56Time2a *pTime) {
|
||
struct timespec ts;
|
||
clock_gettime(CLOCK_REALTIME, &ts);
|
||
struct tm *t = gmtime(&ts.tv_sec);
|
||
pTime->ucYear = t->tm_year - 100;
|
||
pTime->ucMonth = t->tm_mon + 1;
|
||
pTime->ucDay = t->tm_mday;
|
||
pTime->ucHour = t->tm_hour;
|
||
pTime->ucMin = t->tm_min;
|
||
int ms = ts.tv_nsec / 1000000 + t->tm_sec % 60 * 1000;
|
||
pTime->ucLMs = ms & 0xFF;
|
||
pTime->ucHMs = (ms >> 8) & 0xFF;
|
||
return 0;
|
||
}
|
||
|
||
// 遥控校验
|
||
int MyYkVerify(Yk_Info *info, void *param) {
|
||
// 校验成功后执行遥控，失败返回 -1
|
||
return executeYk(info->uiInfoAddr, info->ucStatus, info->ucYkType) ? 0 : -1;
|
||
}
|
||
```
|
||
|
||
|
||
## 5. ASDU 类型标识码映射表
|
||
|
||
### 5.1 监视方向（终端 → 主站）
|
||
|
||
| TypeID | 宏 | 说明 | 品质描述词 |
|
||
|--------|-----|------|------------|
|
||
| 1 | `M_SP_NA` | 单点信息 | SIQ |
|
||
| 3 | `M_DP_NA` | 双点信息 | DIQ |
|
||
| 5 | `M_ST_NA` | 步位置信息 | VTI |
|
||
| 7 | `M_BO_NA` | 32位位串 | QDS |
|
||
| 9 | `M_ME_NA` | 测量值(归一化) | QDS |
|
||
| 11 | `M_ME_NB` | 测量值(标度化) | QDS |
|
||
| 13 | `M_ME_NC` | 测量值(短浮点) | QDS |
|
||
| 15 | `M_IT_NA` | 电能脉冲计数量 | - |
|
||
| 20 | `M_PS_NA` | 带状态变位检出的成组单点 | SIQ |
|
||
| 21 | `M_ME_ND` | 不带品质的测量值 | - |
|
||
| 30 | `M_SP_TB` | 带长时标单点 | SIQ |
|
||
| 31 | `M_DP_TB` | 带长时标双点 | DIQ |
|
||
| 34 | `M_ME_TD` | 带长时标测量值 | QDS |
|
||
| 42 | `M_FT_NA` | 故障事件 | QDP |
|
||
| 70 | `M_EI_NA` | 初始化结束 | COI |
|
||
| 206 | `M_IT_NB` | 不带时标累计量(浮点) | - |
|
||
| 207 | `M_IT_TC` | 带时标累计量(浮点) | - |
|
||
|
||
### 5.2 控制方向（主站 → 终端）
|
||
|
||
| TypeID | 宏 | 说明 |
|
||
|--------|-----|------|
|
||
| 45 | `C_SC_NA` | 单点遥控命令 |
|
||
| 46 | `C_DC_NA` | 双点遥控命令 |
|
||
| 47 | `C_RC_NA` | 升降命令 |
|
||
| 48 | `C_SE_NA` | 设定命令 |
|
||
| 55 | `C_SP_NA` | 参数预置(南网) |
|
||
| 100 | `C_IC_NA` | 总召唤命令 |
|
||
| 101 | `C_CI_NA` | 电度召唤命令 |
|
||
| 102 | `C_RD_NA` | 读数据命令 |
|
||
| 103 | `C_CS_NA` | 时钟同步命令 |
|
||
| 104 | `C_TS_NA` | 测试命令 |
|
||
| 105 | `C_RP_NA` | 复位进程命令 |
|
||
| 106 | `C_CD_NA` | 延时获得命令(南网) |
|
||
| 107 | `C_TS_TA` | 带时标测试命令 |
|
||
| 108 | `C_RS_NA_NANWANG` | 读参数命令(南网) |
|
||
| 112 | `P_ME_NC` | 参数预置 |
|
||
| 113 | `P_AC_NA` | 参数固化 |
|
||
| 200 | `C_SR_NA` | 切换定值区 |
|
||
| 201 | `C_RR_NA` | 读定值区号 |
|
||
| 202 | `C_RS_NA` | 读参数和定值 |
|
||
| 203 | `C_WS_NA` | 写参数和定值 |
|
||
| 210 | `F_FR_NA` | 文件升级 |
|
||
| 211 | `F_SR_NA` | 软件升级 |
|
||
|
||
|
||
## 6. 传送原因 (COT) 速查
|
||
|
||
| COT | 宏 | 说明 |
|
||
|------|-----|------|
|
||
| 1 | `COT_PERCYC` | 周期/循环 |
|
||
| 2 | `COT_BACK` | 背景扫描 |
|
||
| 3 | `COT_SPONT` | 突发(变位) |
|
||
| 4 | `COT_INIT` | 初始化 |
|
||
| 5 | `COT_REQ` | 请求或被请求 |
|
||
| 6 | `COT_ACT` | 激活 |
|
||
| 7 | `COT_ACTCON` | 激活确认 |
|
||
| 8 | `COT_DEACT` | 停止激活 |
|
||
| 9 | `COT_DEACTCON` | 停止激活确认 |
|
||
| 10 | `COT_ACTTERM` | 激活结束 |
|
||
| 20 | `COT_INTROGEN` | 响应总召唤 |
|
||
| 37 | `COT_REQCOGCN` | 响应计数量总召唤 |
|
||
| 44 | `COT_E_TYPE` | 未知类型标识 |
|
||
| 45 | `COT_E_REASON` | 未知传送原因 |
|
||
| 46 | `COT_E_CADDR` | 未知公共地址 |
|
||
| 47 | `COT_E_IADDR` | 未知信息体地址 |
|
||
|
||
|
||
## 7. 定时器与任务调度
|
||
|
||
### 7.1 104 定时器
|
||
|
||
| 定时器 | 默认值 | 说明 |
|
||
|--------|--------|------|
|
||
| T0 | 10s | 连接建立超时—发送 STARTDT 后等待确认 |
|
||
| T1 | 12s | 发送 I 帧后等待确认超时 |
|
||
| T2 | 8s | 接收 I 帧后延迟确认 ACK |
|
||
| T3 | 15s | 空闲测试超时—发送 TESTFR |
|
||
|
||
**定时器处理流程**:
|
||
1. `CS10x_TimerHandle()` 被调用 → 遍历 stM_vTimer[4]
|
||
2. T0 超时 → 重试连接 / T1 超时 → 断开链路 / T3 超时 → 发送测试帧
|
||
|
||
### 7.2 任务标志系统
|
||
|
||
库内部使用 128 位位图 (`VFLAGS`) 管理所有待处理任务：
|
||
|
||
| 任务 ID | 枚举值 | 说明 |
|
||
|---------|--------|------|
|
||
| `TSKID_SummonYx` | - | 总招遥信响应 |
|
||
| `TSKID_SummonYc` | - | 总招遥测响应 |
|
||
| `TSKID_SendCOS` | - | 发送变位遥信 |
|
||
| `TSKID_SendSOE` | - | 发送 SOE |
|
||
| `TSKID_TimeSyn` | - | 时钟同步 |
|
||
| `TSKID_HeartBeat` | - | 心跳 |
|
||
| `TSKID_DdSummon` | - | 总招电能量 |
|
||
| `TSKID_FaultSoe` | - | 故障事件 |
|
||
| `TSKID_YcDisturb` | - | 扰动数据 |
|
||
| `TSKID_ChgConst` | - | 修改定值区 |
|
||
| `TSKID_ReadConst` | - | 读取定值区 |
|
||
|
||
**任务调度流程**: `CS10x_TimerHandle` → 累计各定时计数 → 超时时 `SetSendTask` 置位 → `CS10x_SendTask` → 遍历任务标志 → 调用对应的 `Do_*` 函数。
|
||
|
||
|
||
## 8. 品质描述词 (Quality Descriptor)
|
||
|
||
库提供了 5 种品质描述词的位域定义，封装在 `ASDU_CMD_T` union 中：
|
||
|
||
| 类型 | 字段 | 位 | 说明 |
|
||
|------|------|-----|------|
|
||
| **SIQ** (单点) | SPI | 0 | 0=开, 1=合 |
|
||
| | BL | 4 | 0=未锁定, 1=锁定 |
|
||
| | SB | 5 | 0=未取代, 1=取代 |
|
||
| | NT | 6 | 0=当前值, 1=非当前 |
|
||
| | IV | 7 | 0=有效, 1=无效 |
|
||
| **DIQ** (双点) | DPI | 0-1 | 0/3=不确定, 1=开, 2=合 |
|
||
| **QDS** (测量值) | OV | 0 | 0=未溢出, 1=溢出 |
|
||
| **QDP** (保护事件) | EI | 4 | 0=动作时间有效, 1=无效 |
|
||
| **SCO** (单命令) | SCS | 0 | 0=开, 1=合 |
|
||
| | QU | 1-5 | 0=无定义, 1=短脉冲, 2=长脉冲, 3=持续 |
|
||
| | SE | 6 | 0=执行, 1=选择 |
|
||
| **DCO** (双命令) | DCS | 0-1 | 1=开, 2=合 |
|
||
| | SE | 6 | 0=执行, 1=选择 |
|
||
| **QOS** (设定命令) | QL | 0-6 | 0=缺省 |
|
||
| | SE | 6 | 0=执行, 1=选择 |
|
||
| **COI** (初始化) | UI7 | 0-6 | 0=电源合上, 1=手动复位, 2=远方复位 |
|
||
|
||
|
||
## 9. 101 与 104 的关键差异
|
||
|
||
| 特性 | IEC 101 | IEC 104 |
|
||
|------|---------|---------|
|
||
| **传输层** | 串口 (异步字节流) | TCP/IP 网络 |
|
||
| **链路层帧** | `0x10` 短帧 / `0x68` 长帧 | APCI 6字节头 (I/S/U帧) |
|
||
| **地址** | 链路地址 (1-2 byte) | 无链路地址 |
|
||
| **帧同步** | 起始+结束字符 (0x68/0x10+0x16) | APDU 长度字段 |
|
||
| **重传机制** | FCB/FCV + 超时重发 | 发送序号 + 接收序号 + T1 超时 |
|
||
| **链路管理** | REQUEST_LINK / RESET_LINK 帧 | STARTDT/STOPDT/TESTFR U帧 |
|
||
| **初始化** | 复位链路 → 简单/完整初始化 (可选) | TCP 连接 → STARTDT 激活 |
|
||
| **初始化函数** | `CS10x_101Init(..., CS101_TYPE_S)` | `CS10x_104Init(..., CS104_TYPE_S)` |
|
||
| **缓存** | 固定 255 字节帧 | APCI 6 + ASDU max 249 |
|
||
| **多帧** | 101 连帧 (FCB 位机制) | 104 I 帧序号连续发送 |
|
||
|
||
|
||
## 10. 文件服务与升级流程
|
||
|
||
库内建了基于 IEC 60870-5 文件传输服务的文件操作能力：
|
||
|
||
| 操作 | TypeID / 说明 |
|
||
|------|---------------|
|
||
| 目录召唤 | 读目录 → 返回文件列表 |
|
||
| 读文件 | 激活 → 分段传输数据 → 传输确认 |
|
||
| 写文件 | 激活 → 分段写数据 → 写确认 |
|
||
| 软件升级 | 211 `F_SR_NA` → `CS10x_S_UpdateProcHandler` |
|
||
|
||
**注意**: 旧文件服务接口 (`CS10x_FileReadOprtHandler` 不带 `S_` 前缀) 在库中标记为"待删除"，应使用 `CS10x_S_FileReadOprtHandler` / `CS10x_S_FileWriteOprtHandler`。
|
||
|
||
|
||
## 11. 注意事项与踩坑指南
|
||
|
||
### 11.1 类型兼容
|
||
- CBB 库使用 `u8/u16/u32/s16/s32/f32/BOOL/TRUE/FALSE` 自定义类型
|
||
- **不能修改库文件** — 通过 `release/inc/cbb_compat.h` + gcc `-include` 注入解决
|
||
- 本项目已在 [makefile](../../release/src/protocol/lib60870/makefile) 中配置
|
||
|
||
### 11.2 回调约定
|
||
- 所有回调返回 `0` = 成功，非 `0` = 失败
|
||
- `cbSend` 回调中不要阻塞
|
||
- 库内部是**同步调用**，`CS10x_DoRecv` 内部会立即调用回调获取数据
|
||
|
||
### 11.3 线程安全
|
||
- 库本身**不是线程安全**的，所有 API 调用建议在同一线程
|
||
- 典型架构：通信线程收数据 → CS10x_DoRecv → 定时器线程驱动 CS10x_TimerHandle
|
||
|
||
### 11.4 多实例支持
|
||
- 每个通信链路创建一个 `CS10x` 实例
|
||
- 调用方通过 `void *arg` (初始化参数) 和 `void *pParam` (回调参数) 传递业务上下文
|
||
|
||
### 11.5 从站 vs 主站
|
||
- **此项目 RTU 作为从站** (`_S` 类型) — 回调负责**提供数据**
|
||
- 如果作为主站 (`_M` 类型) — 回调负责**处理收到的数据**
|
||
|
||
### 11.6 101 序列号与链路状态
|
||
- FCB 位每发送一帧翻转
|
||
- 重发帧 FCB 位不变
|
||
- 链路重置时 FCB 复位
|
||
|
||
### 11.7 104 序号机制
|
||
- 发送序号 `usSendNum` 与接收序号 `usRecvNum` 各自独立递增
|
||
- 当 `usSendNum - usAckRecvNum >= K` 时停止发送 (流量控制)
|
||
- T1 超时断开链路，清初始化完成标识
|
||
|
||
|
||
## 12. 版本关键变更摘要
|
||
|
||
| 版本 | 日期 | 关键修改 |
|
||
|------|------|----------|
|
||
| V2.01.059 | 2026-02-02 | 增加 YC 上传品质描述词字段 |
|
||
| V2.01.058 | 2026-01-31 | 增加确认帧通知回调接口（透传给下行设备） |
|
||
| V2.01.057 | 2025-12-25 | T0-T3 最大范围 120→200 |
|
||
| V2.01.056 | 2025-12-09 | 添加关闭链路接口 |
|
||
| V2.01.055 | 2025-10-30 | 优化序号匹配，>=K 时继续闭锁 |
|
||
| V2.01.054 | 2025-10-27 | 修复总召不上送、序号不匹配问题 |
|
||
| V2.01.044 | 2025-09-03 | 参数预置忽略后续帧 + 修复 T1/T3 超时 |
|
||
| V2.01.043 | 2025-08-11 | 添加普洱/贵州参数读写流程 |
|
||
| V2.01.042 | 2025-07-17 | 南网规约参数读写和延时获得命令 |
|
||
| V2.01.039 | 2025-04-21 | 101 错误帧继续解析后续报文 |
|
||
| V2.01.038 | 2025-03-19 | 101 回复长帧 FCV 默认置 1 |
|