espectre README

The project's README from github.com/francescopace/espectre. As one markdown file: README.md.

License SoC CI main C++ coverage Python coverage Web coverage

ESPectre ESPectre logo

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

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 How to contribute and where to discuss the project CONTRIBUTING.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:

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:

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

espectre (francescopace/espectre)

Searching Database…

9.6K ·GitHub
Espectre
Что это такое?ESPectre превращает поддерживаемую плату ESP32 в приватный локальный датчик движения по Wi-Fi: он считывает, как движение меняет Wi-Fi-сигналы в комнате, и сообщает о движении в реальном времени — без камеры, микрофона, носимых устройств или отдельного радарного оборудования.
Как он определяет движение без камеры и радара?Он считывает Wi-Fi CSI (Channel State Information): когда кто-то движется по комнате, он меняет распространение Wi-Fi-сигналов, детектор обрабатывает эти изменения прямо на ESP32 и выдаёт состояние движения и оценку активности.
Как настроить первый датчик?Прошейте его из браузера: откройте Flash в настольном Chrome 151+, подключите поддерживаемую ESP32 по USB, выберите прошивку и канал выпуска, затем завершите настройку Wi-Fi на экране. Локальные сборки и работа через командную строку описаны в файле SETUP.md.
Какое железо и какая сеть нужны?Поддерживаемая плата ESP32 (C6, C5, C3, S3, S2 или классическая) и обычная сеть Wi-Fi 4 (802.11n) на частоте 2,4 ГГц. Для работы через браузер нужен настольный Chrome 151+; прошить можно и в Edge, но разделы Device settings и Monitor там гарантированно не работают.
Какие у него ограничения?Одна плата покрывает одну зону наблюдения, поэтому для покрытия уровня комнаты обычно нужна одна плата на комнату. Он реагирует только на изменения радиосреды: не может опознать или пересчитать людей, доказать, что комната пуста, или заменить сертифицированные охранные, медицинские и экстренные системы.
Куда уходят данные о движении?По умолчанию никуда вовне: CSI обрабатывается на самом устройстве, определение движения происходит локально, и облако не требуется. Запись сырых данных CSI — необязательная опция, предназначенная для исследований и отладки.
Можно ли использовать его в закрытой прошивке?Собственный код проекта распространяется по GPLv3. Чтобы встроить ESPectre в проприетарную прошивку с закрытым исходным кодом без обязанности раскрывать исходники, есть отдельная коммерческая лицензия (см. LICENSING.md); учтите, что C++-фронтенд ESPHome остаётся доступным только под GPLv3.
Работает ли он с Home Assistant?Да — через ESPHome для нативных сущностей Home Assistant или по MQTT с поддержкой Home Assistant MQTT Discovery. Он также предоставляет стандартный датчик присутствия Matter (проверка контроллерами ещё ограничена) и локальный простой HTTP API для своих интеграций.
Какие варианты прошивки можно выбрать?Четыре: Native — для автономных датчиков и интеграций по MQTT, ESPHome — для пользователей Home Assistant, которым нужны нативные сущности, Matter — для контроллеров Matter, и Micro-ESPectre — облегчённая сборка на MicroPython с локальным HTTP-мониторингом только для чтения.
Что входит в проект, кроме прошивки?Встраиваемый C++ SDK, утилита командной строки с полным жизненным циклом устройства, браузерные инструменты (Flash, Device settings, Monitor), открытый набор данных CSI с записями пустых комнат, неподвижного присутствия и движения, а также обученные веса моделей и полный процесс обучения и проверки.
Что реально можно автоматизировать с его помощью?Всё, что зависит от движения: включать экран или свет, когда в комнате кто-то появляется, регулировать отопление и охлаждение по активности в комнате или включать сигнализацию и уведомления там, где движения быть не должно — через Home Assistant, Matter, MQTT или HTTP API.
What are similar projects?Tasmota, WLED, muse-gadget-sdk, EchoMuse, esp-sdr, ESP32Marauder, neonplan3d, Arduino
Which topics is it in?sensors, smart-home, home-assistant, wifi, home-automation, microcontroller, firmware, iot, dataset, embedded, cpp, sdk
Creator
francescopace
Size
407 MB
Stars
9.6K
Updated
CommitOct 16Release3.0.0Oct 07
Age
11mo
Commits · 90 Days