ESPectre 感知准入契约classifier-first 20 MHz CSI 接收规范【免费下载链接】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 仓库中的架构决策记录 2026-07-23-adopt-classifier-first-ht20-sensing-contract.md系统讲解 ESPectreESP32 Wi-Fi CSI 运动感知如何通过先分类、后归一化的准入契约确保进入检测器和训练数据的每一条 CSI 记录都符合生产级 20 MHz 感知契约。你将掌握为什么字节长度不能证明 CSI 有效、lltf20/ht20/vht20三类采集 profile 的物理含义、五步运行时准入顺序、以及 2.4 GHz / 5 GHz 频段选择与检测验证状态的边界。读完本文你将能够理解并审查 ESPectre 固件与主机工具共享的 CSI 准入边界并知道如何在源码中定位与验证这一契约。背景为什么字节长度不足以定义有效输入Parsing a CSI payload does not prove that it is valid detector input.——ADR 原文ESPectre 过去存在两个叠加的隐患固件与主机工具过度依赖字节长度推断格式一段能解析出 I/Q 对的字节流未必是检测器认可的物理格式。长度相同不代表布局相同、PHY 相同、子载波网格相同。频段选择被强制为 2.4 GHz即使在双频目标上早期实现也一律强制 2.4 GHz 采集。生产契约必须把三件事独立定义PHY 准入HT/VHT/ legacy LLTF 是否被允许布局归一化载荷布局能否映射到内部 64 子载波网格Wi-Fi 频段选择2g/5g/auto由集成方显式决定。从源码结构看这套契约在仓库中被拆分为多个职责单一的头文件与实现csi_phy_filter.h 负责 PHY 元数据判定csi_format_classifier.h 负责在归一化之前完成分类csi_payload_normalizer.h 负责把已识别的布局归一化到 64 子载波网格。运行时与主机工具共用同一套准入语义tools/lib/csi_io.py 中的assess_ht20_sensing_record与 C 侧assess_ht20_sensing_format相互对齐。决策唯一的 classifier-first 感知契约ADR 明确采纳一条显式的 classifier-first 感知契约其核心规则如下规则内容命名 profile 白名单生产感知仅接受lltf20、ht20、vht20三种采集 profile布局识别只接受能映射到内部 64 子载波网格的已识别布局分类先行每个数据包或数据集行在归一化之前必须先分类归一化范围只归一化命名的 20 MHz 布局包括精确的 64 子载波载荷以及显式支持的短估计与双倍估计丢弃策略不支持或歧义的格式直接丢弃并携带 reason 遥测训练校验当过滤移除全部有效感知数据时主机侧训练与校验必须显式失败历史数据保留没有 PHY 元数据的历史采集仅当其存储布局本身能证明符合受支持的 20 MHz 契约时才保留频段与带宽由前端或 SDK 集成方选择2g、5g或auto同时强制 20 MHz 带宽、2.4 GHz 上使用 HT、5 GHz 上使用 VHT、禁止 HE 采集验证语料与频段的边界ADR 特别强调一个容易被误解的边界经过验证的检测器语料仍是 2.4 GHz5 GHz 与自动频段模式在受支持的双频目标上可用但可用性不等于在 5 GHz 语料上的检测性能验证HE20、HT40、VHT40 及更宽布局需要各自的显式推广promotion流程。在 ALGORITHMS.md 中可以看到一致的表述The current detection corpus validates 2.4 GHz HT20 with HT-LTF; 5 GHz VHT20 detection quality remains uncharacterized.当前检测语料验证的是 2.4 GHz HT20 HT-LTF5 GHz VHT20 检测质量尚未刻画。五步运行时准入顺序ADR 给出了明确的运行时准入顺序这也是理解整个契约的主干validate structure—— 校验载荷结构validate PHY, LTF, and width metadata—— 校验 PHY、LTF 与带宽元数据recognize the payload layout—— 识别载荷布局normalize a named 20 MHz variant—— 归一化命名的 20 MHz 变体route to sensing or an explicit drop path—— 路由到感知路径或显式丢弃路径。源码中的实现证据这一顺序在 csi_format_classifier.h 的assess_ht20_sensing_format中得到了完整落地src/cpp/runtime/esp_idf/csi_format_classifier.h。其执行路径与 ADR 的五个步骤一一对应结构校验info nullptr、info-buf nullptr、len 0、奇数长度分别映射到NULL_OR_EMPTY、BAD_LENGTH硬件与 PHY 校验非零rx_state优先判定为RX_ERROR硬件故障优先于畸形载荷避免无关的坏接收污染格式切换重置计数在 HE 能力的芯片C5/C6上非零rxend_state判定为RX_END_ERRORrx_channel_estimate_info_vld 0判定为INVALID_ESTIMATE随后通过csi_info_is_ht20_sensing/csi_info_is_vht20_sensing/csi_info_is_legacy_lltf判定 PHY 与带宽布局识别依据长度常量切换到HT20_64、HT20_57、HT20_64_DOUBLE、HT20_57_DOUBLE、LLTF20_53等布局 ID归一化标记短布局与双倍布局被标记为NORMALIZED视图并携带对应的NormalizedCSIPayloadTag如HT57_TO_64、DOUBLE_HT20、LLTF53_TO_64路由或丢弃CsiFormatDisposition::SENSE或DROP决定去向reason_code作为遥测字段。值得注意的细节是UNEXPECTED_LTF这个 reason code 在注释中明确标注为 host-only 词汇——ESP-IDF 的rx_ctrl元数据无法把 LTF 与 PHY 决策分开因此固件分类器在遇到该情形时报告UNSUPPORTED_PHY保留该词汇只是为了与主机侧 reason 词表对齐csi_format_classifier.h。PHY 元数据判定两种芯片代际的分支csi_phy_filter.h 展示了 ESP-IDF 元数据在两种芯片代际上的差异HE 能力芯片C5/C6通过cur_bb_format RX_BB_FORMAT_HT且second 0U判定 HT20VHT20 需要RX_BB_FORMAT_VHT且second 0U经典芯片ESP32/S2/S3 等HT20 需要sig_mode 1U且cwb 0UVHT 不支持。该头文件注释明确指出其与主机侧assess_ht20_sensing_recordphy_modeht、channel_width20对齐保证固件与工具在 PHY 层面判定一致。采集 profile 与频段策略的物理含义三种命名 profilecsi_capture_profile.h 定义了三种物理采集 profile以及构建期策略到物理 profile 的解析HT2020 MHz 802.11nHT载荷训练字段为 HT-LTFLLTF20legacy OFDM 长训练字段LLTF用于 ESP32 / ESP32-S2 等经典芯片这些芯片不支持 HT 的 8 位 CSI 模式VHT2020 MHz 802.11acVHT载荷用于 VHT 能力的 5 GHz 链路。resolve_csi_capture_profilecsi_capture_profile.h展示了构建期策略AUTO/LLTF/HT_VHT如何被解析为物理 profile请求LLTF或AUTO且芯片偏好 LLTF20ESP32/S2→LLTF20支持 VHT20 且信道号 14即 5 GHz→VHT20其余情况 →HT20。频段策略与构建期配置频段选择是显式的集成方决策。在 espectre_config/Kconfig.projbuild 中可以看到ESPECTRE_WIFI_BAND_POLICYchoiceESPECTRE_WIFI_BAND_2G2.4 GHz onlyESPECTRE_WIFI_BAND_5G5 GHz onlydepends on SOC_WIFI_SUPPORT_5GESPECTRE_WIFI_BAND_AUTO自动 2.4/5 GHz 选择同样依赖双频能力。默认值按目标能力区分双频目标默认AUTO否则默认2G。5 GHz 与自动选择都要求双频硅片。运行时配置侧runtime_sensing_kconfig.cpp会把CONFIG_ESPECTRE_WIFI_BAND_5G映射到WifiBandPolicy::BAND_5G否则落到BAND_2G。带宽、HT/VHT 与 HE 上限契约强制在选定频段上固定 20 MHz 带宽2.4 GHz 上使用HT802.11nHT-LTF5 GHz 上使用VHT802.11acVHT-LTF禁止 HE802.11ax / Wi-Fi 6采集。这也解释了 csi_format.h 中布局检测逻辑的成因Wi-Fi 6HE 能力部件交付以 DC 为中心的 HT20 CSIbin 子载波 32而经典 MAC 部件交付 Espressif 原生0~31, -32~-1顺序DC 在 bin 0。两种布局通过 guard 空 bin 区分——bin 0 和 32 在两种约定下都为空而HT20_CLASSIC_ONLY_NULL_BINS29/30/31/33/34/35与HT20_CENTERED_ONLY_NULL_BINS1/2/3/61/62/63恰好各只有一种约定下为空csi_format.h。布局归一化把变体折叠到规范 64 子载波视图支持的载荷变体csi_types.h 定义了全部相关长度常量常量值含义HT20_NUM_SUBCARRIERS64规范子载波数HT20_CSI_LEN128 B精确 64 子载波 HT20 载荷HT20_CSI_LEN_DOUBLE256 B双倍 HT20 载荷2×64 SCHT20_CSI_LEN_SHORT114 B短 HT 估计57 SCHT20_CSI_LEN_SHORT_DOUBLE228 B双倍短 HT 估计2×57 SCLLTF20_CSI_LEN_SHORT106 B紧凑 LLTF 估计53 SC归一化映射表CSI.md 给出了完整的映射表这与分类器中的CsiLayoutId和NormalizedCSIPayloadTag一一对应输入情形原始布局映射到 HT20输出Native HT20128 B 64 SC直通64 SC / 128 B短 HT 估计114 B 57 SC左补 4 个 SC、复制 57 SC、右补 3 个 SC64 SC / 128 B双倍 HT20 载荷256 B 2×64 SC折叠为 1 个128 B半部64 SC / 128 B双倍短 HT 估计228 B 2×57 SC折叠为 57 SC 半部再左补 4、右补 364 SC / 128 B紧凑 LLTF 估计106 B 53 SC居中顺序-26..26DC 在 pair 26左补 6 个 bin、右补 5 个 binDC 落到 bin 3264 SC / 128 B归一化后的分类器结果会记录raw_len、raw_num_subcarriers、normalized_len恒为HT20_CSI_LEN与normalized_num_subcarriers恒为HT20_NUM_SUBCARRIERS以及requires_normalization()视图标记csi_format_classifier.h。注意LLTF 紧凑估计的归一化只接受 8 位分量不解码打包的 12 位采样C5 的 LLTF 采集选择 8 位模式CSI.md。双布局检测与经典→居中旋转对于精确的 128 字节载荷detect_ht20_bin_layoutcsi_format.h要求双向正证据一组 guard 完全为空且另一组完全有能量才判定布局仅凭无能量不足以下结论稀疏或退化载荷在两种约定下都为空。识别为CLASSIC布局后rotate_ht20_classic_to_centered通过交换两半旋转 32 bin 是自身的逆把0~31, -32~-1映射到-32~31csi_format.h。检测器视图的进一步准备归一化后检测器还消费一个规范居中 64 子载波视图ALGORITHMS.md 中的 canonical centered 64-subcarrier view。prepare_ht20_detector_inputcsi_format.h在私有检测器缓冲区上完成两类补齐LLTF 缺失的边缘 tone±26 之外的 ±27/±28从最近的活跃 ±26 tone 复制 I/Qfirst_word_invalid且源为 CLASSIC 布局时把物理子载波 1居中 bin 33从 2 复制。选择依据只有采集 profile、硬件标志和原始 bin 顺序——有效的零值永远不被当作缺失数据的证据。原始 CSI 分支在准备之前运行保留零值与硬件标志。丢弃路径与 reason 遥测不支持或歧义格式直接丢弃并携带 reason 遥测是契约的关键。完整的 reason 词表定义在 csi_format_classifier.hReason code含义判定时机源码依据NULL_OR_EMPTY空指针或空载荷info nullptr/buf nullptr/len 0BAD_LENGTH长度非法奇数、非命名长度raw_len % 2 ! 0等UNSUPPORTED_PHY非 HT/VHT/LLTF 的 PHYcsi_info_is_*判定失败且非选定 PHYUNSUPPORTED_WIDTH带宽不是 20 MHzPHY 匹配但second ! 0/cwb ! 0UNEXPECTED_LTF意外的 LTFhost-only 词汇固件侧以UNSUPPORTED_PHY代替UNKNOWN_LAYOUT布局无法识别长度不在命名集合或布局检测证据不足MISSING_METADATA元数据缺失主机侧见assess_ht20_sensing_recordRX_ERROR/RX_END_ERROR硬件接收错误rx_state/rxend_state非零INVALID_ESTIMATE信道估计无效HE 芯片rx_channel_estimate_info_vld 0INVALID_FIRST_WORD首字无效且无法独立识别布局非全宽或布局检测为UNKNOWNreason 遥测被写入分类评估CsiFormatAssessment并在运行时与主机工具中用于诊断。丢弃路径与感知路径的区分由CsiFormatDisposition::DROP / SENSE承载而reset_detector_before_consume标记会在格式转换或长无效序列时要求先清除检测器历史再消费被接受的包csi_format_classifier.h。主机侧的对齐实现主机工具在 tools/lib/csi_io.py 中实现assess_ht20_sensing_recordtools/lib/csi_io.py按phy_mode与channel_width元数据执行同一套判定元数据缺失时若载荷布局本身能证明 20 MHz 契约历史采集则以METADATA_SOURCE_HISTORICAL标记并放行否则报告MISSING_METADATAphy_mode ! ht报告UNSUPPORTED_PHYchannel_width ! 20报告UNSUPPORTED_WIDTH布局评估失败时报告UNKNOWN_LAYOUT或已归一化数据上的UNNORMALIZED_LAYOUT。MicroPython 运行时也维护了等价的assess_ht20_sensing_phy与assess_ht20_payload_layoutsrc/python/micro_espectre/device_utils.py 与 L214-L238并支持metadata_missing的历史放行路径。训练与校验侧的强制失败语义契约要求require host training and validation to fail explicitly when filtering removes all valid sensing data.当过滤移除全部有效感知数据时主机训练与校验必须显式失败。从 csi_io.py 的过滤逻辑看filter_sensing_rows/filter_ht20_sensing_records等主机在批量读取数据集时会对每行执行assess_ht20_sensing_record并以 reason code 为NONE作为准入条件tools/lib/csi_io.py。当过滤后有效数据为零时上层训练/校验流程应显式失败而非静默训练空集——这保证了不支持格式永远不会悄悄污染训练数据与 ADR 的 fail loudly 目标一致。决策历史契约的演进ADR 的 Decision History 记录了该契约的三次演进对理解当前状态至关重要日期方向结果2026-07-23让 HT20 准入 classifier-first采纳2026-08-05在每个目标上强制 2.4 GHz被替换为显式的集成方频段选择同时在所有选定频段上保持 HT202026-09-01在 5 GHz 上保持 802.11n 上限被替换为在 VHT 能力的 5 GHz 目标上采用 VHT20 采集同时保留规范的 64 子载波检测器视图第二次演进强制 2.4 GHz → 集成方显式选择正是本次 ADR 在 Context 中提到的band selection was initially forced to 2.4 GHz even on dual-band targets的收尾第三次演进HT ceiling → VHT20 on 5 GHz则回答了5 GHz 上到底用什么 PHY 采集的问题并最终形成了 2026-09-01 起的lltf20 / ht20 / vht20三 profile 格局。被拒绝的替代方案及其理由ADR 记录了四个被评估并拒绝的替代方案这些理由构成了契约的边界条件替代方案拒绝理由保持 length-first先看长度再归一化结构兼容性弱于感知兼容性会静默重新解释不支持的输入接受一切可解析的 PHY 或带宽仓库对这些感知契约缺乏经过验证的映射、语料与 parity 门禁在双频设备上强制 2.4 GHz不必要地剥夺集成方选择权验证状态应独立于受支持的无线配置面记录到处使用自动频段选择固定频段部署需要确定性策略集成方必须能显式选择目标频段其中接受一切可解析的 PHY 或宽度被拒绝的理由在源码中得到呼应UNSUPPORTED_WIDTH与UNSUPPORTED_PHY是两个独立的 reason code且 HE/40 MHz/更宽布局的映射、语料与 parity 门禁在仓库中均未建立。后果与影响ADR 的 Consequences 部分总结了采纳后的影响这些在源码中均可验证运行时与主机工具共享同一条感知准入边界C 的assess_ht20_sensing_formatcsi_format_classifier.h、MicroPython 的assess_ht20_sensing_phy/assess_ht20_payload_layoutdevice_utils.py与主机工具assess_ht20_sensing_recordcsi_io.py实现同一套语义reason 词表对齐。不支持的 PHY 大声失败而不是污染检测器或训练数据reason 遥测 显式丢弃路径保证坏数据不会流入特征提取。规范 64 子载波检测器视图保持稳定运行时可从芯片与关联频段选择 LLTF20、HT20 或 VHT20 采集但检测器永远看到同一个居中 64 子载波网格。采集侧的差异在进入检测器之前全部被归一化吸收。新 PHY 支持需要完整证据链布局映射、代表性数据、检测器验证与 Python/C parity 四者缺一不可。这也是 csi_pipeline.cpp 中归一化后normalization_tag与reset_detector_before_consume标记被消费csi_pipeline.cpp的原因——格式转换被当作检测器生命周期边界处理。测试验证布局归一化在 LLTF20 下全量覆盖test_csi_pipeline_lltf20_normalizes_all_ht_layouts_before_detector 直接验证了契约在固件侧的落地在LLTF20profile 下依次注入 128 / 114 / 256 / 228 字节四种受支持长度断言每包都到达检测器expected_packets递增、短布局被正确映射到物理 tone -28..28 的居中网格且 LLTF 边缘 tone 补齐生效nearest_edge_tones_copied。这印证了分类→归一化→路由在真实采集链路上的行为。关联文档导航本 ADR 的前置决策2026-07-03-unify-raw-csi-collection-over-http.md统一 raw CSI 采集传输、2026-07-25-select-the-classic-band-from-channel-coherence.md经典频段选择定义了固定 12-tone 频段DEFAULT_SUBCARRIERS (4, 8, 13, 18, 23, 28, 36, 41, 46, 51, 56, 60)系统级文档ALGORITHMS.md检测算法与语料现状、ARCHITECTURE.md运行时架构采集与归一化细节CSI.md其他相关决策2026-08-15-use-fixed-temporal-csi-admission.md时间槽准入、2026-08-28-retain-provenance-filtered-csi-admission.md来源过滤准入。如需在实际设备上配置可参考 espectre_config/Kconfig.projbuild 中的ESPECTRE_WIFI_BAND_POLICY与ESPECTRE_CSI_CAPTURE_PROFILE选项或在 ESPHome / Native / Matter 前端对应的 YAML 与 Kconfig 中指定auto、lltf、ht-vht采集策略。【免费下载链接】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 感知准入契约：classifier-first 20 MHz CSI 接收规范
ESPectre 感知准入契约classifier-first 20 MHz CSI 接收规范【免费下载链接】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 仓库中的架构决策记录 2026-07-23-adopt-classifier-first-ht20-sensing-contract.md系统讲解 ESPectreESP32 Wi-Fi CSI 运动感知如何通过先分类、后归一化的准入契约确保进入检测器和训练数据的每一条 CSI 记录都符合生产级 20 MHz 感知契约。你将掌握为什么字节长度不能证明 CSI 有效、lltf20/ht20/vht20三类采集 profile 的物理含义、五步运行时准入顺序、以及 2.4 GHz / 5 GHz 频段选择与检测验证状态的边界。读完本文你将能够理解并审查 ESPectre 固件与主机工具共享的 CSI 准入边界并知道如何在源码中定位与验证这一契约。背景为什么字节长度不足以定义有效输入Parsing a CSI payload does not prove that it is valid detector input.——ADR 原文ESPectre 过去存在两个叠加的隐患固件与主机工具过度依赖字节长度推断格式一段能解析出 I/Q 对的字节流未必是检测器认可的物理格式。长度相同不代表布局相同、PHY 相同、子载波网格相同。频段选择被强制为 2.4 GHz即使在双频目标上早期实现也一律强制 2.4 GHz 采集。生产契约必须把三件事独立定义PHY 准入HT/VHT/ legacy LLTF 是否被允许布局归一化载荷布局能否映射到内部 64 子载波网格Wi-Fi 频段选择2g/5g/auto由集成方显式决定。从源码结构看这套契约在仓库中被拆分为多个职责单一的头文件与实现csi_phy_filter.h 负责 PHY 元数据判定csi_format_classifier.h 负责在归一化之前完成分类csi_payload_normalizer.h 负责把已识别的布局归一化到 64 子载波网格。运行时与主机工具共用同一套准入语义tools/lib/csi_io.py 中的assess_ht20_sensing_record与 C 侧assess_ht20_sensing_format相互对齐。决策唯一的 classifier-first 感知契约ADR 明确采纳一条显式的 classifier-first 感知契约其核心规则如下规则内容命名 profile 白名单生产感知仅接受lltf20、ht20、vht20三种采集 profile布局识别只接受能映射到内部 64 子载波网格的已识别布局分类先行每个数据包或数据集行在归一化之前必须先分类归一化范围只归一化命名的 20 MHz 布局包括精确的 64 子载波载荷以及显式支持的短估计与双倍估计丢弃策略不支持或歧义的格式直接丢弃并携带 reason 遥测训练校验当过滤移除全部有效感知数据时主机侧训练与校验必须显式失败历史数据保留没有 PHY 元数据的历史采集仅当其存储布局本身能证明符合受支持的 20 MHz 契约时才保留频段与带宽由前端或 SDK 集成方选择2g、5g或auto同时强制 20 MHz 带宽、2.4 GHz 上使用 HT、5 GHz 上使用 VHT、禁止 HE 采集验证语料与频段的边界ADR 特别强调一个容易被误解的边界经过验证的检测器语料仍是 2.4 GHz5 GHz 与自动频段模式在受支持的双频目标上可用但可用性不等于在 5 GHz 语料上的检测性能验证HE20、HT40、VHT40 及更宽布局需要各自的显式推广promotion流程。在 ALGORITHMS.md 中可以看到一致的表述The current detection corpus validates 2.4 GHz HT20 with HT-LTF; 5 GHz VHT20 detection quality remains uncharacterized.当前检测语料验证的是 2.4 GHz HT20 HT-LTF5 GHz VHT20 检测质量尚未刻画。五步运行时准入顺序ADR 给出了明确的运行时准入顺序这也是理解整个契约的主干validate structure—— 校验载荷结构validate PHY, LTF, and width metadata—— 校验 PHY、LTF 与带宽元数据recognize the payload layout—— 识别载荷布局normalize a named 20 MHz variant—— 归一化命名的 20 MHz 变体route to sensing or an explicit drop path—— 路由到感知路径或显式丢弃路径。源码中的实现证据这一顺序在 csi_format_classifier.h 的assess_ht20_sensing_format中得到了完整落地src/cpp/runtime/esp_idf/csi_format_classifier.h。其执行路径与 ADR 的五个步骤一一对应结构校验info nullptr、info-buf nullptr、len 0、奇数长度分别映射到NULL_OR_EMPTY、BAD_LENGTH硬件与 PHY 校验非零rx_state优先判定为RX_ERROR硬件故障优先于畸形载荷避免无关的坏接收污染格式切换重置计数在 HE 能力的芯片C5/C6上非零rxend_state判定为RX_END_ERRORrx_channel_estimate_info_vld 0判定为INVALID_ESTIMATE随后通过csi_info_is_ht20_sensing/csi_info_is_vht20_sensing/csi_info_is_legacy_lltf判定 PHY 与带宽布局识别依据长度常量切换到HT20_64、HT20_57、HT20_64_DOUBLE、HT20_57_DOUBLE、LLTF20_53等布局 ID归一化标记短布局与双倍布局被标记为NORMALIZED视图并携带对应的NormalizedCSIPayloadTag如HT57_TO_64、DOUBLE_HT20、LLTF53_TO_64路由或丢弃CsiFormatDisposition::SENSE或DROP决定去向reason_code作为遥测字段。值得注意的细节是UNEXPECTED_LTF这个 reason code 在注释中明确标注为 host-only 词汇——ESP-IDF 的rx_ctrl元数据无法把 LTF 与 PHY 决策分开因此固件分类器在遇到该情形时报告UNSUPPORTED_PHY保留该词汇只是为了与主机侧 reason 词表对齐csi_format_classifier.h。PHY 元数据判定两种芯片代际的分支csi_phy_filter.h 展示了 ESP-IDF 元数据在两种芯片代际上的差异HE 能力芯片C5/C6通过cur_bb_format RX_BB_FORMAT_HT且second 0U判定 HT20VHT20 需要RX_BB_FORMAT_VHT且second 0U经典芯片ESP32/S2/S3 等HT20 需要sig_mode 1U且cwb 0UVHT 不支持。该头文件注释明确指出其与主机侧assess_ht20_sensing_recordphy_modeht、channel_width20对齐保证固件与工具在 PHY 层面判定一致。采集 profile 与频段策略的物理含义三种命名 profilecsi_capture_profile.h 定义了三种物理采集 profile以及构建期策略到物理 profile 的解析HT2020 MHz 802.11nHT载荷训练字段为 HT-LTFLLTF20legacy OFDM 长训练字段LLTF用于 ESP32 / ESP32-S2 等经典芯片这些芯片不支持 HT 的 8 位 CSI 模式VHT2020 MHz 802.11acVHT载荷用于 VHT 能力的 5 GHz 链路。resolve_csi_capture_profilecsi_capture_profile.h展示了构建期策略AUTO/LLTF/HT_VHT如何被解析为物理 profile请求LLTF或AUTO且芯片偏好 LLTF20ESP32/S2→LLTF20支持 VHT20 且信道号 14即 5 GHz→VHT20其余情况 →HT20。频段策略与构建期配置频段选择是显式的集成方决策。在 espectre_config/Kconfig.projbuild 中可以看到ESPECTRE_WIFI_BAND_POLICYchoiceESPECTRE_WIFI_BAND_2G2.4 GHz onlyESPECTRE_WIFI_BAND_5G5 GHz onlydepends on SOC_WIFI_SUPPORT_5GESPECTRE_WIFI_BAND_AUTO自动 2.4/5 GHz 选择同样依赖双频能力。默认值按目标能力区分双频目标默认AUTO否则默认2G。5 GHz 与自动选择都要求双频硅片。运行时配置侧runtime_sensing_kconfig.cpp会把CONFIG_ESPECTRE_WIFI_BAND_5G映射到WifiBandPolicy::BAND_5G否则落到BAND_2G。带宽、HT/VHT 与 HE 上限契约强制在选定频段上固定 20 MHz 带宽2.4 GHz 上使用HT802.11nHT-LTF5 GHz 上使用VHT802.11acVHT-LTF禁止 HE802.11ax / Wi-Fi 6采集。这也解释了 csi_format.h 中布局检测逻辑的成因Wi-Fi 6HE 能力部件交付以 DC 为中心的 HT20 CSIbin 子载波 32而经典 MAC 部件交付 Espressif 原生0~31, -32~-1顺序DC 在 bin 0。两种布局通过 guard 空 bin 区分——bin 0 和 32 在两种约定下都为空而HT20_CLASSIC_ONLY_NULL_BINS29/30/31/33/34/35与HT20_CENTERED_ONLY_NULL_BINS1/2/3/61/62/63恰好各只有一种约定下为空csi_format.h。布局归一化把变体折叠到规范 64 子载波视图支持的载荷变体csi_types.h 定义了全部相关长度常量常量值含义HT20_NUM_SUBCARRIERS64规范子载波数HT20_CSI_LEN128 B精确 64 子载波 HT20 载荷HT20_CSI_LEN_DOUBLE256 B双倍 HT20 载荷2×64 SCHT20_CSI_LEN_SHORT114 B短 HT 估计57 SCHT20_CSI_LEN_SHORT_DOUBLE228 B双倍短 HT 估计2×57 SCLLTF20_CSI_LEN_SHORT106 B紧凑 LLTF 估计53 SC归一化映射表CSI.md 给出了完整的映射表这与分类器中的CsiLayoutId和NormalizedCSIPayloadTag一一对应输入情形原始布局映射到 HT20输出Native HT20128 B 64 SC直通64 SC / 128 B短 HT 估计114 B 57 SC左补 4 个 SC、复制 57 SC、右补 3 个 SC64 SC / 128 B双倍 HT20 载荷256 B 2×64 SC折叠为 1 个128 B半部64 SC / 128 B双倍短 HT 估计228 B 2×57 SC折叠为 57 SC 半部再左补 4、右补 364 SC / 128 B紧凑 LLTF 估计106 B 53 SC居中顺序-26..26DC 在 pair 26左补 6 个 bin、右补 5 个 binDC 落到 bin 3264 SC / 128 B归一化后的分类器结果会记录raw_len、raw_num_subcarriers、normalized_len恒为HT20_CSI_LEN与normalized_num_subcarriers恒为HT20_NUM_SUBCARRIERS以及requires_normalization()视图标记csi_format_classifier.h。注意LLTF 紧凑估计的归一化只接受 8 位分量不解码打包的 12 位采样C5 的 LLTF 采集选择 8 位模式CSI.md。双布局检测与经典→居中旋转对于精确的 128 字节载荷detect_ht20_bin_layoutcsi_format.h要求双向正证据一组 guard 完全为空且另一组完全有能量才判定布局仅凭无能量不足以下结论稀疏或退化载荷在两种约定下都为空。识别为CLASSIC布局后rotate_ht20_classic_to_centered通过交换两半旋转 32 bin 是自身的逆把0~31, -32~-1映射到-32~31csi_format.h。检测器视图的进一步准备归一化后检测器还消费一个规范居中 64 子载波视图ALGORITHMS.md 中的 canonical centered 64-subcarrier view。prepare_ht20_detector_inputcsi_format.h在私有检测器缓冲区上完成两类补齐LLTF 缺失的边缘 tone±26 之外的 ±27/±28从最近的活跃 ±26 tone 复制 I/Qfirst_word_invalid且源为 CLASSIC 布局时把物理子载波 1居中 bin 33从 2 复制。选择依据只有采集 profile、硬件标志和原始 bin 顺序——有效的零值永远不被当作缺失数据的证据。原始 CSI 分支在准备之前运行保留零值与硬件标志。丢弃路径与 reason 遥测不支持或歧义格式直接丢弃并携带 reason 遥测是契约的关键。完整的 reason 词表定义在 csi_format_classifier.hReason code含义判定时机源码依据NULL_OR_EMPTY空指针或空载荷info nullptr/buf nullptr/len 0BAD_LENGTH长度非法奇数、非命名长度raw_len % 2 ! 0等UNSUPPORTED_PHY非 HT/VHT/LLTF 的 PHYcsi_info_is_*判定失败且非选定 PHYUNSUPPORTED_WIDTH带宽不是 20 MHzPHY 匹配但second ! 0/cwb ! 0UNEXPECTED_LTF意外的 LTFhost-only 词汇固件侧以UNSUPPORTED_PHY代替UNKNOWN_LAYOUT布局无法识别长度不在命名集合或布局检测证据不足MISSING_METADATA元数据缺失主机侧见assess_ht20_sensing_recordRX_ERROR/RX_END_ERROR硬件接收错误rx_state/rxend_state非零INVALID_ESTIMATE信道估计无效HE 芯片rx_channel_estimate_info_vld 0INVALID_FIRST_WORD首字无效且无法独立识别布局非全宽或布局检测为UNKNOWNreason 遥测被写入分类评估CsiFormatAssessment并在运行时与主机工具中用于诊断。丢弃路径与感知路径的区分由CsiFormatDisposition::DROP / SENSE承载而reset_detector_before_consume标记会在格式转换或长无效序列时要求先清除检测器历史再消费被接受的包csi_format_classifier.h。主机侧的对齐实现主机工具在 tools/lib/csi_io.py 中实现assess_ht20_sensing_recordtools/lib/csi_io.py按phy_mode与channel_width元数据执行同一套判定元数据缺失时若载荷布局本身能证明 20 MHz 契约历史采集则以METADATA_SOURCE_HISTORICAL标记并放行否则报告MISSING_METADATAphy_mode ! ht报告UNSUPPORTED_PHYchannel_width ! 20报告UNSUPPORTED_WIDTH布局评估失败时报告UNKNOWN_LAYOUT或已归一化数据上的UNNORMALIZED_LAYOUT。MicroPython 运行时也维护了等价的assess_ht20_sensing_phy与assess_ht20_payload_layoutsrc/python/micro_espectre/device_utils.py 与 L214-L238并支持metadata_missing的历史放行路径。训练与校验侧的强制失败语义契约要求require host training and validation to fail explicitly when filtering removes all valid sensing data.当过滤移除全部有效感知数据时主机训练与校验必须显式失败。从 csi_io.py 的过滤逻辑看filter_sensing_rows/filter_ht20_sensing_records等主机在批量读取数据集时会对每行执行assess_ht20_sensing_record并以 reason code 为NONE作为准入条件tools/lib/csi_io.py。当过滤后有效数据为零时上层训练/校验流程应显式失败而非静默训练空集——这保证了不支持格式永远不会悄悄污染训练数据与 ADR 的 fail loudly 目标一致。决策历史契约的演进ADR 的 Decision History 记录了该契约的三次演进对理解当前状态至关重要日期方向结果2026-07-23让 HT20 准入 classifier-first采纳2026-08-05在每个目标上强制 2.4 GHz被替换为显式的集成方频段选择同时在所有选定频段上保持 HT202026-09-01在 5 GHz 上保持 802.11n 上限被替换为在 VHT 能力的 5 GHz 目标上采用 VHT20 采集同时保留规范的 64 子载波检测器视图第二次演进强制 2.4 GHz → 集成方显式选择正是本次 ADR 在 Context 中提到的band selection was initially forced to 2.4 GHz even on dual-band targets的收尾第三次演进HT ceiling → VHT20 on 5 GHz则回答了5 GHz 上到底用什么 PHY 采集的问题并最终形成了 2026-09-01 起的lltf20 / ht20 / vht20三 profile 格局。被拒绝的替代方案及其理由ADR 记录了四个被评估并拒绝的替代方案这些理由构成了契约的边界条件替代方案拒绝理由保持 length-first先看长度再归一化结构兼容性弱于感知兼容性会静默重新解释不支持的输入接受一切可解析的 PHY 或带宽仓库对这些感知契约缺乏经过验证的映射、语料与 parity 门禁在双频设备上强制 2.4 GHz不必要地剥夺集成方选择权验证状态应独立于受支持的无线配置面记录到处使用自动频段选择固定频段部署需要确定性策略集成方必须能显式选择目标频段其中接受一切可解析的 PHY 或宽度被拒绝的理由在源码中得到呼应UNSUPPORTED_WIDTH与UNSUPPORTED_PHY是两个独立的 reason code且 HE/40 MHz/更宽布局的映射、语料与 parity 门禁在仓库中均未建立。后果与影响ADR 的 Consequences 部分总结了采纳后的影响这些在源码中均可验证运行时与主机工具共享同一条感知准入边界C 的assess_ht20_sensing_formatcsi_format_classifier.h、MicroPython 的assess_ht20_sensing_phy/assess_ht20_payload_layoutdevice_utils.py与主机工具assess_ht20_sensing_recordcsi_io.py实现同一套语义reason 词表对齐。不支持的 PHY 大声失败而不是污染检测器或训练数据reason 遥测 显式丢弃路径保证坏数据不会流入特征提取。规范 64 子载波检测器视图保持稳定运行时可从芯片与关联频段选择 LLTF20、HT20 或 VHT20 采集但检测器永远看到同一个居中 64 子载波网格。采集侧的差异在进入检测器之前全部被归一化吸收。新 PHY 支持需要完整证据链布局映射、代表性数据、检测器验证与 Python/C parity 四者缺一不可。这也是 csi_pipeline.cpp 中归一化后normalization_tag与reset_detector_before_consume标记被消费csi_pipeline.cpp的原因——格式转换被当作检测器生命周期边界处理。测试验证布局归一化在 LLTF20 下全量覆盖test_csi_pipeline_lltf20_normalizes_all_ht_layouts_before_detector 直接验证了契约在固件侧的落地在LLTF20profile 下依次注入 128 / 114 / 256 / 228 字节四种受支持长度断言每包都到达检测器expected_packets递增、短布局被正确映射到物理 tone -28..28 的居中网格且 LLTF 边缘 tone 补齐生效nearest_edge_tones_copied。这印证了分类→归一化→路由在真实采集链路上的行为。关联文档导航本 ADR 的前置决策2026-07-03-unify-raw-csi-collection-over-http.md统一 raw CSI 采集传输、2026-07-25-select-the-classic-band-from-channel-coherence.md经典频段选择定义了固定 12-tone 频段DEFAULT_SUBCARRIERS (4, 8, 13, 18, 23, 28, 36, 41, 46, 51, 56, 60)系统级文档ALGORITHMS.md检测算法与语料现状、ARCHITECTURE.md运行时架构采集与归一化细节CSI.md其他相关决策2026-08-15-use-fixed-temporal-csi-admission.md时间槽准入、2026-08-28-retain-provenance-filtered-csi-admission.md来源过滤准入。如需在实际设备上配置可参考 espectre_config/Kconfig.projbuild 中的ESPECTRE_WIFI_BAND_POLICY与ESPECTRE_CSI_CAPTURE_PROFILE选项或在 ESPHome / Native / Matter 前端对应的 YAML 与 Kconfig 中指定auto、lltf、ht-vht采集策略。【免费下载链接】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），仅供参考