ESPectre: Wi-Fi (CSI) motion detection for Home Assistant, no cameras or microphones

Espectre is a motion-detection system that uses the Wi-Fi signal itself (CSI analysis, Channel State Information) instead of cameras, microphones, or PIR sensors, with native integration into Home Assistant through ESPHome. As of September 3, 2026 it carries 9,303 stars.

---

What ESPectre is

ESPectre is firmware for ESP32 boards that turns the ordinary Wi-Fi traffic between your home router and the board into a presence sensor. When someone moves in the room, the Wi-Fi waves traveling between the router and the ESP32 get “disturbed”; the device measures that disturbance through Channel State Information (CSI) and decides whether there’s motion or not.

It isn’t a desktop software library or a server — it’s an ESPHome component written in C++ (on top of ESP-IDF) that, once flashed to the board, appears automatically in Home Assistant as a binary motion sensor, a “movement score” sensor, and an adjustable threshold. The author sums it up in three points: it detects motion via Wi-Fi (no cameras, no microphones), needs a ~$10 ESP32 board (S3 and C6 recommended), and installs in 10 to 15 minutes.

As of September 3, 2026, the README documents support for ESP32-S3, ESP32-C6, ESP32-C5, ESP32-C3, ESP32 (original), and, in experimental status, ESP32-S2. The project runs under a GPLv3 license and bills itself as “privacy first,” “through-wall,” and “100% open source.”

Origin

The repository was created on October 26, 2025 by Francesco Pace (GitHub account francescopace), whose public contact is francesco.pace@espectre.dev and whose profile links to his LinkedIn. The project carries the author’s stamp end to end: he’s the only contributor with a significant commit count (226 per the GitHub API), versus 14 from dependabot[bot] and a handful of contributors with a single commit each.

The narrative color shows up in the Show HN thread (45953977, November 17, 2025, 215 points and 50 comments). Pace describes himself as a “math graduate” and argues that, in the default mode, the system “doesn’t use Machine Learning, it relies purely on Math.” User jstanley pushed back that ML is applied math, and Pace clarified that “no ML” meant no training phase, no labeled data, and no neural network inferring the rules: all the logic in MVS mode comes from statistical signal processing.

In that same thread, Pace shared an anecdote that foreshadows the project’s interactive feature: he was working on turning ESPectre into a Wi-Fi theremin (the musical instrument played by moving a hand near the antenna), leveraging the fact that “moving variance of the spatial turbulence” is a continuous, stable value well suited to mapping directly to frequency/pitch. He also responded to someone asking about surveillance implications (“fascinating and frightening,” per culi), clarifying that the open-source nature acts as an ethical safeguard and that the project doesn’t pursue identity-recognition features, only motion detection.

The project was further documented in a two-part Medium series (“How I Turned My Wi-Fi Into a Motion Sensor,” parts 1 and 2), a piece on IoT For All, an article on Hackaday (January 28, 2026, “Make Your Own ESP32-Based Person Sensor, No Special Hardware Needed”), and an episode of its podcast (Hackaday Podcast 355, January 30, 2026, “Person Detectors, Walkie Talkies, Open Smartphones…”).

Philosophy and principles

The README and the ROADMAP explicitly state a privacy-first, vendor-neutral, and community-friendly stance. The principles verifiable in the documentation are:

• Privacy by default: no cameras, no microphones, no wearables. The README explains that the system only collects “anonymous data” about the physical characteristics of the radio channel (OFDM subcarrier amplitudes and phases and statistical variances) and that it does not collect identities, communication content, images, or audio.
• Math before models (in the default MVS mode): the author emphasizes that the default detector requires no training or labeled data. There’s also an optional experimental ML detector (a 9→32→16→1 MLP network).
• Leverage existing infrastructure: the sensor uses the 2.4 GHz Wi-Fi traffic already present at home; there’s no need to modify the router or add special hardware.
• Open and free: GPLv3, precompiled firmware on GitHub Releases, and an ethical-responsibility policy requiring users to obtain explicit consent, comply with GDPR/local laws, and not use the system for illegal surveillance, harassment, or privacy violations.
• Two-platform strategy: a “production platform” (ESPectre in C++/ESPHome, aimed at the end-user home-automation crowd) and an “R&D platform” (Micro-ESPectre in Python/MicroPython, aimed at researchers). Algorithms are prototyped and validated first in Micro-ESPectre and, once proven, ported to ESPectre in C++.

