YAML en Home Assistant desde cero: qué necesitas aprender de verdad

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

Es posible utilizar Home Assistant durante mucho tiempo sin abrir configuration.yaml. Puedes añadir integraciones, crear áreas, preparar un panel e incluso construir automatizaciones desde la interfaz. Entonces llega el día en que encuentras una solución que encaja exactamente con tu problema, pulsas «Editar en YAML» y aparece algo parecido a esto:

alias: "Luz al abrir la 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

No es un programa tradicional, aunque a primera vista pueda parecerlo. Tampoco es una sucesión de palabras que debas memorizar. Es una forma ordenada de describir datos: el nombre de la automatización, el acontecimiento que la inicia y la acción que Home Assistant debe ejecutar.

Al terminar este capítulo todavía no construiremos una automatización completa. Primero vamos a colocar los cimientos: entender qué papel desempeña YAML en Home Assistant, qué merece la pena aprender y qué puedes dejar fuera sin ninguna preocupación. También prepararemos una casa virtual para que los ejemplos del resto del curso se puedan probar aunque no tengas los mismos dispositivos que nosotros.

Home Assistant no te obliga a elegir entre la interfaz y YAML

A veces se presenta la interfaz visual y YAML como si fueran dos maneras enfrentadas de utilizar Home Assistant. Según esa idea, el principiante usaría la interfaz y el usuario avanzado tendría que abandonar los formularios para escribirlo todo a mano. En una instalación real, la división no funciona así.

La interfaz es muy práctica para descubrir opciones, seleccionar entidades y crear una primera versión sin preocuparte todavía por la estructura interna. YAML resulta útil cuando quieres leer esa estructura con precisión, comparar dos configuraciones, modificar varias partes relacionadas, trasladar un ejemplo o entender por qué algo falla. Puedes alternar entre ambas formas de trabajo según la tarea.

Imagina que creas una automatización desde la interfaz: eliges que la puerta sea el desencadenante y que una luz se encienda como acción. El editor visual te muestra campos y menús. La vista YAML representa esas mismas decisiones mediante claves, valores y listas. No son dos automatizaciones diferentes. Son dos vistas de una configuración con el mismo propósito.

Esta relación será una herramienta didáctica durante todo el curso. Cuando un concepto sea nuevo, muchas veces empezaremos construyéndolo desde la interfaz. Después abriremos YAML y observaremos qué ha creado Home Assistant. Más adelante, cuando ya entiendas la estructura, podrás decidir qué forma resulta más cómoda para cada cambio.

Qué es YAML exactamente

YAML es un formato legible para representar información estructurada. Permite expresar datos sencillos —un nombre, un número o un estado— y agruparlos en estructuras más grandes.

Este fragmento, por ejemplo, contiene información sobre una habitación ficticia:

room: "living_room"
occupied: true
temperature: 21.5

Cada línea relaciona un nombre situado a la izquierda con un valor situado a la derecha. YAML no decide qué significa occupied ni enciende la calefacción cuando la temperatura baja. Solo conserva esa información de manera estructurada. Hace falta un programa que conozca esas claves y sepa cómo interpretarlas.

En nuestro caso, ese programa es Home Assistant. Cuando encuentra claves como triggers, conditions, actions o entity_id en el lugar adecuado, no las entiende porque sean palabras especiales de YAML. Las entiende porque forman parte de la configuración que Home Assistant ha definido.

Esta distinción evita una confusión muy frecuente:

YAML organiza los datos. Home Assistant les da significado y ejecuta el comportamiento.

Más adelante añadiremos una tercera pieza, Jinja, que Home Assistant utiliza para calcular valores dinámicos. Por ahora basta con saber que Jinja y YAML tampoco son lo mismo. Cuando lleguemos a las plantillas, separaremos cuidadosamente qué símbolos pertenecen a cada capa.

YAML no es un lenguaje de programación

