Cómo instalar ESPHome con Home Assistant — Guía completa

ESPHome es un framework de firmware de código abierto que le permite convertir microcontroladores comunes — como las placas ESP32, ESP8266 y RP2040 — en dispositivos inteligentes para el hogar totalmente controlables.

Una “configuración” de dispositivo en ESPHome está compuesta por uno o más archivos YAML. Basándose en estos archivos, ESPHome compila un firmware personalizado que puede instalar directamente en su dispositivo. Cualquier hardware definido en la configuración — sensores, interruptores, luces, etc. — aparecerá automáticamente en la interfaz de Home Assistant.

ESPHome tiene dos partes principales:

1. El firmware que se ejecuta en su microcontrolador.

2. La herramienta de gestión que se ejecuta en su computadora o servidor (por ejemplo, una Raspberry Pi, laptop o escritorio): en esta guía, usaremos el complemento ESPHome Device Builder para Home Assistant, que proporciona una interfaz web sencilla para crear, editar e instalar configuraciones.

1. Instalando el complemento ESPHome Device Builder

La forma más fácil de comenzar es instalar ESPHome como un complemento de Home Assistant.

Pasos:

1. En Home Assistant, vaya a Configuración → Tienda de complementos.

2. Search for ESPHome and click Install.

3. Espere a que la instalación termine (esto puede tomar uno o dos minutos).

4. Haga clic en Iniciar, luego en Abrir interfaz web para lanzar el Device Builder.

Nota: Si su instalación de Home Assistant no soporta complementos, puede ejecutar ESPHome Device Builder por separado en Docker.

2. Creando Su Primera Configuración

Cuando abras la interfaz web por primera vez, un asistente de configuración te guiará para crear tu primera configuración de dispositivo.

Necesitarás:

• Introduce un nombre de dispositivo (se recomienda minúsculas con guiones).

• Selecciona tu tipo de placa (por ejemplo, ESP32 DevKit v1).

• Proporciona tu SSID y contraseña de Wi‑Fi para que el dispositivo pueda conectarse a tu red después del flasheo.

Consejo: La primera instalación en un dispositivo nuevo suele ser el paso más intimidante. Si nunca lo has hecho antes, revisa la guía Conexión física a tu dispositivo.

3. Flasheando el firmware por primera vez

Después de crear tu configuración, necesitas instalarla en tu dispositivo:

1. Conecta tu placa al host de Home Assistant vía USB.

2. En ESPHome, haz clic en Instalar y elige la opción USB.

3. Una vez flasheado, el dispositivo se conectará a tu Wi‑Fi y se comunicará con Home Assistant.

4. Explorando la interfaz de Device Builder

La pantalla principal de ESPHome Device Builder lista todas tus configuraciones de dispositivos (“nodos”). Para cada configuración, puedes:

• Actualizar — si la versión de ESPHome del dispositivo es anterior a la versión del complemento.

• Editar — abre el editor de configuración YAML.

• Registros — visualiza los registros del dispositivo vía USB/serial o por Wi‑Fi.

• Menú de desbordamiento — accede a acciones adicionales:

  • Validar — verifica la configuración en busca de errores.

  • Instalar — abre el diálogo de instalación.

  • Limpiar archivos de compilación — eliminar archivos de compilación generados para solucionar problemas de compilación.

  • Eliminar — eliminar la configuración.

Nota: Los archivos de configuración se almacenan en <HOME_ASSISTANT_CONFIG>/esphome/. Acceder a ellos directamente puede requerir el complemento SSH y deshabilitar el “Modo de protección” — evalúe las implicaciones de seguridad antes de hacerlo.

5. Agregando Funcionalidad a Su Dispositivo

Ejemplo: Interruptor GPIO

Abra el archivo YAML de su dispositivo en el editor y agregue:

 
interruptor:
  - plataforma: gpio
    nombre: "Deshumidificador de la Sala"
    pin: GPIO5
  

Esto crea una entidad de interruptor en Home Assistant que controla lo que sea que esté conectado a GPIO5 — podría ser una luz, un ventilador o cualquier otro dispositivo.

En el ejemplo anterior, simplemente estamos agregando un interruptor llamado "Deshumidificador de la Sala" que está conectado al pin GPIO5. Este interruptor realmente podría controlar cualquier cosa: luces o un ventilador de mesa, por ejemplo. Su nombre y función son arbitrarios y deben establecerse según sea apropiado para su aplicación particular.

Ejemplo: Sensor Binario

Para monitorear el estado de un pin GPIO (por ejemplo, un sensor de contacto de ventana), agregue:

  - plataforma: gpio
    nombre: "Ventana de la Sala"
    pin:
      número: GPIO0
      invertido: true
      mode:
        input: true
        pullup: true
  

Después de editar, haz clic en Guardar para almacenar tus cambios.

6. Actualizando tu dispositivo

Guardar el archivo YAML no actualiza el dispositivo automáticamente. Cada vez que hagas cambios:

1. Haz clic en Instalar para recompilar el firmware.

2. Reinstálalo en el dispositivo.

Si ESPHome ya está instalado en el dispositivo, puedes actualizarlo de forma inalámbrica (OTA) sin reconectar el USB.

7. Conectando el dispositivo a Home Assistant

 AGREGAR INTEGRACIÓN A MI

Una vez que el dispositivo esté flasheado y conectado a Wi‑Fi:

• Home Assistant debería descubrirlo automáticamente (si tu red soporta mDNS).

• Si no, ve a Configuración → Dispositivos y Servicios → Agregar Integración, busca ESPHome e ingresa el nombre de host del dispositivo (por ejemplo, living-room-lamp.local) o la dirección IP.

Repite este proceso para cada dispositivo ESPHome que agregues.

8. A dónde ir después

🎉 ¡Felicidades — has configurado tu primer proyecto ESPHome e instalado firmware personalizado en tu dispositivo! También has aprendido cómo agregar componentes básicos mediante YAML.

Próximos pasos:

• Navega por el  Índice de Componentes para encontrar todo el hardware compatible.

• Consulta las Preguntas frecuentes (FAQ) para preguntas comunes.

• Si encuentras problemas o quieres solicitar funciones, abre un ticket en el  rastreador de incidencias de GitHub.