Scripts en Home Assistant: usos, modos y ejemplos prácticos

Si usas Home Assistant desde hace un tiempo, seguro que ya te suenan las automatizaciones, las escenas y los grupos, pero quizá no tengas tan claro para qué sirven los scripts en Home Assistant ni cuándo merece la pena utilizarlos. Y es una pena, porque bien aprovechados son una de las herramientas más potentes para exprimir tu domótica casera.

En este artículo vamos a ver con calma qué son los scripts, en qué se diferencian de las automatizaciones, cómo se configuran tanto desde la interfaz gráfica como con YAML usando la sintaxis de scripts de Home Assistant, qué modos de ejecución existen, cómo pasar variables, cómo esperar (o no) a que terminen y cómo encajarlos con escenas, grupos y zonas. La idea es que, al terminar de leer, tengas una visión clara y práctica de cómo usarlos en tu día a día.

Qué es un script en Home Assistant y para qué sirve

En Home Assistant, un script es básicamente una secuencia de acciones que se ejecutan en el orden que tú definas. No se disparan solos: se ejecutan cuando los «enciendes» (cuando llamas al script) desde la interfaz, desde otra automatización, desde otro script o mediante un servicio.

La integración de Scripts crea una entidad para cada script, de tipo script.nombre_que_tu_elijas. Esa entidad se comporta, a efectos prácticos, como algo que puedes activar, desactivar o llamar desde acciones, igual que harías con un servicio tipo light.turn_on o switch.turn_off.

La gran gracia de los scripts es que permiten encapsular lógicas repetitivas: en lugar de copiar la misma secuencia de pasos en varias automatizaciones, creas un script reusable y lo llamas desde todas ellas. Esto simplifica la configuración, reduce errores y hace que mantener tu instalación sea mucho más cómodo.

Un ejemplo sencillo: puedes tener un script que se encargue de «modo noche» (apagar luces, bajar persianas, ajustar la calefacción y activar una escena de iluminación suave) y luego llamar a ese script desde diferentes automatizaciones: al pulsar un botón físico, al llegar cierta hora, o cuando detectas que todos se han ido a dormir.

Desde un punto de vista más técnico, los scripts se apoyan en la sintaxis de scripts de Home Assistant basada en YAML, la misma filosofía que usan las automatizaciones, pero sin la parte de los disparadores (triggers). Tú decides cuándo se lanzan; el script solo define qué se hace y cómo.

Diferencias entre scripts, automatizaciones, escenas, grupos y zonas

Cuando empiezas con Home Assistant es fácil liarse entre scripts, automatizaciones, escenas, grupos y zonas, porque muchas veces parecen hacer cosas parecidas. Sin embargo, cada uno tiene su papel muy concreto dentro del ecosistema de domótica.

Las automatizaciones son las que definen el «cuándo»: tienen uno o varios disparadores (hora, detección de movimiento, cambio de estado, evento, etc.), condiciones opcionales y una serie de acciones. En cambio, los scripts definen el «qué» y el «cómo», es decir, la secuencia de acciones, pero no cuándo se ejecutan.

Las escenas, por su parte, están pensadas para dejar un conjunto de dispositivos en un estado final concreto: qué luces están encendidas, con qué brillo y color, qué persianas quedan subidas o bajadas, qué climatización hay activa, etc. No tienen lógica condicional ni bucles; simplemente «pintan» un estado predefinido.

Los grupos y las zonas se mueven en otra liga: un grupo agrupa entidades similares (varias luces en un solo grupo de luces, por ejemplo) para encenderlas o apagarlas como si fuesen una sola. Las zonas suelen utilizarse a nivel de presencia y geolocalización (zona casa, trabajo, gimnasio), de manera que puedas saber si un dispositivo o persona está dentro o fuera de un área.

La pregunta habitual es: «¿Qué es mejor usar: grupos, zonas o escenas?» En realidad no compiten entre sí, se complementan. Las escenas fijan estados, los grupos simplifican el control conjunto y las zonas sirven para detectar ubicación. Los scripts están por encima como herramienta para orquestar flujos complejos, y las automatizaciones son quienes se encargan de decidir cuándo se pone todo eso en marcha.

