Dominando YAML en Home Assistant: Guía de Packages y Organización

Todos empezamos igual en Home Assistant. Instalas el sistema, abres tu archivo configuration.yaml y escribes tus primeras tres líneas de código para un sensor. Todo se ve limpio, ordenado y bajo control.

Pero seis meses después, la realidad es muy distinta. Tienes cientos de líneas, integraciones de sensores ESPHome, scripts que no recuerdas qué hacen y comentarios perdidos. Cada vez que quieres cambiar algo, te pasas 5 minutos haciendo scroll arriba y abajo con miedo a tocar lo que no debes.

Si te sientes identificado, tenemos la cura. Hoy vamos a dejar de usar el método básico de cortar y pegar para pasar al nivel profesional: los Packages (Paquetes). Es hora de dominar YAML.

El Caos del Monolito: ¿Por qué tu configuration.yaml es un desastre?

En el mundo del desarrollo de software, un «Monolito» es un programa donde todo el código está mezclado en un solo bloque gigante. Es difícil de leer, difícil de mantener y muy fácil de romper.

Por defecto, Home Assistant te empuja a crear un monolito. Todo va al configuration.yaml. Al principio es cómodo, pero escala fatal.

La evolución natural: De la instalación limpia al «Scroll infinito»

El ciclo de vida de un usuario de Home Assistant suele ser este:

1. Fase Luna de Miel: Tienes 50 líneas de código. Sabes dónde está cada coma.
2. Fase de Expansión: Empiezas a añadir sensores de temperatura y enchufes. El archivo crece a 500 líneas. Usas Ctrl+F para buscar cosas.
3. Fase de Pánico: Integras alarmas, riego y automatizaciones complejas. El archivo supera las 2.000 líneas. Te da pereza añadir cosas nuevas solo por no tener que abrir ese archivo infernal. Aquí es donde muchos abandonan o se pasan a la interfaz gráfica por desesperación.

!include vs. Packages: Entendiendo la diferencia fundamental

Home Assistant ofrece dos formas de dividir archivos. La mayoría de la gente conoce la primera, pero la segunda es la que realmente cambia las reglas del juego. Para entenderlo, consulta la documentación oficial sobre Packages, pero aquí te lo resumimos en cristiano.

La limitación de dividir por dominio (sensors.yaml, switches.yaml)

Seguro que has visto esto en tu configuración:

sensor: !include sensors.yaml
switch: !include switches.yaml
automation: !include automations.yaml

Esto usa la función !include. Separa los archivos por TIPO de entidad (Dominio).

El problema es que tu casa no funciona por tipos, funciona por PROYECTOS.

Imagínate que quieres modificar tu sistema de «Riego Inteligente». Con este método clásico, tienes que:

1. Abrir sensors.yaml para tocar el sensor de humedad.
2. Abrir switches.yaml para tocar la electroválvula.
3. Abrir automations.yaml para cambiar la hora de riego.

Tienes que tener 3 pestañas abiertas y saltar de una a otra. Es fragmentado y mentalmente agotador.

La solución: Agrupar por funcionalidad o proyecto

Aquí es donde entran los Packages. Esta funcionalidad te permite agrupar todo lo relacionado con un proyecto en UN SOLO ARCHIVO, sin importar si son sensores, luces o automatizaciones.

Con Packages, creas un archivo llamado riego_jardin.yaml y dentro metes:

• Los sensores de humedad.
• Los interruptores de las válvulas.
• Los temporizadores (input_datetime).
• Las automatizaciones de regar.

Todo junto. Todo ordenado. Si mañana quieres borrar el sistema de riego, borras ese único archivo y listo. No quedan restos de código basura en tu sistema. Es la diferencia entre tener un cajón de sastre revuelto y tener cajas etiquetadas.

Fundamentos de YAML y Estructura de Carpetas

Antes de escribir código, necesitamos preparar el contenedor. YAML es un lenguaje sensible: un espacio de más o un tabulador en lugar de espacios pueden hacer que tu casa deje de funcionar. Pero no te asustes, con un par de reglas básicas, es muy dócil.

