Files
STM32F4-Base/IEC60870-Slave/README.md
T
STF bdcc8b6500
CI / L0 静态门禁 (pre-commit) (push) Failing after 7m46s
CI / L0.5 主机侧单测 (MSVC) (push) Successful in 21s
添加遥控、参数装载、文件传输等业务
2026-11-16 22:19:17 -08:00

193 lines
20 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# IEC60870-Slave
IEC 60870 子站协议库,提供IEC104子站、Windows TCP后端、总召、计数量召唤、读命令、校时与读时钟、遥控遥调、系统命令、标准参数与远程参数、Type210文件服务、Type211软件升级、突发上送、Type42故障事件及周期/背景扫描。101/104可复用的ASDU、信息对象、时间工具、故障录波与COMTRADE编码、附录B历史和冻结电能、附录C运行日志及其XML生成、持久软件安装核心、子站应答接口集中在公共目录。
## 目录结构
按职责归档,同一模块的 `.c` 和 `.h` 放在一起:
```text
IEC60870-Slave/
├── 104/ # IEC104 专用协议代码
│ ├── IEC104_Slave.c/h # 子站统一入口
│ ├── business/ # 104业务模块
│ │ ├── IEC104_Interrogation.c/h # 共用召唤引擎
│ │ ├── IEC104_Interrogation_Internal.h # 引擎与种类规则的私有接口
│ │ ├── IEC104_GeneralInterrogation.c/h # 站总召、分组总召规则
│ │ ├── IEC104_CounterInterrogation.c/h # 计数量读取、冻结与复位
│ │ ├── IEC104_ClockSynchronization.c/h # 校时/读时校验、显式回调与回复
│ │ ├── IEC104_Command.c/h # 遥控/遥调、带时标命令、选择执行与返回信息
│ │ ├── IEC104_Read.c/h # 单点读取、同步lookup、FIFO与期限
│ │ ├── IEC104_SystemCommand.c/h # 104/107回显、70初始化结束、105复位授权与事件清除
│ │ ├── IEC104_Startup.c/h # 细则配置、初始化与总召后的缓存补发协调
│ │ ├── IEC104_SoftwareUpgrade.c/h # 211升级会话、ACK观察、ABANDON与重启授权
│ │ ├── IEC104_Parameter.c/h # 110–113参数FIFO、运行值确认及可选ACK两阶段
│ │ ├── IEC104_RemoteParameter.c/h # 200–203读区、切区、预置/固化/撤销
│ │ ├── IEC104_FileService.c/h # 210目录、分段读写与提交
│ │ ├── IEC104_Spontaneous.c/h # 突发上送、CP56时标与NORMAL覆盖统计
│ │ └── IEC104_PeriodicScan.c/h # IDLE周期/背景扫描、点级网格与整表替换
│ ├── IEC104_TcpServer.c/h # TCP 服务与事件调度
│ ├── IEC104_Connection.c/h # 连接协调
│ ├── IEC104_Link*.c/h # 链路、主站/子站启停
│ ├── IEC104_Send*.c/h # 发送管理与缓冲
│ ├── IEC104_AsduQueue.c/h # ASDU 队列
│ ├── IEC104_Receiver.c/h # 流式接收
│ ├── IEC104_Codec.c/h # APCI 编解码
│ ├── IEC104_Net.h / IEC104_Net_Windows.c # 网络接口与 Windows 后端
│ └── IEC104*.c/h # 类型、容量配置、日志及旧接收入口
├── common/ # 101/104 公共代码
│ ├── IEC60870_Types.h # 公共类型及应用层参数
│ ├── IEC60870_Codec.c/h # ASDU 公共头编解码
│ ├── IEC60870_Asdu.c/h # ASDU 容器
│ ├── IEC60870_FaultEvent.c/h # Type42故障事件完整ASDU编解码
│ ├── IEC60870_FaultRecorder.c/h # 调用方采样、前后窗口与冻结记录
│ ├── IEC60870_Comtrade.c/h # COMTRADE 1999 CFG与二进制DAT
│ ├── IEC60870_History.c/h # SOE/遥控循环记录、定点及每日极值
│ ├── IEC60870_HistoryFile.c/h # 附录B文件名与流式XML生成
│ ├── IEC60870_EnergyFreeze.c/h # 冻结电能、潮流反转、封存与持久恢复
│ ├── IEC60870_EnergyFreezeFile.c/h # FRZ/FLOWREV文件名及流式XML
│ ├── IEC60870_UserLog.c/h # 附录C的1024条日志循环、持久化及恢复
│ ├── IEC60870_UserLogFile.c/h # ULOG固定路径与流式XML生成
│ ├── IEC60870_FirmwareUpdate.c/h # 三槽升级、持久安装授权、试运行确认与回退
│ ├── IEC60870_InformationObjects*.c/h # 信息对象
│ ├── IEC60870_Slave.c/h # 公共子站应答接口
│ └── IEC60870_Time.c/h / IEC60870_Clock.c/h # 时间工具与时钟接口
├── examples/ # 应用示例
│ ├── iec104_slave_example.c # 模拟点表、业务分派与程序入口
│ ├── iec104_parameter_multi_master.c # 两主站共享参数生效值
│ ├── iec104_example_history.c/h # Windows双副本持久存储与历史文件快照
│ ├── iec104_example_energy_freeze.c/h # 独立energy.store与目录/下载快照
│ ├── iec104_example_energy_meter.c/h # 整数方波、八值恢复与分段校时
│ ├── iec104_example_user_log.c/h # 独立ulog.store与目录/下载快照
│ ├── iec104_example_upgrade.c/h # Windows升级槽、双bank提交与dtu/dtu-1安装恢复
│ ├── iec104_example_recording.c/h # 模拟录波保存与COMTRADE虚拟目录
│ └── iec104_example_config.c/h # 标准/远程参数及TEMP的统一INI持久化
├── test/ # 测试源码与主机脚本
│ ├── iec104_*_test.c # 104 传输、调度、子站及业务测试
│ ├── iec60870_*_test.c # 公共 ASDU 与信息对象测试
│ └── slave_example_loopback_test.cjs # 真实 TCP 回环测试
├── docs/ # 设计、接口、示例及测试说明
│ ├── README.md # 文档索引与推荐阅读顺序
│ ├── 104/ # 104 设计及接口说明
│ ├── common/ # 公共模块说明
│ ├── examples/ # 示例使用说明
│ └── test/ # 测试说明与验证记录
├── scripts/ # 构建与工程包工具
│ ├── build.ps1 # 构建示例,-Test 运行业务回归、容量矩阵及回环
│ └── make_upgrade_package.cjs # 将已有负载封装为I104基线包或上传包
├── .build/ # 本地构建及验证产物(运行脚本后生成)
└── README.md # 项目总览
```
## 构建与测试
按 `DTU(100V1A 100V1A)` 配置演示时,使用专用 DTU 入口。它保留原文件的 59 个遥信、19 个遥控和 345 项已填参数,接入通用示例的完整业务,并补充 30 个遥测、16 个双点反馈和 8 个电量点等演示地址。PT 为 100V/100V,相 CT 和零序 CT 均为 1A/1A;定值预置、固化、撤销及持久化、文件传输、历史、录波和升级的开启方法见 [DTU 配置演示](docs/examples/DTU配置演示.md)。
倍率、取反、测量换算、保护分合闸及触发录波已接入运行链;本地故障输入、逐项覆盖和仍缺定义的 FA/通信等项目见 [DTU 运行模型](docs/examples/DTU运行模型.md)。
```powershell
./scripts/build.ps1
./.build/slave-example/iec104_dtu_example.exe --ca 1
# 固定初值,便于逐点核对
./.build/slave-example/iec104_dtu_example.exe --ca 1 --events 0
# 校验源 XML、点表、参数和真实 TCP 交互
./scripts/build.ps1 -Test -Suite Dtu
```
以下 `iec104_slave_example.exe` 保留通用协议功能及原有 8 点测试布局;DTU 演示应启动上面的 `iec104_dtu_example.exe`。
在本目录的 PowerShell 中执行,需要 MinGW GCC。先构建成功,再启动生成的示例:
```powershell
./scripts/build.ps1
./.build/slave-example/iec104_slave_example.exe --ca 1
```
默认监听 `127.0.0.1:2404`;`--ca 1` 指定公共地址,不能只写 `--ca`。默认开启参数处理及field模拟输入,以达到门限的COT=3变化上送为主、低频COT=2背景刷新8个遥测,固定周期COT=1按需开启。主站用 Type102、COT=5、CA=1、IOA=0x4001(十进制16385)读取当前处理值,返回 Type11;其初始值2300随默认模拟运行变化,精确核对初值时加`--events 0`启动。具体默认值、模拟工况及操作步骤见[示例说明](docs/examples/IEC104子站示例.md#example-quick-start)。
主示例总召遥信使用Type1/3,总召之外的变位、遥控返回和Read遥信使用带CP56的Type30/31。默认全部命令点须选择后执行或撤销,选择保持60秒;没有S/E字段的51/64仅在`--command-extensions`下启用。集中点表按十六进制分区配置,旧标准参数INI须按[迁移说明](docs/examples/IEC104子站示例.md#example-point-migration)迁移;通用库仍保留显式无时标/双报及DIRECT能力。各模块职责、快照寿命及兼容边界见[默认策略设计](docs/104/IEC104_设计架构.md#spec-alignment-design)。
```powershell
# 全量测试:需要 GCC 和 Node.js
./scripts/build.ps1 -Test
# 只运行读命令专项的四种容量配置:只需 GCC
./scripts/build.ps1 -Test -Suite Read
# 系统命令四种容量配置;ACK观察与队列清除另在Transport中
./scripts/build.ps1 -Test -Suite SystemCommand
./scripts/build.ps1 -Test -Suite Transport
# 周期/背景扫描专项与容量矩阵
./scripts/build.ps1 -Test -Suite PeriodicScan
# 参数装载、扩展及ACK两阶段四种容量配置
./scripts/build.ps1 -Test -Suite Parameter
./scripts/build.ps1 -Test -Suite RemoteParameter
./scripts/build.ps1 -Test -Suite FileService
./scripts/build.ps1 -Test -Suite SoftwareUpgrade
# 持久安装核心、实际文件中断恢复及TCP升级;需要Node.js
./scripts/build.ps1 -Test -Suite FirmwareUpdate
# Type42公共编解码与故障事件上送容量矩阵
./scripts/build.ps1 -Test -Suite FaultEvent
# 故障录波、COMTRADE编码与宿主保存适配
./scripts/build.ps1 -Test -Suite Recording
# 附录B历史、持久化故障注入、XML及真实TCP恢复
./scripts/build.ps1 -Test -Suite History
# FRZ/FLOWREV、整数计量、持久恢复及TCP文件调阅
./scripts/build.ps1 -Test -Suite EnergyFreeze
# 附录C日志核心、XML、宿主持久化与TCP调阅
./scripts/build.ps1 -Test -Suite UserLog
```
默认产物分为:
| 路径 | 用途 |
|---|---|
| `.build/slave-example/iec104_slave_example.exe` | 可供主站连接的示例程序 |
| `.build/slave-example/iec104_dtu_example.exe` | DTU 100V/1A 点表、五区定值及完整业务演示;[实现组织](docs/examples/DTU配置演示.md#实现组织与数据流) |
| `.build/slave-example/tests/` | 自动测试可执行程序,由脚本运行 |
| `test/` | 保留测试源码及真实TCP回环脚本 |
需要独立构建目录时使用 `-BuildName read-check`,随后运行 `.build/read-check/iec104_slave_example.exe`。它不会更新默认目录的exe。脚本会打印本次实际产物和启动命令;示例运行中不能覆盖同一路径的exe,应先退出该示例或换BuildName。
`-Test`覆盖公共ASDU、传输容量矩阵及ACK观察、Slave、示例业务、遥控、读命令、系统命令、参数装载及扩展、突发、Type42故障事件、召唤规则及真实TCP回环。实际执行配置数由脚本输出;完整Suite列表与覆盖范围见[测试说明](docs/test/IEC104测试文档.md#1-当前测试入口)。构建参数和源文件依赖统一维护在[build.ps1](scripts/build.ps1)。
`.build/`是本地生成目录,已加入忽略规则。旧exe和编译中间文件可以重新生成;历史`RESULTS.txt`、测量记录及`before/`快照用于追溯,不能作为当前启动入口。
## 接入自己的工程
附录C运行日志由`IEC60870_UserLog`循环保存1024条,`IEC60870_UserLogFile`生成`HISTORY/ULOG/ulog.xml`。示例加`--user-log existing-directory`独立启用并自动开启Type210,不隐含`--history`;启动、通道状态、实际参数变更及带模式标记的升级阶段按事实记录。04..09硬件来源通过公共Append接入,当前示例不生成假硬件事件。类型、XML字段取舍、持久恢复与移植边界见[运行日志设计](docs/common/IEC60870_UserLog_设计架构.md#user-log-design),操作见[日志示例](docs/examples/IEC104子站示例.md#example-user-log),验证见[日志测试](docs/test/IEC104测试文档.md#user-log-tests)。
附录B历史由`IEC60870_History`维护SOE、遥控、定点和极值,`IEC60870_HistoryFile`流式生成XML。示例加`--history existing-directory`启用宿主持久存储并自动开启Type210;保存1024条SOE、30条遥控及32个日槽,导出最新30个完整历史日。库核心使用调用方提供的原子持久提交接口;Windows示例使用独占文件、双副本和系统同步。设计与持久性边界见[历史记录设计](docs/common/IEC60870_History_设计架构.md),启动和调阅见[历史示例](docs/examples/IEC104子站示例.md#example-history),专项入口见[历史测试](docs/test/IEC104测试文档.md#history-tests)。
Type42故障事件使用`IEC60870_FaultEvent`专用编解码和`IEC104_Spontaneous_Publish_Fault_Event`发布入口。应用提供故障时刻冻结的遥信、CP56时标和至少八项电气量,104按已确认的接收端布局使用统一3字节地址及无QDS遥测,默认短浮点;发送沿用NORMAL缓存和故障事件第6级。格式依据、与实施细则的地址差异及调用示例见[故障事件设计](docs/common/IEC60870_FaultEvent_设计架构.md)。接入Spontaneous的工程须同时编译`common/IEC60870_FaultEvent.c`。
连续波形由`IEC60870_FaultRecorder`接收调用方采样,`IEC60870_Comtrade`生成1999格式CFG/BINARY DAT。主示例加`--recording-demo existing-directory`保存一份明确标记的模拟录波,并通过COMTRADE虚拟目录提供下载。模块位置、窗口与迟触发容量、文件布局及生命周期见[录波设计](docs/common/IEC60870_FaultRecorder_设计架构.md);真实采样、及时故障上送、多记录和持久存储见[产品接入要求](docs/common/IEC60870_FaultRecorder_设计架构.md#fault-recording-product)。运行步骤见[录波示例](docs/examples/IEC104子站示例.md#example-recording),已有验证及未验收范围见[录波测试](docs/test/IEC104测试文档.md#recording-tests)。
电能量支持短浮点Type206/207,复用Type101计数量召唤及Spontaneous的COT=3上送。示例默认206读取当前示值,`--counter-type 207`读取冻结值和原冻结时刻;15/37整数模式可显式选择。点地址、单位和内存边界见[计数量示例](docs/examples/IEC104子站示例.md#计数量与主循环),协议范围见[计数量设计](docs/104/IEC104_CounterInterrogation_设计架构.md#1-请求与数据)。
示例加`--energy-freeze existing-directory --energy-period-ms 1200000`启用独立energy.store、整数方波计量和Type210下的`HISTORY/FRZ`、`HISTORY/FLOWREV`,目录必须已存在。该模式采用Type206及QCC=0x05,BEGIN冻结本轮读取快照;QRP1保留计量与持久文件。记录封存、双bank故障边界、八值恢复和临时内存开销见[冻结电能设计](docs/common/IEC60870_EnergyFreeze_设计架构.md)。
Type211软件升级由独立`IEC104_SoftwareUpgrade`提供。`--file-service --software-upgrade`保留RAM演示;`--upgrade-store existing-directory`启用真实文件存储、`dtu/dtu-1`安装备份及跨进程恢复,首次需`--upgrade-seed`提供完整旧程序包。两模式均可用202读回版本/CRC,宿主不执行收到的负载。见[持久安装设计与用法](docs/common/IEC60870_FirmwareUpdate_设计架构.md)、[协议设计](docs/104/IEC104_SoftwareUpgrade_设计架构.md)及[验证](docs/test/IEC104测试文档.md#firmware-update-tests)。
移植软件安装时,公共核心只接收存储及安装回调,Windows后端作为实文件参考实现。协议ACK、持久授权和健康确认分别由不同入口完成;错误处理须区分候选拒绝与提交结果不确定。按[升级文档导航](docs/README.md#firmware-update-guide)阅读布局、接口、恢复和调用时序;首次操作从[持久模式示例](docs/examples/IEC104子站示例.md#example-firmware-update)开始。目标Flash、Bootloader跳转和真实应用健康条件的接入范围见[板端边界](docs/common/IEC60870_FirmwareUpdate_设计架构.md#firmware-update-target)。
Type200–203 远程参数由独立 `IEC104_RemoteParameter` 模块提供;通用示例默认关闭,加 `--remote-parameter` 开启,DTU 示例默认开启。支持切区、读区、TLV 分帧读取和预置/固化/撤销,存储与权限由应用实现。见[远程参数设计](docs/104/IEC104_RemoteParameter_设计架构.md)、[通用示例点表](docs/examples/IEC104子站示例.md#example-remote-parameter)、[DTU 定值与恢复](docs/examples/DTU配置演示.md#标准参数与远程定值)及[专项验证](docs/test/IEC104测试文档.md#remote-parameter-tests)。
Type210 文件服务由独立 `IEC104_FileService` 提供;示例加 `--file-service` 开启,默认关闭。支持目录快照、IDLE读文件、连续写段的BUSY背压和COMMIT原子发布;普通TEMP文件可随`--config`保存到宿主文件,读取目录仍使用示例虚拟目录。见[文件服务设计](docs/104/IEC104_FileService_设计架构.md)、[示例用法](docs/examples/IEC104子站示例.md#example-file-service)及[专项验证](docs/test/IEC104测试文档.md#file-service-tests)。
Type110–113标准参数默认开启,`--no-parameter`可关闭。通用示例提供32项,DTU示例提供120项,用于遥测门限、平滑和量程品质处理,并支持总召读回;点表、QPA3周期控制及操作步骤见[参数应用](docs/examples/IEC104子站示例.md#example-parameter)和[DTU参数](docs/examples/DTU配置演示.md#标准参数与远程定值)。协议模块只负责通信,可选扩展及接入见[参数设计](docs/104/IEC104_Parameter_设计架构.md)和[调用流程](docs/104/IEC104_完整调用流程.md#flow-parameter)。
主示例可加`--config .build/slave-example/parameters.ini`,用一份INI保存和恢复标准参数、远程参数及TEMP文件,备份恢复只需该文件;不指定则只保存在内存。格式、旧文件迁移、加载校验和保存失败规则见[持久化说明](docs/examples/IEC104子站示例.md#example-parameter-persistence)。存储属于示例应用,不加入协议库。
周期扫描使用独立IDLE直发通道,保留HIGH/NORMAL调度。背景扫描默认开启;需要固定周期快照时可加`--cyclic-ms 1000`,背景周期由`--background-ms`单独调整,`--sequence`显式开启连续IOA编码。周期是名义网格,持续应答或突发可能使扫描延迟;点级周期、在线停用和整表替换见[扫描设计](docs/104/IEC104_PeriodicScan_设计架构.md)。
将 `104/` 和 `common/` 加入头文件搜索路径,使用业务模块时再加入 `104/business/`;按所用模块选择源文件,Windows网络后端链接 `Ws2_32`。统一入口为 `IEC104_Slave.h`,模块职责与依赖见[模块索引](docs/104/README.md),执行顺序见[完整调用流程](docs/104/IEC104_完整调用流程.md)。
按本目录细则接入启动补发时,使用 `IEC104_Startup_Config_Default` 统一设置传输、初始化、总召、计数量召唤和突发配置,再由 `IEC104_Startup` 协调本轮 Type70 与各站总召完成;主示例使用同一入口。配置函数不创建业务模块,也不替应用注册站点、登记COI或驱动严格业务循环,完整接线见[统一配置与启动流程](docs/104/IEC104_完整调用流程.md#startup-unified-entry)。五个分散的旧配置入口已移除,主示例和参数多主站示例均接入本轮初始化及总召协调;接口迁移见[迁移说明](docs/104/IEC104_完整调用流程.md#startup-config-migration)。
接收N(S)兼容和收到主站TESTFR后的终端主动探测抑制已统一在链路层实现,无需额外配置。两项修复的条款对应、行为变化、底层接口迁移及验证入口见[链路细则修复汇总](docs/104/IEC104_设计架构.md#link-spec-fixes)。
业务模块的职责、状态和接口见[设计索引](docs/104/README.md#business-module-designs),跨模块的事件分派与发送边界见[业务层总览](docs/104/IEC104_业务层_设计架构.md)。
示例使用模拟点表和时钟;105 QRP1在确认按时被ACK后重建协议实例,不重启宿主进程。报文及操作边界见[系统命令联调](docs/examples/IEC104子站示例.md#example-system-command)。真实采集、设备输出及主站互操作仍由应用接入,完整资料见[文档索引](docs/README.md)。
接入系统命令时,先按[最小调用示例](docs/104/IEC104_完整调用流程.md#flow-system-command)创建模块并登记COI,再分派通知、推进回复及显式调用应用动作。调度与诊断字段见[状态和计数](docs/104/IEC104_API接口汇总.md#system-command-status);模拟复位前须按[收尾步骤](docs/examples/IEC104子站示例.md#example-system-command-shutdown)分别读空业务终结通知和Slave通知。