Cuándo usar un script y cuándo una automatización

Una duda clásica de quien empieza es saber cuándo conviene usar un script y cuándo es mejor tirar de automatización. La respuesta, en general, es que las automatizaciones son ideales para reaccionar a eventos (se abre una puerta, se hace de noche, alguien llega a casa) y los scripts son perfectos para empaquetar la lógica que quieres ejecutar como respuesta a esos eventos.

Si necesitas algo muy sencillo, como encender una luz al detectar movimiento, seguramente puedas arreglarte con una automatización directa que haga una o dos acciones. Pero si las acciones se vuelven largas, con varias llamadas a servicios, esperas, condiciones internas, etc., lo habitual es extraer esa parte a un script separado y que la automatización solo se encargue de llamarlo.

Otra situación en la que los scripts brillan es cuando quieres reutilizar exactamente la misma secuencia de acciones en varios sitios. En lugar de replicar esa lógica en tres automatizaciones distintas, creas un script y lo llamas desde las tres. Si algún día decides cambiar algo, solo actualizas el script y listo.

También son muy útiles cuando interactúas con dispositivos externos o servicios un poco puñeteros, donde necesitas varios pasos encadenados, reintentos, esperas o chequeos de estados. Tener todo eso centralizado en un script ayuda mucho a depurar y mantener el sistema.

Podemos resumirlo así: si tu necesidad principal es «cuando pase X, haz algo», empieza en una automatización; si lo que quieres es «hacer este flujo complejo» y que pueda ser llamado desde varios sitios, plantéalo como script y reutilízalo.

Formas de crear scripts: interfaz gráfica y YAML

Home Assistant permite crear scripts de dos formas: desde la interfaz web (el editor de scripts integrado) o a mano en ficheros YAML. Ambas opciones son totalmente válidas, y suelen convivir bastante bien, sobre todo si te gusta mezclar comodidad visual con flexibilidad avanzada.

En la interfaz, puedes ir al apartado de scripts y crear uno nuevo desde cero. El editor te deja definir nombre, descripción, icono, además de ir añadiendo acciones al estilo «bloques» (encender luz, esperar X segundos, llamar a un servicio, ejecutar una plantilla, etc.). Para quien no domina todavía la sintaxis YAML, esta opción es la más amigable y menos propensa a errores de formato.

Si prefieres el control total, siempre puedes escribir los scripts en tu configuration.yaml o en un fichero separado incluido con !include, por ejemplo usando WSL para tus scripts. En YAML defines el alias del script, la secuencia, los modos, los campos… y puedes explotar todo el poder de la sintaxis de scripts de Home Assistant, incluyendo plantillas Jinja para lógica avanzada.

Independientemente del método, internamente Home Assistant usa la misma lógica de ejecución. No hay diferencia en potencia entre un script creado por UI y uno definido por YAML puro; la diferencia está en que por UI tienes un entorno más visual y por YAML un control más directo del texto.

Lo importante es entender que la «secuencia» de un script es una lista de acciones en orden, y que muchas de las opciones que ya conoces de automatizaciones (wait_template, choose, repeat, etc.) están también disponibles dentro de los scripts para crear flujos de automatización muy elaborados.

Modos de ejecución de scripts en Home Assistant

Una de las partes más importantes (y a menudo ignoradas) de los scripts en Home Assistant es su «modo» de ejecución. Este modo determina cómo se comporta el script cuando se intenta arrancar mientras ya está en marcha, algo que pasa mucho cuando lo llamas desde varias automatizaciones o cuando el usuario es un poco impaciente y lo ejecuta varias veces seguidas.

Home Assistant ofrece cuatro modos principales: single, restart, queued y parallel. Cada uno tiene su casuística y conviene elegir bien cuál se ajusta mejor al comportamiento que esperas.

El modo single es el más sencillo: si el script ya se está ejecutando y se intenta lanzar otra vez, no se inicia una nueva ejecución. En su lugar, Home Assistant emite una advertencia y simplemente ignora el nuevo intento. Es útil cuando no tiene sentido que el script se duplique, por ejemplo, un script de «apagar todo» que no quieres que se solape.

