Motion detection system based on Wi-Fi spectre analysis

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

⚠️ Disclaimer: This is an experimental project for educational and research purposes. The author assumes no responsibility for misuse or damage resulting from the use of this system. Use responsibly and in compliance with applicable laws.

• In 3 Points
• Mathematical Approach
• 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
• Future Evolutions
• References
• License
• Author

1. What it does: Detects movement at home using Wi-Fi (no cameras, no microphones)
2. What you need: A ~€10 device (ESP32-S3) + Home Assistant or MQTT server + ESP-IDF development tools
3. Setup time: 30-45 minutes (first time, including ESP-IDF setup)

This project currently does NOT use Machine Learning models. Instead, it employs a mathematical approach that extracts 10 features from CSI (Channel State Information) data using statistical and signal processing techniques.

• ✅ No ML training required: Works out-of-the-box with mathematical algorithms
• ✅ 10 extracted features: Statistical, spatial, and temporal features
• ✅ Real-time processing: Low latency detection on ESP32-S3 hardware
• ✅ Foundation for ML: These features can serve as the basis for collecting labeled datasets to train ML models for advanced tasks (people counting, activity recognition, gesture detection)

The mathematical approach provides excellent movement detection without the complexity of ML model training, while the extracted features offer a solid foundation for future ML-based enhancements.

• ✅ 2.4GHz Wi-Fi Router (the one you already have at home works fine)
• ✅ ESP32-S3 DevKit bundle with external antennas (~€10) - Available on Amazon, AliExpress, or electronics stores

ESP32-S3 DevKit with external antennas (recommended for better reception)

• ✅ MQTT Broker (required for operation):
  • Home Assistant with built-in MQTT broker (on Raspberry Pi, PC, NAS, or cloud)
  • OR standalone Mosquitto MQTT server (can run on any device, including Raspberry Pi)
• ✅ ESP-IDF v6.1 (development framework for building firmware)

• ✅ Basic command line knowledge required for building and flashing firmware
• ❌ NO router configuration needed
• ✅ Follow the setup guide in SETUP.md

Setup time: ~30-45 minutes (first time)
Difficulty: Intermediate (requires ESP-IDF setup)

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

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-S3 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)

Channel State Information (CSI) represents the physical characteristics of the wireless communication channel between transmitter and receiver. Unlike simple RSSI (Received Signal Strength Indicator), CSI provides rich, multi-dimensional data about the radio channel.

Per-subcarrier information:

• Amplitude: Signal strength for each OFDM subcarrier (up to 64)
• Phase: Phase shift of each subcarrier
• Frequency response: How the channel affects different frequencies

Environmental effects:

• Multipath propagation: Reflections from walls, furniture, objects
• Doppler shifts: Changes caused by movement
• Temporal variations: How the channel evolves over time
• Spatial patterns: Signal distribution across antennas/subcarriers

When a person moves in an environment, they:

• Alter multipath reflections (new signal paths)
• Change signal amplitude and phase
• Create temporal variations in CSI patterns
• Modify the electromagnetic field structure

These changes are detectable even through walls, enabling privacy-preserving presence detection without cameras, microphones, or wearable devices.

• 🏠 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

✅ 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
❌ Avoid metal obstacles between router and sensor (refrigerators, metal cabinets)
❌ Avoid corners or enclosed spaces (reduces multipath diversity)

Each sensor publishes to its own topic:

• home/espectre/kitchen
• home/espectre/bedroom
• home/espectre/living

Home Assistant can then:

• Monitor each room independently
• Create group sensors for whole-house occupancy
• Implement zone-based automations
• Track movement patterns across rooms

Q: Do I need programming knowledge to use it?
A: Basic command line skills are needed to build and flash the firmware using ESP-IDF. Follow the step-by-step guide in SETUP.md.

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 the ESP32-S3 device. Software: All free and open source. You'll also need a device to run the MQTT broker (Home Assistant or Mosquitto), which can be a Raspberry Pi (~€35-50) or any existing PC/NAS you already have (free).

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: Can I try it without Home Assistant?
A: Yes, you can use any MQTT server (e.g., Mosquitto) or even just view data via serial port.

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 detection model (IDLE/DETECTED) 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 Evolutions section).

