espectre

应用程序

francescopace/espectre

基于 Wi-Fi CSI 的移动检测系统,集成 Home Assistant。

项目简介

ESPectre 通过分析 Wi-Fi 信道状态信息 (CSI) 检测人体运动,仅需约 10 欧元的 ESP32 设备,无需摄像头或麦克风,保护隐私。原生集成 Home Assistant,支持多种检测算法,包括基于神经网络的检测器。

README 预览

[](https://github.com/francescopace/espectre/blob/main/LICENSE)\n[](https://esphome.io/)\n[](https://www.espressif.com/en/products/socs)\n[](https://github.com/francescopace/espectre/releases/latest)\n[](https://github.com/francescopace/espectre/actions/workflows/ci.yml?query=branch%3Amain)\n[](https://codecov.io/gh/francescopace/espectre)\n\n# 🛜 ESPectre 👻\n\n**Motion detection system based on Wi-Fi spectre analysis (CSI), with native Home Assistant integration via ESPHome.**\n\n> [!TIP]\n> **New ML Detector**: Neural network-based motion detection. No calibration required, runs on-device. This is an experimental feature, and feedback is welcome in the dedicated [ML detector discussion](https://github.com/francescopace/espectre/discussions/126). A [snapshot build](https://github.com/francescopace/espectre/releases/tag/snapshot) with the latest changes is also available (use `-ml` assets for the machine learning based detector), or follow [Setup guide](SETUP.md#choosing-detection-algorithm) for custom configuration.\n\n---\n\n## Table of Contents\n\n- [In 3 Points](#in-3-points)\n- [What You Need](#what-you-need)\n- [Quick Start](#quick-start)\n- [How It Works](#how-it-works-simple-version)\n- [What You Can Do With It](#what-you-can-do-with-it)\n- [Sensor Placement Guide](#where-to-place-the-sensor)\n- [System Architecture](#system-architecture)\n- [FAQ](#faq-for-beginners)\n- [Security and Privacy](#security-and-privacy)\n- [Technical Deep Dive](#technical-deep-dive)\n- [Two-Platform Strategy](#two-platform-strategy)\n- [Future Evolution](#future-evolution)\n- [Documentation](#documentation)\n- [Media](#media)\n- [Related Projects](#related-projects)\n- [Acknowledgments](#acknowledgments)\n- [License](#license)\n- [Author](#author)\n\n---\n\n## In 3 Points\n\n1. **What it does**: Detects movement using Wi-Fi (no cameras, no microphones)\n2. **What you need**: A ~€10 ESP32 device (S3 and C6 recommended, other variants supported)\n3. **Setup time**: 10-15 minutes\n

常见问题 (5)

故障排除
为什么 ESP32-S3 在启动 ESPHome/ESPectre 后长时间处于校准状态,该如何解决?

校准时间过长通常意味着实际的有效 CSI 数据包速率远低于配置的 traffic_generator_rate。默认的基于 DNS 的流量生成器可能会被某些路由器忽略或限速。请在 YAML 配置中将流量生成器切换为 ping 模式,然后重新编译并烧录:

espectre:
  traffic_generator_rate: 100
  traffic_generator_mode: ping

重启后,检查 CSI 数据包速率是否接近 100 packets/s;校准应该会更快完成。

来源 Issue #125
故障排除
在 ESPHome 中集成 ESPectre 与 NSPanel-Easy 时,如何修复 -Wreorder 和 -Wformat= 编译器警告?

将 ESPectre 升级到 3.0.0-rc1 或更高版本,该版本修复了构造函数初始化顺序以及 %u/uint32_t 日志格式警告。在你的 YAML 中,将外部组件固定到发布标签,例如:

external_components:
  - source:
      type: git
      url: https://github.com/francescopace/espectre
      ref: 3.0.0-rc1
    components: [ espectre ]
    refresh: 300s

然后重新安装 ESPHome 固件。这些警告由 ESPectre 产生,而非 NSPanel-Easy;在 2.8.x 版本中,这些警告是非致命的,编译、OTA 安装和运动检测仍可正常工作。

来源 Issue #157
故障排除
如何修复在 ESPHome/ESP-IDF 中启用 MQTT 后出现的 ESP32-S3 Task Watchdog loopTask 复位问题?

复位是由同步 MQTT 发送在 CSI 处理、BLE 和日志记录同时运行时阻塞 ESPHome 主循环所导致的。在 ESP-IDF 上,启用异步 MQTT 发送,并通过禁用 discovery 和 MQTT 日志转发来减少 MQTT 开销:

mqtt:
  broker: broker.hivemq.com
  port: 1883
  idf_send_async: true
  discovery: false
  log_topic: None

使用以下命令重新构建并烧录:

esphome run espectre-s3.yaml

idf_send_async: true 会将 MQTT 传输移到一个独立的任务中,使其不再阻塞 loopTask。禁用 discovery 和 log_topic 可减少处理开销和网络流量。已确认该配置可以解决看门狗复位问题,同时保持 Wi-Fi、CSI、校准、运动检测、串口日志记录、Home Assistant API 和 MQTT 发布功能正常工作。

来源 Issue #147
故障排除
如何解决 Micro-ESPectre 在 ESP32-S3 上成功刷写后接收到 0 个 CSI 数据包的问题?

无需连接互联网;CSI 采集需要同一 LAN 内设备之间的本地 Wi-Fi 流量。由于 ESP32-S3 已成功关联,但在 traffic-generator 重试后 CSI 仍为 0,请从同一网络中的另一台 PC 或手机向开发板生成外部流量。使用日志中显示的 IP,例如:

Linux/macOS:
ping 192.168.1.100

Windows:
ping -t 192.168.1.100

让其在 Micro-ESPectre 启动期间运行 30–60 秒。同时确认路由器使用的是兼容模式,例如带 HT20 的 802.11n/b/g。如果在 ping 期间出现 CSI 数据包,则问题很可能在于 AP/路由器未处理内部的 traffic-generation/CSI-trigger 路径;请继续使用外部 LAN 流量,或换用另一台路由器进行测试。固件兼容性问题的可能性较小,因为 S3 芯片已被检测到且 Wi-Fi 连接成功。

来源 Issue #110
故障排除
如何修复 ESP32-S3 上 ESPectre 的 movement_score 和 motion_detected 一直停留在 "unknown" 状态的问题?

尝试降低流量生成器速率,并从 ping 模式切换到 dns 模式,然后为校准预留额外时间;校准在初始阶段可能不会产生任何日志或传感器更新:

espectre:
  id: espectre_csi
  traffic_generator_mode: dns
  traffic_generator_rate: 50

保留现有的 detection_algorithm 设置。重新刷写固件,并在超过通常的启动时间后,再检查 sensor.movement_score 和 binary_sensor.motion_detected。

如果仍然没有发布任何数据,可能的原因是 AP 不兼容:路由器必须向 ESP32-S3 返回可用的 802.11n HT20 帧。请确认路由器设置为兼容的 2.4 GHz 802.11n/b/g/n 模式,而不是不兼容的 Wi-Fi 6/AX 或仅 n(n-only)配置,并尽可能换用另一个接入点进行测试。

来源 Issue #146