Ordena Home Assistant antes de que el YAML se vuelva inmanejable

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

Una configuración no se vuelve difícil de mantener porque tenga muchos archivos. Se vuelve difícil cuando no sabemos qué contiene cada archivo, qué estructura espera Home Assistant al incluirlo o cuál de ellos puede reescribir la interfaz.

Hasta ahora hemos trabajado con automatizaciones y scripts aislados para concentrarnos en su comportamiento. En este capítulo colocaremos esas piezas en una estructura real. Aprenderemos qué función cumple configuration.yaml, qué diferencia hay entre incluir un archivo y combinar un directorio y cuándo un package resulta más claro que separar todo por dominios.

No existe una organización universalmente perfecta. Una casa pequeña puede funcionar durante años con automations.yaml y scripts.yaml. El objetivo es que puedas elegir una estructura que entiendas y ampliarla sin convertir cada cambio en una búsqueda a ciegas.

configuration.yaml sigue siendo el punto de entrada

Aunque muchas integraciones se configuran desde la interfaz, configuration.yaml continúa siendo el archivo principal de la configuración YAML. Una instalación habitual contiene, entre otras posibles entradas:

default_config:

automation: !include automations.yaml
script: !include scripts.yaml
scene: !include scenes.yaml

Estas líneas no copian texto de forma indiscriminada. Cada !include se evalúa exactamente donde aparece. Por tanto, el archivo incluido debe devolver el tipo de estructura que ese lugar necesita.

En el ejemplo:

• automations.yaml debe contener una lista de automatizaciones.
• scripts.yaml debe contener un mapa cuyos nombres son las claves de los scripts.
• scenes.yaml debe contener una lista de escenas.

La diferencia entre lista y mapa no es un detalle de formato. Determina si cada entrada empieza con un guion o con una clave.

No repitas la clave que ya existe fuera

Supongamos que configuration.yaml contiene:

automation: !include automations.yaml

Entonces automations.yaml comienza directamente con la lista:

- alias: "Curso YAML - Encender al abrir"
  triggers:
    - trigger: state
      entity_id: binary_sensor.course_front_door
      from: "off"
      to: "on"
  actions:
    - action: light.turn_on
      target:
        entity_id: light.course_living_room

No debe empezar así:

automation:
  - alias: "Curso YAML - Encender al abrir"

La clave automation ya está en el archivo principal. Repetirla equivale conceptualmente a construir automation → automation → lista, una estructura distinta de la que Home Assistant espera.

Con los scripts ocurre algo parecido, pero el contenido esperado es un mapa:

prepare_living_room:
  alias: "Curso YAML - Preparar salón"
  sequence:
    - action: light.turn_on
      target:
        entity_id: light.course_living_room

Aquí no hay guion delante de prepare_living_room. Esa clave da lugar a la entidad script.prepare_living_room.

!include incluye un archivo; las variantes de directorio construyen estructuras

Cuando un solo archivo deja de resultar cómodo, Home Assistant ofrece cuatro directivas para directorios. Sus nombres parecen similares, pero no son intercambiables.

!include_dir_list: un archivo se convierte en un elemento

automation manual: !include_dir_list automations/manual

La directiva devuelve una lista y coloca el contenido completo de cada archivo como un elemento. Por eso cada archivo debe contener una automatización sin el guion exterior:

alias: "Curso YAML - Luz de entrada"
triggers:
  - trigger: state
    entity_id: binary_sensor.course_front_door
    to: "on"
actions:
  - action: light.turn_on
    target:
      entity_id: light.course_living_room

Es útil cuando queremos una automatización por archivo.

!include_dir_merge_list: todos los archivos aportan elementos a una lista

automation manual: !include_dir_merge_list automations/manual

También devuelve una lista, pero ahora cada archivo debe contener su propia lista. Es decir, cada automatización sí empieza con un guion. Un archivo puede aportar una o varias:

- alias: "Curso YAML - Abrir puerta"
  triggers:
    - trigger: state
      entity_id: binary_sensor.course_front_door
      to: "on"
  actions:
    - action: light.turn_on
      target:
        entity_id: light.course_living_room

Esta opción encaja bien si agrupamos varias automatizaciones relacionadas en cada archivo.

!include_dir_named: el nombre del archivo se convierte en una clave

Esta directiva devuelve un mapa. Cada nombre de archivo, sin extensión, se usa como clave y su contenido como valor. Por ejemplo:

homeassistant:
  packages: !include_dir_named packages

Un archivo packages/yaml_course.yaml se carga bajo el nombre de package yaml_course. Su contenido puede reunir diferentes dominios relacionados con la misma función.

!include_dir_merge_named: combina varios mapas

Esta variante también devuelve un mapa, pero no utiliza el nombre de archivo como clave. Fusiona las claves que ya contiene cada archivo:

group: !include_dir_merge_named groups

Un archivo podría definir living_room: y otro exterior:. El resultado es un único mapa con ambas claves. Si repetimos una clave en dos archivos, la estructura deja de ser inequívoca; conviene que cada clave tenga un único propietario.

Las cuatro directivas recorren también los subdirectorios y ordenan los archivos alfanuméricamente. Para las inclusiones de directorio se procesan archivos con extensión .yaml; un .yml no entra automáticamente. El orden puede importar cuando una secuencia depende de la anterior, pero no debería utilizarse para ocultar dependencias difíciles de entender.

Conserva las automatizaciones de la interfaz y separa las manuales

La interfaz de Home Assistant administra normalmente automations.yaml. Si editas una automatización desde el editor visual y la guardas, Home Assistant puede reescribir la representación de ese archivo. No es el lugar adecuado para imponer manualmente una maquetación muy personal o comentarios que deban conservarse.

Podemos mantener las dos formas de trabajo con claves etiquetadas:

automation ui: !include automations.yaml
automation manual: !include_dir_merge_list automations/manual

Las palabras ui y manual son etiquetas que permiten declarar varias configuraciones del mismo dominio. Las automatizaciones de automations.yaml siguen siendo editables desde la interfaz; las manuales se mantienen en nuestros archivos y aparecen como configuración de solo lectura.

No hace falta dividir nada solo porque la opción existe. Si tienes doce automatizaciones y encuentras cualquiera de ellas en segundos, un solo archivo puede ser la solución más clara.

Packages: reunir por función en vez de separar por dominio

Separar por dominio coloca automatizaciones en un sitio, scripts en otro y ayudantes en otro. Eso resulta coherente desde el punto de vista técnico, pero puede dispersar una función completa de la casa.

Un package permite reunir bajo un mismo archivo todo lo relacionado con una habitación o propósito:

homeassistant:
  packages: !include_dir_named packages

Dentro de packages/yaml_course.yaml podemos encontrar, por ejemplo:

input_boolean:
  course_someone_home:
    name: "Curso YAML - Hay alguien en casa"

script:
  course_prepare_living_room:
    alias: "Curso YAML - Preparar salón"
    sequence:
      - action: light.turn_on
        target:
          entity_id: light.course_living_room

automation:
  - alias: "Curso YAML - Entrada"
    triggers:
      - trigger: state
        entity_id: binary_sensor.course_front_door
        to: "on"
    actions:
      - action: script.course_prepare_living_room

El package contiene claves de dominio completas porque se integra a un nivel diferente: no sustituye solamente el contenido de automation, sino que aporta varias secciones a la configuración.

Organizar por habitación suele funcionar cuando cada espacio tiene comportamientos bastante independientes. Organizar por función —seguridad, climatización, iluminación— ayuda cuando una misma lógica cruza varias habitaciones. Lo importante es que una pieza tenga un lugar previsible, no mezclar tres criterios sin una regla.

secrets.yaml separa secretos, pero no los cifra

Cuando una configuración contiene una contraseña, un token o una URL privada, podemos sustituir el valor por una referencia:

password: !secret course_example_password

Y guardar el dato en secrets.yaml:

course_example_password: "valor-privado"

Esto permite compartir un fragmento de configuración sin copiar el secreto y centraliza los valores sensibles. Sin embargo, secrets.yaml sigue siendo texto legible para quien tenga acceso a los archivos. No es cifrado. Tampoco convierte automáticamente en segura una copia de respaldo que lo contenga.

Hay otra limitación práctica: utilizar !secret dentro de automations.yaml o scripts.yaml administrados por la interfaz impide editarlos o verlos normalmente desde ese editor. Si una automatización necesita secretos, conviene colocarla en un archivo manual separado y conocer también que los administradores podrían ver el valor resuelto en vistas como el código fuente o la traza.

Antes de compartir configuración con una persona o con una IA:

• Sustituye claves, tokens, webhooks, direcciones externas y credenciales por valores ficticios.
• Revisa también nombres de personas, coordenadas, matrículas y mensajes de notificación.
• No publiques secrets.yaml.
• Si un secreto se ha compartido por error, cámbialo; borrarlo del mensaje no garantiza que deje de estar expuesto.

Cómo elegir una estructura sin complicarla de más

Una progresión razonable sería:

1. Mantener los archivos estándar mientras sigan siendo cómodos.
2. Separar las automatizaciones escritas a mano de las administradas por la interfaz.
3. Crear directorios solo cuando exista una agrupación clara.
4. Usar packages para funciones que incluyan varios dominios y tenga sentido mantener juntas.
5. Escribir en el README del sistema qué criterio se ha elegido.

No midas la calidad por el número de archivos. Cien archivos de cinco líneas pueden ser tan difíciles de recorrer como uno de cinco mil si sus nombres no explican nada.

Ejercicio: identifica qué estructura devuelve cada inclusión

En el laboratorio encontrarás cuatro situaciones. Antes de mirar la solución, responde para cada una:

1. ¿Home Assistant espera una lista o un mapa en el punto de inclusión?
2. ¿Cada archivo representa un elemento, contiene una lista o aporta claves a un mapa?
3. ¿Debe aparecer la clave padre dentro del archivo incluido?
4. ¿La interfaz administrará ese archivo?

Después reorganiza una automatización manual y un script sin cambiar su comportamiento. El objetivo no es memorizar los cuatro nombres, sino razonar desde la estructura resultante.

automation ui: !include automations.yaml
automation manual: !include_dir_merge_list automations/manual
script: !include scripts.yaml

Lo que ya deberías poder explicar

Al terminar este capítulo, deberías poder abrir configuration.yaml y seguir el recorrido hasta el archivo que contiene una automatización. También deberías distinguir estas ideas:

• !include ocupa un lugar concreto y el archivo devuelve el contenido esperado allí.
• list y named no son preferencias estéticas: producen tipos de datos distintos.
• Un package reúne varios dominios alrededor de una función o espacio.
• Los archivos gestionados por la interfaz tienen reglas diferentes de los manuales.
• secrets.yaml ayuda a separar información sensible, pero no la cifra.

En el próximo capítulo utilizaremos esta estructura para diagnosticar fallos de manera ordenada. Cuando sabemos qué archivo aporta cada bloque, un error deja de ser «algo roto en Home Assistant» y pasa a tener una localización y una capa concretas.

Continúa leyendo

Siguiente guía relacionada · 11 min de lectura

YAML y Jinja no son lo mismo: primeras plantillas en Home Assistant

← Capítulo 7 · Índice del curso Hasta ahora todos nuestros valores eran fijos. Una acción encendía siempre la misma luz y una notificación…

Continuar con este artículo↓