Gráficos Pro con ApexCharts en Home Assistant

En el mundo de la domótica, la visualización de datos es fundamental para entender lo que ocurre en nuestro hogar. Muchos usuarios de Home Assistant han confiado en la excelente Mini Graph Card para mostrar gráficos simples y limpios. Sin embargo, cuando las necesidades crecen y buscamos un nivel de personalización y potencia superior, es hora de conocer a su hermano mayor: la ApexCharts Card. Desarrollada por RomRider y basada en la potente librería de código abierto ApexCharts.js, esta tarjeta personalizada nos permite crear gráficos avanzados y detallados que pueden transformar por completo la apariencia y funcionalidad de nuestros dashboards.

A diferencia de otras tarjetas más sencillas, ApexCharts Card se configura enteramente a través de YAML, lo que le otorga una flexibilidad casi infinita. Desde gráficos de líneas y columnas hasta gráficos radiales, de tarta o de dispersión, las posibilidades son enormes. En este artículo, te guiaremos a través de la instalación, configuración y te mostraremos numerosos ejemplos prácticos para que puedas copiar, pegar y adaptar a tus propias necesidades, llevando tus visualizaciones de datos a un nivel profesional.

¿Qué es ApexCharts Card y por qué usarla?

La ApexCharts Card es una tarjeta personalizada para Lovelace (la interfaz de usuario de Home Assistant) que permite renderizar una amplia variedad de gráficos interactivos y estéticamente agradables. Su principal ventaja radica en su capacidad de personalización extrema, superando con creces a otras alternativas.

Mientras que la Mini Graph Card es perfecta para una visualización rápida y minimalista, ApexCharts Card brilla cuando necesitas:

• Combinar múltiples tipos de gráficos en uno solo (líneas, columnas, áreas).
• Realizar complejas agrupaciones y transformaciones de datos directamente en la configuración.
• Controlar cada aspecto visual del gráfico: colores, ejes, etiquetas, leyendas, etc.
• Crear gráficos más complejos como radiales, de tarta (pie) o de anillo (donut).

Es la herramienta definitiva para quienes desean analizar sus datos de sensores de forma detallada y presentar la información de la manera más clara y efectiva posible.

Instalación de ApexCharts Card

Integrar esta tarjeta en tu Home Assistant es un proceso sencillo, especialmente si utilizas HACS.

Instalación a través de HACS (Recomendado)

HACS (Home Assistant Community Store) es la forma más fácil de gestionar componentes personalizados.

1. Abre HACS en tu Home Assistant.
2. Navega a la sección de "Frontend".
3. Haz clic en el botón azul con el icono "+" (Explorar y descargar repositorios).
4. Busca "ApexCharts" en la barra de búsqueda.
5. Selecciona "ApexCharts Card" de los resultados y haz clic en "Descargar".
6. Sigue las instrucciones para añadir el recurso a tu Lovelace.

Instalación Manual

Si prefieres no usar HACS, puedes instalarla manualmente.

1. Descarga el archivo apexcharts-card.js desde la última versión en el repositorio oficial de GitHub.
2. Coloca el archivo apexcharts-card.js en tu carpeta config/www. Si la carpeta www no existe, créala.
3. Añade la referencia al recurso en Home Assistant. Tienes dos formas de hacerlo:
• Mediante la Interfaz de Usuario: Ve a Configuración → Paneles de Control. Haz clic en los tres puntos en la esquina superior derecha y selecciona Recursos. Haz clic en + Añadir Recurso, introduce la URL /local/apexcharts-card.js y selecciona "Módulo de JavaScript" como tipo de recurso.
• Mediante YAML: Añade el siguiente código a tu archivo configuration.yaml o en la sección de recursos de tu panel de control en modo YAML:

  lovelace: resources: - url: /local/apexcharts-card.js type: module

Variables de Configuración Clave

Para entender el poder de ApexCharts, es crucial familiarizarse con sus variables de configuración más importantes. Estas te permitirán manipular los datos antes de que se muestren en el gráfico.

• graph_span: Define el intervalo de tiempo total del que se recuperarán los datos históricos. Por ejemplo, 24h para las últimas 24 horas o 7d para los últimos 7 días.
• span: Permite acotar el período de tiempo mostrado dentro del graph_span. Es muy útil para mostrar datos de "hoy", "ayer" o "la semana pasada". Por ejemplo, para mostrar solo los datos de hoy, usarías graph_span: 24h y span: { start: day }.
• group_by: Una función muy potente para organizar los datos. Puedes agrupar los valores por una función (last, min, max, mean) dentro de una duración específica (10min, 1h, 1d). Esto es ideal para simplificar gráficos con muchos datos, como mostrar el consumo máximo de energía de cada día durante un mes.
• transform: Permite modificar los datos brutos del historial usando una función de JavaScript. Por ejemplo, puedes convertir el estado de un sensor binario ('on'/'off') a valores numéricos (1/0) o escalar los datos de un sensor (de KB a MB).
• data_generator: Una función avanzada que te permite generar tus propios datos a partir del último estado de un sensor, evitando por completo el historial de Home Assistant.

Ejemplos de Uso por Tipo de Gráfico

