[opensourcedex]

espectre is a free, open source internet of things (iot) project written in Python and released under GPL-3.0. It has 9,388 GitHub stars, 709 forks and 13 open issues, and was last pushed 14 hours ago. On this registry it ranks #5 of 45 tracked projects in Internet of Things (IoT), with 5 head-to-head comparisons available.

What is espectre?

ESPectre is an open-source Wi-Fi CSI motion-sensing platform that turns a supported ESP32 board into a private, local motion sensor reporting movement in real time, and it is built for embedded developers, Home Assistant users, and DIY builders who want room-level sensing without cameras, microphones, wearables, or dedicated radar hardware.

What it is

ESPectre is a platform for turning Wi-Fi channel state information (CSI) into motion detection on Espressif ESP32 hardware. It bundles ready-to-flash firmware, an embeddable C++ SDK, a MicroPython implementation called Micro-ESPectre, browser tools, a host CLI covering the full device lifecycle, an open dataset, open model weights, and the research workflow used to build and validate the detectors. It lives in the Espressif ecosystem: the project is published as the ESP-IDF component francescopace/espectre on the ESP-IDF component registry, with a staging registry entry, and it ships Native, ESPHome, and Matter frontends alongside its Python tooling. It is licensed under GPLv3, with commercial licensing also offered.

The concrete problem it addresses is presence detection without invasive sensing hardware. Rather than installing a camera, a microphone, a wearable, or dedicated radar equipment, ESPectre reads the changes a moving person causes in the Wi-Fi signals already travelling through a room, processes CSI on the device, and reports a motion state and movement score so applications can react without sending raw sensing data to a cloud service.

Key capabilities

  • On-device CSI processing that outputs a motion state and a movement score locally, with no raw sensing data sent to a cloud service.
  • Four firmware paths: Native for standalone sensors and MQTT integrations, ESPHome for Home Assistant, Matter for occupancy-sensor controllers, and Micro-ESPectre for lightweight MicroPython sensing.
  • Home Assistant integration through ESPHome or MQTT, including Home Assistant MQTT Discovery.
  • A standard Matter occupancy sensor and a local Direct HTTP API.
  • An embeddable C++ SDK plus the published ESP-IDF component francescopace/espectre on the ESP-IDF registry and staging registry.
  • Browser-based flashing at espectre.dev/tools/flash/, further browser tools, and a host CLI, with no local build environment required.
  • Support for ESP32-C6, ESP32-C5, ESP32-C3, ESP32-S3, ESP32-S2 and classic ESP32 on a normal Wi-Fi 4 (802.11n) 2.4 GHz network.

Who uses it and how

  • Home Assistant users who choose the ESPHome frontend get native entities, ESPHome provisioning, and Device Builder updates.
  • Builders of standalone sensors and custom applications use the Native frontend for MQTT integrations, including Home Assistant MQTT Discovery.
  • Matter controllers with occupancy-sensor support can consume the Matter frontend, although controller validation is still limited.
  • MicroPython users run Micro-ESPectre for lightweight sensing with local, read-only Direct HTTP monitoring.
  • Room automation is the common workload: switching on displays or lights, adjusting heating and cooling in response to activity, or triggering an alarm when movement occurs in an area that should be empty. One board covers one sensing area, so room-level coverage normally requires one board per room.

Getting started

The quickest path runs in the browser at espectre.dev/tools/flash/ with no local build environment, using desktop Chrome 151 or later. Otherwise the project is consumed as the ESP-IDF component francescopace/espectre, through the C++ SDK, or through the per-frontend READMEs for Native, ESPHome, Matter, and Micro-ESPectre.

How it compares

The facts supplied for this entry name no paid or competing products, so no licence, self-hosting, data-ownership, or cost comparison can be drawn. ESPectre stands alone in this registry: the adjacent projects named in its documentation, namely Home Assistant, ESPHome, MQTT, and Matter, are integrations it feeds rather than tools it displaces.

When to use it — and when not to

A self-hoster needs the physical deployment as much as the software: one supported ESP32 board per sensing area on a normal Wi-Fi 4 (802.11n) 2.4 GHz network, plus a controller or automation layer to act on the reported state; the facts mention no server-side database, object storage, or SMTP service to operate. It is not the right choice if the requirement is to identify people, count them, prove a room is empty, or replace a safety-certified security, medical, or emergency system, because ESPectre detects changes in the radio environment and nothing more. The Matter frontend is the weakest path today, since its controller validation is still limited, and the README excerpt ends mid-sentence, so the homepage and guides should be consulted for current instructions.

project readme (upstream, from github) — read inline

License SoC ESP-IDF component ESP-IDF staging CI main C++ coverage Python coverage Web coverage

ESPectre

Turn an ESP32 into a private, local Wi-Fi motion sensor.

When someone moves through a room, they change the way Wi-Fi signals travel through it. ESPectre reads those changes and reports motion in real time. No camera, no microphone, no wearable, and no dedicated radar hardware: just a supported ESP32 and the Wi-Fi network already in the room.

ESPectre is an open-source platform that brings together ready-to-flash firmware, an embeddable C++ SDK, a MicroPython implementation, browser tools, a host CLI, an open dataset, open model weights, and the research workflow used to build and validate the detectors.

Flash from your browser · See the live tools · Read the documentation · Explore the SDK

Applications and integrations

ESPectre can turn on a display or lights when it detects motion, adjust heating and cooling in response to room activity, trigger an alarm or notification when movement occurs in an area that should be empty, and drive other room automations. It connects to Home Assistant through ESPHome or MQTT, exposes a standard Matter occupancy sensor and a local Direct HTTP API, and can be embedded in custom ESP32 firmware through the C++ SDK.