En YAML no escribes por sí solo un algoritmo capaz de tomar decisiones, repetir operaciones o controlar una casa. Describes una estructura que otra aplicación interpreta. Home Assistant sí contiene un motor de automatizaciones, condiciones, acciones, scripts y plantillas; YAML es una de las formas de expresar la configuración de ese motor.

Esta precisión no es una discusión académica. Si crees que todo lo que aparece dentro de un archivo YAML pertenece al lenguaje YAML, expresiones como light.turn_on, choose o {{ states(...) }} parecen reglas arbitrarias de un mismo idioma. Cuando separas las capas, resulta más fácil buscar el problema correcto:

• Una indentación incorrecta puede ser un error de YAML.
• Una acción que no existe es un problema de configuración de Home Assistant.
• Una expresión dinámica mal escrita pertenece a Jinja.
• Una automatización que se ejecuta pero toma la decisión equivocada tiene un problema de lógica.

Todavía no necesitas memorizar esta clasificación. La iremos utilizando hasta que se convierta en una forma natural de diagnosticar.

Para qué sigue sirviendo YAML en Home Assistant

La mayor parte de las integraciones habituales se pueden configurar desde la interfaz. Eso es una ventaja: Home Assistant puede comprobar campos, mostrar descripciones y guiarte sin obligarte a editar archivos. Aprender YAML no significa renunciar a esas facilidades.

Aun así, saber leerlo y modificarlo continúa siendo valioso en situaciones muy comunes:

Entender ejemplos y documentación

Muchas soluciones se comparten como bloques YAML porque el texto conserva exactamente la estructura. Cuando sabes leerlos, puedes comprobar qué entidades utilizan, qué condiciones aplican y qué acciones ejecutan antes de copiar nada.

Revisar automatizaciones y scripts

Una automatización con varias ramas puede resultar más fácil de comprender en YAML que recorriendo muchos formularios desplegables. La jerarquía completa queda visible y se pueden comparar bloques similares.

Realizar modificaciones precisas

Hay cambios pequeños que resultan rápidos en la vista YAML: sustituir una entidad, duplicar una acción o reordenar una secuencia. Esto solo es una ventaja cuando entiendes lo que estás tocando. Copiar un bloque sin reconocer su nivel de indentación puede introducir un error difícil de ver.

Organizar una instalación que está creciendo

configuration.yaml, los archivos incluidos, packages y secrets.yaml permiten distribuir una configuración manual de manera comprensible. No empezaremos por ahí porque primero necesitas reconocer la forma de los datos que vas a organizar.

Diagnosticar problemas

Los mensajes de error suelen señalar claves, listas, rutas y valores. Si puedes reconstruir la estructura del bloque, dejas de probar cambios al azar. El objetivo no es evitar todos los errores, sino saber qué hacer cuando aparezcan.

Lo que no necesitas aprender para completar este curso

YAML se utiliza también en Docker Compose, Kubernetes, GitHub Actions, Ansible y muchas otras herramientas. Cada sistema define sus propias claves y reglas. Conocer esos ecosistemas no te ayudará necesariamente a crear una automatización mejor en Home Assistant.

Tampoco necesitas estudiar la especificación completa de YAML, conocer la historia de sus creadores o utilizar todas sus posibilidades avanzadas. Este curso se concentrará en el subconjunto que aparece de verdad al configurar una casa:

• Claves y valores.
• Listas y mapas.
• Indentación.
• Cadenas, números, booleanos y valores vacíos.
• Comentarios y bloques de texto.
• La forma de las automatizaciones, scripts y plantillas de Home Assistant.
• Organización y diagnóstico.

Cuando una característica avanzada no resuelva un problema propio de este nivel, no la introduciremos solo para que el temario parezca más completo.

No memorices YAML: aprende a reconstruir su estructura

Volvamos al primer ejemplo:

alias: "Luz al abrir la 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

Aunque todavía no hemos estudiado la sintaxis, podemos leer su intención general:

• Tiene un nombre: «Luz al abrir la puerta».
• Observa el estado de binary_sensor.course_front_door.
• Le interesa el cambio hacia "on".
• Ejecuta la acción light.turn_on.
• El objetivo es light.course_living_room.

Esta lectura no exige conocer de memoria todas las opciones disponibles. Exige reconocer relaciones. En el próximo capítulo veremos por qué algunas líneas están desplazadas, qué significa el guion y cómo distinguir una lista de un mapa. A partir de ahí podrás enfrentarte a ejemplos que nunca habías visto y, al menos, identificar sus piezas.

Antes de modificar: una rutina de trabajo segura

YAML no es peligroso por sí mismo, pero un cambio en la configuración puede impedir que una integración se cargue o hacer que una automatización se comporte de forma distinta. Trabajar con tranquilidad depende más del método que de la experiencia.

Conserva una forma de volver atrás

Antes de modificar archivos importantes, crea una copia de seguridad adecuada para tu tipo de instalación. Si estás editando un único bloque desde la interfaz, también puede ser útil conservar una copia del YAML original en un archivo temporal. La finalidad es poder comparar y restaurar, no acumular copias sin saber cuál es la buena.

Cambia una cosa cada vez

Si sustituyes una entidad, reorganizas la indentación y añades una condición al mismo tiempo, un fallo posterior tiene tres posibles causas. Si haces un cambio pequeño y lo pruebas, la causa queda mucho más acotada.

Identifica dónde debe pegarse el ejemplo

Un bloque puede tener una forma distinta según se coloque en el editor YAML de una automatización, dentro de automations.yaml o bajo una clave de configuration.yaml. Antes de pegar, busca siempre qué contexto describe el autor.

Valida antes de reiniciar

Cuando una modificación afecta archivos de configuración, utiliza la comprobación de Home Assistant antes de reiniciar. Una validación correcta no garantiza que la lógica haga exactamente lo que deseas, pero evita reiniciar con muchos errores estructurales.

No compartas secretos para pedir ayuda

Tokens, contraseñas, URL privadas, identificadores de webhook y datos de localización no son necesarios para explicar la mayoría de errores. Sustitúyelos por valores ficticios antes de pegar una configuración en un foro o enviarla a una IA.

La casa virtual que utilizaremos

Dos personas pueden tener una luz equivalente y, sin embargo, identificadores completamente distintos. En una instalación podría llamarse light.salon; en otra, light.lampara_sofa. Si cada alumno adapta todos los ejemplos desde el primer minuto, resulta difícil distinguir un error del curso de un identificador sustituido incorrectamente.

Por eso utilizaremos una pequeña casa virtual. El laboratorio crea estas entidades principales:

light.course_living_room
binary_sensor.course_front_door
sensor.course_living_room_temperature
binary_sensor.course_hallway_motion
switch.course_fan
binary_sensor.course_someone_home
binary_sensor.course_night

No están conectadas a dispositivos físicos. Unos controles internos permiten abrir o cerrar la puerta, simular movimiento, cambiar la temperatura, indicar si hay alguien en casa y activar un modo nocturno. La luz y el ventilador también son virtuales, pero responden a las mismas clases de acciones que utilizaremos en los ejemplos.

El laboratorio tiene dos ventajas. Primero, todo el mundo observa el mismo resultado. Segundo, puedes provocar situaciones deliberadamente —por ejemplo, abrir la puerta cinco veces— sin recorrer la casa ni esperar a que cambie un sensor real.

El archivo del simulador contiene algunas plantillas que todavía no conoces. No tienes que estudiarlas ahora. Es parecido a utilizar un sensor comprado sin desmontar su electrónica: necesitamos su comportamiento, no comprender todavía cómo está fabricado. En los capítulos sobre Jinja y organización volveremos al mismo archivo y entonces sí podrás leerlo.

