ESPectre 增益鲁棒信号路径保持 AGC 启用并统一 CV 归一化std/mean的架构决策与源码实践【免费下载链接】espectreWi-Fi CSI motion sensing for ESP32. C SDK, ESPHome, Native, and Matter frontends, browser tools, and a CLI for the full device lifecycle. GPLv3 and commercial licensing.项目地址: https://gitcode.com/GitHub_Trending/es/espectre导读本文围绕 ESPectre 项目的一条关键架构决策记录ADR2026-07-04-keep-agc-active-and-standardize-cv-normalization展开为什么生产路径必须放弃硬件增益锁定、让 AGC 在所有芯片上保持启用以及如何用系数变异Coefficient of VariationCV即std / mean作为运行时检测、数据采集、数据集工作流、主机端工具与验证、ML 训练与推理共用的单一归一化契约。读完本文你将理解全局特征缩放 ≠ 结构性增益不变这一核心论断的由来掌握 CV 归一化的数学原理及其在 utils.h 中的实现细节并能在自己的采集与训练流程中复现这套增益鲁棒的信号路径。一、决策背景增益相关的行为如何暴露核心缺陷该 ADR 的开篇并非凭空而起而是由一系列实验结论累积而成。核心证据来自早期基于原始特征的 ML 基线上运行的gain-shift 诊断名义增益下信号质量表现良好但只要人为施加均匀的增益偏移就会引发大范围的误报波动false-positive swings。这一现象直接证明了一个关键命题全局特征缩放global feature scaling并不等同于结构性的增益不变structural gain invariance。也就是说仅仅在特征层做归一化处理无法消除底层增益变化对检测稳定性的影响真正的鲁棒性必须内建在信号特征的定义本身之中。后续的两轮实验非但没有推翻这一结论反而强化了它relative-8 拓扑与fp_weight扫描只有把特征路径迁移到相对统计量relative statistics之后增益稳定的 ML 基线才得以恢复。这说明相对特征才是恢复增益稳定的前提而不是权重调参的结果。MVS 引导的加权重训练虽然改善了部分长时结果但同样印证了另一个重要判断——检测器引导的加权detector-guided weighting不能替代一条干净、增益鲁棒的信号路径。加权只能调优无法从根上修复被增益污染的输入。与此同时强制增益管理forced gain management即锁定硬件增益引入了运营层面的副作用系统不稳定性以及可能加剧丢包的 Wi-Fi RX/TX 问题。收益不足以覆盖代价这为最终决策提供了充分理由。二、决策内容一份跨四层统一的归一化契约该 ADR 的决策由三条动作组成缺一不可从生产路径移除硬件增益锁定hardware gain lock在所有芯片上保持 AGC 启用keep AGC active以系数变异湍流coefficient-of-variation turbulencestd / mean作为唯一共享的归一化路径统一应用于应用层对应仓库产物运行时运动检测支持信号src/cpp/core/utils.h、src/cpp/core/high_accuracy_detector.h采集与数据集工作流docs/ML_DATA_COLLECTION.md明确“采集期间保持 AGC 启用”主机端工具与验证tools/lib/csi_analysis.pycalculate_spatial_turbulence走 AGC-active 归一化路径ML 训练与推理tools/lib/candidate_features.py、tools/lib/csi_features.py这份统一契约的直接收益是运行时、数据集与 ML 三者共享同一个归一化约定跨芯片、跨会话的行为因此更容易解释也彻底规避了强制增益副作用对传输稳定性transport stability的威胁。三、数学原理为什么 CV 是增益不变的为什么偏偏选std / mean因为系数变异天然具备均匀缩放不变性。设 AGC 将所有幅度统一乘以因子k则turbulence std(amplitudes) / mean(amplitudes) CV(kA) std(kA) / mean(kA) (k · std(A)) / (k · mean(A)) std(A) / mean(A) CV(A)只要mean 0任何均匀的增益缩放都不会改变湍流值。这一推导在 docs/ALGORITHMS.md 的 “AGC-Active Normalization” 章节中有完整呈现并明确声明“If AGC scales all amplitudes by a factork, turbulence stays unchanged”——这正是“结构性增益不变”的数学根基不变性来自特征定义本身比值形式而非训练或推理时的缩放补救。3.1 C 侧实现apply_cv_normalization在 src/cpp/core/utils.h 中这一公式被封装为可直接复用的内联函数/** * Apply gain-invariant normalization to standard deviation * * CV (Coefficient of Variation) std / mean * Makes turbulence gain-invariant when AGC is not locked. */ inline float apply_cv_normalization(float std_dev, float mean) { return (mean 0.0f) ? std_dev / mean : 0.0f; } /** * Calculate turbulence from variance with gain-invariant normalization */ inline float calculate_turbulence_from_variance(float variance, const float* values, size_t count) { float std_dev std::sqrt(variance); float mean calculate_mean(values, count); return apply_cv_normalization(std_dev, mean); }值得注意的工程细节除零保护mean 0.0f时返回std / mean否则返回0.0f避免静默产生 NaN/Inf 污染后续阈值比较两遍扫描算法同文件的calculate_mean_variance_two_passutils.h采用variance sum((x - mean)^2) / n的两遍算法而非单遍的E[X²] - E[X]²因为后者在 float32 算术下数值不稳定。注释中还明确解释了单一实现的意义C 与 Python 双运行时之间存在C/Python parity gate一致性门禁两个运行时必须对同样的输入产生完全一致的判定因此累加顺序必须固定在唯一一处——早期这里曾有三份手抄的重复循环。3.2 阈值下限随 CV 缩放调整CV 形式的湍流值天然比绝对值形式的湍流小得多因此阈值边界也必须随之调整。在 src/cpp/core/threshold.h 中有直接注释constexpr float SEGMENTATION_DEFAULT_THRESHOLD 1.0f; // Min threshold lowered to support CV normalization (std/mean produces smaller values) constexpr float SEGMENTATION_MIN_THRESHOLD 1e-9f; constexpr float SEGMENTATION_MAX_THRESHOLD 10.0f;这一注释是CV 归一化贯穿到阈值层的直接证据归一化方式的变更不是局部的而是会连带影响检测阈值的默认值与合法范围。3.3 检测器中的实际消费位置High AccuracyML 路径其算法流程的第一步就是“Calculate spatial turbulence per packet using CV normalization (std/mean)”见 src/cpp/core/high_accuracy_detector.hLightweight非 ML 路径每包空间湍流同为t_i std(A_i) / mean(A_i)随后经 Hampel 滤波后计算 lag-1 自相关其第二个输入turb_iqr_over_mean_aggr也是无量纲、增益不变的稳健离散度见 docs/ALGORITHMS.mdML 特征侧turb_std_over_mean类特征在 tools/lib/candidate_features.py 中以turbulence_std / mean_denom形式计算与 C 端共用同一比值语义保证训练与推理的特征分布一致。四、被否决策方案两条反面路径ADR 明确记录了两个被否决的方案及其理由理解它们有助于避免踩坑4.1 继续采用增益锁定路径Continue with gain-locked paths否决理由实验并不支持将增益锁定作为稳健的跨设备cross-device基础且它自身引入了额外的运营成本不稳定性、Wi-Fi RX/TX 问题可能加剧丢包。换句话说为换取表面上的幅度可比性而付出的传输稳定性代价是不可接受的。4.2 维护多条归一化路径Maintain multiple normalization paths否决理由分裂的路径使推理复杂化、削弱跨栈对齐cross-stack alignment并让数据集与模型难以相互比较。这正是本 ADR 选择单一共享归一化契约的直接反面论证——归一化契约的多样性本身就是技术债。五、影响与权衡收益与代价并存5.1 收益运行时、数据集与 ML 使用同一个归一化契约语义在整条流水线中保持一致跨芯片ESP32 / S2 / S3 / C3 / C5 / C6与跨会话session的行为更容易解释与对比项目规避了强制增益的副作用从而保护传输稳定性与数据质量。5.2 代价部分早期实验与模型从活跃基线降级为历史记录historical rather than active baselines后续所有评估结果都必须放在AGC-active 重置的语境下解读不能与增益锁定时代的数字直接对比。5.3 仓库侧的落地证据决策并非只停留在文档层面仓库中能找到一系列配套变更docs/CHANGELOG.md 记录 ESPHome 配置项的调整中明确移除gain_lock连同segmentation_threshold、selected_subcarriers等旧配置一并废弃并以segmentation_window_size_ms、evaluation_interval_ms、csi_target_pps、csi_traffic_mode等新参数取代docs/ALGORITHMS.md 的术语表明确写着AGC:automatic gain control in the radio; ESPectre keeps it active and therefore favors scale-invariant featuresdocs/ML_DATA_COLLECTION.md 在数据采集约束中要求A GC stays active during collection保证采集数据与运行时检测处于同一增益条件下docs/ARCHITECTURE.md 将“AGC-active sensing path”列为架构要点之一。六、后续演进本 ADR 与后续决策的关联该 ADR 处于决策链的中游与前后多个决策直接相关docs/adr/2026-08-11-promote-channel-shape-trajectory-ml-features.md后续将信道形状轨迹类 ML 特征转正。这类特征在 docs/web/content/sdk/detectors.html 中被描述为Rations, correlations, crossing rates, and normalized geometry limit sensitivity to absolute receive gain while AGC remains enabled——即它们的设计同样以AGC 保持启用为前提与本 ADR 一脉相承docs/adr/2026-06-30-separate-ml-training-data-from-promotion-replays.md训练数据与推广回放分离保证评估数据与训练数据不在同一增益语境下被污染具体落地提交为bf395397、aac68d9d、86d934fe三个 git commitADR 原文记录可在仓库历史中追踪。从源码结构看本 ADR 确立的AGC 启用 CV 归一化契约已经成为 ESPectre 运行时与工具链的公共地基采集端tools/lib/csi_analysis.py的calculate_spatial_turbulence、检测端C 与 Python 双运行时、ML 特征工程candidate_features.py在各自的入口处都复用了同一个std/mean语义这正是一份契约、四处落地的具体体现。七、实践建议对希望在自己的采集与训练流程中复现这套方案的开发者可遵循以下要点不要锁定硬件增益保持 AGC 启用让增益鲁棒性由特征定义承担而不是由硬件状态承担统一使用 CV 湍流所有需要活动量度量的地方统一用std / mean避免运行时用绝对值、ML 用比值造成的分布漂移同步调整阈值范围切换到 CV 后参考 src/cpp/core/threshold.h 将阈值下限下探到1e-9量级并重新校验默认阈值采集与推理保持同一增益语境遵循 docs/ML_DATA_COLLECTION.md 的A GC stays active during collection否则训练集与推理环境的增益差异会重新引入已消除的误报波动用 gain-shift 诊断自检在验证阶段人为施加均匀增益偏移若误报率基本不变则说明信号路径真正达到了结构性增益不变而非仅靠特征缩放掩盖问题。相关文档docs/adr/README.mdADR 索引docs/ALGORITHMS.mdAGC-Active Normalization 与 Lightweight 实现细节src/cpp/core/utils.hCV 归一化实现src/cpp/core/threshold.h阈值范围src/cpp/core/high_accuracy_detector.hML 检测器算法docs/CHANGELOG.mdgain_lock等配置项的移除记录docs/ML_DATA_COLLECTION.md采集期 AGC 约束【免费下载链接】espectreWi-Fi CSI motion sensing for ESP32. C SDK, ESPHome, Native, and Matter frontends, browser tools, and a CLI for the full device lifecycle. GPLv3 and commercial licensing.项目地址: https://gitcode.com/GitHub_Trending/es/espectre创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ESPectre 增益鲁棒信号路径：保持 AGC 启用并统一 CV 归一化（std/mean）的架构决策与源码实践
ESPectre 增益鲁棒信号路径保持 AGC 启用并统一 CV 归一化std/mean的架构决策与源码实践【免费下载链接】espectreWi-Fi CSI motion sensing for ESP32. C SDK, ESPHome, Native, and Matter frontends, browser tools, and a CLI for the full device lifecycle. GPLv3 and commercial licensing.项目地址: https://gitcode.com/GitHub_Trending/es/espectre导读本文围绕 ESPectre 项目的一条关键架构决策记录ADR2026-07-04-keep-agc-active-and-standardize-cv-normalization展开为什么生产路径必须放弃硬件增益锁定、让 AGC 在所有芯片上保持启用以及如何用系数变异Coefficient of VariationCV即std / mean作为运行时检测、数据采集、数据集工作流、主机端工具与验证、ML 训练与推理共用的单一归一化契约。读完本文你将理解全局特征缩放 ≠ 结构性增益不变这一核心论断的由来掌握 CV 归一化的数学原理及其在 utils.h 中的实现细节并能在自己的采集与训练流程中复现这套增益鲁棒的信号路径。一、决策背景增益相关的行为如何暴露核心缺陷该 ADR 的开篇并非凭空而起而是由一系列实验结论累积而成。核心证据来自早期基于原始特征的 ML 基线上运行的gain-shift 诊断名义增益下信号质量表现良好但只要人为施加均匀的增益偏移就会引发大范围的误报波动false-positive swings。这一现象直接证明了一个关键命题全局特征缩放global feature scaling并不等同于结构性的增益不变structural gain invariance。也就是说仅仅在特征层做归一化处理无法消除底层增益变化对检测稳定性的影响真正的鲁棒性必须内建在信号特征的定义本身之中。后续的两轮实验非但没有推翻这一结论反而强化了它relative-8 拓扑与fp_weight扫描只有把特征路径迁移到相对统计量relative statistics之后增益稳定的 ML 基线才得以恢复。这说明相对特征才是恢复增益稳定的前提而不是权重调参的结果。MVS 引导的加权重训练虽然改善了部分长时结果但同样印证了另一个重要判断——检测器引导的加权detector-guided weighting不能替代一条干净、增益鲁棒的信号路径。加权只能调优无法从根上修复被增益污染的输入。与此同时强制增益管理forced gain management即锁定硬件增益引入了运营层面的副作用系统不稳定性以及可能加剧丢包的 Wi-Fi RX/TX 问题。收益不足以覆盖代价这为最终决策提供了充分理由。二、决策内容一份跨四层统一的归一化契约该 ADR 的决策由三条动作组成缺一不可从生产路径移除硬件增益锁定hardware gain lock在所有芯片上保持 AGC 启用keep AGC active以系数变异湍流coefficient-of-variation turbulencestd / mean作为唯一共享的归一化路径统一应用于应用层对应仓库产物运行时运动检测支持信号src/cpp/core/utils.h、src/cpp/core/high_accuracy_detector.h采集与数据集工作流docs/ML_DATA_COLLECTION.md明确“采集期间保持 AGC 启用”主机端工具与验证tools/lib/csi_analysis.pycalculate_spatial_turbulence走 AGC-active 归一化路径ML 训练与推理tools/lib/candidate_features.py、tools/lib/csi_features.py这份统一契约的直接收益是运行时、数据集与 ML 三者共享同一个归一化约定跨芯片、跨会话的行为因此更容易解释也彻底规避了强制增益副作用对传输稳定性transport stability的威胁。三、数学原理为什么 CV 是增益不变的为什么偏偏选std / mean因为系数变异天然具备均匀缩放不变性。设 AGC 将所有幅度统一乘以因子k则turbulence std(amplitudes) / mean(amplitudes) CV(kA) std(kA) / mean(kA) (k · std(A)) / (k · mean(A)) std(A) / mean(A) CV(A)只要mean 0任何均匀的增益缩放都不会改变湍流值。这一推导在 docs/ALGORITHMS.md 的 “AGC-Active Normalization” 章节中有完整呈现并明确声明“If AGC scales all amplitudes by a factork, turbulence stays unchanged”——这正是“结构性增益不变”的数学根基不变性来自特征定义本身比值形式而非训练或推理时的缩放补救。3.1 C 侧实现apply_cv_normalization在 src/cpp/core/utils.h 中这一公式被封装为可直接复用的内联函数/** * Apply gain-invariant normalization to standard deviation * * CV (Coefficient of Variation) std / mean * Makes turbulence gain-invariant when AGC is not locked. */ inline float apply_cv_normalization(float std_dev, float mean) { return (mean 0.0f) ? std_dev / mean : 0.0f; } /** * Calculate turbulence from variance with gain-invariant normalization */ inline float calculate_turbulence_from_variance(float variance, const float* values, size_t count) { float std_dev std::sqrt(variance); float mean calculate_mean(values, count); return apply_cv_normalization(std_dev, mean); }值得注意的工程细节除零保护mean 0.0f时返回std / mean否则返回0.0f避免静默产生 NaN/Inf 污染后续阈值比较两遍扫描算法同文件的calculate_mean_variance_two_passutils.h采用variance sum((x - mean)^2) / n的两遍算法而非单遍的E[X²] - E[X]²因为后者在 float32 算术下数值不稳定。注释中还明确解释了单一实现的意义C 与 Python 双运行时之间存在C/Python parity gate一致性门禁两个运行时必须对同样的输入产生完全一致的判定因此累加顺序必须固定在唯一一处——早期这里曾有三份手抄的重复循环。3.2 阈值下限随 CV 缩放调整CV 形式的湍流值天然比绝对值形式的湍流小得多因此阈值边界也必须随之调整。在 src/cpp/core/threshold.h 中有直接注释constexpr float SEGMENTATION_DEFAULT_THRESHOLD 1.0f; // Min threshold lowered to support CV normalization (std/mean produces smaller values) constexpr float SEGMENTATION_MIN_THRESHOLD 1e-9f; constexpr float SEGMENTATION_MAX_THRESHOLD 10.0f;这一注释是CV 归一化贯穿到阈值层的直接证据归一化方式的变更不是局部的而是会连带影响检测阈值的默认值与合法范围。3.3 检测器中的实际消费位置High AccuracyML 路径其算法流程的第一步就是“Calculate spatial turbulence per packet using CV normalization (std/mean)”见 src/cpp/core/high_accuracy_detector.hLightweight非 ML 路径每包空间湍流同为t_i std(A_i) / mean(A_i)随后经 Hampel 滤波后计算 lag-1 自相关其第二个输入turb_iqr_over_mean_aggr也是无量纲、增益不变的稳健离散度见 docs/ALGORITHMS.mdML 特征侧turb_std_over_mean类特征在 tools/lib/candidate_features.py 中以turbulence_std / mean_denom形式计算与 C 端共用同一比值语义保证训练与推理的特征分布一致。四、被否决策方案两条反面路径ADR 明确记录了两个被否决的方案及其理由理解它们有助于避免踩坑4.1 继续采用增益锁定路径Continue with gain-locked paths否决理由实验并不支持将增益锁定作为稳健的跨设备cross-device基础且它自身引入了额外的运营成本不稳定性、Wi-Fi RX/TX 问题可能加剧丢包。换句话说为换取表面上的幅度可比性而付出的传输稳定性代价是不可接受的。4.2 维护多条归一化路径Maintain multiple normalization paths否决理由分裂的路径使推理复杂化、削弱跨栈对齐cross-stack alignment并让数据集与模型难以相互比较。这正是本 ADR 选择单一共享归一化契约的直接反面论证——归一化契约的多样性本身就是技术债。五、影响与权衡收益与代价并存5.1 收益运行时、数据集与 ML 使用同一个归一化契约语义在整条流水线中保持一致跨芯片ESP32 / S2 / S3 / C3 / C5 / C6与跨会话session的行为更容易解释与对比项目规避了强制增益的副作用从而保护传输稳定性与数据质量。5.2 代价部分早期实验与模型从活跃基线降级为历史记录historical rather than active baselines后续所有评估结果都必须放在AGC-active 重置的语境下解读不能与增益锁定时代的数字直接对比。5.3 仓库侧的落地证据决策并非只停留在文档层面仓库中能找到一系列配套变更docs/CHANGELOG.md 记录 ESPHome 配置项的调整中明确移除gain_lock连同segmentation_threshold、selected_subcarriers等旧配置一并废弃并以segmentation_window_size_ms、evaluation_interval_ms、csi_target_pps、csi_traffic_mode等新参数取代docs/ALGORITHMS.md 的术语表明确写着AGC:automatic gain control in the radio; ESPectre keeps it active and therefore favors scale-invariant featuresdocs/ML_DATA_COLLECTION.md 在数据采集约束中要求A GC stays active during collection保证采集数据与运行时检测处于同一增益条件下docs/ARCHITECTURE.md 将“AGC-active sensing path”列为架构要点之一。六、后续演进本 ADR 与后续决策的关联该 ADR 处于决策链的中游与前后多个决策直接相关docs/adr/2026-08-11-promote-channel-shape-trajectory-ml-features.md后续将信道形状轨迹类 ML 特征转正。这类特征在 docs/web/content/sdk/detectors.html 中被描述为Rations, correlations, crossing rates, and normalized geometry limit sensitivity to absolute receive gain while AGC remains enabled——即它们的设计同样以AGC 保持启用为前提与本 ADR 一脉相承docs/adr/2026-06-30-separate-ml-training-data-from-promotion-replays.md训练数据与推广回放分离保证评估数据与训练数据不在同一增益语境下被污染具体落地提交为bf395397、aac68d9d、86d934fe三个 git commitADR 原文记录可在仓库历史中追踪。从源码结构看本 ADR 确立的AGC 启用 CV 归一化契约已经成为 ESPectre 运行时与工具链的公共地基采集端tools/lib/csi_analysis.py的calculate_spatial_turbulence、检测端C 与 Python 双运行时、ML 特征工程candidate_features.py在各自的入口处都复用了同一个std/mean语义这正是一份契约、四处落地的具体体现。七、实践建议对希望在自己的采集与训练流程中复现这套方案的开发者可遵循以下要点不要锁定硬件增益保持 AGC 启用让增益鲁棒性由特征定义承担而不是由硬件状态承担统一使用 CV 湍流所有需要活动量度量的地方统一用std / mean避免运行时用绝对值、ML 用比值造成的分布漂移同步调整阈值范围切换到 CV 后参考 src/cpp/core/threshold.h 将阈值下限下探到1e-9量级并重新校验默认阈值采集与推理保持同一增益语境遵循 docs/ML_DATA_COLLECTION.md 的A GC stays active during collection否则训练集与推理环境的增益差异会重新引入已消除的误报波动用 gain-shift 诊断自检在验证阶段人为施加均匀增益偏移若误报率基本不变则说明信号路径真正达到了结构性增益不变而非仅靠特征缩放掩盖问题。相关文档docs/adr/README.mdADR 索引docs/ALGORITHMS.mdAGC-Active Normalization 与 Lightweight 实现细节src/cpp/core/utils.hCV 归一化实现src/cpp/core/threshold.h阈值范围src/cpp/core/high_accuracy_detector.hML 检测器算法docs/CHANGELOG.mdgain_lock等配置项的移除记录docs/ML_DATA_COLLECTION.md采集期 AGC 约束【免费下载链接】espectreWi-Fi CSI motion sensing for ESP32. C SDK, ESPHome, Native, and Matter frontends, browser tools, and a CLI for the full device lifecycle. GPLv3 and commercial licensing.项目地址: https://gitcode.com/GitHub_Trending/es/espectre创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考