🛜 ESPectre 👻 - Motion detection system based on Wi-Fi spectre analysis (CSI), with Home Assistant integration.

Motion detection system based on Wi-Fi spectre analysis (CSI), with native Home Assistant integration via ESPHome.

• In 3 Points
• What You Need
• Quick Start
• How It Works
• What You Can Do With It
• Sensor Placement Guide
• System Architecture
• FAQ
• Security and Privacy
• Technical Deep Dive
• Two-Platform Strategy
• Future Evolution
• Documentation
• Media
• Related Projects
• Acknowledgments
• License
• Author

1. What it does: Detects movement using Wi-Fi (no cameras, no microphones)
2. What you need: A ~€10 ESP32 device (S3 and C6 recommended, other variants supported)
3. Setup time: 10-15 minutes

• 2.4GHz Wi-Fi Router - the one you already have at home works fine
• ESP32 with CSI support - ESP32-C6, ESP32-S3, ESP32-C3, ESP32 (original) or other variants. See SETUP.md for the complete platform comparison table.

ESP32-S3 DevKit with external antennas

• Home Assistant (on Raspberry Pi, PC, NAS, or cloud)
• ESPHome (integrated in Home Assistant or standalone)

• Basic YAML knowledge for configuration
• Home Assistant familiarity (optional but recommended)
• NO programming required
• NO router configuration needed

Setup time: ~10-15 minutes
Difficulty: Easy (YAML configuration only)

1. Setup & Installation: Follow the complete guide in SETUP.md
2. Tuning: Optimize for your environment with TUNING.md

Home Assistant dashboard with real-time motion detection, threshold control, and debug sensors

When someone moves in a room, they "disturb" the Wi-Fi waves traveling between the router and the sensor. It's like when you move your hand in front of a flashlight and see the shadow change.

The ESP32 device "listens" to these changes and understands if there's movement.

• No cameras (total privacy)
• No wearables needed (no bracelets or sensors to wear)
• Works through walls (Wi-Fi passes through walls)
• Very cheap (~€10 total)

Want to understand the technical details? See ALGORITHMS.md for CSI explanation and signal processing documentation.

• Home security: Get an alert if someone enters while you're away
• Elderly care: Monitor activity to detect falls or prolonged inactivity
• Smart automation: Turn on lights/heating only when someone is present
• Energy saving: Automatically turn off devices in empty rooms
• Child monitoring: Alert if they leave the room during the night
• Climate control: Heat/cool only occupied zones

Optimal sensor placement is crucial for reliable movement detection.

Optimal range: 3-8 meters

Do:

• Position sensor in the area to monitor (not necessarily in direct line with router)
• Height: 1-1.5 meters from ground (desk/table height)
• External antenna: Use IPEX connector for better reception

Don't:

• Avoid metal obstacles between router and sensor (refrigerators, metal cabinets)
• Avoid corners or enclosed spaces (reduces multipath diversity)

ESPectre uses a focused processing pipeline for motion detection:

┌─────────────┐
│  CSI Data   │  Raw Wi-Fi Channel State Information
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  Gain Lock  │  AGC/FFT stabilization (~3 seconds)
│             │  Locks hardware gain for stable measurements
└──────┬──────┘
       │
       ▼
┌─────────────┐
│    Auto     │  Automatic subcarrier selection (once at boot)
│ Calibration │  Selects optimal 12 subcarriers (NBVI)
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  Adaptive   │  auto: P95 × 1.1 | min: P100
│  Threshold  │  or fixed manual value
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   Hampel    │  Turbulence outlier removal
│   Filter    │  (enabled by default)
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  Low-pass   │  Noise reduction (smoothing)
│   Filter    │  (optional, disabled by default)
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Detection   │  MVS or ML score
│ Evaluation  │  every evaluation_interval packets
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Hit Filter  │  motion_on_hits / motion_off_hits
│             │  edge-driven IDLE ↔ MOTION
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Home        │  Edge-driven motion binary +
│ Assistant   │  periodic Movement Score / Threshold
└─────────────┘

┌─────────┐  ┌─────────┐  ┌─────────┐
│ ESP32   │  │ ESP32   │  │ ESP32   │
│ Room 1  │  │ Room 2  │  │ Room 3  │
└────┬────┘  └────┬────┘  └────┬────┘
     │            │            │
     └────────────┴────────────┘
                  │
                  │ ESPHome Native API
                  ▼
         ┌────────────────────┐
         │   Home Assistant   │
         │   (Auto-discovery) │
         └────────────────────┘

