ESPHome espectre 组件：用一块 ESP32 做零成本 Wi-Fi 人体检测

家里的人体传感器，主流方案是 PIR 红外（几块钱，只能感知”动”）和毫米波雷达（几十到几百块，能感知”存在”）。两样都要额外买硬件、接线、供电。最近 ESPHome 社区冒出个新组件 espectre，宣称只要一块手头已有的 ESP32，连上家里现成的 Wi-Fi，就能做人体移动检测，零外接硬件、零额外成本，而且全部本地推理。

Wi-Fi 信号还能”看见”人？答案是能，靠的是 CSI（Channel State Information，信道状态信息）。

CSI 原理：从”音量”到”光谱”

传统 Wi-Fi 测距定位用的 RSSI（信号强度），只是接收端汇总出来的一个能量数值。打个比方：隔壁房间喊话，你只听得到音量，隔墙、换姿势、距离一变音量就抖，所以拿 RSSI 做检测误报率高、漂移大。

CSI 完全不同。现代 Wi-Fi 用 OFDM 调制，一个 20MHz 信道被切成几十个正交子载波，CSI 记录的是每个子载波在多径传播中的振幅衰减和相位偏移，相当于把”音量”拆成了几十个频段的”光谱”。

人体约 70% 是水分，对 2.4GHz 电磁波有强反射和吸收。人走动、转身、开门、起立，打在人体上再折射到天线的多径反射会剧烈波动，CSI 就把这种波动精确记录了下来：

ESP32 的射频基带本来就吐 CSI 数据，espectre 只是把它接出来，用特征算法或轻量神经网络在芯片本地完成推断，不传云端、不需要 Python 服务器、不挂任何外接电路。

硬件选型：先看芯片再动手

espectre 对芯片有硬性要求，最常见的 ESP8266 直接不支持（老基带只有 RSSI，没有子载波级数据）。支持矩阵：

框架要求：ESP-IDF ≥ 5.5.3、Arduino ≥ 3.3.7，ESP32-C5/C6 强制 ESP-IDF。我的经验是直接选 ESP-IDF 框架最稳。

动手前先查支持列表，这是我踩过的坑：手里的”电子钟”板子是 ESP8266，编译完才发现刷不进——芯片级限制，不是配置能解决的。如果你手里有闲置板子，先确认芯片，再决定要不要投入时间。

怎么用：两条路线

路线 A：零代码，浏览器刷官方固件

用桌面版 Chrome 或 Edge 打开 espectre.dev/tools/flash，USB 连接板子，选固件和发布渠道（Release / Preview / Development），按提示配 Wi-Fi 即可。官方镜像自动给主机名加 MAC 尾缀（如 espectre-a1b2c3.local），一个镜像能服务多块板子。Firefox、Safari 和手机浏览器不支持 USB 刷写。

路线 B：ESPHome YAML，实体原生接入 Home Assistant

组件还在 Beta，用 external_components 直接从 GitHub 拉，不用等正式版：

esphome:
  name: esp32-wifi-motion
  project:
    version: "1.0.0"

esp32:
  board: esp32-s3-devkitc-1
  framework:
    type: esp-idf

wifi:
  ssid: "MyHome_2.4G"
  password: "MyPassword"
  bssid: "AA:BB:CC:DD:EE:FF"   # 多 AP 环境必须锁，见坑 4

external_components:
  - source:
      type: git
      url: https://github.com/francescopace/espectre
      path: src/cpp/frontend/esphome/components
    components: [espectre]

espectre:
  detection_algorithm: lightweight   # 或 high_accuracy
  csi_target_pps: 100
  traffic_generator_mode: ping       # ping/dns/dns_tcp/wifi_raw/external
  motion_sensor:
    name: "室内人员活动"
    device_class: motion
  movement_sensor:
    name: "活动强度分值"
    filters:
      - throttle: 1s

