# App/iec60870/ — IEC 60870-5-104 协议栈(项目自有) 本目录是本项目的 IEC 60870-5-104(变电站远动通信协议,下文简称「104」)协议栈实现:一边接 主站的 TCP 连接,一边经平台接缝取本站数据。**它现在是团队自己的代码**,按项目规范维护; 下文每节说明该目录的边界、改动纪律与真正的知识,避免新接手者必须读遍约 5 万行才能动手。 > **历史出处(一句)**:仓库根的 `IEC60870-Slave/` 是原始第三方快照,保留作独立验证基线; > 本目录代码已于 2026-11-18 收编为项目自有,不再做逐字节保真校验。 ## 1. 目录结构 接手先看这张表:它回答「某个功能该改哪个目录」。 | 子目录 | 职责 | 详情 | |---|---|---| | `common/` | 与传输无关的协议数据面:ASDU(应用服务数据单元)编解码、信息对象、时间表示,以及 101/104 共用的子站发送接口抽象 | [`common/README.md`](common/README.md) | | `104/` | APCI(应用规约控制信息)传输层 + 业务状态机 + **平台适配与装配** | [`104/README.md`](104/README.md) | | `104/business/` | 业务状态机:收到的 I 帧按业务类型分派、校验、应答与主动上送 | [`104/business/README.md`](104/business/README.md) | | `examples/` | 声明式 DTU(配电终端)点表 profile,一份头文件,无示例 main | [`examples/README.md`](examples/README.md) | `104/` 下有两类文件,**命名前缀就是分层标记**:`IEC104_*` 是协议主体(传输与状态机), `iec104_*`(小写)是本项目的装配与平台层——`iec104_core`(生命周期与事件循环)、 `iec104_source`(数据/模拟动作/参数 RAM/虚拟墙钟)、`iec104_net_mcu`(CH395F 网络后端)、 `iec104_dtu_table`(标准 DTU 点表)、`iec104_comm`(`/config.ini` 的 `[comm]` 段:本站公共地址 与端口号的 RAM 副本、工厂默认、getter 合法带与 setter 守卫)。改协议行为先找 `IEC104_*`, 改「数据从哪来」先找 `iec104_source`,改「本站地址写在哪」先找 `iec104_comm`。 ## 2. 能力边界(能做什么、明确不做什么) 动手前先确认需求是否在边界内,越界的功能要复用既有子系统而不是往这里加: **已实现**:APCI 传输(APDU 帧、k=12/w=8 窗口、t1=15 s / t2=10 s / t3=20 s 超时)、 总召与计数量总召(GI/CI)、突发(COT=3)与周期遥测上送、遥控(含选择/执行两段)、校时、 读命令、标准参数(Type200~203 远方参数读写)、Type42 故障事件(扩展布局)。 **未实现**:历史数据、事故记录、文件传输、录波文件、固件升级后端。这些能力在本项目里 已有归属(存储栈、日志子系统、FTP 服务),**集成时必须复用它们**,不要在本目录内实现第二份。 ## 3. 关键设计约束(代码为什么长成这样) 读代码时若觉得某处写法多余,先来这里对照——这些不是历史包袱,是有原因的项目决策。 ### 3.1 C99 没有 `_Static_assert`,用数组宽度实现编译期断言 `common/IEC60870_StaticAssert.h` 是**项目的 C99 约束实现**,不是对第三方的兼容补丁: ARM Compiler 5(AC5,Keil MDK 默认编译器)只到 C99,没有 C11 的 `_Static_assert`。 该头在 `__STDC_VERSION__ < 201112L` 时把 `_Static_assert(condition, message)` 展开成 `typedef char <唯一名>[(condition) ? 1 : -1]`——条件为假时数组宽度为负,编译直接失败, 没有任何运行期开销。C11 及以上的目标仍走原生断言。 全目录 **43 处**断言调用点全部保留,**每条断言条件都没改过**(唯一变动是 SOE 容量守卫的 提示文字随容量宏改数字,而 C99 下该文字本来就被 shim 丢弃,语义不动)。 ### 3.2 SOE 深度取 128 而非上游的 256 SOE(Sequence of Events,事件顺序记录)深度的两个容量宏 `IEC104_TCP_SOE_CAPACITY` 与 `IEC104_ASDU_SOE_MAX_CAPACITY` 都设为 `128U`, 是为了守住 RAM 预算。协议标准本身**不规定** SOE 深度;本项目采信的数值下界是 瑞典 Svk TR02-04-04 §7.4.1 建议的 ≥100 条,因此 128 合规。 断言条件 `SOE_CAPACITY == ASDU_SOE_MAX_CAPACITY` 未被改动,它守的不变式仍然成立。 ### 3.3 遥控点表元素 12 B → 8 B,为的是放进 const Flash `104/business/IEC104_Command.h` 的点表结构去掉了每点各自携带的 `common_address` (公共地址,下文简称 CA),元素从 12 字节降到 8 字节,使整张表能作为 `const` 常量驻留 Flash 而不是占静态 RAM。 代价是 CA 不再逐点存储,改为**实例级绑定**:`IEC104_Command` 在首个被接受的请求时绑定本站 CA,此后 `Find_Point` 在二分查找前先比对 CA,不匹配直接走与「未知 IOA(信息对象地址)」 相同的拒绝路径。所以「CA 不匹配」与「点不存在」对外表现一致——这是设计选择,不是疏漏。 点表按 IOA 严格升序排列,同一 IOA 只允许一项。 ### 3.4 枚举区间判断用无符号上界比较 `104/IEC104_SendManager.c` 与 `104/business/IEC104_Spontaneous.c` 里,非负枚举的区间 校验写成 `(unsigned)x >= (unsigned)上限` 而不是 `x < 0 || x >= 上限`。原因:负数转无符号后 会落到有效范围之上,照样被拒(语义不变),但 AC5 不再报「无意义的有符号/无符号比较」诊断。 这是为了让编译零警告,不是改变判定逻辑。 ### 3.5 `104/IEC104_TcpServer.c` 的显式类型转换 把字节宽度的环形队列头展开进事件校验辅助函数时,有三处显式 `IEC104_TcpEventType_t` 转换:两个校验辅助函数的调用点(`Event_Payload_Length_Valid`、`Is_State_Event`) 与展开后的 `copy.type` 赋值。环里存的是 `uint8_t`,公开结构里是枚举,不加转换 AC5 会因 隐式转换告警。条件、容量、存储布局与运行行为均未改变。 ### 3.6 `common/IEC60870_FaultEvent.c` 是链接依赖,不是可选模块 `IEC104_Spontaneous_Publish_Fault_Event`(`104/business/IEC104_Spontaneous.c`)在发布路径上 调用 `IEC60870_FaultEvent_Encode()`,因此 `common/IEC60870_FaultEvent.c` **必须一起编译链接**, 缺了就是链接期未定义符号。 它实现的是 Type42 故障事件的扩展布局(两组异构记录 + 报文体内计数),不属于基础标准定义。 ## 4. 容量覆盖面(构建期可调,不用改源码) 十一个模块级容量宏都用 `#ifndef` 包着,因此构建时可以直接 `-D` 覆盖, **不必编辑任何源文件**——MCU 骨架档靠这个把工作队列压小,而模拟器保留全部业务模块。 | 宏 | 默认值 | 所在文件 | | --- | --- | --- | | `IEC104_INTERROGATION_TASK_CAPACITY` | `4U` | `104/business/IEC104_Interrogation.c` | | `IEC104_INTERROGATION_EVENT_CAPACITY` | `4U` | `104/business/IEC104_Interrogation.c` | | `IEC104_SYSTEM_COMMAND_TASK_CAPACITY` | `4U` | `104/business/IEC104_SystemCommand.c` | | `IEC104_SYSTEM_COMMAND_RESET_CAPACITY` | `4U` | `104/business/IEC104_SystemCommand.c` | | `IEC104_PERIODIC_SCAN_GROUP_CAPACITY` | `4U` | `104/business/IEC104_PeriodicScan.c` | | `IEC104_PARAMETER_TASK_CAPACITY` | `4U` | `104/business/IEC104_Parameter.c` | | `IEC104_REMOTE_PARAMETER_TASK_CAPACITY` | `2U` | `104/business/IEC104_RemoteParameter.c` | | `IEC104_CLOCK_SYNCHRONIZATION_TASK_CAPACITY` | `4U` | `104/business/IEC104_ClockSynchronization.c` | | `IEC104_READ_TASK_CAPACITY` | `4U` | `104/business/IEC104_Read.c` | | `IEC104_COMMAND_REPLY_CAPACITY` | `4U` | `104/business/IEC104_Command.c` | | `IEC104_SPONTANEOUS_CAPACITY` | `IEC104_TCP_SERVER_CAPACITY` | `104/business/IEC104_Spontaneous.c` | 调之前先知道两件事:① `IEC104_SPONTANEOUS_CAPACITY` 虽可覆盖但**省不下 RAM**——它的池元素是 回调与状态而非按容量分配的数组,所以骨架档让它留在默认值;② 这些宏调的是业务模块内部 单实例工作队列,**不涉及** TCP 服务池、SOE=128、k/w 窗口或并发语义,因此改动它们不影响 92% RAM 门禁的口径。任何容量调整前先按 `docs/内存管理/` 的方法核算。 ## 5. 构建注册与平台后端 新增或删除本目录的 `.c` 必须**双端同步**,两个构建系统都是显式文件清单,不会自动发现: - Keil 工程:`MDK-ARM/STM32F407-Demo.uvprojx` - 模拟器:`simulator/CMakeLists.txt` 的 `IEC104_SOURCES` 注册纪律与动作 → `new-source-file` skill。 **一个目标只能链接一个 Net 后端**:板端用 `104/iec104_net_mcu.c`(经 CH395F), 模拟器用 `104/IEC104_Net_Windows.c`,两份实现同一个 `IEC104_Net` ABI。 两者同时链接会得到重复符号,或更糟——静默链到错的那份。 ## 6. 改动纪律 改这个目录的代码时: - **按项目规范改**,不必迁就上游写法;命名、注释、结构以 `docs/代码规范/` 为准。 - 动数据来源看 `iec104_source.c`,动协议行为看 `IEC104_*`,两者别混在同一个改动里。 - 不许为了消警告把断言、品质位或门禁关掉;SOE 与窗口容量要改,先按 §4 的方法核算并留证据。 - 编码规范门禁对本目录**暂时豁免**(`.pre-commit-config.yaml` 的 `coding-standard` 排除项): 约 1,200 处标识符驼峰(RULE-10)改造尚未进行,属单独排期;豁免不是永久状态, 那批改造完成后必须删除排除项。 ## 7. 权属与许可 **本目录的代码是团队自有代码,项目拥有完整处置权**:可以按本仓规范自由修改命名、注释、 结构与实现,不需要为「保持与上游一致」做任何妥协,也不再有逐字节校验拦路。 仓库根的 `IEC60870-Slave/` 是另一件事:它是收编前的原始快照,**仅作独立验证基线保留**, 其原始许可状态未经确认,与本目录的权属不是一回事——不要因为本目录已收编就认为那份基线 也可以自由分发。要在本目录之外复用那边的代码,先确认许可。 ## 8. 相关文档 - 板端设计与落地结论 → `docs/子系统设计/IEC104上行设计说明.md`、`docs/子系统设计/IEC104_MCU落地规划.md` - 网络层阻塞模型与 `netTask` 调用边界 → `docs/网络/Net层阻塞模型架构设计.md` - Net 适配契约(LISTEN/CLIENT 双句柄、代次不变式)→ `docs/网络/IEC104_Net适配契约.md` - 目录总览 → [`App/README.md`](../README.md)