docs: 四文档同步更新至 V2.5

- devlog: 修订记录修正 30s→10s, 新增 V2.5 - release-notes: V1.6→V2.5, 新增 M4 优化特性 + 完整版本历程 - product-manual: V1.5→V2.5, 补充 V1.6~V2.5 版本历史 - technical-spec: V1.5→V2.5, 重写 §§4.2-4.5/5.2/12.1/13: - §4.2: 双路 IIR 架构（慢速基线 τ=135ms + 快速检测 τ=28ms） - §4.3.2: 进入确认机制（CAPVD_fast + ENTRY_CONFIRM=3） - §4.4: 斜率限幅 5% + 基线更新速率 1s (10ms tick) - §4.5: 冻结超时恢复演进史 V1.5→V2.5，完整逻辑 + 常量表 - §5.2: Tick 改为 10ms，新增 FREEZE_TIMEOUT 参数 - §12.1: 进入延迟 ~530ms，瞬态抑制，温漂 1s 补偿 - §13: 新增 M4 优化编译选项
2026-06-29 10:57:24 +08:00
parent df8e59803a
commit 935e11e006
4 changed files with 191 additions and 80 deletions
--- a/docs/technical-spec.md
+++ b/docs/technical-spec.md
@@ -1,6 +1,6 @@
 # DLD154V4B 技术规格书

-> 单路线圈车辆检测器 | 固件版本: V1.5 | 文档版本: V1.0  
+> 单路线圈车辆检测器 | 固件版本: V2.5 | 文档版本: V2.0  
 > 本文档面向工程开发、系统集成及故障深度分析

 ---
@@ -30,12 +30,14 @@
 ```
 FreeRTOS Kernel (CMSIS-RTOS v2)
 ├── loop_task (主检测任务)
-│   ├── vd1_task() — 每 5ms tick 执行
-│   │   ├── IIR 滤波 (ALFA_CAP1 = 79/256)
+│   ├── vd1_task() — 每 ~10ms 执行 (M4 优化)
+│   │   ├── 双路 IIR 滤波 (慢速 α=18/256, 快速 α=0.5)
+│   │   ├── 斜率限幅 (MAX_SLOPE_RATE=5%)
 │   │   ├── 基线跟踪 (100 窗口滑动平均)
-│   │   ├── 进入/离开检测
+│   │   ├── 进入确认 (ENTRY_CONFIRM=3 次)
+│   │   ├── 离开检测 (平坦性 / cnt_release)
 │   │   ├── 时序状态机 (IN/OUT/PULSE/HOLD)
-│   │   └── 平坦性离开判定 (CN200910309382)
+│   │   └── 冻结超时恢复 (10s + ±2% 稳定性检查)
 │   ├── poll_sw_state() — 拨码去抖
 │   ├── poll_green_led() — 绿灯驱动
 │   └── poll_yellow_led() — 黄灯故障编码
@@ -176,21 +178,47 @@ TMR3 ISR:

 **改进效果**：响应速度提升 16 倍，精度保留全部采样信息。

-### 4.2 IIR 滤波
+### 4.2 IIR 滤波（M4 优化：双路 IIR）
+
+V2.0 起采用双路 IIR 架构，将基线跟踪与检测判定解耦：

 ```c