声明 espectre: 顶层块后，实体全部自动创建：motion_sensor（二值运动状态）、movement_sensor（0.0–1.0 运动评分）、threshold_number（阈值）、detector_select（运行时切换算法）、traffic_generator_mode_select（切换发包模式）、recalibrate_button（重标定）、csi_occupancy_sensor（诊断）等 20 多个。

一个容易踩的配置坑：网上流传的旧写法是 binary_sensor: - platform: espectre，那是早期风格，官方最新版已改为顶层 espectre: 下的命名实体，写配置以官方文档为准。

组件还在快速迭代期，直接 follow GitHub main 分支即可；想锁定版本，在 external_components 里加 ref: 指到具体 tag 或 commit。官方镜像只接受签名 OTA，所以个人编译的固件第一次必须 USB 刷入，之后才能 OTA 更新。

两种算法的取舍

lightweight（默认）：CPU 开销极低，但开机或重标定时房间必须静止至少 10 秒，用来采集纯净背景、确立检测阈值。校准期间家里有人走动，校准会延长甚至失败。适合 ESP32-C3 这类低配板子。

high_accuracy：内置预训练轻量神经网络，不需要静止标定，但 CPU 占用高，官方推荐配 ESP32-S3 使用。

两种算法运行时都可以通过 detector_select 实体热切换，选择会被记忆。recalibrate_button 可以随时手动重标定，适合家具搬动、AP 变化后重新确立基线。

五个最痛的坑

坑 1：它不是毫米波”存在”雷达。 能测走动、转身、开门、坐下起身这类动态位移，测不了静静坐着、睡觉呼吸这类静态存在。马桶上玩手机不动，几秒后它报”无人”。别拿它做卫生间的无延时关灯，适合走廊感应、玄关迎宾、客厅活动、夜间防盗警戒。

坑 2：Wi-Fi 省电被强制关闭，必须常电。 组件要求射频高频收发，底层锁定 power_save_mode=none，断线重连期间也不休眠。干电池、锂电池方案直接排除，必须 5V 常电，功耗比普通休眠节点高。

坑 3：AMPDU 帧聚合被禁用，别同板跑重流量。 为了让更多数据包携带 CSI 样本，双向禁用帧聚合。同板 Web Server 加载变慢、OTA 下载拉长，更不要同板跑 Wi-Fi 音频串流或摄像头画面。

坑 4：多 AP/Mesh 环境必须锁 BSSID。 组件会主动暂停漫游信道扫描，每次离主信道搜网都会把 CSI 数据窗口瞬间清空，在两个弱信号 AP 间摇摆会让检测完全失灵。用信号分析仪挑 -40~-70dBm 之间最稳的 AP，把 MAC 填死在 bssid 字段。

坑 5：csi_occupancy 必须 ≥ 70%。 探测窗口至少 70% 时间槽收到有效 CSI 帧，否则误报漏报。长期低于 70% 说明发包模式被路由限速或丢包，把 traffic_generator_mode 换成 wifi_raw（C6 除外），或引入外部高频 UDP 注入源（Home Assistant OS 有官方 Traffic Generator 插件）。

总结

espectre 的核心价值是”复用”：闲置的 ESP32 插上电、连上家里已有的 Wi-Fi，就多了一个免费的移动检测器，数据全程本地，不依赖任何外接硬件。它沿路由器到板子的直线感应，摆放时把板子和路由分置房间两端、让人垂直切断这条视线路径，灵敏度最高；板子别塞金属盒、远离大件遮挡物，离 AP 约 3–8 米通常是个好起点。

动手前记住三条：先查芯片支持列表（ESP8266 直接放弃，别浪费时间）；想清楚它只测动态不测静态，别用在需要”存在”判断的场景；多 AP 环境锁好 BSSID，上线后盯住 csi_occupancy 指标——它长期低于 70% 说明发包链路有问题，先解决链路再谈调参。

作为对照，商业方案 TOMMY 需要 2–4 台 ESP32 组网、Pro 版收费，但额外支持静态存在检测。如果你确实需要”存在”级判断且预算允许，TOMMY 这类方案仍然值得考虑；只做移动感知，espectre 的性价比没有对手。