ESPectre: Camera‑free real‑time motion detection using Wi‑Fi CSI

ESPectre uses ESP32 to read Wi‑Fi CSI and leverages NBVI (and optional ML) to deliver low‑cost, on‑device, camera‑free motion detection for privacy‑focused smart homes—evaluate maintenance and license gaps before production use.

GitHub francescopace/espectre Updated 2026-06-10 Branch main Stars 8.2K Forks 633

ESP32 Smart Home Monitoring Camera‑free Privacy Home Assistant Integration

💡 Deep Analysis

What exact problem does this project solve and what is its core working principle?

Core Analysis ¶

Project Positioning: ESPectre addresses how to perform indoor motion/occupancy detection without cameras/microphones and without modifying the router, at very low cost (~€10). It captures Wi‑Fi Channel State Information (CSI) on CSI-capable ESP32 devices and runs a compact signal-processing pipeline on-device to produce binary motion events and a Movement Score, integrating natively with Home Assistant via ESPHome.

Technical Features ¶

CSI-based passive sensing: Uses perturbations in the wireless channel between router and sensor, requiring no wearable or network modification.
On-edge processing pipeline: Implements Gain Lock (AGC stabilization), NBVI automatic subcarrier selection, Hampel outlier removal, optional low-pass filtering and adaptive thresholds, optimized for MCU constraints.
Native HA integration: ESPHome exposes binary motion sensor, Movement Score and configurable thresholds for direct use in home automations.

Practical Recommendations ¶

Pre-deployment check: Ensure router-to-sensor distance is within the recommended 3–8m for best signal strength and multipath characteristics.
Start with defaults: Use NBVI and the default pipeline, then tune thresholds based on observed Movement Score distributions.
Edge-first approach: Keep processing and decisioning on-device to maximize privacy and minimize latency; only upload raw data if needed for offline analysis.

Important Notice: The system provides binary motion and a Movement Score only; it does not identify people vs pets or classify actions. Performance depends heavily on physical deployment.

Summary: ESPectre translates CSI into actionable motion events using an engineered, edge-friendly pipeline, offering a practical privacy-first option for smart-home motion detection.

88.0%

What are common deployment issues and how should sensors be placed and tuned to achieve stable detection?

Core Analysis ¶

Core Issue: Stability largely depends on physical placement and initial calibration. Incorrect placement or skipping quiet startup calibration leads to false positives/negatives.

Common Problems (Causes & Symptoms)¶

Too close (<2m): Signal saturation → missed detections due to limited dynamic range.
Too far (>10–15m): Low RSSI and high noise → missed or unreliable detections.
Metal obstructions / corners: Reduced multipath diversity → weaker subcarrier information and higher error rates.
Non-quiet startup: In MVS mode, NBVI can be contaminated, producing poor subcarrier selection.
High Wi‑Fi interference / dense networks: CSI is impacted by other traffic causing transient anomalies.

Best Practices & Tuning Steps ¶

Placement: Keep router-to-sensor distance 3–8m, sensor height 1–1.5m, avoid direct metal obstacles; use external antenna if possible.
Quiet startup (MVS): Keep the environment still for ~10s after boot to complete Gain Lock and NBVI selection.
Observe & tune: Run for 24 hours, inspect Movement Score distributions in HA, set thresholds and adjust motion_on/off_hits to reduce chatter.
Multi-sensor approach: For large rooms or critical zones, deploy multiple sensors (~50–70 m² per sensor) and aggregate events in Home Assistant to reduce false positives.

Important Notice: In environments with heavy metal or persistent interference, validate multiple locations and prefer redundant sensor coverage.

Summary: Correct placement, quiet startup calibration, iterative thresholding based on Movement Score, and multisensor redundancy are the practical steps to attain stable motion detection.

87.0%

Why can the project's signal-processing pipeline (NBVI, Hampel, Gain Lock) achieve reliable detection on an ESP32 and what are its architectural advantages?

Core Analysis ¶

Project Positioning (Architectural Strengths): ESPectre’s strength is a modular, engineered pipeline: Gain Lock (AGC/FFT stabilization) → NBVI (automatic subcarrier selection) → Hampel (outlier filtering) → optional low-pass → adaptive thresholds and hit-filters. This design is optimized for resource-constrained ESP32 devices and balances real-time performance, interpretability and deployability.

Technical Analysis ¶

Dimensionality reduction (NBVI): Selecting ~12 high-information subcarriers reduces compute and memory needs while increasing SNR.
Hardware stabilization (Gain Lock): Brief AGC/FFT stabilization removes startup and hardware-induced offsets that cause false triggers.
Robust processing (Hampel & adaptive threshold): Hampel removes impulsive interference; adaptive thresholds tune sensitivity to ambient noise, reducing manual configuration.
Edge interpretability: The modular pipeline exposes intermediate metrics (e.g., Movement Score, selected subcarriers), aiding tuning and debugging.

Usage Recommendations ¶

Keep default pipeline: Use NBVI + Hampel + adaptive thresholds unless you have signal-processing expertise.
Tuning: In noisy environments, enable low-pass filtering or adjust hit-filter parameters; increase threshold tolerance in high multipath areas to avoid missed detections.
Monitor internals: Inspect which subcarriers NBVI selects and Movement Score distributions to guide sensor placement or antenna choices.

Important Notice: While the pipeline improves usability on MCU, extreme RF interference or unusual building materials may still require manual tuning or multi-sensor deployments.

Summary: The combination of dimensionality reduction, denoising and adaptive decision-making enables practical motion detection on ESP32 with low resource consumption and clear tuning paths.

86.0%

How to scale to multi-room or large-area scenarios? What are the system scalability and Home Assistant-level aggregation strategies?