El archivo descargable contiene el package y una guía de instalación paso a paso. No sustituyas tu configuración por un archivo completo del curso. Si prefieres trabajar con tus dispositivos, también podrás hacerlo reemplazando los identificadores, pero deberás comprobar cada equivalencia.

Primera comprobación del laboratorio

Después de instalarlo y validar la configuración, abre Configuración → Herramientas → Estados y busca binary_sensor.course_front_door. A continuación localiza el control input_boolean.course_front_door_open.

Activa el control. El sensor de puerta debería pasar a abierto. Desactívalo y debería volver a cerrado. Home Assistant puede mostrar palabras como «Abierto» y «Cerrado» en la interfaz debido a la clase de dispositivo, aunque el estado interno que utilizaremos en YAML sea "on" o "off". Esta diferencia entre presentación y estado interno será importante en el capítulo 3.

Haz la misma comprobación con la temperatura: cambia input_number.course_living_room_temperature y verifica que sensor.course_living_room_temperature recibe el nuevo valor.

Si una entidad no aparece, no continúes copiando ejemplos. Revisa primero la validación, el nombre del archivo y la configuración de packages indicada en la guía del laboratorio. Resolver el escenario de práctica ahora evitará falsos errores durante los capítulos siguientes.

Un primer error que conviene reconocer

Observa este objetivo:

target:
  entity_id: Luz del salón

«Luz del salón» puede ser el nombre que ves en una tarjeta, pero no es un identificador de entidad. Home Assistant necesita un valor con dominio y nombre interno, por ejemplo:

target:
  entity_id: light.course_living_room

La diferencia no pertenece a la sintaxis de YAML: ambos valores son texto válido. El problema es que Home Assistant intenta encontrar una entidad con el identificador recibido. Este es nuestro primer ejemplo de YAML correctamente escrito que, aun así, no representa una configuración válida para la acción deseada.

Guarda esta idea: que un bloque sea YAML válido no significa que Home Assistant pueda ejecutarlo ni que haga lo que esperas.

Ejercicio: decide qué herramienta necesitas

Para cada situación, decide cuál sería el primer paso más razonable: utilizar la interfaz, leer YAML o editar YAML. Puede haber más de una respuesta válida, pero debes justificarla.

1. Quieres añadir una integración que ofrece un asistente completo desde Configuración.
2. Has descargado una automatización y quieres comprobar qué entidades controla antes de importarla.
3. Una automatización funciona, pero apunta a la luz equivocada.
4. Home Assistant muestra un error que menciona una tabulación en una línea concreta.
5. Quieres dividir una configuración manual que ha crecido durante varios años.

Después localiza en tu laboratorio las siete entidades principales y cambia al menos dos controles internos. No intentes crear todavía la automatización de la puerta: la construiremos con su estructura completa cuando dispongas de las herramientas necesarias.

Qué debes llevarte de este capítulo

YAML es una manera de representar datos estructurados. Home Assistant define qué significan claves como triggers o actions y ejecuta el comportamiento. La interfaz y YAML no compiten: puedes construir desde una y comprender o ajustar desde la otra.

No necesitas aprender YAML genérico para docenas de plataformas. Necesitas reconocer un conjunto relativamente pequeño de estructuras, entender dónde se utilizan dentro de Home Assistant y adquirir un método seguro para modificar y diagnosticar.

En el siguiente capítulo dejaremos de mirar YAML como un bloque completo. Lo desmontaremos en claves, valores, listas y mapas hasta que la indentación deje de parecer una cuestión estética y empiece a mostrarte, de un vistazo, qué pertenece a qué.

Continúa leyendo

Siguiente guía relacionada · 9 min de lectura

Curso de YAML para Home Assistant desde cero

Puedes utilizar Home Assistant durante mucho tiempo sin escribir YAML a mano. La interfaz permite instalar integraciones, crear automatizaciones y configurar gran parte de…

Continuar con este artículo↓