wandering1/STM32F4-Base
1
0
Fork 0
Code Issues 30 Pull Requests Actions Packages Projects 2 Releases Wiki Activity
Files
dd8210867aefe6f3bc7d8063b994f2be7a76e825
STM32F4-Base/App/algo/README.md
T
wandering1 9231a3c22c adcTask 事件驱动消费（P1-5 方案 a）+ 补 F4 ADC 上电自校准 + 修正 2 ms 忙等过期表述 
P1-5 方案 a（事件驱动消费，Task #32）：
- TIM6 1 kHz ISR 除触发 CONVST 外再调 adc_tick_irq_notify()，置位
  ADC_WAKE_FLAG；adcTask 循环尾改 osThreadFlagsWait(osWaitForever)，
  删除 ADC_TASK_BEAT_MS 定时轮询
- adcTask 优先级 Normal(24) -> AboveNormal(32)（Src/freertos.c USER CODE 区）
- 补消费者就绪门（规划未预见）：TIM6 在 app_main_init 就启动，比调度器
  早约 100 ms，未就绪时 ISR 不得 osThreadFlagsSet
- 实测 6 次上板：idle 由 1~649 降到 0/20000 拍，frames 1000.0 Hz，
  seq-frames=7 正是就绪窗口；UI 侧 uip/uiw/uis 无退化

补 STM32F4 ADC 上电自校准（此前项目从未做过）：
- 核查证实裁剪版 HAL 无 HAL_ADCEx_Calibration_Start、裁剪版 CMSIS 头无
  ADC_CR2_CAL -> 按 RM0090 13.3.6 在 Src/adc.c 的 USER CODE 区手写
  adc1_calibrate()，MX_ADC1_Init() 末尾调用
- 新增 cubemx-survival 审计项 adc1-calibration-call / -impl（清单 21->23）
- 实测校准前后同一拍 STM32 侧 6 路同向偏移 +10~+63 LSB，TPAFE 侧不变

修正两处过期表述（实测反证）：
- 原文 9 通道全超时最坏 = 18 ms 连占 有误：stm32_scan() 在首个超时处即
  Stop+return，单拍上界 = 一次超时约 2~3 ms
- adcm 约 2.1 ms 的峰值归因由 ADC 采集改判为每 10 s 一次的心跳日志；
  6 次对照 adcp = 122 us（无超时）/ 2209 us（超时 1 次）
- 同步修正 adc_task.c 两处过期注释；新发现超时拍 STM32 侧静默沿用
  上一拍值的正确性代价，硬化排序记入 4.4 / 10.4（未实施）

验证：@build 0 错 0 警（Code 256728 -> 256868）；@test 6/6 PASS；
stack_report 7 任务全 PASS（adcTask 832 B / 余 59%）；18 钩子全绿
2026-10-10 22:41:19 +08:00