How it works

The README describes a processing pipeline with several chained stages:

1. CSI data (raw) from the Wi-Fi signal between the router and the board.
2. Gain Lock: AGC/FFT stabilization (~3 s) for coherent measurements.
3. Automatic calibration (NBVI): on every boot, the NBVI algorithm (Normalized Band Variance Index) picks 12 non-consecutive subcarriers based on stability and spectral-diversity metrics, with no manual configuration.
4. Adaptive threshold: auto computes the threshold from baseline noise (P95 × 1.1 formula), or a manual fixed value.
5. Hampel filter: removes outlier spikes in the turbulence signal (enabled by default).
6. Low-pass filter (optional, disabled by default) for smoothing.
7. Detection evaluation (MVS or ML) every evaluation_interval packets.
8. Hit filter (motion_on_hits / motion_off_hits, default 3/3): edge-triggered IDLE ↔ MOTION transitions.
9. Publication to Home Assistant: binary motion sensor published immediately on state change, periodic movement-score sensor, and a numeric threshold entity.

MVS detection: extracts one feature (spatial turbulence) and its moving variance; low CPU usage (roughly ~150 µs/packet on ESP32-S3) and requires ~10 s of NBVI calibration. ML detection: extracts 9 statistical features from a sliding window and runs MLP inference (9→32→16→1, 816 MACs); starts up in ~3 s with no band calibration, but uses pretrained weights and fixed subcarriers.

In MVS mode, the README insists on a practical condition: keep the room still for 10 seconds after boot, because automatic calibration runs during that window and any movement degrades accuracy. ML mode skips that calibration.

The ecosystem

Platforms and repos by the same author

• francescopace/espectre (this repo): the production platform, an ESPHome component in C++.
• Micro-ESPectre (micro-espectre/, a folder inside this same repo): the R&D platform in Python/MicroPython, MQTT-based (not tied to Home Assistant), with CSI analysis tools and an ML training pipeline. Aimed at academic/industrial research, activity recognition, people counting, localization, and gesture detection.
• francescopace/radio-presence-scanner (12 stars, 1 fork): a companion presence project based on BLE radio observations from host devices (Python), with an optional HTTP dashboard.
• francescopace/micropython-esp32-csi (16 stars, 1 fork): a custom MicroPython fork that exposes the ESP32’s CSI APIs; it’s the firmware base for rapid CSI prototyping in the Micro-ESPectre workflow.
• ESPectre – The Game (docs/game/, inside the repo): a browser-based reaction game that uses ESPectre’s Wi-Fi motion detection; it also doubles as an interactive threshold-tuning tool over USB.

Third-party adoption and community material

• espressif/esp-csi (1,538 stars, 232 forks): Espressif’s official CSI application repository recommends ESPectre as a “community project recommendation,” describing it as a reference implementation for bringing CSI research into real home-automation scenarios.
• adafruit/espectre (5 stars): an Adafruit fork with the same project description (a variant aimed at the Adafruit Feather board).
• Adafruit Learn: a guide, “ESPectre Human Detector for Feather.”
• Seeed Studio Wiki: “Deploying Espectre on Seeed Studio XIAO ESP32 Series with ESPHome.”
• outputlayer/espectre-sense (2 stars): a related project for presence detection, motion tracking, vital signs, and sleep analysis using 3 ESP32 Wi-Fi CSI nodes.

