espectre snapshot-dev
ESPectre - Sistema de detección de movimiento basado en el análisis del espectro Wi-Fi (CSI), con integración de Home Assistant.
ESPectre 
Convierte un ESP32 en un sensor de movimiento Wi-Fi local y privado.
Cuando alguien se mueve por una habitación, altera la forma en que las señales Wi-Fi la atraviesan. ESPectre lee esos cambios y reporta movimiento en tiempo real. Sin cámara, sin micrófono, sin dispositivos portátiles y sin hardware de radar dedicado: solo un ESP32 compatible y la red Wi-Fi ya presente en la habitación.
ESPectre es una plataforma de código abierto que reúne firmware listo para flashear, un SDK C++ embebible, una implementación en MicroPython, herramientas de navegador, una CLI para el host, un conjunto de datos abierto, pesos de modelo abiertos y el flujo de trabajo de investigación utilizado para construir y validar los detectores.
Flashea desde tu navegador · Consulta las herramientas en vivo · Lee la documentación · Explora el SDK
Aplicaciones e integraciones
ESPectre puede encender una pantalla o luces cuando detecta movimiento, ajustar la calefacción y refrigeración según la actividad de la habitación, activar una alarma o notificación cuando ocurre movimiento en un área que debería estar vacía, y controlar otras automatizaciones del hogar. Se conecta a Home Assistant mediante ESPHome o MQTT, expone un sensor de ocupación Matter estándar y una API HTTP Direct local, y puede integrarse en firmware ESP32 personalizado mediante el SDK C++.
ESPectre procesa el CSI en el dispositivo y reporta un estado de movimiento y una puntuación de movimiento. Las aplicaciones pueden reaccionar sin enviar datos de sensado en bruto a un servicio en la nube. Una placa cubre una zona de sensado; la cobertura a nivel de habitación normalmente requiere una placa por habitación.
ESPectre detecta cambios en el entorno de radio. No identifica personas, no las cuenta, no demuestra que una habitación está vacía ni reemplaza un sistema de seguridad, médico o de emergencia certificado.
Hardware compatible
- ESP32-C6, ESP32-C5, ESP32-C3, ESP32-S3, ESP32-S2 y ESP32 clásico
- una red Wi-Fi 4 (802.11n) normal en 2.4 GHz
Elige una ruta de firmware
| Ruta | Ideal para | Empieza aquí |
|---|---|---|
| Native | Sensores independientes, integraciones MQTT, incluido Home Assistant MQTT Discovery, y aplicaciones personalizadas | Frontend Native |
| ESPHome | Usuarios de Home Assistant que quieren entidades nativas, aprovisionamiento ESPHome y actualizaciones con Device Builder | Frontend ESPHome |
| Matter | Controladores Matter con soporte de sensor de ocupación; la validación con controladores aún es limitada | Frontend Matter |
| Micro-ESPectre | Sensado ligero en MicroPython con monitoreo HTTP Direct local de solo lectura | README de Micro-ESPectre |
Native, ESPHome y Matter pueden elegir entre un detector lightweight, que aprende un umbral específico de la habitación al iniciar y deja más recursos al resto de la aplicación, y un detector high_accuracy, que ejecuta el modelo entrenado incluido en el repositorio. Su comportamiento y las compensaciones medidas están documentados en SETUP.md, ALGORITHMS.md y el informe de rendimiento.
Inicio rápido
La ruta más rápida usa el navegador y no requiere un entorno de compilación local. Usa Chrome 151 o posterior en escritorio para el flujo de trabajo alojado completo. Edge admite el flasheo desde el navegador, pero la compatibilidad con Device settings y Monitor no está garantizada:
- Abre Flash en Chrome o Edge de escritorio.
- Conecta un ESP32 compatible por USB y luego elige un firmware y un canal de lanzamiento.
- Completa el aprovisionamiento Wi-Fi en pantalla o realiza el comisionado Matter con un controlador compatible.
- Opcionalmente, abre Device settings para fijar un punto de acceso preferido o configurar MQTT.
- Abre Monitor para observar el movimiento, ajustar la detección e inspeccionar el dispositivo.
Estado de Matter: El frontend Matter aún se está validando en distintos ecosistemas de controladores. Un controlador puede admitir sensores de ocupación Matter estándar sin haber sido probado con el firmware actual. Consulta Compatibilidad con controladores Matter para ver la matriz actual.
Configuración local
Para compilaciones locales, flasheo desde este repositorio y el resto de la ruta de operador, empieza con SETUP.md. El envoltorio del repositorio expone los flujos de trabajo disponibles mediante:
./espectre --help
Documentación
| Tema | Qué cubre | Guías |
|---|---|---|
| Instalar y operar | Configuración del dispositivo, flujos de trabajo CLI y ajuste del detector | SETUP.md, CLI.md, TUNING.md |
| Comprender e integrar | Arquitectura de ejecución, API, descubrimiento, algoritmos y el SDK C++ | ARCHITECTURE.md, API.md, DISCOVERY.md, ALGORITHMS.md, SDK.md |
| Recolectar y entrenar | Recolección de CSI, entrenamiento de modelos, historial de características, rendimiento y literatura | ML_DATA_COLLECTION.md, ML_TRAINING.md, FEATURES.md, informe de rendimiento, LITERATURE.md |
| Investigación y dirección | Hoja de ruta, decisiones de arquitectura e historial de lanzamientos | ROADMAP.md, índice ADR, CHANGELOG.md |
| Referencia de frontends | READMEs de rutas de firmware para ESPHome, Native, Matter y Micro-ESPectre | ESPHome, Native, Matter, Micro |
| Contribuir | Cómo contribuir y dónde discutir el proyecto | CONTRIBUTING.md, GitHub Discussions |
Conjuntos de datos, modelos y validación
ESPectre publica los recursos de investigación y la evidencia de validación detrás de sus detectores:
| Recurso | Qué te ofrece | Empieza aquí |
|---|---|---|
| Conjunto de datos CSI | Grabaciones reales de habitaciones vacías, presencia estática y movimiento, con catálogo y procedencia en dataset_info.json | data/ |
| Pesos de modelo | Pesos entrenados en C++ y Python, además del flujo de trabajo de entrenamiento, exportación y validación | ML_TRAINING.md |
| Registro de características | Características probadas, promovidas o rechazadas, incluidos experimentos fallidos | FEATURES.md |
| Algoritmos e informes | Comportamiento del detector, el informe de rendimiento generado y el informe de calidad del conjunto de datos | ALGORITHMS.md |
| Literatura y dirección | Investigación externa, registros de decisiones de arquitectura y la hoja de ruta pública | LITERATURE.md |
Seguridad, privacidad y transparencia
Un sensor que puede revelar presencia no debería ser una caja negra. El sensado Wi-Fi evita imágenes y audio, pero los datos de movimiento y ocupación aún pueden revelar rutinas, sueño o ausencias del hogar. ESPectre trata ese riesgo como parte del trabajo de ingeniería:
- la detección de movimiento es local y no se requiere conectividad en la nube;
- la recolección de CSI en bruto es opcional y está pensada para necesidades definidas de investigación y depuración;
- la guía de seguridad y uso responsable documenta los límites de despliegue, el consentimiento, la minimización de datos, el reporte de abusos y el reporte privado de vulnerabilidades;
- los lanzamientos de firmware incluyen SBOMs específicos de compilación, avisos y archivos de licencia para que su contenido pueda inspeccionarse;
- el sitio web público y cada herramienta de navegador forman parte de este repositorio en docs/web, incluidos su código fuente, reglas de privacidad, contrato de analítica y dependencias de navegador fijadas;
- los protocolos, algoritmos, evidencia de rendimiento, limitaciones, decisiones de hoja de ruta y límites de validación conocidos están documentados públicamente.
Usa ESPectre solo en espacios y redes donde tengas derecho a desplegarlo. Informa a las personas afectadas, obtén consentimiento cuando sea necesario, protege el acceso al dispositivo y sus datos, y cumple con las leyes de privacidad aplicables.
Agradecimientos
- Gracias a Espressif por hacer accesible el CSI en ESP-IDF y por reconocer a ESPectre como un proyecto comunitario en esp-csi.
- Gracias a los mantenedores de MicroPython por revisar, probar y fusionar la contribución CSI de ESPectre, que añadió métodos CSI directos a
network.WLANen la rama principal.
Licencia
El código de primera parte de ESPectre está disponible bajo GPLv3, y las partes elegibles también están disponibles bajo un acuerdo comercial separado:
- Elige GPLv3 cuando tu firmware o aplicación pueda cumplir con GPLv3, incluida la puesta a disposición del código fuente correspondiente. Consulta LICENSE.
- Si quieres integrar ESPectre en firmware propietario o de código cerrado sin las obligaciones de divulgación de código fuente de GPLv3, consulta LICENSING.md para obtener una licencia comercial. La licencia comercial cubre el material elegible y no reemplaza los términos de terceros; el frontend C++ de ESPHome sigue siendo exclusivamente GPLv3.
Los términos de terceros y los artefactos de cumplimiento específicos de compilación se describen en THIRD_PARTY_NOTICES.md.