Files
STM32F4-Base/App/iec60870/common
wandering1 2053f6d913 docs(iec60870): 把 104 板端落地文档归入 docs/iec60870/板端落地
四篇讲「本项目怎么接 104」的文档原来散在子系统设计与网络两个目录,
和随库迁入的 36 篇协议库设计混在一起。现集中到 docs/iec60870/板端落地/:

- IEC104上行设计说明.md(原 docs/子系统设计/)
- IEC104_Net适配契约.md(原 docs/网络/)
- IEC104_MCU落地规划.md(原 docs/子系统设计/)
- IEC104_MCU最小可行性验证.md(原 docs/子系统设计/)

改动:
- 四篇 git mv 保留历史,全库引用经 rename_ref.py 逐篇改写(27 个文件
  54 处引用行),旧路径残留扫描为 0。
- docs/README.md:§5.3 改为「IEC 60870-5-104 文档(40 篇)」,拆成
  「板端落地 4 篇」与「协议库设计与接口 36 篇」两张表,说明两条轴的分工;
  从 §5.1 功能子系统表里移除这三篇的重复条目。
- docs/iec60870/README.md:新增两条轴入口与板端落地表,原阅读顺序
  改标注为「协议库部分」。

验证:
- check_doc_links.py --all --sections-strict:310 篇 0 问题。
- 三份索引 markdown 链接可达性逐个 exists() 校验,断链 0;索引表覆盖
  36 篇协议库文档,与实际磁盘文件双向差集为空。
- 板端落地目录 4 篇 BOM / CR / U+FFFD 均为 0。
- 工作树 Keil 权威构建 0 errors 0 warnings(Code=365896 RO=48336
  RW=2736 ZI=173104),此后预提交 21 Passed / 0 Failed。
2026-11-18 23:31:37 +08:00
..

common/ — 与传输无关的协议数据面

本目录放 104 协议里不关心网络怎么收发的那一半:ASDU 编解码、信息对象(遥信/遥测/遥控/ 累计量)的字段布局、时间表示。要改「报文内容长什么样」在这里;要改「报文怎么送出去」去 104/。这一层同时被 101(串口)等其它 IEC 60870-5 变体共用,所以它刻意不依赖任何网络类型。

1. 文件分工

文件 职责
IEC60870_Types.h 类型与参数基线:应用层参数结构(COT/CA/IOA 各自宽度)、长度上限
IEC60870_StaticAssert.h C99 编译期断言 shim,见 ../README.md §3.1
IEC60870_Asdu.h / .c ASDU 容器:公共头构造与字段读写(Type ID / VSQ / COT / CA)
IEC60870_Codec.h / .c 通用字节层编解码:小端读写、长度校验、视图借用
IEC60870_InformationObjects.h / .c 信息对象类型(Type 1~207)与品质位、CP56Time2a 等结构
IEC60870_Slave.h / .c 101/104 共用的子站发送接口(抽象层,用函数指针分派,不含 TCP/串口/队列/连接状态机,不分配内存);104 的具体实现是 104/IEC104_Slave.c
IEC60870_Time.h / .c CP56Time2a / CP16Time2a 编解码与整数公历换算(400 年周期展开、以三月为年内起点统一处理闰日;仅在 1970..2099 年范围内运算,不读 RTC、不执行校时)
IEC60870_FaultEvent.h / .c Type42 故障事件的扩展布局编解码,见 §2

2. 关键约束

FaultEvent 不是可选模块,是链接依赖。 104/business/IEC104_Spontaneous.c 的 IEC104_Spontaneous_Publish_Fault_Event() 在发布路径上调用 IEC60870_FaultEvent_Encode()。它实现的是 Type42 的扩展布局(两组异构记录共用链路 IOA 宽度、计数位于报文体),不属于基础标准定义的 Type42 对象——所以别拿标准 Type42 的 字节期望去比对它。

应用层参数必须两端一致。 IEC60870_AppLayerParameters_t 定义 Type ID / VSQ / COT / CA / IOA 各占几个字节以及 ASDU 上限。通用上限是 254;接入本工程 104 TCP 时固定用 IEC104_APP_LAYER_PARAMETERS_DEFAULT(COT=2、CA=2、IOA=3,ASDU 上限 249), IEC104_Slave.c 的 Parameters_Compatible() 会拒绝不匹配的配置。改了参数就等于改了线上 字节布局,主站侧必须同步——不存在自动协商。

断言条件一行都不许动。 全目录共 43 处编译期断言,本目录分布 3 处 (IEC60870_FaultEvent.c 1 处、IEC60870_InformationObjects.c 2 处),其余在 104/ 与 104/business/。改容量宏时断言条件(如 SOE_CAPACITY == ASDU_SOE_MAX_CAPACITY) 保持不变,它守的不变式才有意义。shim 本身见 §1 表首行。

3. 相关文档

  • 完整协议栈与目录总览 → ../README.md
  • 信息对象与品质位口径在平台侧怎么消费 → App/algo/meas.h 的 MEAS_QDS_* 注释
  • ASDU 头与 COT 宽度 → docs/iec60870/板端落地/IEC104上行设计说明.md