Preparando el terreno: Habilitando Packages en Home Assistant

Por defecto, Home Assistant no busca paquetes. Tienes que decirle explícitamente: «Oye, mira dentro de esta carpeta».

El bloque de código mágico para tu configuración principal

Abre tu archivo configuration.yaml (el principal) y busca la sección homeassistant:. Si no la tienes, créala al principio del archivo. Debes añadir estas líneas:

homeassistant:
  packages: !include_dir_named packages

¿Qué acabas de hacer?

1. Le has dicho al sistema que active la función packages.
2. Le has dicho que busque una carpeta llamada packages en tu directorio raíz.
3. Le has dicho (con !include_dir_named) que lea todos los archivos YAML que encuentre dentro de esa carpeta y sus subcarpetas.

Ahora, crea una carpeta nueva llamada packages al mismo nivel que tu configuration.yaml. Ahí es donde ocurrirá la magia.

Anatomía de un Package

Un archivo «Package» no tiene nada de especial. Es simplemente un mini-configuration.yaml. La diferencia es que su contenido se «fusionará» con la configuración principal al arrancar.

Imagina que creas el archivo /packages/salon/centro_multimedia.yaml. Dentro puedes poner:

# Archivo: packages/salon/centro_multimedia.yaml

# 1. Un interruptor para la tele
switch:
  - platform: wake_on_lan
    name: "TV Salón"
    mac: "AA:BB:CC:DD:EE:FF"

# 2. Un reproductor multimedia
media_player:
  - platform: universal
    name: "Cine en Casa"
    children:
      - media_player.tv_salon

# 3. Una automatización específica para esto
automation:
  - alias: "Modo Cine Automático"
    trigger:
      - platform: state
        entity_id: media_player.cine_en_casa
        to: "playing"
    action:
      - service: light.turn_off
        entity_id: light.salon_techo

¿Ves lo bonito que es? Tienes el interruptor, el reproductor y la automatización juntos en un solo archivo. Si mañana compras otra TV, borras este archivo y creas uno nuevo. Sin rastros.

Reglas de indentación y sintaxis crítica

YAML no usa llaves {} ni puntos y coma ;. Usa indentación (sangría). Esto significa que los espacios al principio de la línea definen qué pertenece a qué.

• Regla de Oro: Usa siempre 2 espacios por nivel. Nunca uses el tabulador (la tecla Tab), Home Assistant odia los tabuladores.
• Jerarquía:

  switch: (Nivel 0 – Padre)

  - platform: ... (Nivel 1 – Hijo, 2 espacios)

  name: ... (Nivel 2 – Nieto, 4 espacios)

El error más común: Duplicidad de claves de dominio

Dentro de UN mismo archivo package, no puedes repetir la clave principal (el dominio). Esto dará error:

# ❌ ESTO ESTÁ MAL (Dará error de configuración)
sensor:
  - platform: template
    ...

# ... código ...

sensor:  # ¡Error! Ya has declarado 'sensor' arriba en este mismo archivo
  - platform: mqtt
    ...

La forma correcta: Agrupa todo bajo una sola clave sensor: dentro de ese archivo.

# ✅ ESTO ESTÁ BIEN
sensor:
  - platform: template
    ...
  - platform: mqtt
    ...

Metodología de Organización: «El enfoque por Proyectos»

Ya sabes cómo crear los archivos, pero ¿qué debes meter dentro? Existen dos escuelas de pensamiento:

1. Por Habitación: salon.yaml, cocina.yaml. Ideal para luces y persianas.
2. Por Función (Proyecto): riego.yaml, solar.yaml, navidad.yaml. Ideal para sistemas complejos.

Nuestra recomendación es mezclar ambos. Usa archivos de habitación para lo básico y archivos de función para lo avanzado.

Cambio de Mentalidad: De «Tipos de dispositivo» a «Habitaciones o Funciones»

Olvídate de pensar en «Tengo un sensor». Empieza a pensar en «Tengo un problema que resolver».

