Este artículo puede contener enlaces de afiliado. Si compras desde estos enlaces, el precio para ti es el mismo y la tienda me paga una pequeña comisión que ayuda a mantener Tecnoyfoto.
← Capítulo 2 · Índice del curso
Cuando miras una bombilla desde el salón, ves un dispositivo que puede estar encendido, apagado o iluminando con una intensidad concreta. Home Assistant necesita representar esas propiedades de una forma que puedan consultar la interfaz, las automatizaciones y el historial. Para hacerlo utiliza entidades, estados y atributos.
Después necesita una manera de pedir cambios: encender la bombilla, apagarla o ajustar su brillo. Para eso utiliza acciones.
Estas palabras aparecen constantemente en la interfaz y en YAML. Si no distingues qué representa cada una, es fácil intentar controlar un nombre visible, comparar un atributo como si fuera el estado o cambiar un estado desde Herramientas creyendo que se ha enviado una orden al dispositivo.
Al terminar este capítulo sabrás localizar una entidad, interpretar lo que Home Assistant conoce sobre ella y ejecutar una acción de prueba antes de utilizarla en una automatización. Todavía no construiremos la automatización completa de la puerta; primero comprobaremos que todas sus piezas existen y responden como esperamos.
Del aparato físico a su representación en Home Assistant
Un dispositivo suele representar un aparato físico o un servicio conectado: una bombilla, un enchufe, un sensor de movimiento, un termostato o un teléfono. Una integración es el componente que permite a Home Assistant comunicarse con una tecnología o servicio y crear sus representaciones internas.
Una entidad representa una función, una medición o un punto de control. Un solo dispositivo puede aportar varias entidades. Un sensor ambiental, por ejemplo, podría crear:
sensor.dormitorio_temperature
sensor.dormitorio_humidity
sensor.dormitorio_battery
Las tres entidades pueden pertenecer al mismo aparato, pero cada una tiene un estado propio. La temperatura puede ser 21.7, la humedad 48 y la batería 92.
La relación tampoco es obligatoria en sentido contrario. Un helper creado desde la interfaz, una entidad template o una automatización pueden existir sin corresponder a un aparato físico independiente. En nuestro laboratorio, binary_sensor.course_front_door es una entidad virtual: se comporta como un sensor de puerta para los ejercicios, aunque no haya un contacto magnético detrás.
Esta diferencia importa cuando trabajas con YAML. Normalmente las condiciones y acciones apuntan a entidades concretas porque son las unidades que tienen estado o aceptan una operación. El dispositivo ayuda a organizar y relacionar esas entidades, pero no sustituye automáticamente su identificador.
El entity_id: la dirección interna de una entidad
Cada entidad tiene un identificador con dos partes separadas por un punto:
light.course_living_room
La primera parte es el dominio:
light
La segunda es el identificador del objeto dentro de ese dominio:
course_living_room
La forma completa, light.course_living_room, es el entity_id.
El dominio no es una categoría decorativa
El dominio indica qué clase de entidad estamos tratando y condiciona sus estados, capacidades y acciones disponibles.
light.course_living_room
binary_sensor.course_front_door
sensor.course_living_room_temperature
switch.course_fan
light representa una luz controlable. binary_sensor representa un sensor con dos estados principales. sensor expone una medición u otro valor. switch representa un interruptor controlable.
Esta información permite entender por qué una luz utiliza acciones del dominio light, mientras que nuestro ventilador virtual, representado como switch, utiliza acciones de switch. Que ambos puedan encenderse no significa que sean intercambiables en todas sus capacidades.
El nombre visible y el entity_id no son lo mismo
La interfaz podría mostrar «Luz del salón», «Living room course light» o cualquier nombre que hayas elegido. En YAML necesitamos su identificador:
entity_id: light.course_living_room
Esto no funcionaría como objetivo:
entity_id: Luz del salón
La segunda línea sigue siendo YAML válido porque el valor es texto. El error aparece en la capa de Home Assistant: no existe una entidad identificada como Luz del salón.
El entity_id se escribe en minúsculas y normalmente utiliza guiones bajos para separar palabras. No intentes deducirlo únicamente a partir del nombre de una tarjeta. Cópialo desde el selector de entidades o desde Herramientas.
entity_id y unique_id tampoco son equivalentes
Algunas pantallas muestran un identificador único proporcionado por la integración. Ese unique_id ayuda al registro de entidades a reconocer la misma entidad entre reinicios y permite administrarla desde la interfaz. No es el valor que debes colocar en target.entity_id.
Para controlar o consultar una entidad en los ejemplos del curso utilizaremos su entity_id completo, con dominio y objeto.
El estado: un solo valor principal en cada momento
Cada entidad tiene exactamente un estado actual. En una luz suele ser on, off o unavailable. En un sensor de temperatura puede ser 21.5. En una persona puede ser home, not_home o el nombre de una zona.
Podemos imaginar estas entidades en un instante concreto:
light.course_living_room → off
binary_sensor.course_front_door → on
sensor.course_living_room_temperature → 21.5
switch.course_fan → off
binary_sensor.course_someone_home → on
Aunque una temperatura parezca un número, el estado que consultaremos mediante las herramientas y muchas plantillas se presenta como una cadena. Más adelante aprenderemos a convertirla de forma segura cuando necesitemos realizar cálculos.
La interfaz puede traducir o presentar el estado de otra manera
Nuestro sensor de puerta utiliza internamente los estados on y off. Sin embargo, la interfaz puede mostrar «Abierto» y «Cerrado». No se ha cambiado el estado almacenado: Home Assistant conoce que la entidad tiene una clase de dispositivo de puerta y adapta su presentación para que sea más humana.
Por eso no debes copiar a ciegas la palabra visible de una tarjeta para construir una condición. En Herramientas puedes comprobar el estado que Home Assistant maneja en tiempo de ejecución.
La misma idea se aplica a las unidades. Una tarjeta podría mostrar 21,5 °C, pero el estado principal es el valor y la unidad suele estar en un atributo separado.
unknown y unavailable son estados que debes esperar
Una entidad puede estar unknown cuando Home Assistant todavía no dispone de un valor conocido. Puede estar unavailable cuando la entidad existe pero no está disponible, por ejemplo porque un dispositivo está desconectado o una integración no puede obtener datos.
No son necesariamente errores de YAML. Son estados reales que una automatización y, sobre todo, una plantilla robusta deben tener en cuenta. En este capítulo aprenderemos a reconocerlos; en el capítulo de plantillas veremos cómo evitar que una conversión numérica falle cuando aparezcan.
Los atributos: información relacionada con el estado
El estado solo puede contener un valor principal. Una entidad puede necesitar más información para describir su situación actual. Esa información se guarda en atributos.
Una luz encendida podría representarse conceptualmente así:
entity_id: light.example_lamp
state: "on"
attributes:
brightness: 180
color_mode: brightness
friendly_name: "Lámpara de ejemplo"
El estado responde a la pregunta principal: ¿está encendida? Los atributos añaden contexto: brillo, modo de color y nombre visible.
Un sensor de temperatura puede mostrar:
entity_id: sensor.course_living_room_temperature
state: "21.5"
attributes:
unit_of_measurement: "°C"
device_class: temperature
friendly_name: "Course living room temperature"
El atributo unit_of_measurement permite que la interfaz interprete y presente correctamente el valor. device_class describe el tipo de medición. friendly_name aporta el nombre visible.
No todas las entidades tienen los mismos atributos. Una integración puede añadir o retirar atributos según el estado y las capacidades disponibles. Por eso conviene observar la entidad real en lugar de asumir que un ejemplo de Internet coincide exactamente con tu dispositivo.
Un atributo no es una segunda entidad
Si una luz incluye brightness: 180, no existe necesariamente una entidad llamada sensor.example_lamp_brightness. El brillo forma parte del objeto de estado de la luz.
Algunas integraciones deciden crear una entidad independiente para una medición; otras la ofrecen como atributo. La forma correcta de consultarla depende de cómo la integración haya modelado el dispositivo.
Las herramientas de Home Assistant no son solo para programadores
Home Assistant agrupa varias funciones de prueba y diagnóstico bajo «Herramientas». Dos de ellas son esenciales desde el principio:
- Estados, para observar qué entidades conoce Home Assistant y qué valores tienen.
- Acciones, para ejecutar una operación de forma controlada antes de introducirla en una automatización.
Más adelante utilizaremos también YAML, Plantillas y Eventos. El nombre del apartado puede intimidar, pero estas herramientas están pensadas precisamente para comprobar qué ocurre sin tener que construir una automatización completa para cada prueba.
Estados: observar lo que Home Assistant ve
Abre Configuración → Herramientas → Estados. Busca:
binary_sensor.course_front_door
La pantalla muestra el entity_id, su estado actual y sus atributos. Activa después el control interno:
input_boolean.course_front_door_open
El sensor de puerta debería cambiar a on. Al desactivar el control debería regresar a off. La interfaz general puede traducir esos estados, pero en esta pantalla puedes comprobar la representación que utilizarán nuestras automatizaciones.
Repite la observación con:
sensor.course_living_room_temperature
Modifica input_number.course_living_room_temperature y localiza qué parte cambia. El estado contiene el valor; la unidad permanece como atributo.
«Establecer estado» no controla el dispositivo
La herramienta Estados permite introducir manualmente otro estado o modificar atributos. Esta función cambia la representación interna que Home Assistant tiene en ese momento. No envía una orden al aparato físico.
Si estableces manualmente el estado de una bombilla como on, la bombilla no tiene por qué encenderse. Home Assistant creerá temporalmente que su representación está encendida hasta que la integración publique una actualización y sobrescriba el cambio.
La modificación manual puede producir eventos de cambio de estado y activar automatizaciones. Es útil para ciertas pruebas, pero debe utilizarse sabiendo qué se está simulando. Para pedir a una entidad real que actúe, utilizaremos la herramienta Acciones.
Acciones: pedir que algo ocurra
Una acción representa una operación que Home Assistant puede ejecutar. Sus nombres suelen combinar un dominio y una operación:
light.turn_on
light.turn_off
switch.turn_on
switch.turn_off
El punto separa el dominio de la acción concreta. light.turn_on no identifica una entidad: identifica la operación de encender una o más luces. El objetivo se indica por separado.
En la herramienta Acciones, selecciona light.turn_on y elige como objetivo:
light.course_living_room
En modo YAML, la llamada tiene esta forma:
action: light.turn_on
target:
entity_id: light.course_living_room
Ejecuta la acción y vuelve a Estados. light.course_living_room debería aparecer como on. En nuestro laboratorio, la luz es virtual, pero la acción sigue el mismo modelo que utilizarías con una bombilla real.
Ahora apágala:
action: light.turn_off
target:
entity_id: light.course_living_room
Haz una segunda prueba con el ventilador:
action: switch.turn_on
target:
entity_id: switch.course_fan
La acción pertenece a switch porque así está representado el ventilador del laboratorio. No utilizaríamos fan.turn_on salvo que la entidad perteneciera al dominio fan.
Acción, objetivo y datos cumplen funciones distintas
En una llamada completa suelen aparecer tres piezas:
action: light.turn_on
target:
entity_id: light.example_dimmable
data:
brightness_pct: 60
actionresponde a «¿qué operación quieres ejecutar?».targetresponde a «¿sobre qué entidad, dispositivo o área?».datacontiene parámetros de la operación, como el porcentaje de brillo.
La luz virtual del curso solo necesita encenderse y apagarse, por lo que no utilizaremos su brillo como prueba. El ejemplo muestra por qué entity_id no debe colocarse dentro de data: el objetivo y los parámetros son bloques con responsabilidades distintas.
Estado y acción no son órdenes equivalentes
Conviene detenerse en esta diferencia porque será la base de las automatizaciones:
Estado: lo que Home Assistant sabe ahora.
Acción: lo que pedimos que Home Assistant haga.
Una condición puede comprobar que binary_sensor.course_someone_home está on. Una acción puede pedir light.turn_on sobre la luz. La condición no enciende nada y la acción no describe por sí sola cuál era el estado anterior.
Además, ejecutar una acción no garantiza que el dispositivo físico responda. Puede estar desconectado, rechazar la orden o tardar en informar de su nuevo estado. En una automatización bien diagnosticada distinguiremos entre «Home Assistant ejecutó la acción» y «la entidad confirmó el resultado esperado».
Antes de utilizar una entidad en YAML, comprueba cuatro cosas
Cuando adaptes un ejemplo a tu casa, no te limites a sustituir nombres. Comprueba:
- El
entity_idexacto. Cópialo desde Home Assistant. - El dominio. Una entidad
switchno dispone necesariamente de las mismas acciones que una entidadlightofan. - Los estados reales. Observa si utiliza
on,off,home, un número u otros valores. - Los atributos disponibles. No presupongas que tu integración ofrece los mismos que el ejemplo.
Este procedimiento evita muchos fallos atribuidos erróneamente a YAML. El archivo puede estar perfectamente indentado y, aun así, referirse a una entidad inexistente o esperar un estado que nunca se produce.
Leer una acción línea por línea
Ya podemos interpretar con precisión este bloque:
action: light.turn_on
target:
entity_id: light.course_living_room
action y target son claves del mismo mapa. El valor de action identifica la operación turn_on del dominio light. target abre un mapa interior. Dentro de él, entity_id señala la entidad concreta que recibirá la operación.
Y también podemos detectar el problema de este otro:
action: switch.turn_on
target:
entity_id: light.course_living_room
La indentación es correcta y YAML puede analizarlo. El problema es semántico: estamos intentando utilizar una acción de interruptor sobre una entidad cuyo dominio es light. Debemos seleccionar la acción que corresponde a la entidad y a la operación deseada.
Ejercicio: observa, clasifica y actúa
Realiza las tres partes sin crear todavía una automatización.
Parte 1: inventario de entidades
Busca estas entidades en Estados:
binary_sensor.course_front_door
sensor.course_living_room_temperature
light.course_living_room
switch.course_fan
binary_sensor.course_someone_home
Para cada una anota:
- Dominio.
- Identificador situado después del punto.
- Estado actual.
- Dos atributos, si están disponibles.
- Si representa una medición, una observación binaria o un control.
Parte 2: elige Estados o Acciones
Decide qué herramienta utilizarías primero:
- Quieres saber qué estado interno representa una puerta abierta.
- Quieres encender una bombilla real.
- Quieres simular temporalmente un cambio para observar si se dispara un trigger de estado.
- Quieres descubrir qué parámetros acepta
light.turn_on. - Quieres comprobar la unidad de un sensor de temperatura.
Parte 3: corrige las llamadas
Estas dos llamadas son YAML válido, pero no controlan correctamente las entidades del laboratorio:
action: switch.turn_on
target:
entity_id: light.course_living_room
action: light.turn_on
target:
entity_id: Course living room
Corrígelas, ejecútalas desde Acciones y verifica el resultado desde Estados.
Ver la solución explicada
Para encender la luz utilizamos una acción del dominio light y su entity_id real:
action: light.turn_on
target:
entity_id: light.course_living_room
Para encender el ventilador virtual utilizamos el dominio switch:
action: switch.turn_on
target:
entity_id: switch.course_fan
En la parte 2, Estados es la herramienta adecuada para observar el estado interno de la puerta y los atributos de la temperatura. Acciones sirve para encender realmente la bombilla y consultar o probar una acción. Establecer un estado manual puede servir para simular un cambio, recordando que no controla el dispositivo.
Después de ejecutar cada acción, la comprobación en Estados separa dos pasos: primero pedimos la operación y luego observamos la representación resultante.
Qué debes llevarte de este capítulo
Una entidad es una función, medición o punto de control que Home Assistant identifica mediante un entity_id. El dominio situado antes del punto describe su clase y condiciona sus estados, capacidades y acciones.
Cada entidad tiene un solo estado principal y puede añadir atributos relacionados. La interfaz puede traducir o combinar esa información, por lo que la pantalla Estados es el lugar adecuado para comprobar qué ve Home Assistant realmente.
La herramienta Estados permite observar y simular una representación temporal; la herramienta Acciones ejecuta operaciones. Cambiar manualmente un estado no equivale a enviar una orden al dispositivo.
Ya sabemos leer YAML y también sabemos comprobar las piezas que introduciremos en él. En el próximo capítulo construiremos desde la interfaz la primera automatización completa de la casa y después leeremos su YAML línea por línea: abrir la puerta será el trigger y encender la luz será la acción.
Continúa leyendo
Siguiente guía relacionada · 16 min de lectura
Aprende a leer YAML sin memorizarlo
← Capítulo 1 · Índice del curso Cuando una configuración YAML falla, la tentación consiste en mover espacios hasta que Home Assistant deja de…
Continuar con este artículo