Tu primera automatización en YAML, línea por línea

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.

Albert BarnosellEditor y responsable de Tecnoyfoto

← Capítulo 3 · Índice del curso

Ya sabemos leer la estructura de un documento YAML y comprobar qué estados y acciones utiliza Home Assistant. Ha llegado el momento de unir ambas cosas para conseguir un resultado visible: cuando se abra la puerta virtual del laboratorio, Home Assistant encenderá la luz del salón.

La automatización es pequeña a propósito. Solo tendrá un trigger y una acción. Eso nos permitirá seguir el recorrido completo desde el acontecimiento hasta el resultado sin esconder las ideas importantes dentro de veinte opciones nuevas.

Primero la construiremos desde la interfaz. Después abriremos su vista YAML y leeremos cada bloque. Finalmente la probaremos de tres maneras diferentes, porque «ejecutar las acciones» no significa lo mismo que provocar el trigger real.

La estructura mental de una automatización

Una automatización responde a este modelo:

Cuando ocurre algo → comprueba unas condiciones → ejecuta unas acciones

Home Assistant lo representa mediante tres secciones principales:

triggers:
conditions:
actions:

El trigger inicia la automatización. Las condiciones deciden si puede continuar en ese momento. Las acciones describen lo que se ejecutará si llega hasta ellas.

Las condiciones son opcionales. Si no necesitamos ninguna, la sección puede contener una lista vacía:

conditions: []

El trigger y las acciones no son opcionales para nuestro caso. Sin trigger, nada iniciaría la automatización de manera automática. Sin acciones, podría iniciarse, pero no produciría el resultado que buscamos.

Describe el comportamiento antes de abrir el editor

Escribir una frase clara ayuda a no mezclar causas, comprobaciones y resultados:

Cuando la puerta de entrada cambie de cerrada a abierta, enciende la luz del salón.

Podemos separar sus piezas:

• Acontecimiento: la puerta cambia de cerrada a abierta.
• Entidad observada: binary_sensor.course_front_door.
• Estado interno inicial: "off".
• Estado interno final: "on".
• Acción: light.turn_on.
• Objetivo: light.course_living_room.

No hay ninguna condición. La automatización debe reaccionar siempre que ocurra ese cambio.

Crear la automatización desde la interfaz

En Home Assistant, abre Configuración → Automatizaciones y escenas y crea una automatización nueva. Elige empezar con una automatización vacía.

Asigna un nombre que describa el resultado sin necesidad de abrirla:

Curso YAML - Encender luz al abrir la puerta

Puedes añadir esta descripción:

Enciende la luz virtual del salón cuando la puerta del laboratorio pasa de cerrada a abierta.

En el apartado de triggers, añade un trigger de estado:

• Entidad: binary_sensor.course_front_door.
• De: off.
• A: on.

No añadas condiciones.

En las acciones, selecciona la acción para encender una luz y elige:

light.course_living_room

Guarda la automatización. Home Assistant habrá creado su identificador interno y la entidad correspondiente a la automatización.

Los textos exactos de algún botón pueden variar ligeramente según el idioma o una actualización de la interfaz. Las piezas que buscamos no cambian: trigger de estado, ausencia de condiciones y acción light.turn_on sobre la entidad del laboratorio.

El YAML completo que acabamos de construir

Abre el menú de la automatización y entra en Editar en YAML. Deberías encontrar una estructura equivalente a esta:

alias: "Curso YAML - Encender luz al abrir la puerta"
description: >-
  Enciende la luz virtual del salón cuando la puerta del laboratorio pasa
  de cerrada a abierta.
triggers:
  - trigger: state
    entity_id: binary_sensor.course_front_door
    from: "off"
    to: "on"
conditions: []
actions:
  - action: light.turn_on
    target:
      entity_id: light.course_living_room
mode: single

La interfaz puede ordenar algún campo de manera diferente o generar una descripción en una sola línea. Eso no cambia el comportamiento.

alias y description: entender la automatización antes de abrirla

alias: "Curso YAML - Encender luz al abrir la puerta"
description: >-
  Enciende la luz virtual del salón cuando la puerta del laboratorio pasa
  de cerrada a abierta.

alias es el nombre que veremos en la interfaz. Conviene que indique qué hace y, cuando sea útil, en qué contexto. «Automatización puerta» aporta menos información que «Encender luz al abrir la puerta».

description documenta detalles que no caben en el nombre. Aquí hemos utilizado un bloque de texto plegado para dividir una frase larga en el archivo. No afecta a la lógica.

triggers: lo que despierta la automatización

triggers:
  - trigger: state
    entity_id: binary_sensor.course_front_door
    from: "off"
    to: "on"

triggers contiene una lista. Solo hay un elemento, iniciado por el guion de trigger.

