Cómo solucionar el error de actualización OTA en ESPHome tras Home Assistant 2024.6

Desde la versión 2024.6 de Home Assistant, numerosos usuarios han experimentado problemas al intentar actualizar sus dispositivos ESPHome de forma inalámbrica (OTA). Este error impide la actualización tanto desde el panel de Home Assistant como desde el dashboard de ESPHome, mostrando mensajes de error que pueden resultar confusos para quienes no están familiarizados con la configuración YAML.

En este artículo técnico explicaremos en detalle cómo identificar este problema, entender su origen y aplicar la solución definitiva de manera sencilla y efectiva.

Identificación del problema

El error se manifiesta de dos formas principales dependiendo desde dónde intentes realizar la actualización:

Error desde Home Assistant

Cuando intentas actualizar un dispositivo ESPHome desde la interfaz principal de Home Assistant, al seleccionar el dispositivo con actualización pendiente y hacer clic en “Instalar”, aparece el siguiente mensaje:

“Error al llamar al servicio update install”

Este mensaje suele ir acompañado de una sugerencia que indica que intentes realizar la actualización desde el dashboard de ESPHome.

Error desde el dashboard de ESPHome

Si sigues la recomendación anterior y accedes al dashboard de ESPHome para intentar actualizar el dispositivo de forma inalámbrica, el sistema te mostrará un error más específico que, afortunadamente, incluye la solución al problema.

El mensaje de error indica claramente que es necesario agregar la plataforma ESPHome dentro de la configuración OTA del archivo YAML del dispositivo.

Causa del problema

Este inconveniente surge debido a cambios en la estructura de configuración de ESPHome implementados a partir de la versión 2024.6 de Home Assistant. Las versiones anteriores permitían que la sección OTA del archivo de configuración estuviera vacía o con una configuración mínima, pero las versiones más recientes requieren que se especifique explícitamente la plataforma que se utilizará para las actualizaciones inalámbricas.

Muchos dispositivos configurados con versiones anteriores tienen una etiqueta OTA sin contenido o con configuraciones que ya no son compatibles con el nuevo formato, lo que genera el fallo en el proceso de actualización.

Solución paso a paso

La solución a este problema es sorprendentemente sencilla y solo requiere una pequeña modificación en el archivo de configuración YAML del dispositivo afectado.

Paso 1: Acceder al dashboard de ESPHome

Primero, accede al dashboard de ESPHome desde tu instalación de Home Assistant. Puedes hacerlo desde el menú lateral o mediante la URL correspondiente de tu instalación.

Paso 2: Localizar el dispositivo problemático

Identifica el dispositivo que presenta el error de actualización. Generalmente, estos dispositivos mostrarán una indicación de que hay una actualización disponible pero no se puede instalar.

Paso 3: Editar el archivo YAML

Haz clic en el botón de edición del dispositivo para acceder a su archivo de configuración YAML. Este archivo contiene todas las configuraciones del dispositivo ESPHome.

Paso 4: Localizar o crear la sección OTA

Busca en el archivo la etiqueta ota:. Pueden presentarse dos escenarios:

• Escenario 1: La etiqueta OTA existe pero está vacía o sin la configuración de plataforma
• Escenario 2: La etiqueta OTA no existe en el archivo

Paso 5: Agregar la configuración de plataforma

Independientemente del escenario en el que te encuentres, la solución es la misma. Debes agregar o modificar la sección OTA para que incluya la especificación de la plataforma ESPHome.

La configuración correcta debe verse así:

ota:
  platform: esphome

Es importante respetar la indentación correcta en YAML. La línea platform: esphome debe estar indentada con dos espacios respecto a la etiqueta ota:.

Paso 6: Guardar e instalar

Una vez agregada la configuración, guarda el archivo y haz clic en el botón “Instalar”. Selecciona la opción de instalación inalámbrica (Wirelessly).

