wandering1/STM32F4-Base
1
0
Fork 0
Code Issues 30 Pull Requests Actions Packages Projects 2 Releases Wiki Activity
Files
59da40bb4a53db082953164a9d7c58bb342f8c19
STM32F4-Base/App/algo/README.md
T
wandering1 3528644e9d feat(采集标定): 卡2 adc_cal 折算模块 + 卡4 系数落盘 + L5-2 码值贴轨检出 
卡 2（App/algo/adc_cal.*，新增；adc_task.c:335 折算点收口）：
- 模型：工程量 =(code+b)×k（「数据可信」§4.1）；k 以 int32 Q16(µV/码×65536)
  落盘、b 以 int32 码值落盘；ROM 默认 = 卡 1 定死的引脚侧 LSB，Q16 下整除无
  舍入（TPAFE 10,000,000=152.587890625 µV/码；STM32 52,800,000=805.6640625）
- adc_task 每拍 frame[s] 改 adc_cal_apply()（现单位 = ADC 引脚电压 V，eng=0，
  二次值语义等 VALID）；TEMP 透传码值（决策 5）；不缓存 k_f 副本——逐点由
  RAM 现值派生（无回调设计下杜绝陈旧系数；18k flops/s 可忽略）
- 三态 flags（§4.2）：VALID = 文件位图 ∧ k 在合法带；CLIPPED 按来源运行期
  派生（V0.2/N-18 后自动恒 0）；消费者判可用性只查 adc_cal_flags()
- 合法带哨兵：k∉ROM×[0.5,2.0] 或 |b|>8192 → 折算回退 ROM + 每通道每开机
  一条 [ERR] + VALID 压制（位图说谎也兜住）——同时挡坏文件与坏标定
- 两点标定公式 adc_cal_two_point() 算术核齐备（int64、±舍入界、斜率/零点
  守卫 -1/-2 分档）；台架两点标定（卡 12）按用户指示未跑，留台架注入口径：
  心跳新增 cal: 行（ua/un/ia_mv 定点 + vl/cl/rail 位图，未标定 vl 应恒 0x00、
  cl 应恒 0xE6，注入饱和电平 rail 位应起）

卡 4（[adc_cal] k_ua..k_in+valid / [adc_cal_ofs] b_ua..b_in，§4.4 布局）：
- 两段注册进 cfg 引擎（data_size 33/32，不挂回调——RAM 副本即生效值）；
  adc_cal_init() 落 app_main_init 内核前（注册必须先于 defaultTask 的
  cfg_file_load；跨任务读走 4 字节对齐字，µs 级混窗为「数据可信」§4.4 明载
  设计）；文件缺失/损坏 = 引擎回退工厂默认 = ROM 表本体（默认即理论系数）
- adc_cal_set()：整定写入口（属主上下文），越带拒绝 RAM 不动
- 单测走真实 cfg_file 引擎集成：文件值生效 / 越界 k 哨兵兜住且不报 VALID /
  超长损坏文件回退默认且 flags 无 VALID（卡 4 DoD 原句）/ 段缺失默认

L5-2（adc_health v1.2，越界门限按 FS 百分比、码值域与标定正交）：
- adc_health_rail_watch()：连续 20 拍（=一周波）贴同侧轨带（TPAFE±98%半量程、
  STM32 顶 98%/底 2%，门限由 adc_cal_rail_ths 供）且此前见过中带释放沿才
  锁存——空载恒 0 / 开机恒 0 合法工况不误报（短板评测 §6.2 判据①）；
  adc_task 编排：边沿 DBG_ERROR + SYSLOG 每开机一次 + 心跳 rail/edge 位图
- 健康用例 60/60（+13）：释放沿/清零/交替/双侧/init 复位/越界通道守卫