-// α = Flt_Reg / 256 = 79 / 256 ≈ 0.3086
-if (Value > CAPVD)
-    CAPVD += ((Value - CAPVD) * 79) >> 8;
-else
-    CAPVD -= ((CAPVD - Value) * 79) >> 8;
+#define ALFA_CAP1  18      // 慢速 IIR: α = 18/256 ≈ 0.07, τ≈135ms
+#define ALFA_FAST  128     // 快速 IIR: α = 128/256 = 0.5, τ≈28ms
+```
+
+| 滤波器 | α | τ @10ms | 输入 | 用途 |
+|--------|---|---------|------|------|
+| CAPVD (慢速) | 18/256 ≈ 0.07 | 135ms | Value（经斜率限幅） | 基线跟踪 |
+| CAPVD_fast (快速) | 128/256 = 0.5 | 28ms | CAPVD（慢速滤波后） | 进入/离开检测判定 |
+
+**为什么需要双路：**
+- 基线跟踪需要**慢响应**，避免将车辆的频率偏移"学"进基线（τ=135ms，等效 M1H 的 79/256 @50ms）
+- 检测判定需要**快响应**，快速捕捉车辆进入/离开（τ=28ms，5× 快于旧设计）
+- 快速 IIR 输入来自慢速 IIR 的输出，继承斜率限幅的瞬态抑制能力
+
+**进入确认**：快速 IIR 连续 3 次低于阈值才判定有车，单次瞬态干扰被过滤。
+
+```c
+// 快速 IIR: α=0.5 → (old + new) / 2
+loop1_CAPVD_fast = (loop1_CAPVD_fast + loop1_CAPVD) / 2;
+
+// 进入确认
+if (CAPVD_fast < Origin - dlt_ORG) {
+    if (++entry_cnt >= 3)
+        VD_FLAG = 1;        // 确认有车
+} else {
+    entry_cnt = 0;           // 恢复到阈值以上则重置
+}
 ```

 | 参数 | 值 | 说明 |
 |------|-----|------|
-| α | 79/256 ≈ 0.3086 | 指数平滑系数 |
-| 响应速度 | ~3 次达 63% | ~15ms @5ms tick |
-| 噪声抑制 | 良好 | 单次野值影响 < 31% |
+| α_slow | 18/256 ≈ 0.07 | 慢速 IIR 指数平滑系数 |
+| α_fast | 128/256 = 0.5 | 快速 IIR 指数平滑系数 |
+| 慢速 τ | ~135ms | 等效 50ms tick 的 79/256 |
+| 快速 τ | ~28ms | 5× 快于旧设计 |
+| ENTRY_CONFIRM | 3 | 连续确认次数 |

 ### 4.3 检测判据

@@ -208,17 +236,29 @@ const uint16_t SensTable_1[4] = {108,  72,  18,   9};  // 离开阈值（滞回
 | 2 | 36 | 0.055% | 18 | 0.027% |
 | 3 (高) | 10 | 0.015% | 9 | 0.014% |

-#### 4.3.2 进入检测
+#### 4.3.2 进入检测（M4 优化：确认机制）

 ```c
