从信道相干性到固定十二音频段ESPectre HT20 子载波选型决策的技术解析【免费下载链接】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 项目中一个决定传感性能根基的架构决策生产运行时不再在每次启动时为每个环境动态搜索子载波而是采用一个由信道相干性channel coherence测量得出的、固定的十二音twelve-toneHT20 频段并让 Lightweight 与 High Accuracy 两条检测路径、Python 与 C 两套实现共享同一套子载波定义。读完本文你将理解为什么频段跨度比音调密度更能换来独立观测如何识别并归一化不同芯片的 HT20 bin 排序以及该决策在源码、配置与验证中的完整落地方式。决策背景从运行时 NBVI 到固定共享频段ESPectre 最初在运行时使用 NBVI噪声/盲区可见性指标Noise/Blank Visibility Indicator 类方法动态选择子载波。这种做法减少了手工配置但代价是引入了启动校准、额外内存、持久化状态以及跨运行时的一致性复杂度而这些成本并未换来与产品定位匹配的收益。在后续演进中生产路径改为使用一个固定共享频段。但第一版十二音布局建立在一个错误的假设上认为所有芯片都输出 DC 位于 bin 32 的 HT20 CSI。这一假设与实际芯片行为不符——不同 MAC 代际的 ESP32 芯片交付的 CSI 子载波顺序并不一致Classic-MAC 芯片如经典的 ESP32 / S2 / S3 家族交付 Espressif 原生的0~31, -32~-1顺序DC 位于 bin 0Wi-Fi 6 芯片如 ESP32-C6 等交付以 DC 为中心的居中顺序centered orderbin subcarrier 32DC 位于 bin 32。两种布局在归一化到同一个居中网格之后频段选择才真正与芯片物理无关。此后替换频段可以从信道物理特性channel physics出发来选择而不再依赖单一语料上的检测器得分。这正是本 ADRdocs/adr/2026-07-25-select-the-classic-band-from-channel-coherence.md确立的核心方向。核心论断为什么跨度胜于密度频段选型的物理依据来自对 CSI 噪声与运动扰动统计特性的区分安静环境的波动在音与音之间几乎是相互独立的quiet fluctuation is nearly independent tone to tone运动扰动在约 10 个子载波约 3.1 MHz范围内保持相干motion remains coherent over roughly ten subcarriers。由此得出的推论是跨度购买的是独立的信道视图span buys independent channel views而增加音调密度主要只会添加相互关联的测量increasing tone density mostly adds correlated measurements。也就是说把采样点稀疏地铺满整个可用频段比把采样点密集地聚在一小段频带里更能为检测器提供多样化的观测。源码中的注释也明确记录了同样的判断。在 csi_format.h 的 HT20 常量区Subcarriers /-4, /-9, /-14, /-19, /-24, /-28. Spans the full usable range because the motion perturbation stays coherent over ~10 subcarriers (3.1 MHz) while quiet noise is nearly per-tone independent, so span is what buys independent looks. Stops short of |sc| 3, where relative jitter rises ~10%.注意其中停在|sc| 3之外的细节频段刻意不取最靠近 DC 的 ±1±3 号子载波因为这些位置的相对抖动relative jitter会升高约 10%对幅度类特征不利。这也解释了为什么最终频段的下限落在 bin 4对应子载波 -28而非更靠内的位置。最终决策固定的十二音 HT20 频段ADR 确定的生产频段定义如下DEFAULT_SUBCARRIERS (4, 8, 13, 18, 23, 28, 36, 41, 46, 51, 56, 60)这些居中网格索引centered-grid indices对应的物理子载波为居中网格索引物理子载波4-288-2413-1918-1423-928-43644194614511956246028即六对对称子载波/-4, /-9, /-14, /-19, /-24, /-28整体跨越 HT20 全部 56 个可用子载波64 个 bin 去掉下边界 bin 03、上边界 bin 6163 的 guard null 以及 DC bin 32。该决策附带五条明确约束先归一化、后提取在提取频段之前必须先归一化被识别出的 HT20 payload 布局Normalize recognized HT20 payload layouts before band extraction全场景固定频段在会话、芯片、前端ESPHome / Native / Matter、Lightweight 与 High Accuracy 之间保持一致按跨度与独立观测选型选择标准是覆盖全部可用频段跨度并获取独立观测而不是某个语料上的检测器得分十二个单 bin 采样公共幅度路径保持十二个单 bin 采样Keep twelve single-bin samples as the common amplitude path禁止全局相邻平均不要把所有选中音调都平均进相邻子载波。局部聚合只允许以明确的、特性专属的路径存在例如两个生产 profile 都使用的 aggregated-IQR 输入。源码落地C 与 Python 的双端定义C 侧的定义位于 csi_types.h同时包含 HT20 的关键常量constexpr uint16_t HT20_NUM_SUBCARRIERS 64U; // HT20 共 64 个子载波 constexpr uint16_t HT20_CSI_LEN 128U; // 64 SC × 2 字节I/Q 对 constexpr uint8_t HT20_GUARD_BAND_LOW 4U; // 第一个有效子载波-28 constexpr uint8_t HT20_GUARD_BAND_HIGH 60U; // 最后一个有效子载波28 constexpr uint8_t HT20_DC_SUBCARRIER 32U; // 居中约定下的 DC bin constexpr uint8_t HT20_SELECTED_BAND_SIZE 12U; // 选中音调数量 inline constexpr uint8_t DEFAULT_SUBCARRIERS[HT20_SELECTED_BAND_SIZE] { 4U, 8U, 13U, 18U, 23U, 28U, 36U, 41U, 46U, 51U, 56U, 60U, };Python 侧MicroPython 运行时在 config.py 中定义了完全一致的元组并带有与 C 注释呼应的物理依据说明。注意该文件中 local 配置覆盖config_local.py特意排除了DEFAULT_SUBCARRIERS即用户本地配置无法悄悄改变生产频段——这保证了 Python 与 C 始终共享同一条频段定义见 config.py 中_name ! DEFAULT_SUBCARRIERS的判断。docs/ALGORITHMS.md的当前检测器定义也明确指出该集合是当前检测器定义的一部分索引来自实测信道相干性而非检测指标的搜索。源码级解析跨芯片 bin 布局的归一化先归一化、后提取在生产代码里由两条链路实现布局识别与旋转变换。布局识别用 guard null 区分两种约定在 csi_format.h 中两种 bin 布局由无线电上报的guard null精确为零的 bin区分。两个约定下 bin 0 与 bin 32 都是 null不含信息而以下 bin 恰好只在一个约定下为 null// 仅在 Classic 约定下为 null 的 bin constexpr uint8_t HT20_CLASSIC_ONLY_NULL_BINS[] {29, 30, 31, 33, 34, 35}; // 仅在 Centered 约定下为 null 的 bin constexpr uint8_t HT20_CENTERED_ONLY_NULL_BINS[] {1, 2, 3, 61, 62, 63};detect_ht20_bin_layout()csi_format.h要求双向都有正向证据一组 guard 必须全部为 null、另一组必须全部有能量才会判定为对应布局仅凭没有能量不足以下结论因为稀疏或退化的 payload 在两种约定下都可能表现为全 null。无法得出明确结论时返回UNKNOWN由上层决定丢弃或走显式降级路径。旋转变换半个 FFT 即逆变换一旦识别出 Classic 布局rotate_ht20_classic_to_centered()csi_format.h通过一次对半交换把0~31, -32~-1映射到-32~31constexpr uint16_t kHalf HT20_CSI_LEN / 2U; std::memcpy(out, csi_data kHalf, kHalf); std::memcpy(out kHalf, csi_data, kHalf);旋转半个 FFT 大小是自身的逆变换因此这一操作既简单又可逆。归一化后的结果在 csi_payload_normalizer.h 中通过rotated_to_centered标志记录NormalizedCSIPayloadTag则区分DOUBLE_HT20、HT57_TO_64、LLTF53_TO_64等命名变体当格式切换或出现长无效序列时还会通过reset_detector_before_consume要求在消费该包前清空检测器历史避免跨格式的污染。此外LLTF短前导捕获不含最外侧数据音LLTF 只携带物理子载波 -26..-1 与 1..26因此居中约定下的 bin{4, 5, 59, 60}缺失需要由prepare_ht20_detector_input()csi_format.h在私有检测器缓冲区内从相邻音填充。分类器优先的准入顺序布局归一化只是传感契约的一部分。姊妹 ADR classifier-first HT20 sensing contract 规定的运行准入顺序是校验结构validate structure校验 PHY、LTF 与带宽元数据validate PHY, LTF, and width metadata识别 payload 布局recognize the payload layout归一化命名的 20 MHz 变体normalize a named 20 MHz variant路由到传感或显式丢弃路径route to sensing or an explicit drop path。频段提取只发生在第 4 步之后这保证了字节长度可解析不等于可以作为检测器输入。验证证据独立观测数饱和与高帧率代价ADR 的 Validation 部分给出了两组关键实测数据独立观测数independent looks实测信道统计显示选定的频段横跨 HT20 全部 56 个可用子载波并保留了约3.55个独立观测而此前布局只有约2.44个。跨度带来的提升是实质性的而非指标上的巧合。音数扫描count sweep后续基于重拟合refit的音数扫描确认更密的频段只会增加相关correlated信息并且在高速率压力捕获high-rate stress capture中表现更差——即使芯片级聚合chip aggregates看起来有吸引力。因此十二这个数量有两个相互独立的依据信道相干性饱和了独立观测数channel coherence saturates the number of independent looks端到端重放不支撑更密频段的额外运行时代价与降低的高速率动态范围end-to-end replay does not justify the extra runtime cost or reduced high-rate dynamic range of denser bands。公共路径上的相邻 bin 平均同样被否决联合重放joint replay不足以支撑改变 Lightweight 与 High Accuracy 的全部幅度输入。aggregated-IQR 特征在两条 profile 中都使用自己的独立数据流并不重新定义这个共享频段相关决策见 aggregated turbulence IQR ADR。在代码层面相邻聚合的窗口在 csi_format.h 的extract_adjacent_aggregated_subcarrier_amplitudes()中被钳制到 bin 4..60 并跳过 DC nullbin 32与工具侧 adjacent_aggregation.py 中GUARD_LOW 4 / GUARD_HIGH 60 / DC_BIN 32的聚合分组逻辑保持一致——且该工具明确标注为research-only仅用于宿主侧实验生产公共路径不受影响。被否决的备选方案及其理由恢复运行时 NBVI否决。其自适应搜索在当前产品形态下无法证明校准、内存、持久化与双端一致性parity成本的合理性。在当前语料上选最佳检测器得分否决。这会把传感几何与单一数据集纠缠在一起并可能选中某个录制环境特有的巧合recording-specific coincidence损害泛化性。增加共享音数否决。独立观测数饱和而更紧的音调间距会提高相关性并恶化实测的高帧率行为。在全局对相邻 bin 做聚合否决。这会静默地重新定义所有选中频段的消费方。特性专属的聚合必须被独立测量并显式命名。这些否决项与docs/FEATURES.md中记录的频域相干类特征证据相互印证历史上的频率相干frequency-coherence候选如今全部降级为 host-only生产路径不再为完整的全频带相干计算买单见 ALGORITHMS.md 对特性族划分的说明。决策影响启动流程简化启动时不再执行环境特定的子载波搜索Startup no longer performs environment-specific subcarrier search省去校准阶段的额外延迟与状态持久化双端共享Python 与 C 共享同一个归一化网格和同一条频段定义杜绝了两端因常量漂移导致的检测不一致跨芯片一致频段在受支持的芯片家族间一致地跨越可用 HT20 范围前提是 Classic 布局已被旋转到居中约定变更门槛明确任何新的频段、音数或聚合方案提议都需要重拟合refit、生产重放production replay与跨运行时一致性cross-runtime parity证据——这与仓库 ADR 指南docs/adr/README.md要求的质量门槛一致防止缺乏证据的参数微调侵蚀已验收的检测基线。决策历史日期方向结果2025-12-03运行时用 NBVI 选择子载波被固定共享生产频段取代2026-06-09移除运行时 NBVI使用固定共享子载波保留为当前运行模型2026-07-20保留第一版十二音布局在修正跨芯片 HT20 bin 排序后被替换2026-07-25从实测相干性选择全跨度十二音频段接受2026-08-05将相邻 bin 平均并入公共选中音调路径否决仅允许特性局部聚合相关文档classifier-first HT20 sensing contract ADR本决策依赖的准入与归一化契约AGC 与 CV 归一化 ADR幅度类特征的增益不变性前提aggregated turbulence IQR ADR唯一的特性专属聚合路径ALGORITHMS.md当前生产检测器定义与特征几何FEATURES.md频率相干类特性的评测证据与基线沿革实际生产行为可分别核对 csi_types.h、csi_format.h、csi_payload_normalizer.h 与 config.py 中的常量与归一化实现以及 csi_pipeline.cpp 对完整准入与提取链路的调用。【免费下载链接】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），仅供参考
