Scripts: reutiliza acciones sin duplicar YAML

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 6 · Índice del curso

Una automatización responde a un acontecimiento. Un script, en cambio, describe una secuencia que Home Assistant ejecuta cuando alguien la llama. Ese «alguien» puede ser una automatización, un botón del panel, Assist, Herramientas u otro script.

Separar ambas responsabilidades evita repetir acciones. Si la rutina para preparar el salón consiste en encender la luz y el ventilador, no necesitamos copiar esos dos pasos en cada automatización que pueda solicitarla. Podemos escribir la rutina una vez, probarla de manera independiente y llamarla desde lugares diferentes.

En este capítulo crearemos el primer script del curso, lo ejecutaremos manualmente y sustituiremos varias copias de una secuencia por llamadas a una única entidad.

Automatización y script: quién decide cuándo empezar

Una automatización contiene triggers:

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

Ese bloque permite que Home Assistant la inicie automáticamente cuando ocurre el cambio.

Un script no necesita trigger. Contiene una secuencia disponible para ser llamada:

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

Podemos resumir la diferencia:

Automatización: cuándo ocurre X, ejecuta una secuencia.
Script: cuando me llamen, ejecuta esta secuencia.

Ambos utilizan la misma sintaxis de acciones. Todo lo aprendido sobre choose, condiciones dentro de una secuencia, esperas y modos de ejecución también puede aparecer en un script.

Detectar una repetición que merece convertirse en script

Imagina dos automatizaciones:

• Al abrir la puerta de noche con alguien en casa, preparar el salón.
• Cuando la casa pasa de vacía a ocupada, preparar el salón.

Las dos terminan así:

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

Copiar funciona inicialmente. El problema aparece cuando decidimos que la rutina ya no debe encender el ventilador o queremos añadir otra acción. Tendríamos que recordar todas las copias y modificarlas de la misma manera.

Un script crea un único lugar donde vive esa decisión.

Crear el script desde la interfaz

Abre Configuración → Automatizaciones y escenas → Scripts y crea uno nuevo. Utiliza:

• Nombre: Curso YAML - Preparar salón.
• Descripción: Enciende la luz y el ventilador virtuales del salón.
• Modo: single.

Añade estas acciones en orden:

1. Encender light.course_living_room.
2. Encender switch.course_fan.

Guarda el script. Home Assistant creará una entidad parecida a:

script.curso_yaml_preparar_salon

El identificador exacto depende del nombre generado y puede modificarse desde la administración de entidades. Compruébalo antes de copiar las llamadas del curso. Para mantener los archivos del laboratorio predecibles utilizaremos:

script.course_prepare_living_room

Si tu script creado desde la interfaz tiene otro entity_id, reemplázalo en los ejemplos.

El YAML del script

En la vista YAML del editor, el contenido es equivalente a:

alias: "Curso YAML - Preparar salón"
description: "Enciende la luz y el ventilador virtuales del salón."
icon: "mdi:sofa"
sequence:
  - action: light.turn_on
    target:
      entity_id: light.course_living_room
  - action: switch.turn_on
    target:
      entity_id: switch.course_fan
mode: single

sequence desempeña el papel que actions tiene en una automatización: contiene la lista de pasos que se ejecutan de arriba abajo.

alias, description, icon y mode describen y controlan el script. No hay triggers porque el script no decide por sí mismo cuándo empezar.

El mismo script dentro de scripts.yaml

scripts.yaml es un mapa. La clave exterior identifica el script:

course_prepare_living_room:
  alias: "Curso YAML - Preparar salón"
  description: "Enciende la luz y el ventilador virtuales del salón."
  icon: "mdi:sofa"
  sequence:
    - action: light.turn_on
      target:
        entity_id: light.course_living_room
    - action: switch.turn_on
      target:
        entity_id: switch.course_fan
  mode: single

Observa la diferencia con automations.yaml:

• automations.yaml contiene una lista; cada automatización empieza con guion.
• scripts.yaml contiene un mapa; cada script empieza con una clave como course_prepare_living_room:.

Pegar la estructura de uno en el otro no se corrige simplemente moviendo espacios. El contenedor exterior es diferente.