-dlt_ORG = (Origin * SensTable[SENS]) >> 16;   // /65536
-if (CAPVD > Origin + dlt_ORG) {
-    // 频率上升超过阈值 → 有车
-    // 进入 IN_DELAY (500ms) 防抖
+// 使用快速 IIR (CAPVD_fast) 提高响应速度
+// 连续 ENTRY_CONFIRM 次低于阈值才判定有车
+if (CAPVD_fast < Origin - dlt_ORG) {
+    entry_cnt++;
+    if (entry_cnt >= ENTRY_CONFIRM) {  // 3 次连续确认
+        VD_FLAG = 1;  FLAG_IN = 1;
+        entry_cnt = 0;
+    }
+} else {
+    if (entry_cnt > 0) entry_cnt = 0;  // 恢复则重置
 }
 ```

-> **注**：有车时线圈电感减小 → 频率上升 → CAPVD > Origin。公式为 `CAPVD > Origin + dlt_ORG`（判定上升量）。
+| 对比 | 8051/M1H 旧设计 | M4 优化 |
+|------|----------------|---------|
+| 判定依据 | CAPVD（慢速 IIR） | **CAPVD_fast**（快速 IIR，5× 响应） |
+| 确认方式 | 单次阈值 | **连续 3 次确认** |
+| 瞬态抑制 | 无 | **斜率限幅 + 确认双重保护** |
+| 进入响应 | ~550ms (50ms tick + 500ms IN_DELAY) | **~530ms** (10ms tick + 3×10ms + 500ms) |
+| 误触发风险 | 中 | **低** |

 #### 4.3.3 离开检测（滞回）

@@ -272,20 +312,38 @@ if (CAPVD < Origin + dlt_ORG) {

 **整数化适配：** 专利原实现用 float（Hz 频率值），DLD154V4B 用 uint32 定点（Origin ≈ 131K）。导数计算用 int32 整数差分，阈值 /K1、/K2 做整数除法，精度足够。

-### 4.4 基线跟踪
+### 4.4 基线跟踪（M4 优化：斜率限幅 + 冻结超时）
+
+#### 4.4.1 斜率限幅
+
+EMI/闪电等瞬态干扰会造成 CAPVD 瞬间跳变。物理车辆不可能让线圈频率瞬间改变 >5%：

 ```c
-// 有车时冻结，无车时 100 窗口滑动平均
-if (!VD_FLAG && !FLAG_OUT) {
-    if (CAPVD - Origin < dlt_ORG * 4) {    // Origin 污染保护
-        ORG_SUM += CAPVD;
-        if (++ORG_CNT >= 100) {
-            Origin = ORG_SUM / 100;
-            ORG_SUM = ORG_CNT = 0;
-        }
+#define MAX_SLOPE_RATE  5   // 单次最大变化 5%
+
+int32_t raw_delta = Value - CAPVD;
+int32_t max_step  = CAPVD * MAX_SLOPE_RATE / 100;
+if (max_step < 100) max_step = 100;  // 最小限幅，防止低 Origin 时锁死
+if (raw_delta > max_step)  raw_delta = max_step;
+if (raw_delta < -max_step) raw_delta = -max_step;
+uint32_t clamped_value = CAPVD + raw_delta;
+CAPVD = get_flt_value(clamped_value, CAPVD);  // 慢速 IIR
+```
+
+尖峰被截断，真实车辆信号（缓慢的频率漂移）不受影响。
+
+#### 4.4.2 基线跟踪规则
+
+```c
+// 仅无车 + 无离开延时中 → 跟踪基线
+if (!VD_FLAG) {
+    int32_t dev = CAPVD - Origin;
+    if (dev < dlt_ORG * 4) {
+        // CAPVD 未显著偏离 → 正常跟踪
+        loop1_freeze_cnt = 0;
+        update_moving_average(&ORG_SUM, &ORG_CNT, &Origin, CAPVD, 100);
    } else {
-        // 冻结：CAPVD 偏离 Origin 超过进入阈值的 4 倍
-        ORG_SUM = ORG_CNT = 0;
+        // CAPVD 异常偏高 → 冻结 + 超时恢复逻辑
    }
 }
 ```
@@ -293,49 +351,67 @@ if (!VD_FLAG && !FLAG_OUT) {
 | 设计决策 | 原因 |
 |---------|------|
 | 有车时冻结基线 | 防止把车辆的影响"学"进基线（仿 TLD-110） |
-| 100 窗口跟踪 | 缓慢跟踪温漂，但不响应车辆 |
-| 4× 冻结阈值 | 防止异常 CAPVD 上升污染基线（V1.5 新增） |
+| 100 窗口滑动平均 | 缓慢跟踪温漂，但不响应车辆 |
+| 4× 冻结阈值 | 防止异常 CAPVD 上升污染基线（V1.5） |
+| 5% 斜率限幅 | 过滤 EMI/闪电尖峰，保护 IIR（V2.0） |
+| 冻结超时 + 稳定性检查 | 防止永久冻结死锁（V2.3~2.5） |

-#### 4.4.1 更新速率
+#### 4.4.3 基线更新速率

-`vd1_task` 每 50ms（TMR15 5ms×10）执行一次。空闲时每次累加 CAPVD 到 `ORG_SUM`，满 100 次后取平均更新 Origin：
+`vd1_task` 每 ~10ms 执行一次。空闲时每次累加 CAPVD 到 `ORG_SUM`，满 100 次后取平均更新 Origin：

 ```
-100 样本 × 50ms/tick = 5000ms = 5 秒
+100 样本 × 10ms/tick = 1000ms = 1 秒
 ```

 | 产品 | 窗口大小 | 更新周期 | 空闲时跟踪 | 有车时冻结 |
 |------|---------|---------|-----------|-----------|
-| **DLD154V4B** | 100 次 | **5000ms** | ✅ | ✅ |
-| **M1H** | 100 次 | **5000ms** | ✅ | ❌（有车也跟踪） |
-| **TLD-110** | 16 次 | **~800ms** | ✅ | ✅ |
+| **DLD154V4B** | 100 次 | **1000ms** | ✅ | ✅ |
+| **M1H** | 100 次 | 5000ms | ✅ | ❌（有车也跟踪） |
+| **TLD-110** | 16 次 | ~800ms | ✅ | ✅ |

-**关键差异：**
+> **注意**：V2.0 将 tick 从 50ms 提升到 10ms，基线更新从每 5 秒加速到每 1 秒 —— 对温漂的跟踪能力显著提升，同时保持 100 窗口的抗噪能力。

- **DLD154V4B vs M1H**：同为 100 窗口 5s，但 DLD154V4B 有车时冻结基线。M1H 有车也跟踪的风险——长时间有车会把频率偏移"学"进基线，安全性不如冻结方案。
- **TLD-110 最快**：16 次累积 ~800ms 完成一次更新，有车冻结 + 小窗口快跟踪，对温漂响应最敏捷。但 16 样本窗口的抗噪能力弱于 100 窗口。
- DLD154V4B 的 100 窗口 5s 取 M1H 的窗口大小 + TLD-110 的冻结策略，Origin 更稳定但温漂跟踪慢于 TLD-110。
- 注意：TMR3 ISR 在 50ms 间隙内可能完成多次测量窗口（每次 ~1ms），但 vd1_task 只取最新一个 Value 做 IIR，基线更新速率受 vd1_task 的 50ms tick 限制，与测量窗口大小无关。
+### 4.5 Origin 污染保护与冻结超时恢复（V1.5 → V2.5）

-### 4.5 Origin 污染保护（V1.5）
+#### 4.5.1 问题演进

-**问题**：实测发现车辆驶入时 Xn 偶尔先增大再减小。无车状态下 Origin 跟踪上升被污染到虚高值，导致离开时 `|f - f_b|` 远超阈值 → 绿灯常亮、永远不释放。
+| 版本 | 问题 | 方案 | 遗留问题 |
+|------|------|------|---------|
+| V1.5 | 车辆驶入时 Xn 先增，Origin 被污染后无法释放 | 4×阈值冻结 | 环境变化时永久冻结，需复位 |
+| V2.3 | 永久冻结导致死锁 | 冻结超时（30s 后强制更新） | 波动值也可能超时触发 |
+| V2.4 | 波动值被误判为"新常态" | 稳定性检查（±2% 窗口） | — |
+| V2.5 | 30s 等待太长 | 缩短到 10s | — |

-**修复**：基线跟踪前增加保护条件：
+#### 4.5.2 当前完整逻辑

 ```c
-// 仅当 CAPVD 偏离 Origin < dlt_ORG × 4 时才更新基线
-// 超出则冻结+重置累计
-if (CAPVD - Origin < dlt_ORG * 4)
+if (dev < dlt_ORG * 4) {
+    /* 正常范围 → 跟踪，清零冻结状态 */
+    loop1_freeze_cnt = 0;
    update_moving_average(...);
-else
-    freeze();
+} else {
+    /* 异常偏高 → 冻结 + 超时 + 稳定性验证 */
+    if (loop1_freeze_cnt == 0)
+        loop1_freeze_ref = CAPVD;            // 记录冻结起始值
+    else if (|CAPVD - freeze_ref| > freeze_ref * FREEZE_STABILITY_RATE / 100)
+        reset(freeze_cnt, freeze_ref);        // 波动 > ±2% → 重新计时
+
+    loop1_freeze_cnt++;
+    if (loop1_freeze_cnt >= FREEZE_TIMEOUT) { // 10s @ 10ms/tick
+        Origin = CAPVD;                       // 连续稳定 → 接受为新基线
+    }
+}
 ```

-| 场景 | Origin | CAPVD | dev | 4×阈值 | 结果 |
-|------|--------|-------|-----|--------|------|
-| 正常无车 | 127080 | 127081 | +1 | 276 | 跟踪 ✓ |
-| 异常上升 | 127085 | 127884 | +799 | 276 | 冻结 ✓ |
+#### 4.5.3 关键常量
+
+| 常量 | 值 | 说明 |
+|------|-----|------|
+| 冻结触发阈值 | dlt_ORG × 4 | CAPVD 偏离 Origin 的倍数 |
+| FREEZE_TIMEOUT | 1000 | ~10s @ 10ms/tick |
+| FREEZE_STABILITY_RATE | 2 | 稳定性窗口：参考值的 ±2% |
+| 基线窗口 | 100 | 滑动平均样本数（更新周期 ~1s） |

 ---

@@ -355,16 +431,17 @@ else

 ### 5.2 时序参数

-| 参数 | Tick (50ms) | 时间 | 说明 |
+| 参数 | Tick (10ms) | 时间 | 说明 |
 |------|------------|------|------|
-| IN_DELAY | 10 | **500 ms** | 进入确认防抖 |
-| OUT_DELAY | 10 | **500 ms** | 离开防抖（仅 SW_4=ON 时生效，OFF 时为 0） |
-| PULSE_DELAY | 10 | **500 ms** | 脉冲输出宽度 |
+| IN_DELAY | 50 | **500 ms** | 进入确认防抖（3 次 IIR 确认 + 500ms IN_DELAY） |
+| OUT_DELAY | 50 | **500 ms** | 离开防抖（仅 SW_4=ON 时生效，OFF 时为 0） |
+| PULSE_DELAY | 50 | **500 ms** | 脉冲输出宽度 |
 | HOLD_TIME | 5×1200 | **~5 min** | 有限存在超时 |
 | LC_HOLD_TIME | 4×1200 | **~4 min** | 安全复位超时 |
 | STABLE_SAMPLES | 128 tick | **~128 ms** | 上电稳定期 |
+| FREEZE_TIMEOUT | 1000 | **~10 s** | 基线冻结超时（连续稳定后更新 Origin） |

-> **SW_4 离开延时**：SW_4=ON 时，OUT_DELAY=500ms；SW_4=OFF 时，离开延时为 0，FLAG_OUT 立即切换到 FLAG_PLUSE。PULSE_DELAY 固定 500ms，不受 SW_4 影响。
+> **M4 优化**：V2.0 将 tick 从 50ms (TMR15 5ms×10) 提升到 10ms (vTaskDelay 10ms)。IIR 系数同步调整（α 从 79/256→18/256），保持等效时间常数。进入确认 3×10ms + 500ms IN_DELAY = ~530ms，比旧设计 (50ms + 500ms = 550ms) 略快。基线更新从 5s 加速到 1s。

 ### 5.3 系统 Tick 来源

@@ -537,7 +614,7 @@ if (!g_loop_stable) {
 DLD154V4B/
 ├── utilities/at32f421_freertos_demo/
 │   ├── src/
-│   │   └── TaskLoop.c          # 主检测逻辑 (~868 行 V1.5)
+│   │   └── TaskLoop.c          # 主检测逻辑 (~945 行 V2.5)
 │   ├── inc/
 │   │   └── TaskLoop.h          # 全局变量和函数声明
 │   └── ...                     # FreeRTOS + HAL 框架
@@ -556,6 +633,7 @@ DLD154V4B/
 | 原始 | ~1177 行 | 包含二阶滤波、FltHistoryManager 等死代码 |
 | V1.1 | ~706 行 | 精简重构，-40% |
 | V1.5 | ~868 行 | 增加平坦性判定、污染保护 |
+| V2.5 | ~945 行 | 增加双路 IIR、斜率限幅、进入确认、冻结超时+稳定性 |

 **删除的死代码：**
 - 二阶差分滤波（计算但从未参与判决）
@@ -572,12 +650,13 @@ DLD154V4B/

 | 指标 | 值 | 说明 |
 |------|-----|------|
-| 进入检测延迟 | < 3 ms (测量) + 500 ms (防抖) | 电信号延迟 |
-| 离开检测延迟 | < 3 ms (测量) + 平坦性确认 + 1.9 s (防抖) | 含双重确认 |
+| 进入检测延迟 | < 3 ms (测量) + 3×10ms (确认) + 500 ms (防抖) = **~530 ms** | M4 优化，比旧 550ms 略快 |
+| 离开检测延迟 | < 3 ms (测量) + 平坦性确认 + 500 ms (防抖) | 含双重确认 |
 | 误检率（单阈值） | — | 基准参考 |
 | 误检率（平坦性） | 显著降低 | 大车多峰场景 |
 | 频率分辨率 | < 0.01% | 取决于线圈 Q 值 |
-| 温漂补偿 | 自动（100 窗口基线跟踪） | 仅无车时 |
+| 温漂补偿 | 自动（100 窗口基线跟踪，更新周期 ~1s） | 仅无车时；冻结超时 10s |
+| 瞬态抑制 | 5% 斜率限幅 + 3 次进入确认 | EMI/闪电免疫 |

 ### 12.2 CPU 占用

@@ -585,7 +664,7 @@ DLD154V4B/
 |------|------|-----------------|------|
 | TMR3 ISR (捕获) | 50k/s @100kHz | ~2.1% | 每边沿约 50 周期 |
 | TMR15 ISR (tick) | 200/s | < 1% | LED + 计数 |
-| vd1_task | 20/s | < 1% | 滤波 + 检测 |
+| vd1_task | 100/s | < 1% | 滤波 + 检测（M4 10ms tick） |
 | FreeRTOS 开销 | — | < 1% | 任务调度 |
 | **总计** | — | **< 5%** | 余量充足 |

@@ -606,9 +685,13 @@ DLD154V4B/

 #define USE_FLATNESS_EXIT  1   // 1 = 平坦性离开判定 (CN200910309382)
                                // 0 = 简单 cnt_release 防抖
-```

-置 0 回退到传统 `cnt_release >= 3`，方便对比测试两种方案的差异。
+// M4 优化参数
+#define MAX_SLOPE_RATE        5   // 斜率限幅: 单次最大变化 5%
+#define ENTRY_CONFIRM         3   // 进入确认: 连续 N 次低于阈值
+#define FREEZE_TIMEOUT     1000   // 冻结超时: ~10s @ 10ms/tick
+#define FREEZE_STABILITY_RATE 2   // 稳定性窗口: 参考值的 ±2%
+```

 ---

@@ -626,4 +709,5 @@ DLD154V4B V1.4 起实现该专利的整数化版本，用于大车通行时的

 | 版本 | 日期 | 说明 |
 |------|------|------|
-| V1.0 | 2026-06-24 | 技术规格书初版 |
+| V1.0 | 2026-06-24 | 技术规格书初版（V1.5 固件） |
+| V2.0 | 2026-06-29 | 更新至 V2.5 固件：双路 IIR、斜率限幅、进入确认、冻结超时+稳定性 |