Sustituciones y packages en ESPHome: guÃa prÃ¡ctica

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

Actualizado el 2 de agosto de 2026 para la sintaxis actual de ESPHome.

Cuando tienes varios dispositivos ESPHome, copiar el mismo Wi-Fi, la API, OTA y los sensores de diagnóstico en cada archivo termina siendo difícil de mantener. Las sustituciones de ESPHome y los packages permiten separar lo común de lo específico: corriges una sola vez el archivo base y reutilizas el cambio en todos tus nodos.

En esta guía aprenderás a usar substitutions, !include, packages locales y remotos, !extend, !remove y secrets.yaml. Todos los ejemplos utilizan la plataforma moderna esp32:, API cifrada y OTA en formato de lista. Si estás empezando, antes puede ayudarte mi explicación sobre qué es ESPHome.

Descargar ejemplos completos en ZIP

Qué son las sustituciones de ESPHome

Una sustitución es un valor reutilizable. ESPHome procesa el bloque superior substitutions: antes de validar el YAML y reemplaza cada aparición de $variable o ${variable}. Los nombres distinguen mayúsculas y minúsculas.

substitutions:
  device_name: office-climate
  friendly_name: "Clima del despacho"
  update_interval: 60s

esphome:
  name: ${device_name}
  friendly_name: ${friendly_name}

sensor:
  - platform: wifi_signal
    name: "Señal Wi-Fi"
    update_interval: ${update_interval}

Además de texto, las sustituciones actuales pueden contener números, booleanos, listas y diccionarios. También admiten expresiones Jinja dentro de ${...}. Eso permite mantener configuraciones genéricas sin recurrir a grandes bloques duplicados.

substitutions:
  device:
    name: "Tiempo activo"
    interval: 30
    diagnostics: true

sensor:
  - platform: uptime
    name: ${device.name}
    update_interval: ${device.interval}s
    disabled_by_default: ${not device.diagnostics}

Sustituciones desde la línea de comandos

La opción -s permite reemplazar valores sin editar el archivo. Es útil para validar una plantilla con diferentes nombres o placas. En la CLI actual, el comando va antes del archivo:

esphome -s device_name office-sensor -s board esp32dev config device-example.yaml

Los valores indicados en la línea de comandos tienen prioridad sobre los definidos en el YAML. Para instalar, cambia config por run, pero valida siempre primero.

Diferencias entre substitutions, !include y packages

Herramienta	Qué hace	Cuándo utilizarla
`substitutions`	Reemplaza valores	Nombres, pines, intervalos, placas y opciones
`!include`	Inserta otro archivo o fragmento	Automatizaciones, listas o secciones concretas
`packages`	Fusiona configuraciones completas	Wi-Fi, API, OTA, diagnósticos y bases comunes
`<<: !include`	Aplica la fusión YAML tradicional	Archivos base sencillos; no admite sustituciones en el nombre del archivo

Los packages se fusionan de forma no destructiva. Los diccionarios se combinan clave por clave, los componentes con id pueden modificarse y las sustituciones del archivo principal prevalecen sobre las incluidas en un package.

Estructura recomendada de archivos

esphome/
├── device-example.yaml
├── secrets.yaml
└── packages/
    ├── base.yaml
    ├── wifi.yaml
    └── diagnostics.yaml

El archivo del dispositivo conserva únicamente sus valores y hardware particulares. En el ejemplo descargable se ve así:

substitutions:
  device_name: office-climate
  friendly_name: "Office Climate"
  board: esp32dev
  log_level: INFO
  wifi_ssid: !secret wifi_ssid
  wifi_password: !secret wifi_password
  fallback_password: !secret office_climate_fallback_password
  api_encryption_key: !secret office_climate_api_key
  ota_password: !secret office_climate_ota_password

packages:
  base: !include packages/base.yaml
  wifi: !include packages/wifi.yaml
  diagnostics: !include packages/diagnostics.yaml

Para un ESP8266, no vuelvas a colocar platform: ESP8266 dentro de esphome:. Sustituye el bloque de plataforma del package por uno superior como este:

esp8266:
  board: nodemcuv2
  restore_from_flash: false

Si necesitas elegir entre placas, consulta también mi guía del ESP32. Los tutoriales del BMP280, el DS18B20 y el sensor de lluvia MH-RD son buenos ejemplos de dispositivos que pueden compartir estos packages.

Package base con API cifrada y OTA actual