ESPectre processes CSI on the device and reports a motion state and movement score. Applications can react without sending raw sensing data to a cloud service. One board covers one sensing area; room-level coverage normally requires one board per room.

ESPectre detects changes in the radio environment. It does not identify people, count them, prove that a room is empty, or replace a safety-certified security, medical, or emergency system.

Supported hardware

  • ESP32-C6, ESP32-C5, ESP32-C3, ESP32-S3, ESP32-S2, and classic ESP32
  • a normal Wi-Fi 4 (802.11n) network on 2.4 GHz

Choose a firmware path

Path Best for Start here
Native Standalone sensors, MQTT integrations, including Home Assistant MQTT Discovery, and custom applications Native frontend
ESPHome Home Assistant users who want native entities, ESPHome provisioning, and Device Builder updates ESPHome frontend
Matter Matter controllers with occupancy-sensor support; controller validation is still limited Matter frontend
Micro-ESPectre Lightweight sensing in MicroPython with local, read-only Direct HTTP monitoring Micro-ESPectre README

Quick start

The quickest path uses the browser and requires no local build environment. Use desktop Chrome 151 or later for the complete hosted workflow. Edge supports browser flashing, but compatibility with Device settings and Monitor is not guaranteed:

  1. Open Flash in desktop Chrome or Edge.
  2. Connect a supported ESP32 over USB, then choose a firmware and release channel.
  3. Complete on-screen Wi-Fi provisioning, or commission Matter with a supported controller.
  4. Optionally, open Device settings to pin a preferred access point or set up MQTT.
  5. Open Monitor to watch motion, tune detection, and inspect the device.

ESPectre Monitor

Matter status: The Matter frontend is still being validated across controller ecosystems. A controller may support standard Matter occupancy sensors without having been tested with current firmware. See Matter controller compatibility for the current matrix.

Local setup

For local builds, flashing from this repository, and the rest of the operator path, start with SETUP.md. The repository wrapper exposes the available workflows through:

./espectre --help

Documentation

Topic What it covers Guides
Install and operate Device setup, CLI workflows, and troubleshooting SETUP.md, CLI.md, TROUBLESHOOTING.md
Understand and integrate Runtime architecture, CSI acquisition, API, discovery, algorithms, and the C++ SDK ARCHITECTURE.md, CSI.md, API.md, DISCOVERY.md, ALGORITHMS.md, SDK.md
Collect and train CSI collection, model training, feature history, performance, and literature ML_DATA_COLLECTION.md, ML_TRAINING.md, FEATURES.md, performance report, LITERATURE.md
Research and direction Roadmap, architecture decisions, and release history ROADMAP.md, ADR index, CHANGELOG.md
Frontend reference Firmware-path READMEs for ESPHome, Native, Matter, and Micro-ESPectre ESPHome, Native, Matter, Micro
Contributing Contributions, release procedures, and project discussions CONTRIBUTING.md, RELEASING.md, GitHub Discussions

Datasets, models, and validation

ESPectre publishes the research assets and validation evidence behind its detectors:

Asset What it gives you Start here
CSI dataset Real recordings for empty rooms, static presence, and motion, with catalog and provenance in dataset_info.json data/
Model weights Trained weights in C++ and Python, plus the training, export, and validation workflow ML_TRAINING.md
Feature ledger Features that were tested, promoted, or rejected, including unsuccessful experiments FEATURES.md
Algorithms and reports Detector behavior, the generated performance report, and the dataset quality report ALGORITHMS.md
Literature and direction External research, architecture decision records, and the public roadmap LITERATURE.md

Security, privacy, and transparency

A sensor that can reveal presence should not be a black box. Wi-Fi sensing avoids images and audio, but motion and occupancy data can still reveal routines, sleep, or absence from home. ESPectre treats that risk as part of the engineering work:

  • motion detection is local, and cloud connectivity is not required;
  • raw CSI collection is optional and intended for defined research and debugging needs;
  • the security and responsible-use guide documents deployment boundaries, consent, data minimization, abuse reporting, and private vulnerability reporting;
  • firmware releases include build-specific SBOMs, notices, and license archives so their contents can be inspected;
  • the public website and every browser tool are part of this repository under docs/web, including their source, privacy rules, analytics contract, and pinned browser dependencies;
  • protocols, algorithms, performance evidence, limitations, roadmap decisions, and known validation boundaries are documented in public.

Use ESPectre only in spaces and networks where you have the right to deploy it. Inform affected people, obtain consent where required, protect access to the device and its data, and follow applicable privacy laws.

Acknowledgments

License

ESPectre first-party code is available under GPLv3, and eligible parts are also available under a separate commercial agreement:

  • Choose GPLv3 when your firmware or application can comply with GPLv3, including making the corresponding source available. See LICENSE.
  • If you want to embed ESPectre in proprietary or closed-source firmware without GPLv3 source-disclosure obligations, see LICENSING.md for commercial licensing. The commercial license covers eligible material and does not replace third-party terms; the ESPHome C++ frontend remains GPLv3-only.

Third-party terms and build-specific compliance artifacts are described in THIRD_PARTY_NOTICES.md.

Frequently asked questions

Is espectre free to use?

espectre is open source under the GPL-3.0 licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does espectre do?

Wi-Fi CSI motion sensing for ESP32. C++ SDK, ESPHome, Native, and Matter frontends, browser tools, and a CLI for the full device lifecycle. GPLv3 and commercial

What is espectre written in?

espectre is primarily written in Python. Its source is publicly available at https://github.com/francescopace/espectre, and it has 9,388 GitHub stars.