Si tu objetivo es optimizar tus placas solares, no tiene sentido que la lógica esté dispersa. Cuando fallan los excedentes, no quieres buscar en automations.yaml (línea 4000) y luego en sensors.yaml (línea 200). Quieres abrir gestion_solar.yaml y ver todo el panorama de un vistazo.

Ejemplo Práctico: Creando el Package gestion_solar.yaml

Vamos a crear un paquete completo. Imagina que quieres que un enchufe se encienda cuando tus placas solares produzcan más de 2000W.

Integrando Sensores, Inputs y Automatizaciones en un solo archivo

Crea el archivo /packages/energia/gestion_solar.yaml y pega esto:

# --- 1. LOS SENSORES (Calculan el excedente) ---
template:
  - sensor:
      - name: "Excedente Solar Neto"
        unit_of_measurement: "W"
        state: >
          {{ (states('sensor.produccion_solar')|float(0)) - (states('sensor.consumo_casa')|float(0)) }}

# --- 2. LOS INPUTS (Tú defines el umbral desde el Dashboard) ---
input_number:
  umbral_activacion_calefactor:
    name: "Watts para encender calefactor"
    min: 500
    max: 3000
    step: 100
    icon: mdi:solar-power

# --- 3. LA LÓGICA (Actúa según los datos anteriores) ---
automation:
  - alias: "Solar - Encender Calefactor por Excedente"
    trigger:
      - platform: numeric_state
        entity_id: sensor.excedente_solar_neto
        above: input_number.umbral_activacion_calefactor
    condition:
      - condition: state
        entity_id: switch.calefactor_bano
        state: "off"
    action:
      - service: switch.turn_on
        entity_id: switch.calefactor_bano
      - service: notify.mobile_app
        data:
          message: "☀️ ¡Sol gratis! Encendiendo calefacción."

¿Ves la elegancia? Tienes el cálculo matemático (sensor), la configuración de usuario (input) y la acción (automation) visibles en una sola pantalla. Si quieres cambiar la lógica, está todo aquí.

Ventaja: Portabilidad y facilidad de compartir código

La mayor ventaja de este sistema es que tu código se vuelve modular. Si un amigo se compra una casa y pone placas solares, puedes enviarle tu archivo gestion_solar.yaml por WhatsApp.

Él solo tendrá que cambiar los nombres de sus sensores reales al principio del archivo, y toda tu lógica compleja funcionará en su casa al instante. Es así como la comunidad comparte «Blueprints» complejos en foros y GitHub.

Desventaja: Cómo manejar las IDs de las entidades

Hay un pequeño precio a pagar. Cuando defines un sensor en YAML sin especificar un unique_id, Home Assistant genera la ID basándose en el nombre (Name).

El problema: Si en el futuro entras en este archivo y cambias name: "Excedente Solar Neto" por name: "Sobra Solar", Home Assistant creará una entidad nueva y perderás el historial de la antigua.

La solución: Para entidades críticas, añade siempre la línea unique_id: mi_id_super_unico_solar_01 debajo del nombre. Así podrás cambiar el nombre visible las veces que quieras sin romper la base de datos.

Estrategias Avanzadas para Expertos en YAML

Si ya has migrado tus configuraciones a Packages, tu sistema está ordenado. Pero, ¿está optimizado? YAML es mucho más potente de lo que parece. Vamos a ver trucos que usan los programadores para escribir la mitad y hacer el doble.

Uso de !include dentro de Packages (Inception de archivos)

A veces, un proyecto es tan grande que incluso su propio archivo Package se vuelve inmanejable. Imagina un sistema de riego con 50 zonas. El archivo riego.yaml podría tener 2.000 líneas.

Cuándo es útil fragmentar un Package grande

Lo bueno de Home Assistant es que permite recursividad. Puedes usar !include dentro de un paquete.

Puedes tener tu archivo packages/jardin/riego_general.yaml y dentro hacer esto:

# packages/jardin/riego_general.yaml

# Las automatizaciones son tantas que las saco a otro archivo
automation: !include riego_automatizaciones.yaml
script: !include riego_scripts.yaml