测试与注册：新套件 test/host/adc_cal（89/89，8 通道×≥3 码点期望值由 LSB
常数独立推导、Q16 无舍入、set 边界含端点、两点还原合成 k/b 往返）；
编号形态返工一轮：TC-ADCCAL-00A~00D 改 014~017、注释 FS-1 字样改写、
id_registry 族 pattern 转义修正、族游标登至 017；coding-standard 返工：
公开实现函数补齐函数头注释块（CODE-RULE-09）
uvprojx 仅增 adc_cal.c 一条挂载（diff 已核零抖动）；SIM_EXEMPT/id_registry
(TC-HOST-ADCCAL 族)/adc-cal-unit-test 钩子行按 new-source-file 与 B 层口径
补齐；覆盖率 34/34 套件 89.6%，adc_cal.c 99.2%（baseline --update 属共享
台账文件，留 lead done 后统一回填）

gate：@build 0 错 0 警（Code=215440 RO=19780 RW=1220 ZI=131980）；
RAM 增量 +144 B（RW+16/ZI+128：贴轨 9×6B + 两段 RAM 副本，IRAM1 57.7%→
约 57.8%）；Flash +1336B/+920B RO。adcTask 栈 worst=1344B margin 1216B
(47%) PASS（stack_report 实测）。staged 门禁除 mem-numbers/mem-budget 外
全绿（该两条 = 台账漂移，回填 --write 落 docs/内存管理/** 单写者区，按
Lead 既定例外归 lead done 后处理）：
gate: only mem-budget/mem-numbers pending lead ledger backfill
BOM/CR/U+FFFD/字面量 ASCII 已逐文件自查（本次未触碰任何带 BOM 文件）
2026-10-25 04:21:12 +08:00

13 KiB
Raw Blame History

App/algo/ — 采集与算法层（L1 / L2 / L3）

本目录的索引：文件清单、依赖、逐文件的"改代码必须知道"、构建与测试入口、新增模块动作。 详细设计——机制、契约、判据、为什么这样设计 → docs/算法/采集与算法层设计说明.md（本文不复制其内容）。 分层归属与功能项状态 → docs/算法/继电保护功能复现规划.md §2.1； 通道映射唯一权威 → docs/硬件平台/ADC通道映射说明.md；采样节拍 → docs/子系统设计/ADC采样节拍设计说明.md。

1. 文件清单（一眼版）

文件 层 作用（一句话） 主要对外入口 覆盖规划项
adc_input.h / .c L1 统一语义取数：两片转换器的码值按语义（UA…IN / 温度）暴露，并消费 STM32 ADC1 的 DMA 乒乓缓冲 adc_input_init() adc_input_poll() adc_input_raw() L1-2 / L1-3 / L1-4
adc_health.h / .c L1 采样有效性判定：吃计数快照，产出静默 / 丢帧 / 单调性 / 错误增量故障位（判定与告警编排分离）；L5-2 残余的码值贴轨观察器同层 adc_health_check() adc_health_flags() adc_health_rail_watch() L1-6 / L5-2（残余）
adc_cal.h / .c L1.5 通道标定折算（「数据可信」卡 2/卡 4）：工程量 =(code+b)×k，Q16 系数/零点两段落盘 + 三态 flags + 合法带哨兵 + 两点公式 adc_cal_apply() adc_cal_flags() adc_cal_set() L1-5（M4 半边）
sample_ring.h / .c L2 输入 按语义通道存最近 2 周波（40 点），供相量层"以当前时刻为终止"取窗 sample_ring_push_frame() sample_ring_window() L2 输入（为 L2-6 供数）
phasor.h / .c L2 全周傅氏：一周波 20 点 DFT → 基波 / 谐波相量（有效值口径），双区原子切换供无锁读 phasor_run() phasor_get() phasor_calc() L2-1 / L2-2 / L2-3 / L2-6 / L2-7
freq.h / .c L2 派生量 频率测量：相邻两拍基波相量共轭乘积取角 + 自适应窗滑动平均 + 假值钳制 + 幅值门（UA→IA 源回退） freq_run() freq_get() freq_valid() L3-5 测量侧（测频范围 → docs/算法/继电保护功能复现规划.md §4.2）
prot_set.h / .c L3 输入 保护定值模型：Q10 定点 RAM 表 + 范围校验 + 校验和封存 / 自检 / 闭锁 + 持久化 blob 纯逻辑 prot_set_load_raw() prot_set_get_f() prot_set_selfcheck() L5-1 载体
prot_elm.h / .c L3 保护元件框架：通用"越限 + 返回系数滞回 + 定时限"核 + 数据驱动实例表（过流三段 / 过负荷 / 过压 / 欠压 / 零序过压 / 过频 / 低频） prot_elm_run() prot_elm_eval() prot_elm_active_mask() L3-1 / L3-3 / L3-4 / L3-5 / L3-6（软件侧）

依赖（自下而上、无环）：adc_input.h（纯枚举 + 声明）← adc_cal（另依赖 cfg_file.h 接口， 纯头文件级）← sample_ring ← phasor ← freq； prot_set 独立；prot_elm ← prot_set + phasor + freq。 adc_health 只吃调用方喂进来的计数 / 码值，不反向依赖 L1 实现（L5-2 贴轨门限由调用方 从 adc_cal_rail_ths() 取，本层仍零算法依赖）。

除 adc_input.c 外全部零平台依赖（只用 stdint.h / math.h / stddef.h 与本目录头） → 可被主机单测 #include 原样纳入、免桩跑。adc_input.c 另依赖 adc.h（hadc1）与 tpafe5160.h（快照），主机侧以桩头替身。

2. 一拍的数据流（一眼版）

adc_input_poll() → adc_input_raw() ×9 → adc_cal_apply() ×9（L1.5 折算，现口径 = ADC 引脚电压 V）+ adc_health_rail_watch() ×9（L5-2，码值域）→ sample_ring_push_frame() → phasor_run() → freq_run() → 消费者（adcTask 心跳与 L1 健康判定；protectTask 每 20 ms 取相量 / 频率跑 prot_elm_run()）。节拍 = TIM3 1 kHz 更新事件，两片转换器同源触发。 完整数据流图与初始化落点 → docs/算法/采集与算法层设计说明.md §2。

3. 逐文件要点（只留"改代码时必须知道"的；机制与理由见设计文档）

改本目录前先记五条红线：① 取数只经 adc_input_raw()，不写死下标；② 禁止跨转换器做 相位 / 功率 / 矢量运算（N-18）；③ 帧值已是 L1.5 工程量，但 未标定（adc_cal_flags() 无 VALID）时单位只是 ADC 引脚电压，不是端子二次值——下游消费精度判据见「数据可信」§4.2 三态 表；④ 工程量 → 帧的唯一折算点是 adc_cal_apply()，禁止旁路再乘系数；⑤ 本层不建任务、 不等事件、不写日志（adc_cal 的 [ERR] 哨兵留痕是唯一例外，且每通道每开机一次）， *_init() 才可在内核前调。 全文 → docs/算法/采集与算法层设计说明.md §10。

3.1 adc_input.c / adc_input.h — L1 语义取数

  • 语义映射表 k_adc_map[] 的内容唯一权威是 docs/硬件平台/ADC通道映射说明.md；V0.2 改版只改表内容，API 不动。
  • adc_input_poll() 仅任务上下文（TPAFE 快照是临界区）；STM32 侧固定滞后 1 拍。
  • 四类 STM32 计数（adc1_seq / adc1_gap / adc1_err / adc1_hw）成因不同，勿混读。
  • 本目录唯一允许出现 HAL 调用的文件。→ docs/算法/采集与算法层设计说明.md §3。

3.2 sample_ring.c / .h — L2 输入采样环

  • 整帧写入后才推进写指针 → 取到的窗永远落在整帧边界。
  • 本拍取数失败 → 整拍跳过入环（adc_task.c 的 skip），绝不补 0 点。
  • 不做跨通道运算、不做丢帧判定（只出 frames() 计数）。→ docs/算法/采集与算法层设计说明.md §5。

3.3 phasor.c / .h — L2 相量计算

  • 系数表预乘 √2/N → fAmSQ 直接是有效值（口径 docs/算法/傅氏算法详解.md §2.3）。
  • 实例表 k_inst[] 数据驱动：新增实例只在表尾加一行。
  • 任一实例不足一周波 → 本拍整体不产出（不切使用区）；每拍 20 点全部重算（不做增量递推）。
  • → docs/算法/采集与算法层设计说明.md §6。

3.4 adc_health.c / .h — L1 有效性判定

  • 三类位严格分开：电平（可自愈）/ 锁存（必留痕）/ 边沿事件（仅当拍）；静默 ≠ 丢帧。
  • gap 不告警（消费者超拍是已知现象）；告警编排在 adc_task.c，不在本层。
  • 首拍 check() 只建基线。→ docs/算法/采集与算法层设计说明.md §4。

3.5 prot_set.c / .h — 保护定值模型（L5-1 载体）

  • 装载 all-or-nothing：任一项越界整表不装载，越界项由 prot_set_bad_mask() 指认。
  • 批量 prot_set_set() 后必须 prot_set_seal()；单项原子写用 prot_set_set_sealed()。
  • 定值项 / 实例只许尾部追加（枚举序 = 数组序 = 校验和覆盖序）。
  • blob 换代（返回 2）≠ 损坏（返回负）：前者打 INFO、不记自检。→ docs/算法/采集与算法层设计说明.md §8、§12.3。

3.6 prot_elm.c / .h — L3 保护元件框架

  • 数据缺失两种处理刻意不同：相量类任一未就绪 → 整拍跳过；频率类无有效读数 → 按方向填"必不启动"值，不整拍跳过。
  • prot_set_locked() 或投退 = 0 → 元件整体复位不判据；跨上下文复归走 prot_elm_request_reset()。
  • 零序过流（IN 走 STM32）故意不在实例表；OF / UF 无独立 104 遥信点，只经 YX15 总聚合可见。
  • prot_elm_init() 须在 phasor_init() 之后。→ docs/算法/采集与算法层设计说明.md §9。

3.7 freq.c / .h — 频率测量（L3-5 的测量输入）

  • freq_run() 仅 adcTask 上下文，须在 phasor_run() 之后同拍调；保护口径 = freq_get() == 0 && freq_valid() == 1。
  • 精度靠自适应窗长（窗长 = 泄漏纹波周期的整数倍）；定长平均压不到 0.02 Hz， 换窗长 = 换精度，二者不是独立旋钮。
  • 源切换即废相位基准重建（UA / IA 无共同相位基准，N-18）。
  • 判据 J1~J6 与实测口径 → docs/算法/采集与算法层设计说明.md §7.2（与 test/host/freq/freq_test.c 文件头同源）。

3.8 adc_cal.c / .h — L1.5 通道标定折算（「数据可信」卡 2 / 卡 4）

  • 折算模型：工程量 = (code + b) × k；k 落盘用 int32 Q16（µV/码 × 65536）、b 用 int32 码值（负零点靠 CFG_VAL_INT）——单位与定点格式的选型依据见 docs/任务规划/数据可信.md §4.1，勿改回 V/码 直存（Q16 只剩 20 个刻度）。
  • ROM 默认 = 卡 1 定死的引脚侧 LSB（TPAFE 152.59 / STM32 805.66 µV/码， docs/硬件平台/ADC通道映射说明.md §7.1）；表下标 = 语义枚举（UA0…IN7）， V0.2 改版与本目录 adc_input 映射表同步改。
  • 三态可用性 adc_cal_flags()：VALID（已按变比标定，二次值成立——卡 0b/12 前恒 0） / CLIPPED（运行期按来源派生，V0.2 后自动清零）。消费者判「能不能信」只许查它， adc_cal_apply() 不返回可用性（「数据可信」§8 风险表）。
  • 合法带哨兵：k ∉ ROM×[0.5,2.0] 或 |b| > 8192 → 折算回退 ROM + 每通道每开机一条 [ERR] + VALID 被压制（即便文件位图说已标定）；这层兜底同时挡坏文件与坏标定。
  • adc_cal_set() / adc_cal_two_point()：整定与两点公式的算术核已齐备（单测还原合成 k/b）；台架两点标定（卡 12）待实测，本层不含注入。
  • cfg 两段 [adc_cal] / [adc_cal_ofs] 不挂回调（RAM 副本即生效值，引擎 load/poll 原地改写，逐点现读）；注册在 app_main_init() 内核前完成，必须先于 cfg_file_load。

4. 构建与测试

4.1 挂载与模拟器边界

  • 八个 .c 已登记在 MDK-ARM/STM32F407-Demo.uvprojx；../App/algo 已在 <IncludePath> 内。
  • 本层不进 simulator/CMakeLists.txt（UI 模拟器不跑采集链路）：八个文件全部登记在 scripts/check_registration.py 的 SIM_EXEMPT（附理由），registration-check 钩子反向校验（N-23）。

4.2 主机侧单测（L0.5）——生产源文件以 #include 原样纳入

模块 命令 pre-commit 钩子
相量 / 采样环 & '.venv\Scripts\python.exe' test/host/phasor/run_unit_test.py phasor-unit-test
ADC 输入层 & '.venv\Scripts\python.exe' test/host/adc_input/run_unit_test.py adc-input-unit-test
有效性校验 & '.venv\Scripts\python.exe' test/host/adc_health/run_unit_test.py adc-health-unit-test
定值模型 & '.venv\Scripts\python.exe' test/host/prot_set/run_unit_test.py prot-set-unit-test
元件框架 & '.venv\Scripts\python.exe' test/host/prot_elm/run_unit_test.py prot-elm-unit-test
频率测量 & '.venv\Scripts\python.exe' test/host/freq/run_unit_test.py freq-unit-test
通道标定（含真实 cfg_file 引擎集成） & '.venv\Scripts\python.exe' test/host/adc_cal/run_unit_test.py adc-cal-unit-test

改本目录任一 .c/.h，提交时对应钩子自动跑。用例清单与判据数字的属主是各 test/host/<模块>/ 与 docs/测试说明/ 下的单测说明，本文不复制（三处抄数字必然打架）。

4.3 板端

@build 0 错误 0 警告 → @test 看 [ADC_TASK] 首拍 / 心跳（phasor(...)、freq(...)、 cal: ua_mv=… vl=0x00 cl=0xE6 rail=…、ring / skip / adc1_* / tgap）； 健康判据 = 零 [ERR]（健康告警与标定哨兵全以 [ERR] 开头，误报会被闭环直接抓住； vl 在未标定默认构建必须为 0x00，卡 5 闭锁落地后 cal: 行就是台架期望的直接证据）。 → docs/算法/采集与算法层设计说明.md §12。

5. 新增一个算法模块的固定动作

  1. 在本目录建 xxx.c/h，文件头写模块注释块（规范 V1.0），尽量零平台依赖以便免桩单测。
  2. 用 new-source-file skill 注册到 MDK-ARM/STM32F407-Demo.uvprojx（新建子目录还要补 <IncludePath>）。 模拟器侧二选一：有消费路径 → 加 simulator/CMakeLists.txt；纯算法无消费路径 → 加 scripts/check_registration.py 的 SIM_EXEMPT（照本目录既有七条写理由），否则 registration-check 拦。
  3. 加 test/host/<模块>/ 主机单测 + .pre-commit-config.yaml 钩子（照 phasor-unit-test 抄）。
  4. 消费者写在 App/task/，本层只出"数"；跨转换器禁令见 §3 开头四条红线。
  5. 在本 README §1 清单加一行，并在 docs/算法/采集与算法层设计说明.md 里写清该模块的契约与理由。

6. 相关文档

  • 本层设计与判据：docs/算法/采集与算法层设计说明.md
  • 通道映射权威口径：docs/硬件平台/ADC通道映射说明.md
  • 分层与功能项清单：docs/算法/继电保护功能复现规划.md
  • 傅氏算法与有效值口径：docs/算法/傅氏算法详解.md
  • 采样节拍（TIM3 1 kHz + TRGO 触发 ADC1 / DMA）：docs/子系统设计/ADC采样节拍设计说明.md
  • 相量层 / ADC 输入层单测细则：docs/测试说明/相量层单元测试说明.md、docs/测试说明/ADC输入层单元测试说明.md
  • RAM 与栈台账：docs/内存管理/RAM使用分析与优化方案.md
Reference in New Issue View Git Blame Copy Permalink