home-assistant-info: Add-ons avanzados para monitorización en Home Assistant
La automatización doméstica está transformando la manera en que interactuamos con nuestros hogares. Sin embargo, a medida que los entornos como Home Assistant crecen en complejidad, también lo hace la necesidad de contar con herramientas de monitorización y supervisión más potentes y personalizadas. Este fue el punto de partida que me llevó a desarrollar home-assistant-info: un conjunto de add-ons diseñados para llevar la visibilidad y el control del ecosistema Home Assistant a otro nivel.
En este post te cuento cómo abordé este reto, las decisiones arquitectónicas detrás del proyecto, los desafíos técnicos que enfrenté y los resultados obtenidos. Si buscas inspiración para crear tus propios add-ons, o simplemente quieres optimizar tu instalación de Home Assistant, sigue leyendo.
¿por qué necesitaba home-assistant-info?
Como usuario avanzado y desarrollador de Home Assistant, notaba ciertas limitaciones en las herramientas de monitorización disponibles:
- Visibilidad Fragmentada: Los sensores nativos y add-ons existentes ofrecían datos, pero de forma dispersa y sin granularidad suficiente.
- Dificultad para Integrar Nuevos Sensores: Añadir métricas específicas (temperatura CPU, errores de red, detalles de hardware Raspberry Pi) requería trabajo manual y scripts poco mantenibles.
- Falta de Centralización: No existía una solución que integrara toda la información relevante en un solo lugar, lista para ser visualizada y automatizada.
El objetivo era claro: crear un add-on (o conjunto de ellos) fácil de instalar, que expusiera decenas de métricas clave del sistema y facilitara el diagnóstico y la gestión avanzada, todo accesible desde la UI de Home Assistant y compatible con cualquier arquitectura soportada.
Enfoque y arquitectura técnica
Decisiones iniciales
Dado el ecosistema de Home Assistant, las prioridades técnicas fueron:
- Portabilidad: Soporte para múltiples arquitecturas (amd64, aarch64), indispensable para usuarios de Raspberry Pi y servidores x86.
- Despliegue sencillo: Integración vía Docker y siguiendo el modelo de add-ons oficiales de Home Assistant.
- Integración transparente: Uso de MQTT Discovery para que los sensores aparezcan automáticamente sin configuración manual.
- Extensibilidad: Arquitectura modular, permitiendo añadir o mejorar sensores fácilmente.
Componentes principales
1. Contenedor Docker personalizado
Cada add-on es un contenedor Docker con todo lo necesario para funcionar de forma aislada. El Dockerfile define:
- Imagen base ligera (Python 3.x slim)
- Instalación de dependencias en tiempo de build
- Scripts de entrada (
entrypoint.sh) para inicializar servicios y manejar logs - Volúmenes para persistencia y configuración
1FROM python:3.11-slim2 3COPY requirements.txt .4RUN pip install -r requirements.txt5 6COPY src/ /app/7WORKDIR /app8 9ENTRYPOINT ["bash", "entrypoint.sh"]2. Servicio de monitorización en Python
El núcleo del add-on es un servicio Python que:
- Recolecta métricas del sistema usando módulos como
psutily comandos shell - Publica los datos como sensores MQTT usando la especificación de Home Assistant Discovery
- Ciclo de actualización configurable (por defecto, cada 10 segundos)
Ejemplo de snippet para publicar el uso de CPU:
1import psutil2import paho.mqtt.client as mqtt3 4client = mqtt.Client()5client.connect("mqtt_broker", 1883, 60)6 7cpu_usage = psutil.cpu_percent(percpu=True)8for idx, usage in enumerate(cpu_usage):9 topic = f"homeassistant/sensor/cpu_core_{idx+1}/state"10 client.publish(topic, usage)3. Integración con MQTT Discovery
Automatizar la creación de sensores en Home Assistant fue clave. El add-on genera mensajes de autodiscovery según el formato requerido para cada métrica, permitiendo:
- Zero-config: Los sensores aparecen y se actualizan automáticamente
- Naming consistente: Prefijos y categorías claras para fácil identificación
- Compatibilidad: Funciona con cualquier broker MQTT soportado por Home Assistant
4. Interfaz HTML embebida
Para usuarios que prefieran un vistazo rápido sin abrir la UI de Home Assistant, incluí una pequeña página HTML servida dentro del contenedor, mostrando información clave en formato amigable. Esto se logra con un micro-servidor Python (Flask) expuesto en el puerto del add-on.
Add-on estrella: System Monitor Pro
El primer y más completo miembro de la suite es System Monitor Pro. Sus principales features:
- 30+ sensores automáticos para CPU, memoria, disco, red, seguridad y hardware específico de Raspberry Pi
- Detección de throttling y under-voltage en Raspberry Pi (clave para instalaciones DIY)
- Visualización de puertos abiertos y conexiones activas para mejorar la seguridad
- Monitorización de procesos, uptime y carga
- Integración cross-platform (funciona igual en x86 y ARM)
- Configuración personalizable (intervalos, exclusiones)
Puedes ver la documentación completa aquí.
Retos técnicos y soluciones
1. Compatibilidad multi-arquitectura
Uno de los principales desafíos era que los usuarios pueden correr Home Assistant en Raspberry Pi, NUCs, servidores x86, etc. Esto implica diferencias en:
- Disponibilidad de comandos y rutas del sistema
- Acceso a sensores hardware (temperatura CPU, voltaje)
Solución:
- Uso de Python y dependencias multiplataforma (
psutil) para la mayoría de métricas - Detección de arquitectura en tiempo de ejecución para adaptar comandos
- Módulos específicos para Raspberry Pi (lectura de
/sys/class/thermalyvcgencmd) - Builds Docker multi-arch con GitHub Actions
2. Seguridad y permisos
Para obtener métricas avanzadas (puertos abiertos, conexiones activas), algunos comandos requieren permisos elevados.
Solución:
- Solicitar solo los permisos estrictamente necesarios en el
config.jsondel add-on - Documentar claramente los riesgos y cómo mitigar (por ejemplo, limitar acceso a la red interna)
- Evitar comandos peligrosos (nunca ejecutar con root innecesariamente)
3. Performance y eficiencia
Correr un monitor en segundo plano puede impactar el rendimiento, sobre todo en hardware limitado como Raspberry Pi.
Solución:
- Intervalos de sondeo configurables (por defecto, 10s; se puede aumentar para minimizar carga)
- Uso de procesos ligeros y subsampling para métricas menos críticas
- Monitoreo del propio uso de recursos del add-on
4. Actualización dinámica de sensores
Asegurar que los sensores aparezcan/desaparezcan según cambios en el sistema (nuevas interfaces de red, unidades montadas) fue un reto.
Solución:
- Re-sondeo periódico de la estructura del sistema
- Publicación dinámica de nuevos sensores MQTT Discovery si se detecta un cambio
Resultados e impacto
Desde su lanzamiento, home-assistant-info ha sido adoptado por decenas de usuarios avanzados de Home Assistant. Las métricas recolectadas han permitido:
- Diagnóstico proactivo: Detección temprana de problemas de temperatura, cuellos de botella de CPU/RAM, errores de red.
- Ahorro de tiempo: Los sensores permiten automatizaciones como alertas por temperaturas anómalas o desconexión de red.
- Visibilidad centralizada: Toda la información relevante en tarjetas Lovelace o dashboards personalizados.
Métricas destacadas
- Más de 30 sensores generados automáticamente
- Tiempos de actualización < 500ms en hardware modesto
- Uso de CPU del add-on < 2% (en Raspberry Pi 4)
Aprendizajes y mejoras futuras
Crear home-assistant-info fue un ejercicio excelente de integración entre sistemas, automatización y portabilidad. Algunos de los aprendizajes clave:
- La modularidad paga dividendos: Separar sensores por módulos hizo fácil añadir nuevas métricas y mantener el código.
- El feedback de usuarios es oro: Las sugerencias ayudaron a priorizar features y mejorar la UX.
- La documentación importa: Un buen README y docs detallados reducen issues y facilitan la adopción.
Ideas para el futuro
- Dashboards web más avanzados: Integración con frameworks como Dash para visualizaciones en tiempo real ricas.
- Alertas proactivas: Notificaciones push ante umbrales críticos, sin depender solo de Home Assistant.
- Integración con otros ecosistemas: Soporte para OpenHAB, Domoticz u otros sistemas domóticos.
Recursos y comunidad
Made with ❤️ para la comunidad Home Assistant.
Si tienes ideas, sugerencias o quieres colaborar, ¡te espero en GitHub! 🚀
¿Te gustaría que profundice en alguna parte del código, o tienes dudas sobre la arquitectura de add-ons para Home Assistant? ¡Déjame tus comentarios!