Primeros pasos con ESPHome

Qué es ESPHome

Describes el dispositivo en un archivo YAML: qué placa, qué sensores en qué pines y cómo se conecta a tu red. ESPHome convierte esa descripción en firmware, lo compila y lo graba en la placa. Después, Home Assistant se comunica con el dispositivo mediante la API nativa de ESPHome, una conexión directa por el puerto TCP 6053 que se puede cifrar con una clave de 32 bytes.

Para lo habitual no hay que escribir código. Cuando cambias el YAML, vuelves a instalar y el dispositivo pasa a usar el nuevo firmware.

Instalar ESPHome

La herramienta con la que trabajas se llama ESPHome Device Builder: un panel web que guarda tus archivos YAML, los compila e instala el firmware. Elige cómo ejecutarlo:

• En Home Assistant. Ve a Configuración → Aplicaciones → Instalar aplicación (Home Assistant llama ahora «aplicaciones» a sus complementos), busca ESPHome Device Builder y pulsa Instalar, Iniciar y Open Web UI. Si no aparece, añade el repositorio https://github.com/esphome/home-assistant-addon desde el menú ⋮.
• Como app de escritorio. La página de instalación ofrece ESPHome Device Builder para macOS (un .dmg), para Windows y para Linux (un .deb o un AppImage). En Linux, si no aparecen los puertos serie, añade tu usuario al grupo dialout.
• En Docker. El mismo panel escucha en el puerto 6052. Arranca el contenedor con la red del host (--net=host) para que encuentre los dispositivos por mDNS; con Docker Desktop, publica el puerto 6052.
• Desde la línea de comandos. Instala con pip install esphome (en un entorno virtual si puedes) y luego usa esphome run salon.yaml, que valida, compila, graba y muestra el registro en un solo paso.

Para la primera grabación también puedes usar ESPHome Web, en web.esphome.io, que graba el firmware en la placa desde el navegador. Necesita Web Serial: Chrome, Edge y, según la documentación de ESP Web Tools, Firefox; no funciona en iOS.

Elegir la placa

Sirve cualquier placa de desarrollo con ESP32 o ESP8266. Estas cuatro son comunes, baratas y están bien soportadas; el identificador de la placa es lo que va en el YAML.

Identificadores comprobados con esphome config en ESPHome 2026.10.2. Nuestra comparativa ESP32 recoge las diferencias entre los chips.

Si dudas, empieza con un ESP32 DevKit: es el de esta guía, y la mayoría de las respuestas que encontrarás en internet dan por hecho que lo usas.

Una primera configuración, línea a línea

En el Device Builder, Create device abre un asistente que escribe casi todo por ti. Este es el archivo completo de un dispositivo llamado salon, antes de añadir sensores:

esphome:
  name: salon                  # nombre de host: minúsculas, cifras, guiones
  friendly_name: Salón         # el nombre que muestra Home Assistant

esp32:
  board: esp32dev              # tu placa
  framework:
    type: esp-idf              # el predeterminado desde 2026.1

logger:                        # registro por USB y Wi-Fi

api:                           # la conexión con Home Assistant
  encryption:
    key: !secret api_key

ota:
  - platform: esphome          # actualizaciones por Wi-Fi
    encryption:                # reutiliza la clave de la API

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  ap:                          # punto de acceso de reserva
    password: !secret ap_password

captive_portal:                # su página

• esphome: → name es el nombre de host en tu red, salon.local: hasta 31 caracteres, letras minúsculas, cifras y guiones. friendly_name es lo que muestra Home Assistant.
• esp32: → board le indica a ESPHome el chip y el tamaño de la flash. Desde ESPHome 2026.1 el framework predeterminado en el ESP32 es ESP-IDF; indicarlo de forma explícita deja el archivo más claro. Arduino sigue soportado con type: arduino.
• logger: → el registro por USB y por la red, por defecto en nivel DEBUG y a 115200 baudios.
• api: → la API nativa que usa Home Assistant, con su clave de cifrado. Sin clave, la conexión no va cifrada.
• ota: → las actualizaciones por Wi-Fi. Desde ESPHome 2026.9, un encryption: vacío las cifra con la clave de la API.
• wifi: → tu red, leída de secrets.yaml. ap: activa un punto de acceso de reserva, con el nombre del dispositivo, si este no consigue conectarse en 90 segundos.
• captive_portal: → una página en ese punto de acceso donde introducir los nuevos datos del Wi-Fi.

Los valores !secret salen de un segundo archivo, secrets.yaml, en la misma carpeta:

wifi_ssid: "MyNetwork"
wifi_password: "MyWiFiPassword"
api_key: "…"                   # openssl rand -base64 32
ap_password: "…"

La clave de la API son 32 bytes aleatorios en base64: la crea el asistente, o puedes generarla con el comando del comentario. No publiques nunca secrets.yaml.

Un primer sensor: BME280 por I²C

El BME280 mide temperatura, humedad y presión y se comunica por I²C, así que le bastan dos cables de señal. En un ESP32 DevKit, los pines I²C que ESPHome suele usar son GPIO21 para SDA y GPIO22 para SCL.

Añade esto al final del archivo:

i2c:
  sda: GPIO21
  scl: GPIO22
  scan: true                   # lista las direcciones que encuentra

sensor:
  - platform: bme280_i2c
    address: 0x76              # o 0x77, mira el registro
    temperature:
      name: Temperatura
    pressure:
      name: Presión
    humidity:
      name: Humedad
    update_interval: 60s

