espectre
Applicationfrancescopace/espectre
Motion detection system using Wi-Fi CSI with Home Assistant integration.
Overview
ESPectre detects human movement by analyzing Wi-Fi Channel State Information (CSI) using an ESP32 microcontroller. It is privacy-friendly (no cameras or microphones), costs about €10, and integrates natively with Home Assistant via ESPHome. The project supports multiple detection algorithms including a neural network-based detector.
README Preview
[](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
FAQ (5)
TroubleshootingWhy does ESP32-S3 stay in calibration for a long time after booting ESPHome/ESPectre, and how do I fix it?
Long calibration usually means the effective CSI packet rate is far below the configured traffic_generator_rate. The default DNS-based traffic generator may be ignored or rate-limited by some routers. Switch the traffic generator to ping mode in your YAML config, then recompile and flash:
espectre:
traffic_generator_rate: 100
traffic_generator_mode: ping
After rebooting, check that the CSI packet rate is close to 100 packets/s; calibration should complete much faster.
TroubleshootingHow do I fix -Wreorder and -Wformat= compiler warnings when integrating ESPectre with NSPanel-Easy in ESPHome?
Upgrade ESPectre to 3.0.0-rc1 or newer, which fixes the constructor initialization order and %u/uint32_t logging format warnings. In your YAML, pin the external component to the release tag, for example:
external_components:
- source:
type: git
url: https://github.com/francescopace/espectre
ref: 3.0.0-rc1
components: [ espectre ]
refresh: 300s
Then reinstall the ESPHome firmware. These warnings are generated by ESPectre, not NSPanel-Easy; in 2.8.x they are non-fatal and compilation, OTA installation, and motion detection can still work.
TroubleshootingHow do I fix the ESP32-S3 Task Watchdog `loopTask` reset that occurs after enabling MQTT in ESPHome/ESP-IDF?
The reset is caused by synchronous MQTT sends blocking the ESPHome main loop while CSI processing, BLE, and logging are also running. On ESP-IDF, enable asynchronous MQTT sending and reduce MQTT overhead by disabling discovery and MQTT log forwarding:
mqtt:
broker: broker.hivemq.com
port: 1883
idf_send_async: true
discovery: false
log_topic: None
Rebuild and flash with:
esphome run espectre-s3.yaml
idf_send_async: true moves MQTT transmission into a separate task so it no longer blocks loopTask. Disabling discovery and log_topic reduces processing and network traffic. This configuration was confirmed to resolve the watchdog reset while keeping Wi-Fi, CSI, calibration, motion detection, serial logging, the Home Assistant API, and MQTT publishing working.
TroubleshootingHow to fix Micro-ESPectre receiving 0 CSI packets on ESP32-S3 after successful flashing?
Internet connectivity is not required; CSI collection needs local Wi-Fi traffic between devices on the same LAN. Since the ESP32-S3 associates successfully but CSI remains 0 after traffic-generator retries, generate external traffic toward the board from another PC or phone on the same network. Use the IP shown in the log, for example:
Linux/macOS:
ping 192.168.1.100
Windows:
ping -t 192.168.1.100
Let it run for 30–60 seconds while Micro-ESPectre starts. Also verify the router is using a compatible mode such as 802.11n/b/g with HT20. If CSI packets appear while pinging, the problem is likely the AP/router not handling the internal traffic-generation/CSI-trigger path; continue using external LAN traffic or test with another router. Firmware compatibility is less likely because the S3 chip is detected and Wi-Fi connects successfully.
TroubleshootingHow to fix ESPectre movement_score and motion_detected staying "unknown" on ESP32-S3?
Try reducing the traffic-generator rate and switching from ping to dns mode, then allow extra time for calibration; calibration can produce no logs or sensor updates initially:
espectre:
id: espectre_csi
traffic_generator_mode: dns
traffic_generator_rate: 50
Keep your existing detection_algorithm setting. Re-flash and wait beyond the usual startup period before checking sensor.movement_score and binary_sensor.motion_detected.
If it still publishes nothing, the likely cause is AP incompatibility: the router must return usable 802.11n HT20 frames to the ESP32-S3. Verify the router is set to a compatible 2.4 GHz 802.11n/b/g/n mode rather than an incompatible Wi-Fi 6/AX or n-only configuration, and test against another access point if possible.