En modo restart, cuando se lanza el script de nuevo mientras sigue corriendo, la ejecución actual se detiene inmediatamente y se arranca desde el principio. Este modo es ideal cuando la prioridad es que la última orden sea la que manda, por ejemplo, un script que ajusta iluminación y clima de una estancia según un perfil, y quieres que cualquier llamada nueva sobrescriba la anterior.

El modo queued encola las ejecuciones: cada llamada que llegue mientras el script está en marcha se guarda en una cola y se ejecuta cuando termine la anterior. Home Assistant garantiza que las ejecuciones se realizan en el orden en que se han recibido, lo que resulta muy útil cuando las acciones no deben solaparse pero sí necesitas que todas se procesen, como controlar un mismo dispositivo con varias peticiones rápidas.

Por último, el modo parallel permite que cada nueva llamada genere una ejecución independiente, de forma que varios hilos del mismo script puedan correr a la vez. Esto hay que usarlo con cabeza, porque puede provocar comportamientos inesperados si todos esos hilos manipulan las mismas entidades, pero es muy potente para tareas no bloqueantes o que actúan sobre recursos distintos.

Uso de variables y campos en scripts

Los scripts ganan un nivel extra de flexibilidad cuando les pasas variables. En lugar de tener un script fijo, puedes tener algo así como una «función» a la que le dices, por ejemplo, qué luz encender, qué nivel de brillo usar o durante cuánto tiempo mantener un dispositivo activado.

Desde la interfaz gráfica, esto se hace añadiendo «campos» al script. En el editor de scripts, puedes abrir el menú de tres puntos y seleccionar la opción de «Añadir campos» para definir entradas personalizadas. Al hacerlo, aparece una sección de Campos donde configuras nombre, tipo (texto, número, selector de entidad, etc.) y otras opciones para cada campo.

Estos campos se usan después en las plantillas del script, empleando la clave que hayas definido. Por ejemplo, si creas un campo llamado «nivel_brilio» (mejor escrito, claro), dentro de las acciones puedes hacer referencia a él con una plantilla que tome ese valor para ajustar un servicio, como el brillo de una luz.

Lo interesante es que, cuando ese script se use desde otras partes de la interfaz (por ejemplo, desde una automatización), esos campos se verán como inputs configurables en el editor. Así puedes reutilizar el mismo script con parámetros distintos, sin duplicar lógica.

Además de los campos definidos en el editor, puedes pasar variables a un script dentro de los datos de la acción al llamarlo. Esto funciona tanto cuando llamas directamente a la entidad script.nombre como cuando usas el servicio script.turn_on, y todas las claves que envíes estarán disponibles como variables en las plantillas del script, aunque no las tengas definidas como campos.

Llamar a scripts: script.NOMBRE vs script.turn_on

En Home Assistant hay dos formas principales de poner en marcha un script desde una acción: llamando directamente a la entidad del script (por ejemplo script.modo_noche) o usando el servicio genérico script.turn_on y pasándole la entidad como objetivo.

A primera vista parece lo mismo, pero la diferencia clave está en el comportamiento respecto a la espera. Cuando llamas al script «directamente» (usándolo como acción de tipo script), la automatización o script que lo llama espera a que el script llamado termine su ejecución antes de continuar con sus siguientes pasos.

En este modo, si el script llamado falla por algún error y se aborta, el script o automatización que lo invocó también se aborta. Es un comportamiento muy útil cuando necesitas que todo se comporte como un bloque atómico: o se ejecuta todo correctamente, o abortas la acción de alto nivel.

En cambio, si utilizas el servicio script.turn_on para lanzar uno o varios scripts, el que llama no espera a que terminen. Simplemente pide que se arranquen (en el orden en que los has listado) y a continuación sigue con sus propias acciones sin bloquearse.

En este segundo caso, los errores que puedan producirse en los scripts llamados no afectan al que hizo la llamada. Esto abre la puerta a patrones tipo «ejecutar en segundo plano»: lanzas un script que hace un trabajo pesado (por ejemplo, registrar datos, ajustar múltiples dispositivos, etc.) mientras tu automatización sigue con lo suyo.