Paso 7: Esperar la compilación e instalación

El sistema comenzará el proceso de compilación e instalación del firmware actualizado. Este proceso puede tardar varios minutos dependiendo de:

• La velocidad del dispositivo donde se ejecuta Home Assistant
• La complejidad de la configuración del dispositivo ESPHome
• La velocidad de la conexión de red
• Los recursos disponibles en el sistema

Durante este proceso verás información en tiempo real sobre el progreso de la compilación y la instalación.

Paso 8: Verificación

Una vez finalizado el proceso, el dispositivo se reiniciará automáticamente con la nueva configuración. A partir de este momento, el dispositivo podrá recibir actualizaciones OTA sin problemas, tal como funcionaba antes de la versión 2024.6.

Puedes verificar que todo funciona correctamente comprobando que:

• El dispositivo aparece como “Online” en el dashboard de ESPHome
• No hay mensajes de error en los logs
• Las futuras actualizaciones se pueden instalar sin problemas

Consideraciones adicionales

Aplicar la solución a múltiples dispositivos

Si tienes varios dispositivos ESPHome que presentan el mismo problema, deberás aplicar esta solución a cada uno de ellos individualmente. No existe una forma de aplicar este cambio de manera masiva desde la interfaz de ESPHome, por lo que tendrás que editar el archivo YAML de cada dispositivo afectado.

Dispositivos con configuraciones OTA existentes

Algunos dispositivos pueden tener configuraciones OTA más complejas que incluyen contraseñas u otras opciones de seguridad. En estos casos, simplemente agrega la línea platform: esphome dentro de la sección OTA existente, manteniendo las demás configuraciones intactas.

Por ejemplo, si tu configuración actual es:

ota:
  password: "tu_contraseña_segura"

Deberás modificarla para que quede así:

ota:
  platform: esphome
  password: "tu_contraseña_segura"

Prevención en nuevos dispositivos

Para evitar este problema en dispositivos nuevos que configures en el futuro, asegúrate de incluir siempre la especificación de plataforma en la sección OTA desde el principio. Esto garantizará la compatibilidad con las versiones actuales y futuras de Home Assistant y ESPHome.

Ventajas de las actualizaciones OTA

Resolver este problema es importante porque las actualizaciones OTA (Over-The-Air) ofrecen numerosas ventajas:

• Comodidad: No es necesario conectar físicamente el dispositivo al ordenador
• Rapidez: El proceso es más rápido que las actualizaciones por cable
• Accesibilidad: Puedes actualizar dispositivos instalados en lugares de difícil acceso
• Mantenimiento simplificado: Facilita mantener todos tus dispositivos actualizados con las últimas mejoras de seguridad y funcionalidad

Solución de problemas adicionales

Si la actualización sigue fallando

En casos excepcionales, después de aplicar la solución, la actualización OTA podría seguir presentando problemas. En estos casos, considera:

• Verificar que la indentación del archivo YAML sea correcta
• Comprobar que no haya errores de sintaxis en el archivo de configuración
• Revisar los logs de ESPHome para identificar mensajes de error específicos
• Verificar la conectividad de red del dispositivo
• Como último recurso, realizar una actualización por cable USB

Errores de sintaxis YAML

YAML es muy sensible a la indentación y el formato. Asegúrate de:

• Usar espacios en lugar de tabulaciones
• Mantener una indentación consistente de 2 espacios por nivel
• No dejar espacios al final de las líneas
• Respetar el formato clave: valor con un espacio después de los dos puntos

Compatibilidad y versiones

Esta solución es aplicable específicamente para:

• Home Assistant versión 2024.6 y posteriores
• Dispositivos ESPHome configurados con versiones anteriores
• Todos los tipos de dispositivos basados en ESP8266 y ESP32

La configuración platform: esphome es compatible con todas las versiones actuales de ESPHome y se mantendrá como el estándar recomendado para futuras versiones.