security-ha-addon: Detección de movimiento inteligente y grabación para Home Assistant con cámaras HLS

En el mundo de la domótica, la integración de cámaras de seguridad suele ser un punto de dolor: muchas soluciones comerciales son propietarias, poco flexibles o consumen demasiados recursos para dispositivos modestos como una Raspberry Pi. Al trabajar con Home Assistant en mi propia casa, me encontré con la necesidad de grabar video solo cuando realmente ocurre algo relevante, evitando horas de metraje vacío. Así nació security-ha-addon: un complemento ligero, configurable y robusto para Home Assistant que detecta movimiento y graba video desde cualquier cámara con streaming HLS (m3u8), incluidas las populares EZVIZ.

En este post te cuento el _por qué_ de este proyecto, cómo resolví los principales retos técnicos, la arquitectura elegida y el impacto real en escenarios domésticos.

¿Por qué era importante resolver esto?

Las cámaras IP modernas suelen ofrecer streaming HLS, pero la mayoría de soluciones de grabación:

• No filtran eventos irrelevantes: Graban continuamente o con sensores poco precisos.
• Requieren hardware potente: Soluciones como Frigate o ZoneMinder pueden ser overkill para un usuario doméstico.
• Integración limitada: No exponen sensores ni APIs fácilmente consumibles desde Home Assistant.
• Compatibilidad cerrada: Muchos addons solo funcionan con RTSP o cámaras muy específicas.

Mi objetivo era:

• Compatibilidad amplia (HLS/m3u8)
• Detección de movimiento eficaz y personalizable
• Grabaciones automáticas solo cuando importa (con _pre_ y _post roll_)
• Exposición de sensores y API HTTP para integraciones
• Bajo consumo de recursos, ideal para Raspberry Pi

Arquitectura general y enfoque técnico

Elegí una arquitectura modular, orientada a la eficiencia y la facilidad de despliegue:

1+----------------------------+
2|   Home Assistant Add-on    |
3|----------------------------|
4| 1. Stream Handler (HLS)    |
5| 2. Motion Detector (OpenCV)|
6| 3. Recorder (FFmpeg)       |
7| 4. API HTTP (Flask)        |
8| 5. State & Sensors         |
9+----------------------------+
10       |           ^
11       v           |
12   /share/security_recordings

Componentes principales

1. Stream Handler:

- Abre el stream HLS (m3u8) usando OpenCV (cv2.VideoCapture) y FFmpeg como backend.

- Gestiona reconexiones automáticas en caso de fallo.

1. Motion Detector:

- Usa background subtraction (MOG2 de OpenCV) para detectar movimiento real.

- Filtra zonas de interés (ROI) y ajusta sensibilidad vía configuración.

- Implementa un _umbral temporal_ para ignorar movimientos breves (p.ej. alguien pasando rápido).

1. Recorder:

- Cuando se detecta movimiento, inicia una grabación con _pre-roll_ y _post-roll_ usando buffers circulares.

- Utiliza FFmpeg en segundo plano para ensamblar los clips en MP4.

- Guarda los archivos en /share/security_recordings.

1. API HTTP (Flask):

- Expone endpoints REST para consultar grabaciones y estado del sistema.

- Permite integraciones fáciles con Home Assistant y otros sistemas.

1. State & Sensors:

- Publica sensores virtuales en Home Assistant (por ejemplo: binary_sensor.motion_detected).

- Permite automatizaciones basadas en eventos de movimiento.

¿Por qué estas tecnologías?

• Python: Versatilidad y ecosistema maduro para visión por computador.
• OpenCV: Soporte robusto para procesamiento de video en tiempo real y detección de movimiento.
• FFmpeg: Estándar para manipulación de streams y codificación eficiente.
• Docker: Facilita el despliegue como add-on en cualquier instancia de Home Assistant sin conflictos de dependencias.
• Flask: Ligero y suficiente para una API REST local.

Profundizando en el motion detection inteligente

La detección de movimiento eficiente fue el núcleo del proyecto. Tras probar varias técnicas, opté por el _background subtraction_ adaptativo de OpenCV (MOG2):

1fgbg = cv2.createBackgroundSubtractorMOG2(history=500, varThreshold=16, detectShadows=True)
2while True:
3    ret, frame = cap.read()
4    if not ret:
5        # reconexión
6        continue
7    mask = fgbg.apply(frame)
8    # Filtrado por ROI y umbral de área
9    roi = mask[y_start:y_end, x_start:x_end]
10    contours, _ = cv2.findContours(roi, ...)
11    for cnt in contours:
12        if cv2.contourArea(cnt) > motion_threshold:
13            # ¡Movimiento detectado!

Ventajas de este enfoque:

• Se adapta a cambios graduales de iluminación.
• Ignora sombras y fluctuaciones menores.
• Permite definir zonas de interés (porcentaje del frame, configurable).

Smart filtering:

Muchos sistemas disparan ante cualquier frame con movimiento; aquí, solo se activa la grabación si el movimiento supera una duración mínima (p.ej., 3 segundos). Así evitamos clips inútiles causados por insectos, reflejos o vecinos pasando por la acera.

Challenges técnicos y cómo los resolví

1. Procesamiento eficiente en hardware limitado

Problema:

Raspberry Pi 4 tiene CPU/GPU limitados; el procesamiento en tiempo real de streams HLS es demandante.

Solución:

• Reduje la resolución del stream para la detección (sin afectar la grabación final).
• Procesamiento por lotes: solo se analiza un frame cada N milisegundos.
• Uso de buffers circulares en RAM para almacenar el pre-roll sin escribir a disco constantemente.

2. Reconexión robusta a streams HLS

Problema:

Las cámaras domésticas a veces reinician o el WiFi cae, cortando el stream HLS.

Solución:

• Implementé reconexión automática con backoff exponencial.
• Manejé errores de FFmpeg/OpenCV de forma explícita para evitar bloqueos.
• Cuando la cámara se recupera, se reanuda la detección y grabación sin intervención.

3. Sincronización de grabaciones (pre-roll/post-roll)

Problema:

Grabar los segundos anteriores y posteriores al movimiento requiere almacenar video "hacia atrás" y "hacia adelante".

Solución:

• Usé un deque de frames para el pre-roll; al detectarse movimiento, se vacía el buffer en el archivo de grabación.
• El post-roll se controla con un timer que mantiene la grabación activa unos segundos tras el último movimiento.

1from collections import deque
2 
3pre_roll_buffer = deque(maxlen=pre_roll_frames)
4while True:
5    frame = get_frame()
6    pre_roll_buffer.append(frame)
7    if motion_detected:
8        # Escribir pre_roll_buffer y continuar grabando post_roll

4. Integración con Home Assistant

Problema:

Muchos addons no exponen sensores ni endpoints flexibles.

Solución:

• Usé el API de Home Assistant para publicar estados (motion_detected, grabación activa, etc).
• Exposición de una API HTTP local (Flask) para consultar grabaciones y recibir triggers externos.

5. Compatibilidad EZVIZ y otros fabricantes

Problema:

EZVIZ y otras cámaras suelen tener streams HLS con protecciones o particularidades.

Solución:

• Aproveché el ezviz-camera-addon para obtener streams HLS autenticados.
• Probé con varias cámaras y ajusté el pipeline para tolerar delays y headers atípicos.

Resultados y métricas

Tras varios meses de uso en mi propia casa y feedback de otros usuarios:

• Reducción de metraje irrelevante: El 90% de los clips grabados incluyen personas, mascotas o eventos reales (no ruido).
• Uso de recursos: Consumo estable de < 25% CPU en Raspberry Pi 4 (con 2 cámaras simultáneas a 720p).
• Latencia baja: Detecta movimiento en menos de 1 segundo desde que ocurre.
• Integración total: Se puede usar en automatizaciones de Home Assistant (“enciende la luz si hay movimiento en el garaje”).
• API REST: Permite monitorizar y descargar grabaciones fácilmente.

Lecciones aprendidas y mejoras futuras

Lo que funcionó bien

• La combinación Python + OpenCV + FFmpeg es sorprendentemente robusta para procesamiento de video en edge.
• La arquitectura en Docker facilita muchísimo el despliegue y actualizaciones.
• Permitir configuración granular (zonas, sensibilidad, duración) es clave para evitar falsos positivos.

Posibles mejoras

• Soporte RTSP: Aunque HLS es popular en cámaras modernas, añadir RTSP ampliaría la compatibilidad.
• Notificaciones push: Integrar directamente con servicios de notificación (Telegram, mobile).
• UI para recortes: Una pequeña interfaz web para visualizar y recortar grabaciones desde el navegador.
• Machine Learning: Explorar modelos ligeros para diferenciar humanos, mascotas, vehículos, etc.

Conclusión

security-ha-addon es una solución práctica, ligera y flexible para llevar inteligencia real a la vigilancia doméstica desde Home Assistant. El proyecto sigue creciendo gracias a la comunidad, y es un ejemplo de cómo la combinación de tecnologías open-source puede resolver problemas reales sin depender de servicios propietarios ni hardware caro.

¿Te interesa probarlo, aportar ideas o reportar bugs?

El código está en GitHub y toda contribución es bienvenida 🚀

¡Gracias por leer! Si tienes preguntas técnicas o sugerencias, deja un comentario o abre un issue en el repo. La seguridad inteligente en el hogar está al alcance de todos con las herramientas adecuadas.