Volver a actualizaciones
Nuevo releaseAug 18, 2026

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.

Compartir

License ESPHome Platform Release CI codecov

🛜 ESPectre 👻

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 -ml para el detector basado en machine learning), o sigue la guía de configuración para una configuración personalizada.

Tabla de contenidos

En 3 puntos

  1. Qué hace: Detecta movimiento usando Wi-Fi (sin cámaras, sin micrófonos)
  2. Qué necesitas: Un dispositivo ESP32 de ~10 € (se recomiendan S3 y C6, otras variantes compatibles)
  3. Tiempo de configuración: 10-15 minutos

Lo que necesitas

Hardware

  • Router Wi-Fi de 2.4GHz - el que ya tienes en casa funciona perfectamente
  • ESP32 compatible con CSI - ESP32-C6, ESP32-S3, ESP32-C3, ESP32 (original) u otras variantes. Consulta SETUP.md para la tabla comparativa completa de plataformas.

Lote de 3 x ESP32-S3 DevKit con antenas externas ESP32-S3 DevKit con antenas externas

Software (Todo gratis)

  • Home Assistant (en Raspberry Pi, PC, NAS o en la nube)
  • ESPHome (integrado en Home Assistant o independiente)

Habilidades requeridas

  • Conocimientos básicos de YAML para la configuración
  • Familiaridad con Home Assistant (opcional pero recomendada)
  • NO se requieren conocimientos de programación
  • NO es necesaria configuración del router

Inicio rápido

Tiempo de configuración: ~10-15 minutos
Dificultad: Fácil (solo configuración YAML)

  1. Configuración e instalación: Sigue la guía completa en SETUP.md
  2. Ajuste: Optimiza según tu entorno con TUNING.md

Panel de ESPectre en Home Assistant Panel de Home Assistant con detección de movimiento en tiempo real, control de umbral y sensores de depuración

Cómo funciona

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.

Ventajas

  • Sin cámaras (privacidad total)
  • No necesita dispositivos portables (sin pulseras ni sensores que llevar)
  • Funciona a través de paredes (el Wi-Fi atraviesa las paredes)
  • Muy económico (~10 € en total)

¿Quieres entender los detalles técnicos? Consulta ALGORITHMS.md para la explicación del CSI y la documentación sobre procesamiento de señales.

Qué puedes hacer con ello

Ejemplos prácticos

  • Seguridad en el hogar: Recibe una alerta si alguien entra mientras estás fuera
  • Cuidado de personas mayores: Supervisa la actividad para detectar caídas o inactividad prolongada
  • Automatización inteligente: Enciende luces/calefacción solo cuando hay alguien presente
  • Ahorro de energía: Apaga automáticamente los dispositivos en habitaciones vacías
  • Supervisión infantil: Alerta si salen de la habitación durante la noche
  • Control de clima: Calienta/enfría solo las zonas ocupadas

Dónde colocar el sensor

La colocación óptima del sensor es crucial para una detección de movimiento fiable.

Distancia recomendada respecto al router

Rango óptimo: 3-8 metros

DistanciaSeñalMultitrayectoSensibilidadRuidoRecomendación
< 2mDemasiado fuerteMínimoBajaBajo❌ Demasiado cerca
3-8mFuerteBuenoAltaBajo✅ Óptimo
> 10-15mDébilVariableBajaAlto❌ Demasiado lejos

Consejos de colocación

Hacer:

  • Coloca el sensor en el área a monitorear (no necesariamente en línea directa con el router)
  • Altura: 1-1.5 metros del suelo (altura de escritorio/mesa)
  • Antena externa: Usa el conector IPEX para mejor recepción

No hacer:

  • Evita obstáculos metálicos entre el router y el sensor (refrigeradores, armarios metálicos)
  • Evita esquinas o espacios cerrados (reduce la diversidad de multitrayecto)

Arquitectura del sistema