La mejor manera de aprender es viendo ejemplos prácticos. A continuación, exploraremos los tipos de gráficos más comunes con código que puedes adaptar.

Gráficos de Línea, Columna y Área

Estos son los tipos de gráficos más fundamentales, perfectos para visualizar la evolución de sensores como la temperatura o la humedad a lo largo del tiempo.

type: custom:apexcharts-card graph_span: 24h header: show: true title: Temperatura y Humedad del Salón show_states: true colorize_states: true span: start: day now: show: true label: Ahora series: - entity: sensor.temperatura_salon name: Temperatura type: line stroke_width: 2 group_by: func: avg duration: 15m show: extremas: true # Muestra los valores máximos y mínimos - entity: sensor.humedad_salon name: Humedad type: area opacity: 0.3 show: in_chart: true 

En este ejemplo, mostramos la temperatura como una línea y la humedad como un área en el mismo gráfico. Los datos se agrupan en promedios de 15 minutos para suavizar la visualización.

Gráfico de Barra Radial (Radial Bar)

Ideal para representar porcentajes, como el nivel de batería, el uso de CPU o la ocupación de disco.

type: custom:apexcharts-card chart_type: radialBar header: show: true title: Monitor del Sistema show_states: true series: - entity: sensor.uso_cpu_porcentaje name: Uso de CPU - entity: sensor.uso_memoria_porcentaje name: Uso de Memoria - entity: sensor.uso_disco_porcentaje name: Uso de Disco 

Gráfico de Tarta y Anillo (Pie & Donut)

Perfectos para mostrar la distribución de una totalidad, como el desglose del consumo energético por electrodoméstico.

type: custom:apexcharts-card chart_type: donut # Cambia a 'pie' para un gráfico de tarta completo header: show: true title: Consumo Energético Mensual (kWh) show_states: true colorize_states: true series: - entity: sensor.consumo_lavadora_mensual name: Lavadora - entity: sensor.consumo_nevera_mensual name: Nevera - entity: sensor.consumo_tv_mensual name: Televisión - entity: sensor.consumo_horno_mensual name: Horno 

Gráfico de Dispersión (Scatter)

Útil para visualizar la relación entre dos variables diferentes, mostrando los datos como una nube de puntos. Por ejemplo, puedes correlacionar la temperatura interior con la exterior.

type: custom:apexcharts-card chart_type: scatter graph_span: 7d header: title: Correlación Temperatura Interior/Exterior series: - entity: sensor.temperatura_interior name: Interior group_by: func: avg duration: 1h data_generator: | return entity.history.map((h, i) => { return [new Date(h.last_changed).getTime(), parseFloat(h.state)]; }); - entity: sensor.temperatura_exterior name: Exterior group_by: func: avg duration: 1h 

Tabla Comparativa: Mini Graph Card vs. ApexCharts Card

Para aclarar las diferencias, aquí tienes una tabla comparativa:

Preguntas Frecuentes (FAQ)

¿Necesito saber programar para usar ApexCharts Card?

No es estrictamente necesario saber programar, pero sí es fundamental tener un buen conocimiento de YAML, ya que toda la configuración se realiza en este formato. Para funciones avanzadas como transform o data_generator, tener conocimientos básicos de JavaScript será de gran ayuda.

¿Por qué no veo un editor visual en la interfaz de usuario?

La ApexCharts Card está diseñada para ofrecer la máxima flexibilidad, lo cual solo es posible a través de la configuración en código YAML. No incluye un editor visual para mantener su potencia y evitar las limitaciones que una interfaz gráfica podría imponer.

¿Por qué mis datos en el gráfico y en la tabla de datos a veces no coinciden exactamente?

Esto puede ocurrir debido a las zonas horarias. A menudo, los datos en la base de datos de Home Assistant se almacenan en UTC, mientras que el gráfico en tu navegador se muestra en tu zona horaria local. Esta diferencia puede causar pequeños desajustes en cómo se visualizan los datos, especialmente en los límites de los días.

¿Esta tarjeta consume muchos recursos del sistema?

Debido a su complejidad y la cantidad de datos que puede procesar, ApexCharts Card puede ser más exigente en recursos que tarjetas más simples, tanto para el servidor de Home Assistant (al consultar el historial) como para el navegador del cliente (al renderizar el gráfico). Para gráficos con grandes volúmenes de datos, es recomendable usar la función group_by para reducir la cantidad de puntos a mostrar y optimizar el rendimiento.

Conclusión

La ApexCharts Card es, sin duda, una de las herramientas de visualización más potentes y versátiles disponibles para Home Assistant. Aunque su curva de aprendizaje es más pronunciada que la de otras tarjetas debido a su dependencia del YAML, la inversión de tiempo se ve recompensada con creces. La capacidad de crear gráficos detallados, personalizados y funcionales te permitirá tener una comprensión mucho más profunda de los datos que generan tus dispositivos y, en última instancia, un hogar más inteligente.

Te animamos a experimentar con los ejemplos proporcionados, a consultar la documentación oficial para descubrir todas las opciones disponibles y a no tener miedo de probar configuraciones complejas. ¡Transforma tu dashboard de Home Assistant y empieza a ver tus datos como nunca antes!