francescopace/espectreESPectre - Sistema de detección de movimiento basado en el análisis del espectro Wi-Fi (CSI), con integración de Home Assistant.
Sistema de detección de movimiento basado en el análisis del espectro Wi-Fi (CSI), con integración nativa con Home Assistant mediante ESPHome.
[!TIP] Nuevo detector ML: Detección de movimiento basada en redes neuronales. No requiere calibración y se ejecuta en el propio dispositivo. Esta es una función experimental, y agradecemos tus comentarios en la discusión sobre el detector ML. También hay una compilación snapshot con los últimos cambios disponible (usa los archivos
-mlpara el detector basado en machine learning), o sigue la guía de configuración para una configuración personalizada.
ESP32-S3 DevKit con antenas externas
Tiempo de configuración: ~10-15 minutos
Dificultad: Fácil (solo configuración YAML)
Panel de Home Assistant con detección de movimiento en tiempo real, control de umbral y sensores de depuración
Cuando alguien se mueve en una habitación, "perturba" las ondas Wi-Fi que viajan entre el router y el sensor. Es como cuando mueves la mano delante de una linterna y ves cómo cambia la sombra.
El dispositivo ESP32 "escucha" estos cambios y sabe si hay movimiento.
¿Quieres entender los detalles técnicos? Consulta ALGORITHMS.md para la explicación del CSI y la documentación sobre procesamiento de señales.
La colocación óptima del sensor es crucial para una detección de movimiento fiable.
Rango óptimo: 3-8 metros
Hacer:
No hacer:
ESPectre utiliza un pipeline de procesamiento enfocado en la detección de movimiento:``` ┌─────────────┐ │ CSI Data │ Raw Wi-Fi Channel State Information └──────┬──────┘ │ ▼ ┌─────────────┐ │ Gain Lock │ AGC/FFT stabilization (~3 seconds) │ │ Locks hardware gain for stable measurements └──────┬──────┘ │ ▼ ┌─────────────┐ │ Auto │ Automatic subcarrier selection (once at boot) │ Calibration │ Selects optimal 12 subcarriers (NBVI) └──────┬──────┘ │ ▼ ┌─────────────┐ │ Adaptive │ auto: P95 × 1.1 | min: P100 │ Threshold │ or fixed manual value └──────┬──────┘ │ ▼ ┌─────────────┐ │ Hampel │ Turbulence outlier removal │ Filter │ (enabled by default) └──────┬──────┘ │ ▼ ┌─────────────┐ │ Low-pass │ Noise reduction (smoothing) │ Filter │ (optional, disabled by default) └──────┬──────┘ │ ▼ ┌─────────────┐ │ Detection │ MVS or ML score │ Evaluation │ every evaluation_interval packets └──────┬──────┘ │ ▼ ┌─────────────┐ │ Hit Filter │ motion_on_hits / motion_off_hits │ │ edge-driven IDLE ↔ MOTION └──────┬──────┘ │ ▼ ┌─────────────┐ │ Home │ Edge-driven motion binary + │ Assistant │ periodic Movement Score / Threshold └─────────────┘
### Uno o varios sensores```
┌─────────┐ ┌─────────┐ ┌─────────┐
│ ESP32 │ │ ESP32 │ │ ESP32 │
│ Room 1 │ │ Room 2 │ │ Room 3 │
└────┬────┘ └────┬────┘ └────┬────┘
│ │ │
└────────────┴────────────┘
│
│ ESPHome Native API
▼
┌────────────────────┐
│ Home Assistant │
│ (Auto-discovery) │
└────────────────────┘
Cada sensor se descubre automáticamente en Home Assistant con:
ESPectre implementa NBVI (Índice de Varianza de Banda Normalizada) para la selección automática de subportadoras, logrando un rendimiento casi óptimo (F1>96%) con cero configuración manual. El algoritmo selecciona 12 subportadoras no consecutivas basándose en métricas de estabilidad y diversidad espectral.
⚠️ IMPORTANTE (modo MVS): Mantenga la habitación en silencio y sin movimiento durante 10 segundos tras el arranque del dispositivo. La auto-calibración se ejecuta durante este tiempo y el movimiento afectará a la precisión de detección. El modo ML omite la calibración.
Para más detalles sobre el algoritmo, consulte ALGORITHMS.md.
P: ¿Necesito conocimientos de programación para usarlo?
R: ¡No! ESPectre utiliza archivos de configuración YAML. Solo descarga el ejemplo, flashea y configura el WiFi a través de la aplicación ESPHome o la interfaz web.
P: ¿Funciona con mi router?
R: Sí, si tu router tiene Wi-Fi de 2.4GHz (prácticamente todos los routers modernos lo tienen).
P: ¿Cuánto cuesta en total?
R: Hardware: ~€10 por un dispositivo ESP32 (se recomiendan S3/C6, otras variantes también funcionan). Software: todo gratuito y de código abierto. También necesitarás Home Assistant en algún lugar (Raspberry Pi ~€35-50, o cualquier PC/NAS existente).
P: ¿Necesito modificar algo en el router?
R: ¡No! El router funciona con normalidad. El sensor "escucha" las señales Wi-Fi sin modificar nada.
P: ¿Funciona a través de paredes?
R: Sí, la señal Wi-Fi de 2.4GHz penetra en los paneles de yeso. Las paredes de hormigón armado reducen la sensibilidad, pero la detección sigue siendo posible a distancias reducidas.
P: ¿Cuántos sensores se necesitan para una casa?
R: Depende del tamaño. Un sensor puede monitorizar ~50 m². Para casas más grandes, usa varios sensores (1 sensor cada 50-70 m² para una cobertura óptima).
P: ¿Puede distinguir entre personas y mascotas?
R: El sistema utiliza un modelo de segmentación de 2 estados (IDLE/MOTION) que identifica movimiento genérico sin distinguir entre personas, mascotas u otros objetos en movimiento. Para una clasificación más sofisticada (personas vs mascotas, reconocimiento de actividades, detección de gestos), se necesitarían modelos de IA/ML entrenados (consulta la sección Evolución Futura).
P: ¿Funciona con redes Wi-Fi mesh?
R: Sí, funciona con normalidad. Asegúrate de que el ESP32 se conecta a la banda de 2.4 GHz.
P: ¿Qué precisión tiene la detección?
R: La precisión de la detección depende en gran medida del entorno y requiere un ajuste adecuado. Los factores que afectan al rendimiento incluyen: distribución de la habitación, materiales de las paredes, colocación de los muebles, distancia al router (óptima: 3-8 m) y niveles de interferencia. En condiciones óptimas con un ajuste correcto, el sistema proporciona una detección de movimiento fiable. Ajusta el parámetro segmentation_threshold para adaptar la sensibilidad a tu entorno específico.
P: ¿Cuál es el consumo de energía? R: ~500mW típico durante el funcionamiento continuo. El firmware incluye soporte para optimización de energía, y se pueden implementar modos de suspensión profunda para implementaciones con batería, aunque esto requeriría modificaciones personalizadas del código.
El sistema recopila datos anónimos relacionados con las características físicas del canal de radio Wi-Fi:
Los datos CSI representan únicamente las propiedades del medio de transmisión y no contienen información de identificación directa.
ADVERTENCIA: A pesar del anonimato intrínseco de los datos CSI, este sistema puede utilizarse para:
El usuario es el único responsable del uso de este sistema y debe:
Para detalles sobre los algoritmos (MVS, calibración NBVI, filtro de Hampel), consulte ALGORITHMS.md.
Para métricas de rendimiento (matriz de confusión, puntuación F1, benchmarks), consulte PERFORMANCE.md.
Este proyecto sigue un enfoque de doble plataforma para equilibrar la velocidad de innovación con la estabilidad de producción:
Público objetivo: Usuarios finales, entusiastas del hogar inteligente, usuarios de Home Assistant
Público objetivo: Investigadores, desarrolladores, aplicaciones académicas/industriales
Micro-ESPectre te proporciona los fundamentos para:
┌─────────────────────┐ Validated ┌──────────────────────┐ │ Micro-ESPectre │ ─────────────────► │ ESPectre │ │ (R&D Platform) │ algorithms │ (Production Platform)│ │ │ │ │ │ • Fast prototyping │ │ • ESPHome component │ │ • Algorithm testing │ │ • Home Assistant │ │ • Data analysis │ │ • End-user ready │ │ • MQTT flexibility │ │ • Native API │ └─────────────────────┘ └──────────────────────┘
**Ciclo de innovación**: Las nuevas funcionalidades y algoritmos se desarrollan y validan primero en Micro-ESPectre (Python) y luego se portan a ESPectre (C++) una vez que demuestran su eficacia.
---
## Evolución futura
Mientras que ESPectre v2.x se centra en la **detección de movimiento** (MVS + selección automática de subportadoras), el proyecto está explorando capacidades de aprendizaje automático para aplicaciones avanzadas:
| Capacidad | Estado | Descripción |
|------------|--------|-------------|
| **Detector ML** | Experimental | Red neuronal (MLP 9→32→16→1)|
| **Reconocimiento de gestos** | Planificado | Detecta gestos con la mano (deslizar, empujar, círculo) para el control del hogar inteligente |
| **Reconocimiento de actividad humana** | Planificado | Identifica actividades (sentarse, caminar, caerse) |
| **Conteo de personas** | Planificado | Estima el número de personas en una habitación |
| **Localización 3D** | Investigación | Posicionamiento en interiores (precisión de 30-50 cm) mediante una matriz de antenas con coherencia de fase |
El detector ML ya está disponible con `detection_algorithm: ml` en tu configuración YAML. Para conocer los detalles del algoritmo, consulta [ALGORITHMS.md](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/ALGORITHMS.md#ml-neural-network-detector) y `PERFORMANCE.md` para las métricas actuales.
La infraestructura de recopilación de datos y entrenamiento de ML está documentada en [ML_DATA_COLLECTION.md](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/ML_DATA_COLLECTION.md).
Consulta [ROADMAP.md](https://github.com/francescopace/espectre/blob/HEAD/ROADMAP.md) para conocer los planes detallados, los cronogramas y cómo contribuir.
---
## Documentación
### ESPectre (Producción)
| Documento | Descripción |
|----------|-------------|
| [Intro](https://github.com/francescopace/espectre/blob/HEAD/README.md) | (Este archivo) Descripción general del proyecto, inicio rápido, FAQ |
| [Guía de configuración](https://github.com/francescopace/espectre/blob/HEAD/SETUP.md) | Instalación y configuración con ESPHome |
| [Guía de ajuste](https://github.com/francescopace/espectre/blob/HEAD/TUNING.md) | Ajuste de parámetros para una detección óptima |
| [Rendimiento](https://github.com/francescopace/espectre/blob/HEAD/PERFORMANCE.md) | Benchmarks, matriz de confusión, puntuación F1 |
| [El juego](https://github.com/francescopace/espectre/blob/HEAD/docs/game/README.md) | Juego de navegador, API de streaming USB, ajuste interactivo de umbrales |
| [Suite de pruebas](https://github.com/francescopace/espectre/blob/HEAD/test/README.md) | Documentación de pruebas PlatformIO Unity |
### Micro-ESPectre (I+D)
| Documento | Descripción |
|----------|-------------|
| [Intro](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/README.md) | Descripción general de la plataforma de I+D, CLI, MQTT, Monitor web |
| [Algoritmos](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/ALGORITHMS.md) | Documentación científica de MVS, calibración NBVI, filtro de Hampel |
| [Herramientas de análisis](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/tools/README.md) | Scripts de análisis y optimización de CSI |
| [Recopilación de datos ML](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/ML_DATA_COLLECTION.md) | Creación de conjuntos de datos etiquetados para aprendizaje automático |
| [Referencias](https://github.com/francescopace/espectre/blob/HEAD/micro-espectre/README.md#references) | Artículos académicos y recursos de investigación |
### Proyecto
| Documento | Descripción |
|----------|-------------|
| [Roadmap](https://github.com/francescopace/espectre/blob/HEAD/ROADMAP.md) | Visión del proyecto y planes de ML |
| [Contribuciones](https://github.com/francescopace/espectre/blob/HEAD/CONTRIBUTING.md) | Cómo contribuir (código, datos, documentación) |
| [Registro de cambios](https://github.com/francescopace/espectre/blob/HEAD/CHANGELOG.md) | Historial de versiones y notas de publicación |
| [Seguridad](https://github.com/francescopace/espectre/blob/HEAD/SECURITY.md) | Política de seguridad y notificación de vulnerabilidades |
| [Código de conducta](https://github.com/francescopace/espectre/blob/HEAD/CODE_OF_CONDUCT.md) | Normas de la comunidad |
---
## Medios
| Artículos | Título |
|-------------|-------|
| Medium | [Cómo convertí mi Wi-Fi en un sensor de movimiento - Parte 1](https://medium.com/@francesco.pace/how-i-turned-my-wi-fi-into-a-motion-sensor-61a631a9b4ec?sk=c7f79130d78b0545fce4a228a6a79af3&utm_source=github&utm_medium=readme&utm_campaign=espectre) |
| Medium | [Cómo convertí mi Wi-Fi en un sensor de movimiento - Parte 2](https://medium.com/@francesco.pace/how-i-turned-my-wi-fi-into-a-motion-sensor-part-2-62038130e530?sk=7c8b6f11cf3fcb8d279648016ebff72a&utm_source=github&utm_medium=readme&utm_campaign=espectre) |
| IoT For All | [Cómo convertí mi Wi-Fi en un sensor de movimiento](https://www.iotforall.com/wifi-motion-sensor-iot) |
| Hackaday | [Crea tu propio sensor de presencia basado en ESP32, sin necesidad de hardware especial](https://hackaday.com/2026/01/28/make-your-own-esp32-based-person-sensor-no-special-hardware-needed/) |
| Adafruit Learn | [Detector de presencia ESPectre para Feather](https://learn.adafruit.com/espectre-human-detector-for-feather) |
| Seeed Studio Wiki | [Despliegue de Espectre en la serie Seeed Studio XIAO ESP32 con ESPHome](https://wiki.seeedstudio.com/xiao-esp32--series-espresense/) |
| Blog | Discusión |
|----------|------------|
| Home Assistant | [ESPectre - Detección de movimiento por Wi-Fi para Home Assistant](https://community.home-assistant.io/t/espectre-wi-fi-motion-detection-for-home-assistant/961251) |
| Vídeos | Vídeo |
|---------|-------|
| @GithubAwesome | [ESPectre](https://www.youtube.com/shorts/iQ_DPHLn8ms) |
| Podcasts | Episodio |
|-------------|---------|
| Hackaday | [Episodio 355 del podcast: Detectores de personas, walkie talkies, teléfonos inteligentes abiertos...](https://hackaday.com/2026/01/30/hackaday-podcast-episode-355-person-detectors-walkie-talkies-open-smartphones-and-a-wifi-traffic-light/) |
---
## Proyectos relacionados
- [radio-presence-scanner](https://github.com/francescopace/radio-presence-scanner): proyecto complementario de detección de presencia centrado en observaciones de radio BLE desde dispositivos host (Python), con panel HTTP opcional.
- [micropython-esp32-csi](https://github.com/francescopace/micropython-esp32-csi): fork personalizado de MicroPython que expone las API CSI del ESP32, utilizado como base de firmware para la creación rápida de prototipos CSI en el flujo de trabajo de Micro-ESPectre.
---
## Agradecimientos
ESPectre aprovecha las capacidades nativas de CSI Wi-Fi de los chips ESP32. Gracias a [Espressif](https://www.espressif.com/) por hacer accesible CSI en el framework ESP-IDF y por reconocer a ESPectre como [proyecto comunitario](https://github.com/espressif/esp-csi#6-related-resources) en su repositorio [esp-csi](https://github.com/espressif/esp-csi).
---
## Licencia
Este proyecto se publica bajo la **GNU General Public License v3.0 (GPLv3)**.
GPLv3 garantiza que:
- El software permanezca libre y de código abierto
- Cualquier persona pueda usarlo, estudiarlo, modificarlo y distribuirlo
- Las modificaciones deban compartirse bajo la misma licencia
- Proteja los derechos de los usuarios finales y la libertad del software
Consulta [LICENSE](https://github.com/francescopace/espectre/blob/HEAD/LICENSE) para ver el texto completo de la licencia.
Las contribuciones se envían bajo GPLv3 y deben incluir una marca DCO
`Signed-off-by` en cada commit (`git commit -s`).
## Autor
**Francesco Pace**
Correo electrónico: [[email protected]](mailto:[email protected])
LinkedIn: [linkedin.com/in/francescopace](https://www.linkedin.com/in/francescopace/)
Si encuentras útil ESPectre y quieres apoyar su desarrollo, puedes invitarme a un café. Es completamente opcional.
Trabajo en este proyecto porque me apasiona. Las contribuciones me ayudan a comprar nuevo hardware para ampliar la lista de dispositivos probados y compatibles, y a dedicar más tiempo a nuevas funcionalidades.
<a href="https://www.buymeacoffee.com/espectre" target="_blank"><img src="https://assets.kitploit.com/production/public/readmes/9574/a7e8174c892355a24fbaec083cbef385d097a0b488fd4823dbbb0061643bb5e2.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" ></a>
| Distancia | Señal | Multitrayecto | Sensibilidad | Ruido | Recomendación |
|---|
| < 2m | Demasiado fuerte | Mínimo | Baja | Bajo | ❌ Demasiado cerca |
| 3-8m | Fuerte | Bueno | Alta | Bajo | ✅ Óptimo |
| > 10-15m | Débil | Variable | Baja | Alto | ❌ Demasiado lejos |
P: Si no funciona, ¿puedo obtener ayuda?
R: Sí, abre un Issue en GitHub o contacta conmigo por correo electrónico.