Los nombres de clave manuales de los scripts utilizan minúsculas y guiones bajos. No deben contener mayúsculas ni guiones medios.

Probar el script sin ninguna automatización

Antes de reutilizarlo, pruébalo como una unidad independiente:

1. Apaga la luz y el ventilador virtuales.
2. Abre el script desde la interfaz.
3. Ejecuta la secuencia.
4. Comprueba los estados de ambas entidades.
5. Abre la traza del script y revisa los dos pasos.

También puedes llamarlo desde Configuración → Herramientas → Acciones seleccionando su acción directa:

action: script.course_prepare_living_room

Si falla aquí, no necesitamos abrir las automatizaciones que lo utilizarán. El problema vive dentro del script o en las entidades que controla.

Esta posibilidad de probar por separado es una segunda ventaja de la reutilización: además de reducir duplicación, reduce el tamaño del problema durante el diagnóstico.

Llamar al script directamente desde una automatización

La automatización de la puerta puede sustituir las dos acciones copiadas por una llamada:

alias: "Curso YAML - Preparar salón al abrir"
triggers:
  - trigger: state
    entity_id: binary_sensor.course_front_door
    from: "off"
    to: "on"
conditions:
  - condition: state
    entity_id: binary_sensor.course_night
    state: "on"
  - condition: state
    entity_id: binary_sensor.course_someone_home
    state: "on"
actions:
  - action: script.course_prepare_living_room
mode: single

La automatización conserva la responsabilidad de decidir cuándo: puerta abierta, noche y presencia. El script decide qué significa preparar el salón.

La llamada directa espera a que el script termine. Si el script contiene un delay de un minuto, la automatización permanece en ese paso hasta que finalice. Si el script aborta debido a un error no controlado, la secuencia que lo llamó también puede abortar.

Iniciar un script sin esperar con script.turn_on

Existe otra forma:

actions:
  - action: script.turn_on
    target:
      entity_id: script.course_prepare_living_room

script.turn_on inicia el script y la automatización continúa sin esperar a que termine. Los errores posteriores del script llamado no detienen la secuencia que lo inició.

La diferencia no consiste en sintaxis nueva para hacer lo mismo; cambia la relación entre ambas ejecuciones:

Utiliza la llamada directa cuando el siguiente paso depende de que el script haya terminado. Utiliza script.turn_on cuando solo quieres iniciarlo y las dos secuencias pueden continuar de manera independiente.

En nuestro ejemplo no hay pasos posteriores, por lo que ambas formas producirán un resultado parecido. Preferimos la llamada directa porque expresa una secuencia dependiente y facilita seguirla en la traza.

Reutilizarlo desde una segunda automatización

Ahora podemos preparar el salón cuando la casa pasa de vacía a ocupada:

alias: "Curso YAML - Preparar salón al llegar"
triggers:
  - trigger: state
    entity_id: binary_sensor.course_someone_home
    from: "off"
    to: "on"
conditions: []
actions:
  - action: script.course_prepare_living_room
mode: single

Las dos automatizaciones tienen triggers y condiciones diferentes, pero comparten la misma acción de alto nivel.

Si retiramos el ventilador del script, ambas adoptan el cambio. Si añadimos una tercera llamada manual desde el panel, también utiliza la nueva versión.

No conviertas cada acción en un script

La reutilización no consiste en envolver cada línea:

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

Un script que solo renombra una acción utilizada una vez puede añadir navegación sin aportar claridad. Suele tener sentido cuando ocurre al menos una de estas situaciones:

• La secuencia se utiliza desde varios lugares.
• Representa una operación doméstica con nombre propio, como «preparar salón» o «cerrar la casa».
• Necesita probarse y mantenerse por separado.
• Oculta detalles que el llamador no necesita conocer.
• Aceptará datos distintos para reutilizar una misma lógica.

También puede haber una razón legítima para mantener dos copias parecidas: quizá hoy coinciden, pero representan comportamientos que evolucionarán de forma independiente. La decisión depende de la responsabilidad, no solo del número de líneas iguales.

Campos de entrada: el siguiente nivel de reutilización