Note: in the repo’s fork search, the vast majority (704 forks) are personal forks with no stars; only 4 forks have 1 star each (for example bosszlatan/espectre, omgluis/espectre). We found no unofficial translations of the repo into other languages.

Official and semi-official status

• Espressif recognition: the official espressif/esp-csi repository links to and presents ESPectre as a recommended community project. ESPectre’s own README thanks Espressif for “recognizing ESPectre as a community project in their esp-csi repository.” This is endorsement from the chip vendor, not a quality certification.
• “Made for ESPHome” compliance: the v2.1.0 release notes (December 10, 2025) state that “all example configurations now meet ‘Made for ESPHome’ requirements” (BLE provisioning via esp32_improv, USB provisioning via improv_serial, captive portal). This aligns the example configurations with ESPHome’s guidelines for provisionable devices.
• Presence in the Home Assistant ecosystem: ESPectre installs as an ESPHome external component and appears via auto-detection in Home Assistant; there’s also a dedicated thread on the official Home Assistant forum (see Reception). We found no formal “de facto standard” designation or listing in a third-party plugin marketplace in the sources consulted; its status is that of a widely adopted community component cited by the hardware manufacturer.

Quick-start guide

Installation and first boot

Requirements: an ESP32 board with CSI support (S3/C6 recommended, C5/C3/original ESP32 also tested, S2 experimental), a USB cable, a 2.4 GHz Wi-Fi router, and Home Assistant (on Raspberry Pi, PC, NAS, or cloud). No programming or router configuration required.

Option A — Web flashing (no code):

1. Download the .bin for the latest release from Releases for your chip (e.g., espectre-2.8.0-esp32c6.bin).
2. Open ESPConnect in Chrome, connect the board via USB, select the port, choose the .bin, and click Flash.
3. Configure Wi-Fi via BLE (the ESPHome / Home Assistant Companion app), via USB (web.esphome.io), or via captive portal (connect to the “ESPectre Fallback” network).
4. The device auto-detects in Home Assistant.

Option B — ESPHome CLI (for developers):

python3 -m venv venv && source venv/bin/activate
pip install esphome                 # ESPHome >= 2026.5.0, Python 3.12 (3.14 has known issues)
esphome run espectre-c6.yaml        # example file downloaded for your platform

The example files (per platform) already pull the component automatically from GitHub. For development/contribution, the -dev.yaml files are used (local source, secrets.yaml, logger: DEBUG, and debug sensors).

On first boot (MVS mode), keep the room still for 10 seconds for NBVI calibration; the logs show ✓ Calibration successful: [<12 auto-selected subcarriers>].

Common workflows

• To detect motion and turn on lights only when someone is present: the binary motion sensor appears in Home Assistant via auto-detection; you create an automation that turns on a switch when binary_sensor becomes MOTION and turns it off when it returns to IDLE.
• To tune sensitivity without re-flashing: in MVS mode, the adaptive threshold recalculates on every boot; real-time adjustment via the Home Assistant slider or “The Game” is temporary (session-only), so to persist the value you change segmentation_threshold in the YAML and run esphome run <config>.yaml. Rule of thumb: false positives → auto or a higher threshold (2.0–5.0); missed motion → min or a lower threshold (0.5–0.8).
• To switch algorithms: in the YAML, espectre: detection_algorithm: ml activates the experimental neural detector (starts in ~3 s, no band calibration); mvs (default) uses moving variance.
• To test detection live: esphome logs <config>.yaml shows state=MOTION / state=IDLE while you walk around the room.

Essential configuration

Parameters are edited under the espectre: section of the YAML. The five a new user will touch first:

Parameter	Default	What it’s for
detection_algorithm	mvs	Choose between moving variance (mvs) and the experimental neural network (ml).
segmentation_threshold	auto	Sensitivity: auto (adaptive, minimizes false positives), min (maximum sensitivity), or a number 0.0–10.0.
segmentation_window_size	100	Packets in the moving-variance window (10–200); 100 is the recommended balance.
traffic_generator_rate	100	Packets/second the sensor generates to measure CSI (0–1000); 0 disables the generator and uses external Wi-Fi traffic.
motion_on_hits / motion_off_hits	3 / 3	Consecutive hits needed to switch to MOTION / back to IDLE (debounce).