170 lines
12 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.
# App/algo/ — 采集与算法层（L1 / L2）
> **自研代码**，属 `docs/算法/继电保护功能复现规划.md` §2.1 分层中的 **L1（采集与预处理）**
> 与 **L2（相量计算）**。原则：**算法与 I/O、与调度分离**——本层不建任务、不做保护判据、
> 不碰寄存器（唯一例外见 §3.1），只做"数"（原始码值 → 语义通道）与"相量"
> （采样序列 → 复相量），因而可被主机侧单元测试（L0.5）离线全覆盖（落实登记簿 **A-4**）。
>
> 任务侧（`App/task/adc_task.c`）只做**消费与编排**；任何新算法一律落在本目录，勿塞进 `App/task/`。
## 1. 文件清单（一眼版）
| 文件 | 层 | 作用（一句话） | 主要对外入口 | 覆盖规划项 |
|---|---|---|---|---|
| `adc_input.h` / `adc_input.c` | L1 | **统一语义取数层**：把两片转换器的原始码值按语义（`UA…IN`/温度）暴露，并驱动 STM32 ADC1 9 通道顺序扫描 | `adc_input_init()` `adc_input_poll()` `adc_input_raw()` | L1-2 / L1-3 / L1-4 |
| `sample_ring.h` / `sample_ring.c` | L2 输入 | **采样环缓冲**：按语义通道保存最近 2 个周波（40 点）采样值，供相量层"以当前时刻为终止"取窗 | `sample_ring_push_frame()` `sample_ring_window()` | L2 输入（为 L2-6 滑动窗供数） |
| `phasor.h` / `phasor.c` | L2 | **全周傅氏相量计算**：一周波 20 点单频 DFT → 基波/谐波相量（有效值口径），双区原子切换供无锁读 | `phasor_run()` `phasor_get()` `phasor_calc()` | L2-1 / L2-2 / L2-3 / L2-6 / L2-7 |
依赖关系（自下而上，无环）：`adc_input.h`（纯枚举 + 声明）← `sample_ring` ← `phasor`。
`sample_ring.c` / `phasor.c` **零平台依赖**（只用 `math.h` / `stddef.h` 与本目录头）；
`adc_input.c` 另依赖 `adc.h`（`hadc1`）与 `tpafe5160.h`（快照），主机侧以桩头替身。
## 2. 数据流（一拍 = TIM6 1 kHz 节拍）
```mermaid
flowchart TD
TIM6["TIM6 更新中断 1 kHz<br/>Src/main.c → tpafe5160_start_conv_irq()<br/>+ adc_tick_irq_notify()"] --> TPAFE["TPAFE5160 转换<br/>BUSY EXTI 收帧"]
TIM6 -. "ADC_WAKE_FLAG<br/>osThreadFlagsWait" .-> TASK
TPAFE --> POLL
TASK["adcTask（事件驱动唤醒，非定时轮询）<br/>App/task/adc_task.c"] --> POLL["adc_input_poll()<br/>TPAFE 快照 + STM32 ADC1 9 通道扫描"]
POLL --> RAW["adc_input_raw(ch) × 9<br/>按语义取原始码值"]
RAW --> RING["sample_ring_push_frame()<br/>整帧入环（40 点窗）"]
RING --> RUN["phasor_run()<br/>逐实例 20 点重算 + 双区切换"]
RUN --> GET["phasor_get(idx)"]
GET --> CONS["消费者：adcTask 日志（现状）<br/>UI / 自检 / L3 保护任务（待接）"]
```
初始化落点：`adc_input_init()` 与 `phasor_init()` 由 `App/app/app_main.c` 的
`app_main_init()` 在**内核启动前**调用（三者 `*_init()` 均无 RTOS 依赖、幂等）；
`phasor_init()` 内部会连带 `sample_ring_init()`，等价于"刚上电"。
## 3. 逐文件说明
### 3.1 `adc_input.c` / `adc_input.h` — L1 ADC 输入层
**解决的问题**：V0.1 上 8 路电气量被两片转换器分片（硬件缺陷 **N-18**），且网名 `AINn`
≠ 板级 `ADCn` ≠ 转换器通道号（13/17 路置换）。若消费侧直接索引驱动缓冲，改版即全线错位。
本层把"哪一路"收进一张表，上层**按语义取数、不写死下标**。
| API | 干什么 | 注意 |
|---|---|---|
| `adc_input_init()` | 清缓冲与统计 + **映射表自检**（每个 STM32 语义通道必须落在扫描 Rank 序列内） | 内核启动前调用；返回 `-1` = 映射指向了从不扫描的通道（会恒读陈旧值） |
| `adc_input_poll()` | 采一拍：`tpafe5160_snapshot()` 原子快照（8 通道）+ STM32 ADC1 9 通道软件触发顺序扫描 | **仅任务上下文**（快照走临界区）；只搬码值，不做标定/运算 |
| `adc_input_raw(ch, &out)` | 按语义读原始码值（TPAFE 16 位补码 / STM32 0..4095） | 消费侧取数**唯一入口**；须先成功 `poll()`；`-2` = 该来源尚无有效数据 |
| `adc_input_desc(ch)` | 语义 → 物理通道描述（来源 + 下标/通道号） | 供自检注入、UI 通道序；返回静态地址，勿改 |
| `adc_input_stm32_rc()` / `adc_input_stm32_errs()` | STM32 侧最近扫描状态码 / 累计失败次数 | 心跳日志观测面（`adc1_rc` / `adc1_err`） |
**要点**
- 语义映射表 `k_adc_map[]` 的**唯一权威口径**是 `docs/硬件平台/ADC通道映射说明.md`：
`UA/UN/IA` → TPAFE `buf[6]/[5]/[2]`；`UB/UC/IB/IC/IN/TEMP` → ADC1 `CH14/3/6/1/2/5`。
**V0.2 改版只改这张表的内容**，本层 API 与上层语义不动。
- STM32 侧是**顺序扫描**（Rank1..8 = CH0..CH7、Rank9 = CH14，与 `MX_ADC1_Init()` 严格一致），
9 个通道**不是同一时刻**；单通道轮询超时 2 ms，超时判失败、绝不拖垮消费节拍。
- 本文件是本层**唯一**允许出现 HAL 调用的地方（它必须驱动 ADC1）；新增模块若不需要外设，
请保持 `sample_ring` / `phasor` 那种零依赖形态，才能免桩单测。
### 3.2 `sample_ring.c` / `sample_ring.h` — L2 输入采样环
**解决的问题**：相量计算要"以当前时刻为终止的一周波"，而 L1 每次只给最新一帧。
本层按**语义通道**存最近 `SAMPLE_RING_CYCLES = 2` 个周波（`SAMPLE_RING_DEPTH = 40` 点），
与参考系统 `CN_BUFSAM_CYCLE = 2` 一致，并为后续加长数据窗（1.5~2 周波抗衰减直流）预留空间。
| API | 干什么 | 返回 |
|---|---|---|
| `sample_ring_init()` | 清全部通道历史与计数（幂等，内核启动前可调） | — |
| `sample_ring_push_frame(values, n)` | 整帧压入（长度须 `= ADC_SEM_COUNT`） | `0` / `-1` 参数错 |
| `sample_ring_window(ch, n, out)` | 取该语义通道最近 `n` 点，**按时间序旧 → 新**（`out[n-1]` 最新） | `0` / `-1` 参数错 / `-2` 点数不足 |
| `sample_ring_filled()` | 已累积点数（**饱和**于 40）——判"够不够一周波" | `0..40` |
| `sample_ring_frames()` | 累计入环帧数（**不饱和**，1 kHz 下约 49.7 天回绕） | 帧数 |
**要点**
- **整帧写入后统一推进写指针** → 单帧内不可能"半新半旧"，消费侧取到的窗永远落在整帧边界。
- 本层**只做按时序存/取，不做任何跨通道运算**：同刻性由上游 L1 负责，本层既不保证也不假设。
- `frames()` 与 L1 的 `tpafe5160_frame_seq()` 对照即可判丢帧（L1-6 的判据之一）；
本层只提供计数，**判定不在这里**。
- 上层若某通道本拍取数失败，应**整拍跳过入环**（现 `adc_task` 的 `s_frames_skip` 即此），
切勿补 0 点——0 会污染相量窗。
### 3.3 `phasor.c` / `phasor.h` — L2 相量计算
**算法**：全周傅氏（单频 DFT），`N = PHASOR_N = 20`（1 kHz @ 50 Hz）。系数表
`k_fft_sin/k_fft_cos` **离线生成**并**预乘 √2/N**（口径 `docs/算法/傅氏算法详解.md` §2.3），
故 `fAmSQ = √(fRe²+fIm²)` **直接就是有效值**，`fAm = √2·fAmSQ` 为峰值。运行期不调 `sinf/cosf`。
| API | 干什么 | 注意 |
|---|---|---|
| `phasor_init()` | 双区清零 + 使用区/就绪复位 + `sample_ring_init()` | 幂等；内核启动前调用 |
| `phasor_inst_count()` / `phasor_inst(idx)` | 遍历实例表（`{name, sem, harm}`） | 返回静态地址，勿改；越界 `NULL` |
| `phasor_run()` | 逐实例取 20 点窗 → 重算 → 写计算区 → **一次性切换使用区** | 仅任务上下文；须先 `push_frame()` |
| `phasor_get(idx, &out)` | 读**使用区**结果 | `0` / `-1` 参数错 / `-2` 未攒满一周波 |
| `phasor_calc(x, n, harm, &out)` | 对给定窗口算 `harm` 次相量 | **纯函数**，可脱离采样环独立单测 |
**要点**
- **实例表数据驱动**（`k_inst[]`，现 5 行）：`C01-IA-F1`（过流/过负荷）、`C02-UA-F1`（过压/欠压/频率）、
`C03-UN-F1`（零序过压）、`C04-IA-F2`（二次谐波制动）、`C05-IA-F5`（五次谐波选线）。
**新增实例只在表尾加一行**，遍历/日志/单测自动适配。
- **双区（计算区 / 使用区）**：结果先写非使用区，全部实例写完后单字节 `volatile` store 切换
`s_use_zone`（Cortex-M 上原子）→ 消费侧无锁、无撕裂。今日唯一消费者是 adcTask 自身，
该机制为后续独立 L3 保护任务预留。
- **任一实例数据不足一周波 → 本拍整体不产出**（不切换使用区），避免"部分新部分旧"的混合结果。
- 每拍 20 点**全部重算**（暴力法，无累积误差；迭代加减首尾项会累积）。相量刷新周期 = 1 ms。
- 相位（L2-4）**未常驻**结构体，需要时自行 `atan2f(fIm, fRe)`。
## 4. 关键约定
- **语义映射唯一权威口径**：`docs/硬件平台/ADC通道映射说明.md`。取数一律经 `adc_input_raw()`，
禁止在消费侧直接索引驱动缓冲或写死下标。
- **禁止跨转换器运算**（V0.1 硬件缺陷 N-18）：`UA/UN/IA` 在 TPAFE、`UB/UC/IB/IC/IN` 在 STM32 ADC1，
两者无共同采样触发 → 无同一时刻性、相位不确定。故本层**不做**跨转换器的相位 / 功率 /
功率因数 / 负序零序类矢量运算（V0.2 把 8 路电气量全接 TPAFE 后方可解禁）。
- **标定（L1-5）尚未实现**（缺标准源）：现以**原始码值**充当工程量（系数 = 1），
因此相量读数只证明**链路通**，**不可作幅值精度判据**。
- **本层不建任务、不等事件、不写日志之外的副作用**；日志由调用侧（adcTask）打。
- 内核启动前只允许调 `*_init()`；`adc_input_poll()` / `phasor_run()` 仅任务上下文。
## 5. 静态足迹（BSS，供栈/RAM 预算参考）
| 位置 | 量 |
|---|---|
| `sample_ring.c` `s_ring[9][40]` float | **1440 B** |
| `phasor.c` `s_zone[2][5]` `phasor_t` | 160 B |
| `adc_input.c` `s_stm32_raw[16]` + `s_tpafe_raw[8]` | 48 B |
| 运行期栈：`phasor_run()` 的 `win[20]` | 80 B/帧 |
改容量（`SAMPLE_RING_CYCLES` / 实例数 / `ADC_SEM_COUNT`）前后各跑一次
`& '.venv\Scripts\python.exe' scripts/stack_report.py`（口径见 `mem-budget` skill）。
## 6. 构建与测试
- **挂载**：三个 `.c` 已登记在 `MDK-ARM/STM32F407-Demo.uvprojx`，`../App/algo` 已在 `<IncludePath>` 内。
本层**不进** `simulator/CMakeLists.txt`（UI 模拟器不跑采集链路）。
- **主机侧单测（L0.5）**——生产源文件以 `#include` 原样纳入，无需改产品代码：
| 套件 | 命令 | pre-commit 钩子 |
|---|---|---|
| 相量层（57 用例：系数表逐项复核 / 幅值·相位 / 谐波抑制与提取 / 频偏 / 采样环 / 双区交换） | `& '.venv\Scripts\python.exe' test/host/phasor/run_unit_test.py` | `phasor-unit-test` |
| ADC 输入层（逐 Rank 注入互异码值钉死映射 + HAL 启动失败/超时分支） | `& '.venv\Scripts\python.exe' test/host/adc_input/run_unit_test.py` | `adc-input-unit-test` |
改本目录任一 `.c/.h`，提交时对应钩子自动跑；详见 `docs/测试说明/相量层单元测试说明.md`。
- **板端**：`@build` 0 错误 0 警告 → `@test` 看 `[ADC_TASK]` 首拍/心跳日志（`phasor(...)` 行、
`ring` / `skip` 计数、`adc1_rc` / `adc1_err`）。
## 7. 新增一个算法模块的固定动作
1. 在本目录建 `xxx.c/h`，文件头写模块注释块（规范 V1.0），**尽量零平台依赖**以便免桩单测。
2. 用 `new-source-file` skill 注册到 `MDK-ARM/STM32F407-Demo.uvprojx`（目录已在 IncludePath，
若新建子目录则必须补 IncludePath）。
3. 加 `test/host/<模块>/` 主机单测 + `.pre-commit-config.yaml` 钩子（照 `phasor-unit-test` 抄）。
4. 消费者写在 `App/task/`，本层只出"数"；跨转换器运算的禁令见 §4。
## 8. 相关文档
- 通道映射权威口径：`docs/硬件平台/ADC通道映射说明.md`
- 分层与路线图（L1/L2 清单与状态）：`docs/算法/继电保护功能复现规划.md`
- 傅氏算法与有效值口径：`docs/算法/傅氏算法详解.md`
- 采样节拍（TIM6 1 kHz）：`docs/子系统设计/ADC采样节拍设计说明.md`
- 相量层单测细则：`docs/测试说明/相量层单元测试说明.md`
Reference in New Issue View Git Blame Copy Permalink