Core Analysis ¶

Core Issue: A single CSI sensor’s coverage is limited (~50–70 m²), so large-area or multi-room deployments require horizontal scaling and centralized aggregation.

Scalability Approach ¶

Physical scaling: Deploy multiple ESP32 sensors according to recommended density, prioritizing entrances, corridors, and room centers. Each device reports binary state and Movement Score via ESPHome to Home Assistant.
Central aggregation (HA layer): Use strategies in Home Assistant such as:
Majority voting / logical combination: Combine multiple sensors in the same space to reduce single-point false positives.
Time-window aggregation: Accumulate events over short windows to filter transient noise.
Template sensors & automations: Synthesize robust occupancy decisions from movement scores, thresholds and hit-counts.

Ops & Consistency ¶

Firmware management: Use ESPHome OTA/version control to push consistent firmware and parameter sets across nodes.
Calibration consistency: NBVI may choose different subcarriers per node—after baseline deployment, inspect Movement Score distributions and harmonize thresholds.
Network/bandwidth: Reporting is low-bandwidth (binary + periodic score), but ensure reliable Wi‑Fi and power to each sensor.

Important Notice: Multinode setups increase maintenance overhead; validate aggregation strategies in a few key areas before broad roll-out.

Summary: Add sensors and aggregate in Home Assistant using voting/time-window techniques and unified firmware management to scale coverage while preserving privacy and low cost.

86.0%

What are the hardware compatibility and firmware considerations? How to choose the right ESP32 model and firmware?

Core Analysis ¶

Core Issue: Not all ESP32 variants offer the same CSI capabilities or firmware support; using an incompatible board/firmware combo can break functionality.

Technical Points ¶

Preferred chips: README and the insights recommend ESP32‑S3 and ESP32‑C6 as they provide more reliable CSI support. Other variants (ESP32‑C3, original ESP32) may work but require checking SETUP.md.
Firmware branch: Use the project or community-supported firmware builds that explicitly enable CSI; some features depend on specific SDK/driver versions.
Resources for ML: If enabling the ML detector, ensure the board has enough flash/RAM to hold the model and ESPHome firmware.
Antenna & reception: For longer ranges or through-wall scenarios, prefer dev boards with IPEX external antenna connectors to boost reception.

Practical Recommendations ¶

Read docs first: Verify board support in the SETUP.md compatibility table before purchase.
Choose recommended hardware: Prefer ESP32‑S3 / ESP32‑C6 for best CSI support.
Firmware build: Use the project-provided build instructions or prebuilt images (including -ml variants for the ML detector) with matching SDK/driver versions.
Validate non-recommended boards: If using other chips, test a single device thoroughly (NBVI, Movement Score, optional ML) before mass deployment.

Important Notice: Hardware/firmware incompatibility typically manifests as missing CSI data, abnormal subcarrier counts, or excessive noise—check compatibility table first.

Summary: Selecting documented-supported chips and matching firmware, reserving resources for ML, and optionally using external antennas ensures complete functionality and better stability.

85.0%

How to trade off on-device threshold/MVS-based detection versus the new ML detector, and when to choose each mode?

Core Analysis ¶

Core Question: Should you use on-device Movement Score (MVS) + adaptive-threshold detection or the experimental on-device ML detector? The choice depends on the trade-off between stability/interpretability and deployment convenience/generalization.

Technical Comparison ¶

MVS / threshold-based (Pros):
Lightweight: Low compute and memory, fits all supported CSI-capable ESP32 devices.
Interpretable & tunable: You can inspect Movement Score distributions and tweak thresholds and hit-filter parameters.
Proven & predictable: Performs reliably when startup calibration (quiet 10s) and recommended placement (3–8m) are followed.
MVS / threshold-based (Cons):
Sensitive to startup calibration and environment changes; may require iterative tuning under RF interference or complex multipath.
ML detector (Pros):
No calibration required: Good for deployments where a quiet startup cannot be guaranteed.
Potentially better feature learning: Can capture complex temporal/frequency patterns beyond simple scoring.
ML detector (Cons):
Experimental: README marks it experimental; stability may vary by environment.
Resource & interpretability cost: Uses more flash/RAM and is harder to debug when misclassifications occur.

Practical Recommendations ¶

Conservative: Use MVS/threshold for critical monitoring or initial rollouts; observe for 24–72 hours and tune.
Experimental rollout: Try ML on a subset of sensors if you want calibration-free installs, collect metrics and compare.
Resource check: Monitor MCU memory/CPU when ML is enabled to avoid impacting ESPHome features.

Important Notice: While ML removes calibration steps, its generalization is not guaranteed—validate in target environments before full deployment.

Summary: Prefer MVS/threshold for reliability and explainability; use the ML detector when calibration-free deployment is a priority and you are prepared to test its experimental behavior.

84.0%

✨ Highlights

Low‑cost, camera‑free real‑time motion detection using CSI
Native Home Assistant integration and ESPHome compatibility
ML‑based detector is experimental and should be evaluated cautiously
Repository license, contributors and releases metadata are missing

🔧 Engineering

Collects CSI on ESP32 and uses NBVI to auto‑select subcarriers for high‑accuracy detection
No cameras or wearables required; supports multi‑sensor setups and reports to Home Assistant via ESPHome

⚠️ Risks

Compatibility varies across ESP32 variants and routers; on‑site tuning and testing may be needed
Repository lacks license, contributor records and release history, posing maintenance and legal uncertainty

👥 For who?

Suitable for smart‑home hobbyists and DIY deployers familiar with Home Assistant/ESPHome
Applicable to privacy‑sensitive homes and care scenarios needing low‑cost indoor motion monitoring