Common pitfalls and fixes

• Motion during boot degrades detection (MVS): NBVI calibration runs during the first ~10 s; if someone moves, accuracy suffers. Fix: keep the room still on boot.
• Threshold adjusted via the slider doesn’t persist: changes via Home Assistant or “The Game” are session-only; the adaptive threshold recalculates on every boot. To persist it, set segmentation_threshold in the YAML and re-flash.
• No logs after flashing on boards with a USB-UART bridge (CH340, CP2102, CH343): uncomment hardware_uart: UART0 in the YAML’s logger: section.
• Python 3.14 with ESPHome: known issues exist; use Python 3.12.
• ESP32-C5 without improv_serial: USB provisioning isn’t supported yet in ESPHome; use BLE or Wi-Fi AP.
• Original ESP32 (WROOM-32) without gain lock: AGC/FFT unavailable; CSI amplitudes may have more variation than on newer chips.
• Routers that rate-limit or ignore root-domain DNS queries: v2.8.0 switched the default traffic mode to ping (ICMP) specifically for this reason (dns is still available).
• Doesn’t distinguish people from pets: the model is a 2-state one (IDLE/MOTION) and detects generic motion; it doesn’t classify people vs. pets or activity (that depends on advanced ML models, not yet ready).

Integrations and migration

• Home Assistant / ESPHome: native integration via auto-detection (binary motion sensor + movement score + adjustable threshold). Works with ESPHome integrated into Home Assistant or standalone (also via Docker / add-on).
• Micro-ESPectre (MQTT): for environments that don’t want Home Assistant, the R&D platform publishes over MQTT, enabling flexible integrations.
• Wi-Fi mesh: works normally; the ESP32 associates with the mesh node with the best 2.4 GHz signal and monitors that specific node’s CSI.
• Adding to existing devices: a forum user asked about combining it with ESPHome Bluetooth proxies; the author flagged it as theoretical and untested, pointing to the sdkconfig settings needed to enable CSI.
• Migrating from PIR/cameras: since it’s a motion sensor (not a presence sensor), it behaves essentially like a PIR (detects active movement; if someone is still, it reports “no motion”). The author notes that presence detection (micro-movements like breathing) is on the roadmap via Micro-ESPectre.

Current metrics

Measured: September 3, 2026, GitHub API.

Metric	Value
Stars	9,303
Forks	704
Subscribers (real watchers)	97
Open issues per the API	6
Commits on the main branch	253
Primary language (API)	Python
License	GPL-3.0 (GPLv3)
Created	October 26, 2025
Last metadata update	September 3, 2026
Latest stable release	2.8.0, May 21, 2026
Latest pre-release	snapshot-dev, August 22, 2026

Real language composition (bytes): Python 996,113, C++ 448,563, HTML 124,858, Jupyter Notebook 91,280, C 23,285, Shell 7,885, CMake 302. The top contributor is francescopace (226 commits), followed by dependabot[bot] (14) and kylefmohr (2); everyone else has 1 commit each.

API caveats: open_issues_count (6) may include open pull requests, so it shouldn’t be read as an issues-only count. watchers_count mirrors the star count (9,303), so subscribers_count (97) is reported separately as real watchers. The 253 count corresponds to the default main branch, obtained by paginating the commits API.

Community reception

Hacker News — Show HN 45953977 (November 17, 2025, 215 points, 50 comments). Concrete anchors:

• tetris11: “Amazing stuff! Am I right in understanding that only a single ESP32 device is needed (plus a router)?” — immediate interest in the minimal hardware.
• roger_: had spent “two years” working on the same idea with ESP-IDF and couldn’t get “the statistical signal processing just right” (had tried LMS, Kalman, NEWMA/MMD kernel methods, CUSUM/GLR detectors, random projections, online PCA). The exchange with the author about the architecture (traffic between router and ESP32 in station mode versus STA/AP) is one of the densest technical discussions in the thread.
• Gys: asked about tommysense.com, a similar project. francescopace replied that Tommysense builds a sensing mesh between devices, while ESPectre uses the existing Wi-Fi router as the transmitter; ESPectre needs one device per area and “is open-source.”
• jstanley: objected to the “no Machine Learning” claim; the author clarified that it refers to no training phase or neural network in MVS mode.
• culi: “The surveillance implications for this technology are fascinating and frightening.” — the author replied that open source acts as an ethical safeguard and that it doesn’t pursue identity recognition.
• sgc: asked whether it could be calibrated to ignore cats; the author clarified it only does binary IDLE/MOTION detection.
• The author shared the Wi-Fi theremin idea, and acl asked about mesh routers (answer: the ESP32 associates with the node with the best signal).

Other Hacker News submissions: 45869402 (November 9, 2025, 5 points, 1 comment) and 46437438 (December 30, 2025, 5 points, 2 comments, about espectre.dev).

Home Assistant forum — thread 961251 (December 11, 2025). Anchors:

• Saoshen: asked whether the board needs to be dedicated and how to use it with existing ESP32 devices without affecting their original purpose. The author replied that CSI requires ESP32-family hardware/firmware and recommended dedicated boards (C6) for their low cost.
• Pfandadler: pushed for ambition toward presence detection instead of simple motion, for lighting and heating automations. The author explained that ESPectre does motion detection (like a PIR: still = “no motion”) and that presence (micro-movements, breathing) is on the roadmap via Micro-ESPectre.
• justone: pointed out that “presence is limited to known individuals, while movement includes unwanted guests,” and tried a variant with promising results.

Taken together: clear enthusiasm for the minimal hardware, the privacy angle, and native Home Assistant integration, plus a recurring — and honestly acknowledged by the author — criticism that this is motion, not presence, with advanced classification (people vs. pets, activity) not yet available.

Comparison with similar projects

Only real, verifiable competitors (cited from the project’s own ROADMAP and the HN thread):

Project	Verifiable overlap	Verifiable difference
Tommysense (tommysense.com)	Wi-Fi presence sensing mentioned as similar in the Show HN.	Builds a sensing mesh between devices; ESPectre uses the existing router as the transmitter and is open source (per the author’s reply in the thread).
Origin Wireless	Wi-Fi presence detection (cited in the ROADMAP).	Proprietary and cloud-dependent; ESPectre bills itself as open source, edge-first, and subscription-free.
Cognitive Systems	Wi-Fi sensing (cited in the ROADMAP).	Enterprise-only and high-cost; ESPectre targets ~$5 of hardware and DIY.
Tommysense / BLE mesh (via Bermuda BLE / ESPHome Bluetooth proxy)	In the HN thread, a user mentioned Bermuda BLE trilateration and ESPHome proxies.	BLE/mesh approach versus router-Wi-Fi CSI.

The project’s ROADMAP claims ESPectre is “uniquely positioned as the only production-ready open-source WiFi sensing platform with native home automation integration.” That claim comes from the project itself and doesn’t constitute independent verification.

How to contribute

The repo documents a complete process in CONTRIBUTING.md:

• Branch model: develop is the active development branch (all PRs target develop); main is the stable release branch (merges from develop).
• Flow: fork → clone → create a branch from develop (git checkout -b feature/...) → changes with tests and documentation → run tests → commit with clear messages (types feat/fix/docs/test/refactor/perf/chore) → push → PR to develop.
• DCO required: CI enforces the Developer Certificate of Origin; every commit needs a Signed-off-by trailer (git commit -s).
• Tests: C++ via cd test && pio test (ESPHome/PlatformIO Unity); Python via cd micro-espectre && pytest tests/ -v (with --cov for coverage). Stated criteria: >80% coverage on core modules, green CI, documentation, and one review approval.
• Data contributions: labeled CSI datasets for ML (gestures and HAR) are accepted under micro-espectre/data/<label>/, with quality requirements (≥10 samples per label, ≥30 s each, a still room for the baseline) and setup documentation.
• License: contributions are published under GPLv3 and must be certified with the DCO trailer.

