Integrando cámaras EZVIZ en Home Assistant de forma local y privada: Arquitectura y retos de ezviz-ha-addon

Uno de los grandes atractivos de la domótica es la posibilidad de centralizar dispositivos de múltiples fabricantes en una única plataforma, maximizando control, eficiencia y, sobre todo, privacidad. Sin embargo, muchos fabricantes de cámaras IP, como EZVIZ, fuerzan el uso de sus servicios en la nube para acceder a la transmisión en vivo, lo que puede implicar riesgos de privacidad y limitaciones de integraciones locales.

En este post te cuento cómo diseñé y desarrollé ezviz-ha-addon, un complemento para Home Assistant que permite integrar cámaras EZVIZ de forma local, sin depender de servicios en la nube. Repasaremos la arquitectura, los principales desafíos técnicos, las decisiones clave y aprendizajes del proceso. 🚀

¿Por qué crear ezviz-ha-addon?

Home Assistant es una de las plataformas de domótica más populares entre entusiastas y profesionales por su enfoque abierto, extensible y local. Sin embargo, integrar cámaras EZVIZ presentaba varios problemas:

• Dependencia del cloud de EZVIZ: Para ver la transmisión en vivo, los usuarios debían autenticarse y enrutar el tráfico por servidores externos.
• Privacidad y seguridad: El vídeo de tu hogar pasaba por servidores de terceros, lo que es una preocupación legítima.
• Integración limitada: Las soluciones existentes no permitían un control granular ni una integración fluida con otras automatizaciones de Home Assistant.

El objetivo era claro: permitir la visualización y gestión de cámaras EZVIZ 100% localmente, usando Home Assistant como interfaz central y sin sacrificar facilidad de uso.

Arquitectura técnica: Simplicidad y robustez con Python y Docker

Enfoque general

Elegí una arquitectura basada en Python por su ecosistema maduro para el manejo de vídeo, su facilidad de integración con Home Assistant y la disponibilidad de librerías para interactuar con dispositivos EZVIZ. Para empaquetar y distribuir el add-on, utilicé Docker, siguiendo las mejores prácticas de add-ons en Home Assistant.

Componentes principales

1. Servicio de streaming local

Un script en Python que se comunica directamente con las cámaras EZVIZ usando credenciales locales, obtiene la URL de streaming (RTSP) y la expone a Home Assistant.

1. Gestor de configuración

Permite al usuario ingresar sus credenciales y la configuración de cámaras a través de la UI del add-on.

1. Integración con Home Assistant

El add-on expone el stream como un recurso local, que Home Assistant consume usando la integración nativa de cámaras.

1. Contenedor Docker

Encapsula el servicio y sus dependencias, asegurando portabilidad y facilidad de despliegue en cualquier instancia de Home Assistant.

1+---------------------+               +---------------------------+
2|   Home Assistant    |  <------->    |  ezviz-ha-addon (Docker)  |
3+---------------------+               +---------------------------+
4          |                                        |
5          |                                        v
6          |                             +-----------------------+
7          |                             | EZVIZ Cameras (local) |
8          |                             +-----------------------+

Tecnologías utilizadas

• Python 3.11+
• ffmpeg para manipular flujos RTSP si es necesario
• Docker/Dockerfile para el empaquetado
• Shell scripts para la gestión y control del contenedor
• Home Assistant Add-on API para la integración y configuración

Decisiones técnicas clave

1. Acceso a la transmisión local sin cloud

El primer reto fue encontrar la forma de obtener el stream RTSP directamente desde las cámaras, sin pasar por la nube. Tras analizar la documentación (y bastante ingeniería inversa), confirmé que muchas cámaras EZVIZ soportan streaming RTSP local, aunque la documentación oficial es escasa.

Solución:

Utilicé una librería Python para EZVIZ que permite autenticación local y recuperación del endpoint RTSP, construyendo dinámicamente la URL a partir de las credenciales del usuario.

1from ezviz import EzvizClient
2 
3client = EzvizClient(username, password)
4rtsp_url = client.get_rtsp_url(device_serial)

2. Seguridad y manejo de credenciales

Exponer credenciales en texto plano es una mala práctica. Todo el flujo de configuración está aislado dentro del contenedor Docker y solo accesible para el host donde corre Home Assistant.

• Las credenciales se almacenan en variables de entorno internas al contenedor.
• No hay almacenamiento en disco fuera del contenedor, aumentando la privacidad.

