Integraciones, dispositivos y entidades en Home Assistant

6 min
Iniciación

Home Assistant organiza la información mediante integraciones, dispositivos y entidades que representan las capacidades de nuestra casa.

El instinto natural ahora mismo es empezar a vincular cuentas y añadir aparatos a lo loco. Sin embargo, para diseñar un sistema mantenible a largo plazo, debemos detenernos a entender el modelo de datos interno del sistema.

Home Assistant no es una simple aplicación de control remoto; internamente mantiene una máquina de estados. Para normalizar protocolos y fabricantes, el núcleo utiliza una capa de abstracción basada en integraciones, dispositivos y entidades.

Si no comprendemos bien esta jerarquía desde el minuto cero, nuestras futuras automatizaciones serán bastante más difíciles de mantener.

La capa de abstracción

El objetivo de diseño de Home Assistant es que, a la hora de programar la lógica de la casa, nos dé exactamente igual si una bombilla es Zigbee, WiFi de Shelly o Matter sobre Thread.

Para lograr esto, el código fuente de Home Assistant abstrae el hardware físico convirtiéndolo en objetos de software estandarizados.

Estos conceptos suelen estar relacionados, pero no forman una jerarquía obligatoria. Una integración puede crear entidades sin dispositivo físico, y una entidad puede representar un cálculo, una persona o un servicio externo.

Integraciones: los conectores

Una integración es el componente que conecta Home Assistant con un protocolo, un fabricante o un servicio. Se parece a un controlador, aunque también puede aportar cálculos y funciones que no dependen de hardware.

Una integración es un módulo de código (escrito en Python) que sabe cómo “hablar” el idioma específico de un fabricante, servicio o protocolo, y se encarga de traducir esa comunicación al lenguaje interno de Home Assistant.

Podemos clasificar las integraciones en varias categorías técnicas:

Integraciones de Hardware/Protocolo: Como ZHA (Zigbee Home Automation) que habla con nuestro Dongle USB, o MQTT, que se conecta a un broker de mensajería.
Integraciones de Proveedor (Nube o Local): Como la integración de Shelly (que busca dispositivos en nuestra red local vía CoAP/RPC) o la de Tuya (que hace peticiones HTTP a la API REST de sus servidores).
Integraciones Lógicas o Virtuales: No todas las integraciones interactúan con el mundo físico. Existen integraciones como Meteorología (AEMET o OpenWeatherMap), Sol (que calcula el azimut y la elevación solar en base a nuestras coordenadas) o Workday (para saber si hoy es festivo).

Cuando configuramos Home Assistant por primera vez, nuestro primer paso siempre será configurar las integraciones correspondientes a los protocolos o marcas que tengamos en nuestra red.

Dispositivos: el objeto físico

Los Dispositivos (Devices) suelen representar el objeto físico y tangible que hemos comprado o fabricado, y agrupan sus distintas capacidades.

Por ejemplo, un dispositivo sería “El enchufe inteligente del salón” o “El sensor de temperatura de la marca Xiaomi”.

Los dispositivos tienen propiedades estáticas asociadas a su hardware:

Fabricante (Manufacturer)
Modelo (Model)
Versión del firmware
Dirección MAC o identificador de red (IEEE en el caso de Zigbee).

Es crucial entender que, a nivel de programación en Home Assistant, un dispositivo rara vez hace algo por sí solo. Es simplemente un contenedor lógico que agrupa funcionalidades. Nosotros no “encendemos” un dispositivo; encendemos el relé que está dentro de ese dispositivo. Ahí aparece el concepto más importante de todos.

Entidades: la unidad de información y control

Las Entidades (Entities) son el núcleo absoluto de Home Assistant. Representan la unidad atómica de información o de control.

Un único Dispositivo físico casi siempre expone múltiples Entidades.

Tomemos como ejemplo un enchufe inteligente avanzado (como un Shelly Plug S o un enchufe Zigbee con medidor de consumo). Aunque físicamente es un solo aparato (un Dispositivo), en la máquina de estados de Home Assistant generará automáticamente varias Entidades distintas:

Una entidad tipo switch (el relé que permite encender y apagar la corriente).
Una entidad tipo sensor para el consumo instantáneo (midiendo en Vatios).
Una entidad tipo sensor para la energía total acumulada (midiendo en kWh).
Una entidad tipo sensor para el voltaje de la red (230V).
Una entidad tipo button virtual para reiniciar el chip internamente.
Una entidad tipo switch de configuración para activar o desactivar el LED físico del propio enchufe.

Cuando creamos automatizaciones, normalmente es preferible trabajar con entidades y sus estados, porque son referencias explícitas y fáciles de depurar. Home Assistant también ofrece disparadores y acciones de dispositivo para determinados casos.

Dominios de las entidades (`entity_id`)

Para mantener el orden en la base de datos, cada entidad en Home Assistant tiene un identificador único e irrepetible llamado entity_id.

Este identificador siempre sigue una nomenclatura estricta dividida por un punto: dominio.nombre_del_objeto.

Ese entity_id es, en la práctica, el nombre técnico con el que vais a trabajar en automatizaciones, plantillas y dashboards. Por eso conviene que sea legible y estable desde el principio.

El Dominio define el comportamiento base y las capacidades de esa entidad en el código. Los dominios más comunes que vamos a manejar son:

light.*: Entidades que emiten luz. Soportan atributos extra como brillo, temperatura de color y color RGB. (Ej: light.lampara_salon).
switch.*: Relés binarios. Solo admiten dos estados: on u off. (Ej: switch.calentador).
sensor.*: Sensores de valores analógicos o cadenas de texto. (Ej: sensor.temperatura_exterior).
binary_sensor.*: Sensores digitales que solo tienen dos estados booleanos, generalmente on (detectado/abierto) u off (normal/cerrado). Se usan para sensores de puertas, ventanas o detectores de movimiento PIR.
climate.*: Termostatos y equipos de aire acondicionado.

Estado y atributos

Por último, dentro de cada Entidad, la información se divide en dos bloques.

El Estado es el valor principal de la entidad. Para un switch, será siempre on u off. Para un sensor de temperatura, será un número (ej. 22.5).

Los Atributos son metadatos secundarios asociados a ese estado en ese instante preciso. Por ejemplo, una entidad light.led_tv puede tener como Estado on, pero en sus Atributos indicará que el brillo está a 255 y el color en hexadecimal es #FF0000.

Nombres, áreas y orden mental

Home Assistant permite renombrar dispositivos y entidades desde la interfaz. Parece una tontería, pero nombrar bien desde el principio evita un caos tremendo cuando la instalación crece.

Una convención sencilla es usar nombres que indiquen ubicación y función: light.salon_techo, sensor.cocina_temperatura, binary_sensor.puerta_entrada. No hace falta ponerse obsesivos, pero sí evitar nombres como sensor.temperature_158d00045ab2c9, porque dentro de seis meses no sabréis si eso era el salón, el baño o el trastero.

Usad también las Áreas de Home Assistant. Asignar cada dispositivo a Salón, Cocina, Dormitorio o Garaje hace que los Dashboards, automatizaciones y búsquedas sean muchísimo más manejables.

Cómo se relacionan

En un dispositivo físico típico, el flujo será:

Instalamos una Integración (ej. ZHA).
La integración detecta un hardware físico en la red y crea un Dispositivo (ej. Sensor multientorno Zigbee).
La integración genera sus Entidades correspondientes (sensor.temperatura, sensor.humedad, sensor.bateria).
Nuestras interfaces y automatizaciones leen y escriben sobre los estados de esas Entidades.