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

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:

1. Abre Flash en Chrome o Edge de escritorio.
2. Conecta un ESP32 compatible por USB y luego elige un firmware y un canal de lanzamiento.
3. Completa el aprovisionamiento Wi-Fi en pantalla o realiza el comisionado Matter con un controlador compatible.
4. Opcionalmente, abre Device settings para fijar un punto de acceso preferido o configurar MQTT.
5. 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

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:

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.WLAN en 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.