🛜 ESPectre 👻

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

[!TIP] New in v2.5 — ML Detector: Neural network-based motion detection. No calibration required, runs on-device. This is an experimental feature, feedback is welcome in the discussion. A snapshot build with the latest changes is also available (use -ml assets for the machine learning based detector), or follow Setup guide for custom configuration.

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
Acknowledgments
License
Author

In 3 Points

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

What You Need

Hardware

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.

3 x ESP32-S3 DevKit bundle with external antennas ESP32-S3 DevKit with external antennas

Software (All Free)

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

Required Skills

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

Quick Start

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

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

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

How It Works

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.

Advantages

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.

What You Can Do With It

Practical Examples

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

Where to Place the Sensor

Optimal sensor placement is crucial for reliable movement detection.

Recommended Distance from Router

Optimal range: 3-8 meters

| Distance | Signal | Multipath | Sensitivity | Noise | Recommendation | |----------|--------|-----------|-------------|-------|----------------| | < 2m | Too strong | Minimal | Low | Low | ❌ Too close | | 3-8m | Strong | Good | High | Low | ✅ Optimal | | > 10-15m | Weak | Variable | Low | High | ❌ Too far |

Placement Tips

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)

System Architecture

Processing Pipeline

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)
└──────┬──────┘
       │
       ▼
┌─────────────┐
│Segmentation │  MVS algorithm
│    (MVS)    │  IDLE ↔ MOTION
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Home        │  Native ESPHome integration
│ Assistant   │  Binary sensor + Movement/Threshold
└─────────────┘

Single or Multiple Sensors

┌─────────┐  ┌─────────┐  ┌─────────┐
│ 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
Movement score sensor
Adjustable threshold (number entity)

Automatic Subcarrier Selection

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.

FAQ for Beginners

<details> <summary>Click to expand FAQ</summary>

Q: Do I need programming knowledge to use it?
A: No! ESPectre uses YAML configuration files. Just download the example, flash it, and configure WiFi via the ESPHome app or web interface.

Q: Does it work with my router?
A: Yes, if your router has 2.4GHz Wi-Fi (virtually all modern routers have it).

Q: How much does it cost in total?
A: Hardware: ~€10 for an ESP32 device (S3/C6 recommended, other variants also work). Software: All free and open source. You'll also need Home Assistant running somewhere (Raspberry Pi ~€35-50, or any existing PC/NAS).

Q: Do I need to modify anything on the router?
A: No! The router works normally. The sensor "listens" to Wi-Fi signals without modifying anything.

Q: Does it work through walls?
A: Yes, the 2.4GHz Wi-Fi signal penetrates drywall. Reinforced concrete walls reduce sensitivity but detection remains possible at reduced distances.

Q: How many sensors are needed for a house?
A: It depends on size. One sensor can monitor ~50 m². For larger homes, use multiple sensors (1 sensor every 50-70 m² for optimal coverage).

Q: Can it distinguish between people and pets?
A: The system uses a 2-state segmentation model (IDLE/MOTION) that identifies generic movement without distinguishing between people, pets, or other moving objects. For more sophisticated classification (people vs pets, activity recognition, gesture detection), trained AI/ML models would be required (see Future Evolution section).

Q: Does it work with mesh Wi-Fi networks?
A: Yes, it works normally. Make sure the ESP32 connects to the 2.4 GHz band.

Q: How accurate is the detection?
A: Detection accuracy is highly environment-dependent and requires proper tuning. Factors affecting performance include: room layout, wall materials, furniture placement, distance from router (optimal: 3-8m), and interference levels. In optimal conditions with pr

Espectre

Install / Use

README