Un patrón interesante es combinar script.turn_on con una espera más adelante (por ejemplo, usando wait_template) para esperar a que el script de fondo alcance cierto estado, pero sin que un fallo lo tumbe todo. Es una forma fina de desacoplar procesos y hacer tu domótica más robusta frente a errores puntuales.

Scripts, seguridad y buenas prácticas

En una instalación domótica compleja, los scripts no solo sirven para encender luces o mover persianas; también pueden tocar dispositivos sensibles, exponer datos o interactuar con servicios externos. Por eso es importante aplicar buenas prácticas de seguridad cuando diseñamos scripts en Home Assistant.

Si tus scripts se conectan con servicios remotos, APIs, o manejan tokens y credenciales, conviene que uses las opciones de secretos de Home Assistant en lugar de hardcodear contraseñas o claves API directamente en el YAML. Así mantienes la configuración más limpia y, si compartes fragmentos, no filtras información sensible.

También es recomendable que tus scripts incluyan cierta lógica de comprobación de estados antes de ejecutar acciones delicadas. Por ejemplo, puedes verificar que un dispositivo está en el estado esperado antes de cambiarlo, o que determinadas condiciones de seguridad se cumplen (nadie en casa, puertas cerradas, etc.) antes de dar órdenes que afecten a accesos físicos.

En entornos más avanzados, donde se integran soluciones a medida, inteligencia artificial o sistemas de análisis de datos, la parte de ciberseguridad se vuelve crítica. En esos escenarios es habitual combinar Home Assistant con desarrollos específicos y auditorías de seguridad, ya sea de la mano de proveedores externos o expertos en la materia.

En paralelo, no está de más revisar periódicamente tus scripts y automatizaciones para asegurarte de que no se han quedado anticuados, que no hay referencias a entidades eliminadas y que no acumulas lógica innecesaria que pueda provocar comportamientos raros. Una base limpia y ordenada es clave para mantener una instalación estable y segura.

Scripts y análisis de datos en el hogar inteligente

Otro campo donde los scripts pueden aportar mucho es en la recogida y procesado de datos. Al final, Home Assistant registra un montón de información sobre consumos, temperaturas, estados de dispositivos, presencia, etc., y los scripts pueden actuar como pegamento para preparar esos datos antes de enviarlos o procesarlos.

Por ejemplo, puedes crear scripts que periódicamente recopilen ciertos valores y los envíen a un sistema de análisis de negocio, como un panel de Power BI u otra herramienta de visualización, o procesarlos con Python para análisis. De este modo, transformas tu domótica en una fuente de datos reales sobre hábitos de uso y eficiencia energética, lo que te ayuda a tomar decisiones más informadas.

Si además combinas esto con lógica avanzada o con modelos de inteligencia artificial externos, puedes ir un paso más allá: tus scripts pueden llamar a servicios que analicen patrones, propongan ajustes de horario o detecten anomalías en el comportamiento de los dispositivos. Todo ello se puede integrar de vuelta en Home Assistant a través de automatizaciones o scripts adicionales.

En escenarios de este tipo, es habitual que empresas de desarrollo a medida ofrezcan soluciones específicas que enlazan Home Assistant con cuadros de mando personalizados, algoritmos de predicción de consumo o sistemas de alertas inteligentes. Los scripts se convierten en el mecanismo práctico con el que Home Assistant habla con ese ecosistema externo.

Lo interesante es que, con una buena planificación, consigues que tu hogar no solo sea más cómodo y automatizado, sino también más eficiente y transparente en términos de datos, con todo orquestado mediante scripts bien diseñados y automatizaciones que los disparan en el momento oportuno.

Después de ver todo esto, queda bastante claro que los scripts en Home Assistant son mucho más que una curiosidad avanzada: son la herramienta clave para estructurar la lógica compleja de tu instalación, reutilizar acciones, separar el «qué» del «cuándo», integrar servicios externos, cuidar la seguridad y preparar datos para análisis más serios. Con una combinación sensata de scripts, automatizaciones, escenas, grupos y zonas, tu sistema pasa de ser un simple conjunto de dispositivos conectados a convertirse en una plataforma domótica coherente, flexible y preparada para crecer sin volverse un caos.