Q: Does it consume a lot of Wi-Fi bandwidth?
A: No, MQTT traffic is minimal. With smart publishing disabled (default), the system publishes all detection updates. When smart publishing is enabled, the system only sends data on significant changes or every 5 seconds as a heartbeat, resulting in ~0.2-0.5 KB/s per sensor during idle periods and up to ~1 KB/s during active movement. Network impact is negligible.

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: Is a dedicated server necessary?
A: No, Home Assistant can run on Raspberry Pi, NAS, or cloud. Alternatively, just an MQTT broker (Mosquitto) on any device is sufficient.

Q: How accurate is the detection?
A: Detection accuracy is highly environment-dependent and requires proper calibration. Factors affecting performance include: room layout, wall materials, furniture placement, distance from router (optimal: 3-8m), and interference levels. In optimal conditions with proper calibration, the system provides reliable movement detection. Use the built-in calibration tools (MQTT commands: analyze, threshold) to tune parameters for your specific environment.

Q: What's the power consumption?
A: ~500mW typical during continuous operation. The firmware includes support for power optimization, and deep sleep modes can be implemented for battery-powered deployments, though this would require custom modifications to the code.

Q: If it doesn't work, can I get help?
A: Yes, open an Issue on GitHub or contact me via email.

The system collects anonymous data related to the physical characteristics of the Wi-Fi radio channel:

• Amplitudes and phases of OFDM subcarriers
• Statistical signal variances
• NOT collected: personal identities, communication contents, images, audio

CSI data represents only the properties of the transmission medium and does not contain direct identifying information.

✅ No cameras: Respect for visual privacy
✅ No microphones: No audio recording
✅ No wearables: Doesn't require wearable devices
✅ Aggregated data: Only statistical metrics, not raw identifying data

WARNING: Despite the intrinsic anonymity of CSI data, this system can be used for:

• Non-consensual monitoring: Detecting presence/movement of people without their explicit consent
• Behavioral profiling: With advanced AI models, inferring daily life patterns
• Domestic privacy violation: Tracking activities inside private homes

The user is solely responsible for using this system and must:

1. ✅ Obtain explicit consent from all monitored persons
2. ✅ Respect local regulations (GDPR in EU, local privacy laws)
3. ✅ Clearly inform about the presence of the sensing system
4. ✅ Limit use to legitimate purposes (home security, personal home automation)
5. ✅ Protect data with encryption and controlled access
6. ❌ DO NOT use for illegal surveillance, stalking, or violation of others' privacy

• Native ESP32 CSI API captures Wi-Fi Channel State Information via callback
• Extracts amplitude and phase data from OFDM subcarriers (up to 64 subcarriers)
• Typical capture rate: ~10-100 packets/second depending on Wi-Fi traffic

The espectre.c firmware applies an advanced multi-stage processing pipeline:

Stage 1: Advanced Filters (Configurable via MQTT)

• Butterworth Low-Pass: Removes high-frequency noise >8Hz (environmental interference) - Enabled by default
• Wavelet db4: Removes low-frequency persistent noise using Daubechies wavelet transform.
• Hampel Filter: Outlier removal using MAD (Median Absolute Deviation)
• Savitzky-Golay Filter: Polynomial smoothing (enabled by default)
• Adaptive Normalization: Running statistics with Welford's algorithm, with auto-reset to prevent signal degradation

Filter Pipeline: Raw CSI → Butterworth (high freq) → Wavelet (low freq) → Hampel → Savitzky-Golay → Normalization

Stage 2: Feature Extraction (10 mathematical features)

• Statistical (5): Variance, Skewness, Kurtosis, Entropy, IQR
• Spatial (3): Spatial variance, correlation, gradient across subcarriers
• Temporal (2): Delta mean, delta variance (changes between consecutive packets)

Stage 3: Multi-Criteria Detection

• Weighted scoring from selected features (4-6 features)
• Weights optimized via automatic calibration using Fisher's criterion
• Optimized ranges based on empirical analysis

Stage 4: State Machine (2 states)

• IDLE: No movement detected
• DETECTED: Movement detected (score above threshold)
• Debouncing: Requires consecutive detections (configurable, default: 10)
• Persistence: Timeout before downgrading state (configurable, default: 3 seconds)
• Hysteresis: Prevents state flickering using dual thresholds

• Publishes JSON payload every 1 second (configurable)
• QoS level 0 (fire-and-forget) for low latency
• Retained message option for last known state
• Automatic reconnection on connection loss

• MQTT Sensor subscribes to topic and creates entity
• State: Primary movement value (0.0-1.0)
• Attributes: All other metrics available for conditions
• History: Automatic logging to database for graphs

Trigger automations based on:

• Numeric state: movement > 0.6 (active movement)
• Confidence level: confidence > 0.7 (high certainty)
• State changes: idle → detected transitions
• Time patterns: Only during specific hours
• Template conditions: Complex logic combining multiple sensors

ESPectre uses a mathematical approach (no ML required) that extracts 10 features from CSI data:

Statistical properties of the CSI signal distribution:

1. Variance - Signal variability, increases significantly with movement
2. Skewness - Distribution asymmetry, detects irregular movement patterns
3. Kurtosis - Distribution "tailedness", identifies outliers and sudden changes
4. Entropy - Signal randomness/disorder, increases when environment changes
5. IQR (Interquartile Range) - Robust spread measure (Q3-Q1), resistant to outliers

Characteristics across OFDM subcarriers (frequency domain):

6. Spatial Variance - Variability across subcarriers, indicates multipath diversity
7. Spatial Correlation - Correlation between adjacent subcarriers, affected by movement
8. Spatial Gradient - Rate of change across subcarriers, highly sensitive to movement

Changes between consecutive CSI packets:

9. Temporal Delta Mean - Average absolute difference from previous packet
10. Temporal Delta Variance - Variance of differences from previous packet

The system automatically selects the 4-6 most discriminant features for your specific environment and optimizes their weights using Fisher's criterion. This typically provides better detection accuracy than the default configuration.

• Board: ESP32-S3-DevKitC-1 N16R8
• Flash: 16MB
• PSRAM: 8MB
• Wi-Fi: 802.11 b/g/n (2.4 GHz only)
• Antenna: Built-in PCB antenna + IPEX connector for external
• Power: USB-C 5V or 3.3V via pins

• Framework: ESP-IDF v6.1
• Language: C
• Build System: CMake
• Flash Tool: esptool.py

• CSI Capture Rate: 10-100 packets/second
• Processing Latency: <50ms per packet
• MQTT Publish Rate: Smart publishing (only on significant changes + 5s heartbeat)
• MQTT Bandwidth: ~0.2-1 KB/s depending on activity
• Power Consumption: ~500mW typical
• Detection Range: 3-8 meters optimal
• Detection Accuracy: Environment-dependent, requires calibration

• Works only on 2.4 GHz band (ESP32-S3 hardware limitation)
• Sensitivity dependent on: wall materials, antenna placement, distances, interference
• Not suitable for environments with very high Wi-Fi traffic
• Cannot distinguish between multiple people (without ML models)
• Reduced performance through metal obstacles or thick concrete walls

The current implementation uses an advanced mathematical approach with 10 features and multi-criteria detection to identify movement patterns. While this provides excellent results without requiring ML training, scientific research has shown that Machine Learning and Deep Learning techniques can extract even richer information from CSI data for complex tasks like people counting, activity recognition, and gesture detection.

Classification or regression models can estimate the number of people present in an environment by analyzing complex patterns in CSI.

References:

• Wang et al. (2017) - "Device-Free Crowd Counting Using WiFi Channel State Information" - IEEE INFOCOM
• Xi et al. (2016) - "Electronic Frog Eye: Counting Crowd Using WiFi" - IEEE INFOCOM

Neural networks (CNN, LSTM, Transformer) can classify human activities like walking, falling, sitting, sleeping.

References:

• Wang et al. (2015) - "Understanding and Modeling of WiFi Signal Based Human Activity Recognition" - ACM MobiCom
• Yousefi et al. (2017) - "A Survey on Behavior Recognition Using WiFi Channel State Information" - IEEE Communications Magazine
• Zhang et al. (2019) - "WiFi-Based Indoor Robot Positioning Using Deep Neural Networks" - IEEE Access

Deep learning algorithms can estimate position and trajectory of moving people.

References:

• Wang et al. (2016) - "CSI-Based Fingerprinting for Indoor Localization: A Deep Learning Approach" - IEEE Transactions on Vehicular Technology
• Chen et al. (2018) - "WiFi CSI Based Passive Human Activity Recognition Using Attention Based BLSTM" - IEEE Transactions on Mobile Computing

Models trained on CSI temporal sequences can recognize hand gestures for touchless control.

References:

• Abdelnasser et al. (2015) - "WiGest: A Ubiquitous WiFi-based Gesture Recognition System" - IEEE INFOCOM
• Jiang et al. (2020) - "Towards Environment Independent Device Free Human Activity Recognition" - ACM MobiCom