# Los sensores son pocos, los dejo aquí
sensor:
  - platform: template
    ...

Esto mantiene la estructura lógica del proyecto, pero limpia el archivo principal. Es como tener carpetas dentro de carpetas en tu escritorio.

Optimizando con Anclas y Referencias (& y *)

Este es el truco definitivo. En programación existe el principio DRY (Don’t Repeat Yourself) o «No te repitas».

Imagina que tienes 5 notificaciones distintas que envían el mismo mensaje al mismo móvil con los mismos parámetros. ¿Vas a copiar y pegar esas 10 líneas 5 veces? No.

Reduciendo código repetitivo (DRY – Don’t Repeat Yourself)

YAML permite definir un bloque de código una vez (Ancla &) y pegarlo virtualmente en otro sitio (Referencia *).

Ejemplo práctico: Configuración de nodos repetitiva

# Definimos la configuración común UNA vez y le ponemos nombre (mi_config_luz)
light:
  - platform: mqtt
    name: "Luz Salón"
    command_topic: "home/salon/switch"
    <<: &mi_config_luz  # Aquí creamos el ancla
      qos: 1
      payload_on: "ON"
      payload_off: "OFF"
      retain: true

  - platform: mqtt
    name: "Luz Cocina"
    command_topic: "home/cocina/switch"
    <<: *mi_config_luz # ¡MAGIA! Esto inyecta las 4 líneas de arriba automáticamente

Si mañana decides cambiar qos: 1 a qos: 2, solo lo cambias en el ancla y se actualiza en todas las luces que usen la referencia.

Limitaciones de las anclas entre diferentes archivos

⚠️ Advertencia Crítica: Las anclas YAML solo funcionan dentro del mismo archivo. No puedes definir un ancla en luces.yaml e intentar usarla en enchufes.yaml. El sistema fallará al validar. Esta es la razón principal por la que los usuarios avanzados prefieren tener archivos Package un poco más largos en lugar de fragmentarlos demasiado: para poder reutilizar el código.

La sección customize: dentro de Packages

Normalmente, para cambiar el icono de un sensor o su nombre amigable, vas al archivo customize.yaml global. Esto rompe la filosofía de «Proyecto Único», porque tienes la lógica en un sitio y la cosmética en otro.

Asignando iconos y nombres amigables localmente

Poca gente sabe que puedes invocar el bloque homeassistant: dentro de un paquete para personalizar entidades in situ.

Esto es especialmente útil cuando integras dispositivos DIY siguiendo nuestra guía de sensores ESPHome, ya que a menudo vienen con iconos genéricos.

# packages/bano/calefaccion.yaml

# Definimos el sensor
sensor:
  - platform: template
    name: "Temp Baño Real"
    id: sensor.temp_bano_real_raw
    ...

# Lo "maquillamos" en el mismo archivo
homeassistant:
  customize:
    sensor.temp_bano_real_raw:
      friendly_name: "Temperatura Espejo"
      icon: mdi:thermometer-water

Ahora, si borras el archivo calefaccion.yaml, también se borran sus personalizaciones. Limpieza absoluta.

Mantenimiento y Depuración (Debugging)

Dividir tu configuración en Packages es maravilloso para el orden, pero añade una capa de complejidad al mantenimiento. Si tienes un error de sintaxis en la línea 40 del archivo riego.yaml, Home Assistant podría negarse a arrancar.

Aquí aprenderás a blindar tu sistema contra errores humanos y a mantener tu carpeta de packages tan limpia como el primer día.

Cómo detectar errores antes de reiniciar

La regla de oro de Home Assistant es: «Nunca reinicies sin validar». Ignorar esto es la causa número 1 de foros llenos de gente pidiendo ayuda porque su servidor no responde.

Validación de configuración y logs específicos

Antes de aplicar cambios, ve siempre a Herramientas para desarrolladores > YAML > Verificar configuración.

Si usas Packages, los mensajes de error cambian ligeramente:

• Error genérico: A veces te dirá «Error loading /config/configuration.yaml». No entres en pánico. Esto suele significar que el error está en UN paquete que se carga desde ahí.
• Error específico: Si el validador es capaz de leer el archivo, te dirá: «Package riego_jardin setup failed. Component automation…». Esto te confirma que el problema está aislado en ese archivo concreto.

Organización física: Subcarpetas y nomenclatura de archivos

Una carpeta packages con 50 archivos sueltos es igual de mala que un archivo monolítico. Necesitas una jerarquía visual.

Recuerda que usamos !include_dir_named packages. Esto significa que Home Assistant buscará archivos YAML recursivamente, incluso dentro de subcarpetas. Úsalo a tu favor.

Ordenando alfabéticamente vs. Numéricamente (01_sistema.yaml)

Los exploradores de archivos (y tu cerebro) ordenan alfabéticamente. Si tienes archivos llamados alarma.yaml y zigbee.yaml, estarán en puntas opuestas de la lista, aunque ambos sean sistemas críticos.

Recomendamos usar un sistema de prefijos numéricos para agrupar por importancia:

• 00_globals.yaml: Variables globales, Inputs que usa toda la casa.
• 01_system.yaml: Configuración de grabadoras, logs y base de datos.
• 10_energy.yaml: SAI, Placas solares, medidores Shelly.
• 20_lighting.yaml: Luces y escenas.
• 99_testing.yaml: El cajón de arena para pruebas. Si algo falla, sabes que probablemente sea el último archivo que tocaste (el 99).

Este sistema hace que, al abrir tu editor de código (VS Code), veas primero lo crítico y al final lo experimental, evitando cambios accidentales en el núcleo de tu sistema.

Conclusión: Tu Home Assistant, ahora profesional

Has pasado de tener un archivo configuration.yaml de 2.000 líneas que te daba miedo tocar, a tener una estructura modular, limpia y profesional. Ahora, cuando quieras mejorar tu sistema de calefacción, no tendrás que bucear en un mar de código; irás directo a calefaccion.yaml.

Adoptar el sistema de Packages no es solo una cuestión estética; es una cuestión de salud mental y estabilidad. Es el paso que separa a los usuarios que «juegan» con la domótica de los que «administran» un sistema inteligente.

---

Preguntas Frecuentes (FAQ)

¿Tengo que reiniciar Home Assistant cada vez que toco un Package?

Depende. Si creas un archivo nuevo o cambias el nombre de uno existente, SÍ necesitas un reinicio completo del servidor. Si solo modificas el código dentro de un archivo que ya existía (ej: cambias una automatización en riego.yaml), basta con ir a «Herramientas para desarrolladores» y pulsar «Recargar toda la configuración YAML».

¿Puedo mezclar el método antiguo con Packages?

¡Sí! Puedes mantener tu sensor: !include sensors.yaml para cosas genéricas y usar la carpeta packages/ para tus proyectos específicos. Home Assistant cargará ambas cosas y las fusionará en memoria. Es una buena estrategia de transición para no tener que migrar todo en una tarde.

¿Matter y Thread eliminarán la necesidad de YAML?

El nuevo estándar promete facilitar la integración de dispositivos, como explicamos en nuestra guía técnica sobre Matter. Sin embargo, para lógica personalizada compleja (automatizaciones avanzadas, sensores template, cálculos matemáticos), YAML seguirá siendo el rey durante muchos años.

He borrado un archivo Package pero las entidades siguen ahí. ¿Por qué?

Si borras el archivo y reinicias, las entidades aparecerán como «No disponibles» o con un icono de advertencia. Tienes que ir a Ajustes > Dispositivos y Servicios > Entidades, buscar las que tienen el símbolo de «Restaurada» (rojo) y eliminarlas manualmente de la base de datos.

¿Te ha sido útil? ¡Compártelo con otros!

WhatsApp Facebook X (Twitter) Telegram

Únete a la Comunidad

Síguenos en nuestras redes para ver tutoriales en vídeo, ideas de decoración y trucos rápidos para tu hogar inteligente.