• i2c: → el bus y sus pines. scan: true, el valor predeterminado, escribe en el registro las direcciones que encuentra.
• platform: bme280_i2c → el controlador del BME280. Su dirección predeterminada es 0x77; muchas placas baratas responden en 0x76, como aquí. Nuestra página sobre la dirección del BME280 explica cómo se elige una u otra con el pin SDO.
• Cada medida lleva un name, que se convierte en una entidad de Home Assistant. update_interval: 60s lee el sensor una vez por minuto.

¿Prefieres hacer clic? Nuestro generador crea un archivo equivalente, con este BME280 ya añadido, y te prepara las claves. Pone la clave de la API directamente en el archivo, no en secrets.yaml, y añade sensores de señal Wi-Fi y de tiempo encendido.Abrir el generador de ESPHome

¿Quieres otro sensor? Nuestra comparativa de sensores compara los más comunes, del DHT22 a los SHT4x.

Grabar el firmware: primero por USB, luego por Wi-Fi

La primera instalación tiene que hacerse con un cable USB. En el Device Builder, pulsa Install en la tarjeta del dispositivo y elige cómo:

• Plug into this computer graba desde tu navegador. Usa Web Serial, que necesita una página segura: el panel abierto por HTTPS, o en localhost, como con la app de escritorio.
• Plug into the computer running ESPHome Device Builder graba desde el equipo en el que corre el panel, por ejemplo tu servidor de Home Assistant.
• Manual download y después Factory format te dan un archivo .bin que grabas con ESPHome Web: Connect, eliges el puerto, Install.

Desde la línea de comandos, esphome run salon.yaml te pregunta qué puerto serie usar. Si no aparece ninguno:

• Prueba otro cable USB: los que solo cargan no llevan los hilos de datos.
• Instala el controlador del chip USB-serie de la placa, normalmente un CH34x o un CP2102.
• Mantén pulsado el botón BOOT de la placa mientras la conectas y suéltalo después: así el chip arranca en modo de descarga.

En cuanto el dispositivo se une a tu Wi-Fi, cada Install posterior ofrece Wirelessly, y esphome run sube el firmware por la red.

Añadirlo a Home Assistant

Si el mDNS funciona en tu red, Home Assistant encuentra el dispositivo nuevo por sí solo. Ve a Configuración → Dispositivos y servicios: en el apartado Descubierto verás una tarjeta de ESPHome con su nombre. Pulsa Configurar, introduce la clave de cifrado cuando te la pida (si el Device Builder corre como app de Home Assistant, a menudo ya viene rellena) y elige un área.

Si no se descubre nada, pulsa Añadir integración, elige ESPHome e introduce salon.local o la dirección IP del dispositivo. Las tres medidas del sensor aparecen como entidades, listas para el panel.

Entre las opciones de la integración está la que permite al dispositivo ejecutar acciones de Home Assistant, desactivada por defecto. Actívala solo en dispositivos de confianza, y solo si tu YAML la necesita.

Leer el registro

El registro es donde aparece primero cualquier problema. En el Device Builder, Logs lo lee por USB si la placa está conectada y, si no, por la red; en la línea de comandos, esphome logs salon.yaml. Al conectarte, el dispositivo imprime su configuración, incluido el escaneo I²C:

[C][i2c:113]: Results from bus scan:
[C][i2c:119]: Found device at address 0x76

El número que sigue a i2c indica la línea del código fuente de ESPHome, así que cambia de una versión a otra. «Found no devices» indica un problema de cableado o de alimentación, no del YAML. Una lectura cada minuto, en las líneas [D], significa que el sensor funciona.

Errores comunes

Los pines de arranque deciden cómo se inicia el chip: un sensor o un LED que mantenga uno de ellos a nivel alto o bajo puede impedir que arranque.

Seguridad

• Cifrado de la API. Pon siempre una clave: sin ella, la conexión no va cifrada ni pide ninguna clave, y cualquier equipo de tu red puede conectarse.
• Actualizaciones cifradas. Con encryption: en ota: (ESPHome 2026.9 y posteriores), el dispositivo solo acepta firmware cifrado con tu clave. Las guías antiguas usan password:; ESPHome avisa ahora de que la contraseña gasta flash y RAM y recomienda el cifrado, y las dos opciones no se pueden combinar.
• Una contraseña en el punto de acceso de reserva. Su página permite a quien se conecte cambiar el Wi-Fi y subir un firmware.
• Mantén secrets.yaml en privado, y guarda una copia: sin la clave no podrás actualizar el dispositivo por Wi-Fi.

Mantenerlo al día

ESPHome publica una versión nueva cada mes. Actualizar el Device Builder (o pip install --upgrade esphome) no cambia tus dispositivos: cada uno sigue con el firmware que le instalaste hasta que vuelvas a pulsar Install. Lee antes los cambios incompatibles de las notas de la versión y actualiza un dispositivo antes que el resto.

Con batería: deep sleep

Un sensor que solo tiene que informar cada pocos minutos puede dormir entre medias con el componente deep_sleep:, que se ajusta con run_duration y sleep_duration. Mientras duerme, Home Assistant lo muestra como no disponible, y solo admite una actualización cuando está despierto. La elección de placa, batería y regulador, con consumos reales, está en nuestra guía para alimentar un ESP32 con batería.