• UT-HAR: Human Activity Recognition dataset (University of Texas)
• Widar 3.0: Gesture recognition dataset with CSI
• SignFi: Sign language recognition dataset
• FallDeFi: Fall detection dataset

Currently, only a limited number of Wi-Fi chipsets support CSI extraction, which restricts hardware options for Wi-Fi sensing applications. However, the IEEE 802.11bf (Wi-Fi Sensing) standard should significantly improve this situation by making CSI extraction a standardized feature.

The 802.11bf standard was officially published on September 26, 2025, introducing Wi-Fi Sensing as a native feature of the Wi-Fi protocol. Main characteristics:

🔹 Native sensing: Detection of movements, gestures, presence, and vital signs
🔹 Interoperability: Standardized support across different vendors
🔹 Optimizations: Specific protocols to reduce overhead and power consumption
🔹 Privacy by design: Privacy protection mechanisms integrated into the standard
🔹 Greater precision: Improvements in temporal and spatial granularity
🔹 Existing infrastructure: Works with already present Wi-Fi infrastructure

Market: The Wi-Fi Sensing market is in its early stages and is expected to experience significant growth in the coming years as the 802.11bf standard enables native sensing capabilities in consumer devices.

Hardware availability:

• ⚠️ Consumer routers: Currently there are no widely available consumer routers with native 802.11bf support
• 🏢 Commercial/industrial: Experimental devices and integrated solutions already in use
• 🔧 Hardware requirements: Requires multiple antennas, Wi-Fi 6/6E/7 support, and AI algorithms for signal processing

Expected timeline:

• 2025-2026: First implementations in enterprise and premium smart home devices
• 2027-2028: Diffusion in high-end consumer routers
• 2029+: Mainstream adoption in consumer devices

When 802.11bf is widely adopted, applications like this project will become:

• More accessible: No need for specialized hardware or modified firmware
• More reliable: Standardization ensures predictable behavior
• More efficient: Protocols optimized for continuous sensing
• More secure: Privacy mechanisms integrated at the standard level
• More powerful: Ability to detect even vital signs (breathing, heartbeat)

Perspective: In the next 3-5 years, routers and consumer devices will natively support Wi-Fi Sensing, making projects like this implementable without specialized hardware or firmware modifications. This will open new possibilities for smart home, elderly care, home security, health monitoring, and advanced IoT applications.

For now: Solutions like this project based on ESP32 CSI API remain the most accessible and economical way to experiment with Wi-Fi Sensing.

This project builds upon extensive research in Wi-Fi sensing and CSI-based movement detection. The following academic works and theses provide valuable insights into mathematical signal processing approaches for human activity recognition using Wi-Fi Channel State Information:

1. Wi-Fi Sensing per Human Identification attraverso CSI
   University thesis (in Italian) covering CSI data collection for human recognition through Wi-Fi signal analysis, with in-depth exploration of mathematical signal processing methods.
   📄 Read thesis

2. Channel State Information (CSI) Features Collection in Wi-Fi
   Detailed analysis of CSI feature collection and processing in Wi-Fi environments, with methods for extraction and analysis suitable for mathematical processing.
   📄 Read thesis

3. Indoor Motion Detection Using Wi-Fi Channel State Information (2018)
   Scientific article describing indoor movement detection using CSI with approaches based on signal mathematics and physics, minimizing the use of machine learning models.
   📄 Read paper

4. WiFi Motion Detection: A Study into Efficacy and Performance (2019)
   Study using CSI data collected from standard devices to detect movements, with analysis of signal processing methods to extract movement events without relying on ML.
   📄 Read paper

5. CSI-HC: A WiFi-Based Indoor Complex Human Motion Recognition Using Channel State Information (2020)
   Recognition of complex indoor movements through CSI with methods based on mathematical signal features, ideal for projects with signal-based analysis without advanced ML.
   📄 Read paper

6. Location Intelligence System for People Estimation in Indoor Environment During Emergency Operation (2022)
   Demonstrates the use of ESP32 with wavelet filtering (Daubechies db4) for people detection in emergency scenarios. This paper directly influenced ESPectre's wavelet filter implementation, showing that wavelet denoising outperforms traditional filters on ESP32 hardware.
   📄 Read paper

These references demonstrate that effective Wi-Fi sensing can be achieved through mathematical and statistical approaches, which is the foundation of ESPectre's design philosophy.

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.

Francesco Pace
📧 Email: [email protected]
💼 LinkedIn: linkedin.com/in/francescopace
🛜 Project: ESPectre