Un script puede declarar campos para recibir datos cuando se llama: un mensaje, un tiempo, una entidad o una opción. Home Assistant utiliza esa información para mostrar controles apropiados en la interfaz.

La estructura general es:

fields:
  example_value:
    name: "Valor de ejemplo"
    description: "Dato que recibirá el script."
    required: true
    selector:
      text:

Al ejecutar el script, example_value estará disponible como variable. Para utilizarla dentro de una acción necesitaremos una plantilla:

{{ example_value }}

No introduciremos esa sintaxis a mitad de este capítulo. En el siguiente separaremos YAML de Jinja y podremos volver a los campos entendiendo qué capa aporta cada parte:

• YAML define el campo y organiza la secuencia.
• Home Assistant entrega el valor como variable.
• Jinja inserta o transforma el valor dentro de una acción.

Modos de ejecución en scripts

Un script también puede ser llamado de nuevo mientras continúa activo. mode tiene el mismo propósito que en automatizaciones:

• single: rechaza una llamada nueva.
• restart: cancela la ejecución anterior y comienza otra.
• queued: conserva las llamadas en orden.
• parallel: ejecuta llamadas independientes al mismo tiempo.

Nuestro script termina enseguida, por lo que single es suficiente. Si más adelante «preparar salón» incluyera esperas, tendríamos que revisar si una segunda llamada debe ignorarse, reiniciar la rutina o ponerse en cola.

El modo de la automatización y el modo del script son decisiones separadas. La automatización gestiona sus ejecuciones; el script gestiona las suyas.

Error deliberado: actualizar una copia y olvidar la otra

Imagina que dejamos las acciones duplicadas y retiramos el ventilador únicamente de la automatización de la puerta. La llegada por presencia todavía lo encendería. Ningún validador informaría de un error: las dos configuraciones son correctas, pero el comportamiento global ya no es coherente.

Este es un error de mantenimiento, no de sintaxis. Extraer la secuencia a un script elimina la posibilidad de que esas copias concretas diverjan.

El cambio se revisa mejor como una sustitución:

Antes: cada automatización conoce las dos entidades y acciones.
Después: cada automatización conoce una sola operación doméstica: preparar salón.

Ejercicio: extrae una secuencia repetida

Partes de dos automatizaciones que contienen estas acciones:

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

Tu tarea es:

1. Crear script.course_prepare_living_room.
2. Mover las dos acciones a su sequence.
3. Probar el script de manera independiente.
4. Sustituir la secuencia de cada automatización por una llamada directa.
5. Retirar temporalmente la acción del ventilador en el script y comprobar que ambas automatizaciones adoptan el cambio.
6. Restaurar la acción al terminar la prueba.

course_prepare_living_room:
  alias: "Curso YAML - Preparar salón"
  description: "Enciende la luz y el ventilador virtuales del salón."
  icon: "mdi:sofa"
  sequence:
    - action: light.turn_on
      target:
        entity_id: light.course_living_room
    - action: switch.turn_on
      target:
        entity_id: switch.course_fan
  mode: single

actions:
  - action: script.course_prepare_living_room

Qué debes llevarte de este capítulo

Una automatización decide cuándo empezar mediante triggers. Un script define una secuencia que se ejecuta cuando otro elemento la llama. Ambos comparten la sintaxis de acciones, condiciones, esperas y modos.

Extraer una secuencia repetida permite probarla por separado y mantener una única definición. La llamada directa a script.nombre espera a que termine; script.turn_on lo inicia sin esperar.

La reutilización debe expresar una operación comprensible, no fragmentar la configuración por sistema. En el siguiente capítulo añadiremos valores dinámicos. Antes de utilizarlos, separaremos claramente YAML y Jinja para que una plantilla no parezca otra regla arbitraria del mismo lenguaje.

Continúa leyendo

Siguiente guía relacionada · 12 min de lectura

Acciones que duran en el tiempo: retrasos, esperas y modos de ejecución

← Capítulo 5 · Índice del curso Hasta ahora nuestras acciones terminaban casi inmediatamente. Home Assistant encendía una luz, creaba una notificación o apagaba…

Continuar con este artículo↓