3. Compatibilidad y facilidad de despliegue

Quería que cualquier usuario pudiera instalar el add-on desde el Add-on Store de Home Assistant, sin pasos manuales complejos.

• Dockerfile optimizado: Usé una imagen base ligera de Python y minimicé la instalación de dependencias.
• Shell scripts: Simplifican la inicialización y manejo de logs para debugging.

1FROM python:3.11-slim
2COPY requirements.txt .
3RUN pip install -r requirements.txt
4COPY . /app
5WORKDIR /app
6ENTRYPOINT ["python", "main.py"]

4. Integración con la UI de Home Assistant

El add-on se registra como proveedor de cámara en Home Assistant. El usuario solo tiene que instalar el add-on, configurar sus credenciales y la cámara aparece automáticamente en su dashboard.

Desafíos técnicos y cómo los resolví

1. Variabilidad en modelos de cámaras EZVIZ

No todos los modelos de EZVIZ permiten acceso RTSP igual de fácil. Algunos requieren habilitar la función desde la app oficial, y otros ni siquiera lo soportan.

Mitigación:

• Documenté claramente en el README los modelos compatibles.
• El add-on detecta errores de autenticación o endpoints no válidos y los muestra en logs detallados.

2. Manejo de streams RTSP inestables

El protocolo RTSP puede ser sensible a microcortes de red o a cámaras de bajo coste con firmware inestable.

Solución:

• Añadí lógica de reconexión automática al perder el stream.
• Implementé una pequeña cola de reintentos exponenciales para estabilizar la experiencia.

1def get_stream():
2    for attempt in range(5):
3        try:
4            # Lógica de conexión RTSP
5            break
6        except Exception as e:
7            time.sleep(2 ** attempt)

3. Consumo de recursos

La manipulación de streams de vídeo puede consumir CPU y RAM, sobre todo en dispositivos como Raspberry Pi.

Solución:

• El add-on solo inicia el stream bajo demanda (cuando Home Assistant lo solicita).
• Opcionalmente, permite definir la resolución/calidad para reducir consumo.

4. Seguridad y aislamiento

El add-on corre en un contenedor restringido, solo con los permisos necesarios. No se expone ningún puerto externo salvo los definidos por Home Assistant.

Resultados y métricas

Desde la publicación inicial, el add-on ha permitido a usuarios:

• Integrar cámaras EZVIZ de forma local en Home Assistant sin cloud.
• Reducir latencia: el acceso a vídeo es mucho más veloz al no depender de servidores externos.
• Mejorar privacidad: los vídeos nunca salen de la red local.
• Automatizar eventos: las cámaras se pueden usar en automatizaciones (ej: detección de movimiento, snapshots, etc.).

Hasta la fecha, el repositorio ha recibido varias contribuciones y feedback positivo en la comunidad de Home Assistant.

Lecciones aprendidas y mejoras futuras

Lo que funcionó bien

• Docker simplificó enormemente la portabilidad y el aislamiento de dependencias.
• Apostar por un enfoque 100% local fue muy valorado por los usuarios.
• El diseño modular del servicio permite añadir soporte a más cámaras en el futuro.

Lo que planeo mejorar

1. Soporte para más modelos: Investigar compatibilidad ampliada (incluyendo cámaras con autenticación distinta).
2. UI enriquecida: Facilitar la configuración de cámaras y credenciales desde la interfaz gráfica de Home Assistant.
3. Métricas y healthchecks: Añadir endpoints de estado para monitorizar la salud del stream.
4. Integración avanzada: Soporte para eventos de movimiento y grabación bajo demanda.

Conclusión

Trabajar en ezviz-ha-addon ha sido un reto técnico y una oportunidad para aportar a la comunidad de Home Assistant una solución práctica, eficiente y respetuosa de la privacidad. Integrar dispositivos propietarios en ecosistemas abiertos no es trivial, pero con el enfoque adecuado, se puede lograr una experiencia de usuario robusta y segura.

Si tienes una cámara EZVIZ y quieres aprovechar todo el potencial de Home Assistant, te invito a probar el add-on y contribuir en GitHub. ¡La domótica privada y local es posible! 💡🔒

¿Preguntas, sugerencias o ideas?

Déjalas en los comentarios o abre un issue en el repo. ¡Me encanta colaborar con otros entusiastas de la tecnología!