Pipeline de procesamiento

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:

  • Sensor binario para detección de movimiento, publicado inmediatamente en las transiciones de estado
  • Sensor de puntuación de movimiento, publicado en la cadencia periódica
  • Umbral ajustable (entidad numérica)

Selección Automática de Subportadoras

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.

FAQ para Principiantes

Haz clic para expandir el FAQ

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.

P: Si no funciona, ¿puedo obtener ayuda?
R: Sí, abre un Issue en GitHub o contacta conmigo por correo electrónico.

Seguridad y Privacidad

Consideraciones de Privacidad, Seguridad y Ética (haz clic para expandir)

Naturaleza de los Datos Recopilados

El sistema recopila datos anónimos relacionados con las características físicas del canal de radio Wi-Fi:

  • Amplitudes y fases de las subportadoras OFDM
  • Varianzas estadísticas de la señal
  • NO se recopilan: identidades personales, contenidos de comunicación, imágenes, audio

Los datos CSI representan únicamente las propiedades del medio de transmisión y no contienen información de identificación directa.

Ventajas de Privacidad

  • Sin cámaras: Respeto por la privacidad visual
  • Sin micrófonos: Sin grabación de audio
  • Sin wearables: No requiere dispositivos ponibles
  • Datos agregados: Solo métricas estadísticas, no datos identificativos en bruto

ADVERTENCIA: A pesar del anonimato intrínseco de los datos CSI, este sistema puede utilizarse para:

  • Monitoreo no consensuado: Detectar presencia/movimiento de personas sin su consentimiento explícito
  • Perfilado de comportamiento: Con modelos avanzados de IA, inferir patrones de la vida diaria
  • Violación de la privacidad doméstica: Rastrear actividades dentro de hogares privados

Responsabilidad de Uso

El usuario es el único responsable del uso de este sistema y debe:

  1. Obtener el consentimiento explícito de todas las personas monitoreadas
  2. Respetar la normativa local (GDPR en la UE, leyes de privacidad locales)
  3. Informar claramente sobre la presencia del sistema de detección
  4. Limitar el uso a fines legítimos (seguridad del hogar, domótica personal)
  5. Proteger los datos con cifrado y acceso controlado
  6. NO USAR para vigilancia ilegal, acoso o violación de la privacidad de otras personas

Inmersión Técnica

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.

Estrategia de Doble Plataforma

Este proyecto sigue un enfoque de doble plataforma para equilibrar la velocidad de innovación con la estabilidad de producción:

ESPectre (Este Repositorio) - Plataforma de Producción

Público objetivo: Usuarios finales, entusiastas del hogar inteligente, usuarios de Home Assistant

  • Componente ESPHome con integración nativa con Home Assistant
  • Configuración YAML - no se requiere programación
  • Auto-descubrimiento - los dispositivos aparecen automáticamente en Home Assistant
  • Listo para producción - estable, probado, fácil de desplegar
  • Demostrativo - muestra los resultados de la investigación en un paquete fácil de usar

Micro-ESPectre - Plataforma de I+D

Público objetivo: Investigadores, desarrolladores, aplicaciones académicas/industriales

  • Implementación en Python/MicroPython para prototipado rápido
  • Basado en MQTT - integración flexible (no limitada a Home Assistant)
  • Iteración rápida - prueba nuevos algoritmos en segundos, no en minutos
  • Herramientas de análisis - suite completa para análisis de datos CSI
  • Casos de uso: investigación académica, detección industrial, desarrollo de algoritmos

Micro-ESPectre te proporciona los fundamentos para:

  • Conteo de personas
  • Reconocimiento de actividades (caminar, caerse, sentarse, dormir)
  • Localización y seguimiento
  • Reconocimiento de gestos

Flujo de Desarrollo```

┌─────────────────────┐ 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>
Leer más

Categorías

Seguridad IoTSeguridad InalámbricaPrivacidadSeguridad de Hardware e IoTAprendizaje AutomáticoAprendizaje y EducaciónDetección de Anomalías