esphome:
  name: ${device_name}
  friendly_name: ${friendly_name}
  min_version: 2026.7.0

esp32:
  board: ${board}
  framework:
    type: esp-idf

logger:
  level: ${log_level}

api:
  encryption:
    key: ${api_encryption_key}

ota:
  - platform: esphome
    password: ${ota_password}

Este diseño evita guardar claves directamente en el package. Cada dispositivo obtiene su clave API y contraseña OTA desde secrets.yaml. Deben ser únicas; no reutilices una misma clave en toda la casa. Encontrarás más recomendaciones generales en mi guía para proteger contraseñas con secrets.yaml.

Personalizar un package con !extend y !remove

Cuando un componente del package tiene id, puedes modificarlo desde el archivo principal sin copiarlo entero. El package descargable crea uptime_sensor con una actualización cada 60 segundos; este fragmento la cambia a 30 segundos:

sensor:
  - id: !extend uptime_sensor
    update_interval: 30s

Para eliminarlo por completo:

sensor:
  - id: !remove uptime_sensor

También puedes retirar una sección completa con captive_portal: !remove. Estas operaciones hacen que un package común siga siendo flexible sin mantener varias copias casi idénticas.

Packages remotos desde Git

ESPHome puede descargar uno o varios archivos desde GitHub, GitLab o Codeberg. Conviene fijar ref a una versión o commit revisado; seguir siempre main permite que un cambio remoto llegue a tu siguiente compilación sin previo aviso.

packages:
  remote_base:
    url: https://github.com/OWNER/REPOSITORY
    ref: v1.0.0
    files:
      - packages/base.yaml
    refresh: 1d

Un package remoto no puede leer directamente tus valores !secret. Debe declarar sustituciones con valores predeterminados y el archivo local debe proporcionar los secretos. Revisa siempre el código remoto antes de compilarlo.

Cómo compartir los secretos de Home Assistant

La opción más sencilla es mantener un secrets.yaml dentro del directorio de ESPHome. Si quieres reutilizar el archivo superior de Home Assistant, el secrets.yaml de ESPHome puede contener:

<<: !include ../secrets.yaml

No publiques ese archivo, no lo incluyas en el ZIP y añádelo a .gitignore. El descargable proporciona únicamente secrets.example.yaml, con marcadores que debes reemplazar.

Errores frecuentes

Platform not found: coloca esp32: o esp8266: como bloque superior, nunca dentro de esphome:.
Substitution not found: comprueba el nombre y las mayúsculas; $device_name y $Device_Name son distintos.
Duplicate ID: dos packages han definido el mismo identificador. Elimina uno o usa !extend cuando quieras modificarlo.
Could not find file: las rutas de !include son relativas al archivo que realiza la inclusión.
Error con un package remoto: revisa URL, ruta, ref y que el repositorio sea accesible.
Clave API inválida: genera una clave base64 de 32 bytes desde ESPHome y no inventes una cadena cualquiera.

Antes de instalar, ejecuta siempre:

esphome config device-example.yaml

Vídeo original y capítulos

El vídeo conserva su valor para comprender la idea y el flujo de trabajo, pero fue grabado con una versión antigua. Utiliza el YAML actualizado de este artículo y del ZIP, no los bloques de plataforma que aparecen en pantalla.

Preguntas frecuentes

¿Están obsoletos los packages de ESPHome?

No. Los packages locales y remotos siguen soportados y ahora incluyen plantillas, variables, inclusiones condicionales, nombres dinámicos, !extend y !remove.

¿Qué diferencia hay entre una sustitución y un secret?

Una sustitución evita repetir un valor y puede ser pública. Un secret protege información sensible y vive fuera del archivo compartido. Un secret puede asignarse a una sustitución para pasarlo a un package.

¿Debo usar packages para un único dispositivo?

No es obligatorio. Resultan especialmente útiles cuando tienes varios nodos o bloques largos que quieres probar y mantener por separado.

Descarga y siguientes pasos

El ZIP incluye el archivo principal, tres packages, una plantilla de secretos, un ejemplo de package remoto y README en español e inglés. Sustituye los marcadores, valida la configuración y después añade el hardware específico de tu proyecto.

Descargar plantilla ESPHome

Documentación oficial consultada: substitutions, packages, API nativa, YAML y buenas prácticas de seguridad.

Si el proyecto te ha resultado útil, puedes suscribirte al canal de Tecnoyfoto para ver más ejemplos de ESPHome y Home Assistant.

Continúa leyendo