Each sensor is automatically discovered by Home Assistant with:

• Binary sensor for motion detection, published immediately on state edges
• Movement score sensor, published on the periodic cadence
• Adjustable threshold (number entity)

ESPectre implements NBVI (Normalized Band Variance Index) for automatic subcarrier selection, achieving near-optimal performance (F1>96%) with zero manual configuration. The algorithm selects 12 non-consecutive subcarriers based on stability metrics and spectral diversity.

⚠️ IMPORTANT (MVS mode): Keep the room quiet and still for 10 seconds after device boot. The auto-calibration runs during this time and movement will affect detection accuracy. ML mode skips calibration.

For algorithm details, see ALGORITHMS.md.

For algorithm details (MVS, NBVI calibration, Hampel filter), see ALGORITHMS.md.

For performance metrics (confusion matrix, F1-score, benchmarks), see PERFORMANCE.md.

This project follows a dual-platform approach to balance innovation speed with production stability:

Target: End users, smart home enthusiasts, Home Assistant users

• ESPHome component with native Home Assistant integration
• YAML configuration - no programming required
• Auto-discovery - devices appear automatically in Home Assistant
• Production-ready - stable, tested, easy to deploy
• Demonstrative - showcases research results in a user-friendly package

Target: Researchers, developers, academic/industrial applications

• Python/MicroPython implementation for rapid prototyping
• MQTT-based - flexible integration (not limited to Home Assistant)
• Fast iteration - test new algorithms in seconds, not minutes
• Analysis tools - comprehensive suite for CSI data analysis
• Use cases: Academic research, industrial sensing, algorithm development

Micro-ESPectre gives you the fundamentals for:

• People counting
• Activity recognition (walking, falling, sitting, sleeping)
• Localization and tracking
• Gesture recognition

┌─────────────────────┐     Validated      ┌──────────────────────┐
│   Micro-ESPectre    │ ─────────────────► │      ESPectre        │
│   (R&D Platform)    │    algorithms      │ (Production Platform)│
│                     │                    │                      │
│ • Fast prototyping  │                    │ • ESPHome component  │
│ • Algorithm testing │                    │ • Home Assistant     │
│ • Data analysis     │                    │ • End-user ready     │
│ • MQTT flexibility  │                    │ • Native API         │
└─────────────────────┘                    └──────────────────────┘

Innovation cycle: New features and algorithms are first developed and validated in Micro-ESPectre (Python), then ported to ESPectre (C++) once proven effective.

While ESPectre v2.x focuses on motion detection (MVS + automatic subcarrier selection), the project is exploring machine learning capabilities for advanced applications:

The ML Detector is already available with detection_algorithm: ml in your YAML configuration. For algorithm details, see ALGORITHMS.md and PERFORMANCE.md for current metrics
The ML data collection and training infrastructure is documented in ML_DATA_COLLECTION.md.

See ROADMAP.md for detailed plans, timelines, and how to contribute.

• radio-presence-scanner: complementary presence-sensing project focused on BLE radio observations from host devices (Python), with optional HTTP dashboard.
• micropython-esp32-csi: custom MicroPython fork exposing ESP32 CSI APIs, used as the firmware foundation for rapid CSI prototyping in the Micro-ESPectre workflow.

ESPectre leverages the native Wi-Fi CSI capabilities of ESP32 chips. Thanks to Espressif for making CSI accessible in the ESP-IDF framework and for recognizing ESPectre as a community project in their esp-csi repository.

This project is released under the GNU General Public License v3.0 (GPLv3).

GPLv3 ensures that:

• The software remains free and open source
• Anyone can use, study, modify, and distribute it
• Modifications must be shared under the same license
• Protects end-user rights and software freedom

See LICENSE for the full license text.

Contributions are submitted under GPLv3 and must include a DCO Signed-off-by trailer on each commit (git commit -s).

Francesco Pace
Email: francesco.pace@espectre.dev
LinkedIn: linkedin.com/in/francescopace

If you find ESPectre useful and want to support its development, you can buy me a coffee. It's completely optional. I work on this project because I'm passionate about it. Contributions help me buy new hardware to expand the list of tested and supported devices, and dedicate more time to new features.