El valor state indica que observamos un cambio de estado. entity_id identifica qué entidad observamos. from y to delimitan la transición exacta: debe salir de "off" y entrar en "on".

En nuestro sensor de puerta, "off" significa cerrada y "on" significa abierta. Utilizamos los estados internos que comprobamos en el capítulo anterior, no las palabras traducidas que puede mostrar una tarjeta.

Por qué especificamos from y to

Podríamos escribir:

triggers:
  - trigger: state
    entity_id: binary_sensor.course_front_door
    to: "on"

Esta versión se inicia cuando la entidad entra en "on" desde cualquier estado anterior, incluido unknown o unavailable. Puede ser exactamente lo que deseas en algunos casos.

Al añadir from: "off", expresamos una transición más concreta: una puerta conocida como cerrada se ha abierto. En este primer ejercicio preferimos esa precisión porque nos ayuda a razonar sobre el cambio observado.

Tampoco conviene eliminar tanto from como to sin comprender el efecto:

triggers:
  - trigger: state
    entity_id: binary_sensor.course_front_door

Así el trigger puede responder a cualquier cambio del objeto de estado, incluidos determinados cambios de atributos. Ya no significa específicamente «la puerta se ha abierto».

conditions: []: una lista vacía también comunica una decisión

conditions: []

Los corchetes representan una lista vacía. La automatización no tiene condiciones: una vez disparado el trigger, pasa directamente a las acciones.

Podríamos omitir la clave en una configuración manual, pero el editor suele conservar las tres secciones para mostrar la estructura completa. No hay nada que corregir en esa lista vacía.

actions: el resultado que pedimos

actions:
  - action: light.turn_on
    target:
      entity_id: light.course_living_room

actions es otra lista. Su primer elemento pide ejecutar light.turn_on. Dentro de target, entity_id identifica la luz que debe recibir la orden.

Ya probamos esta llamada en Herramientas → Acciones. Al introducirla en una automatización no cambia su significado; cambia el momento en que se ejecuta. Antes pulsábamos un botón. Ahora se ejecutará después del trigger.

mode: single: qué ocurre si vuelve a iniciarse

mode: single

El modo controla qué debe ocurrir si la automatización recibe un nuevo trigger mientras una ejecución anterior todavía está activa.

single permite una sola ejecución y rechaza una nueva mientras la anterior no haya terminado. Nuestra acción termina casi inmediatamente, así que es muy improbable que este detalle produzca una diferencia observable. En el capítulo 6 trabajaremos con esperas y veremos por qué entonces el modo sí cambia el comportamiento.

¿Dónde está id?

Una automatización creada desde la interfaz tiene un identificador único almacenado en automations.yaml. Dependiendo de la vista YAML que muestre el editor, el campo id puede no aparecer en el fragmento editable.

Una entrada completa de automations.yaml suele tener esta forma:

- id: "course_turn_on_light_when_door_opens"
  alias: "Curso YAML - Encender luz al abrir la puerta"
  description: "Enciende la luz virtual del salón al abrir la puerta."
  triggers:
    - trigger: state
      entity_id: binary_sensor.course_front_door
      from: "off"
      to: "on"
  conditions: []
  actions:
    - action: light.turn_on
      target:
        entity_id: light.course_living_room
  mode: single

El guion exterior existe porque automations.yaml es una lista de automatizaciones. id permite a Home Assistant identificar esta automatización de manera estable. También es necesario para conservar trazas de automatizaciones escritas manualmente en YAML.

El id no es el entity_id de la automatización, ni el alias visible. Debe ser único dentro del conjunto de automatizaciones. Si utilizas el editor, deja que Home Assistant lo gestione.

Probar la acción no es lo mismo que probar el trigger

Home Assistant ofrece varias maneras de realizar pruebas. Cada una responde a una pregunta diferente.

Ejecutar una acción individual

Desde el menú de una acción en el editor puedes ejecutarla directamente. Esto confirma que la llamada y su objetivo funcionan. No comprueba el trigger ni las condiciones.

En nuestro caso responde a:

¿Puede Home Assistant ejecutar light.turn_on sobre light.course_living_room?

Ejecutar todas las acciones de la automatización

La opción Ejecutar acciones recorre la secuencia de acciones, pero omite triggers y condiciones. Si la luz se enciende así, solo sabemos que la parte final funciona.

Esta prueba es útil, pero puede conducir a una conclusión incorrecta: «La automatización funciona manualmente, por tanto el trigger funciona». No hemos probado el trigger.

Provocar el acontecimiento real

Para probar el recorrido completo:

1. Apaga light.course_living_room.
2. Comprueba que input_boolean.course_front_door_open está desactivado.
3. Activa input_boolean.course_front_door_open.
4. Verifica que binary_sensor.course_front_door pasa de off a on.
5. Comprueba que la luz cambia a on.

Ahora sí hemos provocado la transición configurada y observado el resultado.

Para repetir la prueba debes cerrar primero la puerta virtual. Activar un control que ya está activado no produce una nueva transición de off a on.

Leer la primera traza

Después de provocar el trigger, abre la automatización y consulta sus trazas. Home Assistant muestra el recorrido de la ejecución paso a paso.

En esta automatización deberías ver:

Trigger de estado activado
        ↓
Sin condiciones que comprobar
        ↓
Acción light.turn_on ejecutada

Selecciona el paso del trigger. La traza conserva información del cambio que inició la automatización, incluidos el estado anterior y el nuevo. Selecciona después la acción y revisa el objetivo utilizado.

La traza no solo sirve cuando algo falla. Mirarla ahora, mientras el comportamiento es sencillo, te ayudará a interpretarla cuando existan condiciones y varias ramas.

Home Assistant almacena un número limitado de trazas recientes. En automatizaciones YAML, deben tener un id para que las trazas se conserven.

Primer diagnóstico: la acción funciona, pero la puerta no la inicia

Supongamos que Ejecutar acciones enciende la luz, pero abrir la puerta virtual no hace nada. Ya hemos aislado una parte del problema:

• La acción y su objetivo probablemente son correctos.
• Debemos revisar el trigger, el estado de la automatización y la transición real de la puerta.

Comprueba:

1. Que la automatización está activada.
2. Que el entity_id del trigger coincide exactamente.
3. Que la puerta parte de off.
4. Que cambia realmente a on.
5. Que existe una traza nueva después de abrirla.

Si no hay traza, la automatización no llegó a iniciarse. Mover espacios en la acción no ayudará. El diagnóstico se concentra en aquello que todavía no hemos demostrado.

Ejercicio: apagar la luz cuando se cierre la puerta

Crea una segunda automatización. El requisito es:

Cuando la puerta pase de abierta a cerrada, apaga la luz del salón.

No copies inmediatamente la solución. Parte de la automatización que ya funciona y decide qué piezas deben cambiar.

Debes obtener:

• Un alias diferente.
• La misma entidad de trigger.
• La transición inversa: de "on" a "off".
• La acción light.turn_off.
• El mismo objetivo.

Prueba las dos automatizaciones alternando el control de la puerta. Abierta debe encender la luz; cerrada debe apagarla.

alias: "Curso YAML - Apagar luz al cerrar la puerta"
description: >-
  Apaga la luz virtual del salón cuando la puerta del laboratorio pasa
  de abierta a cerrada.
triggers:
  - trigger: state
    entity_id: binary_sensor.course_front_door
    from: "on"
    to: "off"
conditions: []
actions:
  - action: light.turn_off
    target:
      entity_id: light.course_living_room
mode: single

Un error deliberado: confundir una entrada de lista con el editor

Este bloque pertenece a automations.yaml:

- id: "course_close_door_turn_off_light"
  alias: "Curso YAML - Apagar luz al cerrar la puerta"
  triggers:
    - trigger: state
      entity_id: binary_sensor.course_front_door
      from: "on"
      to: "off"
  conditions: []
  actions:
    - action: light.turn_off
      target:
        entity_id: light.course_living_room
  mode: single

Si lo pegas completo dentro de la vista YAML de una automatización individual, introduces una lista exterior donde el editor espera el mapa de una sola automatización. No debes «arreglar la indentación» al azar. Debes retirar el guion exterior y comprender que id lo gestiona el contexto de almacenamiento.

La pregunta correcta antes de copiar siempre es:

¿Este fragmento representa una automatización, un elemento de automations.yaml o toda la sección automation:?

Qué debes llevarte de este capítulo

Una automatización se inicia con uno de sus triggers, comprueba las condiciones y ejecuta las acciones. Nuestra primera automatización no tiene condiciones, pero conserva la sección como una lista vacía.

El trigger de estado no describe simplemente un valor: puede describir una transición concreta mediante from y to. La acción conserva el mismo significado que ya probamos en Herramientas → Acciones; ahora es el motor de automatizaciones quien decide cuándo llamarla.

También hemos separado tres pruebas diferentes: ejecutar una acción, ejecutar la secuencia de acciones y provocar el trigger real. Solo la tercera recorre el comportamiento completo. La traza nos permite comprobar qué camino siguió Home Assistant.

En el siguiente capítulo haremos crecer la automatización. Abrir la puerta ya no será suficiente: tendrá que ser de noche y haber alguien en casa. Después utilizaremos choose para expresar resultados distintos sin esconder la lógica dentro de una plantilla.

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↓