ESPHome: guía completa en español para empezar

Borrador editorial: comprobar nombres de componentes y sintaxis contra la versión de ESPHome usada al publicar. El YAML de ejemplo no contiene secretos.

Qué es ESPHome

ESPHome es un sistema para convertir microcontroladores compatibles, como un ESP32, en dispositivos de domótica mediante archivos YAML. En vez de escribir todo el firmware en C++, describes la placa, la red y los sensores; ESPHome genera el firmware y lo instala en el dispositivo.

El resultado no es una aplicación que se ejecuta solo en el ordenador. El firmware queda en la placa y puede seguir leyendo sensores y ejecutando algunas acciones aunque Home Assistant no esté disponible. Home Assistant añade el panel, el histórico y las automatizaciones centralizadas cuando conectas el dispositivo por la API nativa de ESPHome.

Qué necesitas

• Una placa compatible, normalmente un ESP32 para el primer proyecto.
• Un cable USB de datos y una fuente estable.
• Un ordenador o una instalación de Home Assistant donde ejecutar ESPHome.
• Una red WiFi compatible con la placa.
• El sensor o actuador que quieras añadir, junto con su ficha técnica.

La guía de ESP32 para principiantes explica cómo elegir la placa y evitar errores de alimentación. No conectes el sensor antes de saber qué tensión y qué pinout necesita.

Formas de instalar ESPHome

ESPHome se puede utilizar desde el Device Builder integrado en Home Assistant, desde la línea de comandos o mediante un contenedor. La opción más simple depende de tu instalación:

Consulta la documentación oficial de ESPHome para confirmar los pasos de instalación y los cambios de la versión actual.

Crear la primera configuración

Empieza por un dispositivo pequeño con un nombre corto y estable. Un archivo mínimo puede tener esta estructura:

esphome:
  name: sensor-prueba
  friendly_name: Sensor de prueba

esp32:
  board: esp32dev

logger:

api:
  encryption:
    key: !secret api_encryption_key

ota:
  - platform: esphome
    password: !secret ota_password

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

El valor de board es solo un ejemplo. Debe corresponder a la placa real; dos placas con un ESP32 parecido pueden tener pines, memoria o periféricos distintos. Las claves de secrets.yaml se quedan en tu instalación local y no deben copiarse a un repositorio público.

Añadir un sensor

Después de comprobar que la configuración mínima compila, añade un componente. Por ejemplo, un DHT22 puede declararse así:

sensor:
  - platform: dht
    pin: GPIO4
    model: DHT22
    temperature:
      name: "Temperatura"
    humidity:
      name: "Humedad"
    update_interval: 30s

La configuración debe coincidir con el hardware: modelo, GPIO, alimentación y frecuencia de lectura. La comparativa DHT11 frente a DHT22 explica por qué el intervalo y el cableado importan. Si utilizas otro sensor, busca su componente en la documentación oficial y empieza con el ejemplo más pequeño posible.

Compilar e instalar

El flujo normal tiene cuatro pasos:

1. Validar la configuración. ESPHome analiza el YAML y avisa de errores de sintaxis, componentes incompatibles o campos ausentes.
2. Compilar el firmware. La primera compilación puede tardar más porque descarga herramientas y dependencias.
3. Instalar por USB. Para el primer flasheo suele ser la opción más fiable. Mantén la placa conectada y no interrumpas la alimentación.
4. Actualizar por OTA. Cuando el dispositivo ya está en la red puedes usar actualizaciones inalámbricas, pero conserva siempre una forma de recuperarlo por cable.

No desconectes la placa durante una actualización. Si un firmware incompleto impide el arranque, normalmente tendrás que volver a instalarlo por USB y revisar los logs de compilación.

Conectar ESPHome con Home Assistant

Cuando el dispositivo arranca y se conecta a la red, Home Assistant suele detectar la integración de ESPHome. Añádela desde el panel de dispositivos, comprueba la dirección del dispositivo y acepta la clave de cifrado configurada.

Después revisa que las entidades tengan nombres claros y que sus unidades sean correctas. Un sensor llamado sensor_1 puede funcionar, pero complica el panel cuando tengas diez dispositivos. También conviene asignar un área, como salón, terraza o taller.

Cómo depurar problemas

• Error de compilación: lee la primera línea que señala un archivo o campo, no solo el último mensaje. Comprueba la documentación de la versión instalada.
• La placa no aparece por USB: cambia el cable, revisa el puerto y prueba el botón BOOT si el modelo lo necesita.
• No conecta al WiFi: verifica SSID, contraseña, cobertura y compatibilidad de la red. No todas las placas trabajan con las mismas bandas.
• Home Assistant no detecta el dispositivo: comprueba que ambos están en redes que pueden comunicarse y que la API está configurada.
• Sensor NaN o sin valores: revisa alimentación, GPIO, modelo, pull-up y frecuencia de lectura antes de cambiar todo el firmware.
• Fallo después de OTA: conecta por USB, recupera una configuración mínima y vuelve a añadir componentes uno a uno.

Seguridad y mantenimiento

No publiques las credenciales WiFi, claves de API ni contraseñas OTA. Usa secrets.yaml y un gestor de contraseñas para conservar una copia. Mantén ESPHome y Home Assistant actualizados, pero no actualices todos los dispositivos sin revisar antes la compatibilidad del cambio.

El acceso remoto no debe consistir en abrir sin más el puerto de la API en el router. Si necesitas acceder desde fuera de casa, utiliza un método de acceso documentado y aplica autenticación fuerte.

Siguiente paso

Empieza con un solo ESP32 y un sensor de temperatura. Cuando la lectura sea estable, crea una automatización sencilla en Home Assistant, como un aviso si la temperatura supera un límite. Esa prueba te enseñará más que preparar desde el primer día un sistema con muchos dispositivos y reglas difíciles de depurar.