Use cases and who this repository can help

• Home Assistant enthusiasts who want presence without cameras: the component integrates via auto-detection and enables lighting, heating, and security automations with a binary motion sensor at ~$10 per board. This is the core, best-documented use case.
• Elder care / wellness monitoring: the README cites it for monitoring activity and detecting prolonged inactivity or falls (fall detection itself depends on advanced HAR ML models not yet ready). Well suited for those who prioritize privacy over cameras in bedrooms or bathrooms.
• Home security: alerting if someone enters while the house is empty; the HN thread and the forum emphasize “unwanted” movement versus the presence of known individuals.
• Energy savings and climate control: turning on/off or conditioning only occupied zones, per the README’s examples.
• CSI / HAR / localization researchers and developers: Micro-ESPectre (Python, MQTT) provides the rapid-prototyping pipeline, analysis tools, and ML training pipeline to explore people counting, activity recognition, localization, and gestures, with the option to port validated results into production firmware.
• Education and outreach: “The Game” (browser-based reaction game) and the Adafruit/Seeed guides make it useful for workshops and demonstrations of Wi-Fi sensing without specialized hardware.

Resources

• Repository: https://github.com/francescopace/espectre
• Official site / documentation: https://espectre.dev
• Installation guide (SETUP.md): https://github.com/francescopace/espectre/blob/main/SETUP.md
• Tuning guide (TUNING.md): https://github.com/francescopace/espectre/blob/main/TUNING.md
• Algorithms (ALGORITHMS.md): https://github.com/francescopace/espectre/blob/main/micro-espectre/ALGORITHMS.md
• Performance metrics (PERFORMANCE.md): https://github.com/francescopace/espectre/blob/main/PERFORMANCE.md
• Roadmap (ROADMAP.md): https://github.com/francescopace/espectre/blob/main/ROADMAP.md
• Contributing (CONTRIBUTING.md): https://github.com/francescopace/espectre/blob/main/CONTRIBUTING.md
• Releases / precompiled firmware: https://github.com/francescopace/espectre/releases
• The Game (interactive demo / threshold tuning): https://espectre.dev/game
• Micro-ESPectre (R&D platform): https://github.com/francescopace/espectre/tree/main/micro-espectre
• The author’s sibling projects: https://github.com/francescopace/radio-presence-scanner · https://github.com/francescopace/micropython-esp32-csi
• Espressif endorsement: https://github.com/espressif/esp-csi (recommended as a community project)
• Home Assistant forum: https://community.home-assistant.io/t/espectre-wi-fi-motion-detection-for-home-assistant/961251
• Hacker News threads: https://news.ycombinator.com/item?id=45953977 · https://news.ycombinator.com/item?id=45869402 · https://news.ycombinator.com/item?id=46437438
• The author’s articles (Medium): Part 1 · Part 2
• Press: Hackaday (Jan 28, 2026) · IoT For All · Hackaday Podcast 355
• Third-party guides: Adafruit Learn · Seeed Studio Wiki
• Video (YouTube): ESPectre — @GithubAwesome (short)
• Community: the repository’s GitHub Issues and GitHub Discussions (author contact: francesco.pace@espectre.dev)

---

Methodology note: this article draws on the README, the guides (SETUP/TUNING/PERFORMANCE/ROADMAP/CONTRIBUTING) and release notes of ESPectre, the GitHub API, Hacker News results, and the Home Assistant forum consulted on September 3, 2026. Figures (stars, forks, commits, performance metrics) change over time.