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.
Actualizado el 3 de agosto de 2026. He revisado toda la guía conforme a los cambios introducidos por ESPHome 2024.6, 2025.7 y 2026.1, además de retirar contraseñas escritas directamente en los ejemplos.
Las actualizaciones OTA en ESPHome permiten instalar un firmware nuevo mediante la red sin volver a conectar el dispositivo por USB. Para la mayoría de instalaciones de Home Assistant, el método recomendado es la plataforma OTA nativa de ESPHome, protegida mediante una contraseña única guardada en secrets.yaml.
La sintaxis cambió profundamente en junio de 2024. El bloque antiguo ota: dejó de ser un componente independiente y pasó a contener una lista de plataformas. Posteriormente, la carga desde el servidor web también se convirtió en una plataforma explícita. Esta guía explica qué método elegir, cómo migrar sin perder el acceso y qué comprobar cuando una actualización falla.
Qué significa OTA y qué no hace
OTA significa Over the Air. ESPHome compila un firmware para una placa concreta, lo envía por WiFi o Ethernet y el dispositivo lo escribe en una partición de actualización. Si la instalación termina correctamente, el nodo reinicia con el firmware nuevo.
- OTA no sustituye la primera instalación por USB en una placa nueva.
- No permite recuperar cualquier fallo de hardware, particionado o conectividad.
- No convierte el ESP en un dispositivo seguro para exponer directamente a Internet.
- La clave de cifrado de la API y la contraseña OTA son credenciales diferentes.
Conserva siempre el YAML, sus secretos y una forma razonable de acceder físicamente al dispositivo. OTA es muy cómoda, pero USB sigue siendo la vía de recuperación más fiable.
Los tres cambios que explican casi todos los ejemplos antiguos
| Versión | Cambio | Consecuencia |
|---|---|---|
| ESPHome 2024.6 | OTA pasó de componente único a componente con plataformas | Ahora se escribe ota: seguido de una lista con - platform: esphome |
| ESPHome 2025.7 | La carga de firmware integrada en web_server se separó | Para actualizar desde el navegador hay que añadir - platform: web_server |
| ESPHome 2026.1 | Se eliminó la autenticación OTA MD5 antigua y SHA-256 pasó a ser obligatoria | Herramientas anteriores a ESPHome 2025.10 no pueden actualizar nodos que ya ejecuten 2026.1 o posterior |
La documentación OTA oficial mantiene la lista actual de plataformas y sus opciones. No copies un bloque de 2023 o principios de 2024 sin migrarlo.
Configuración OTA recomendada en ESPHome
Este es un ejemplo mínimo y seguro para un ESP32 conectado a Home Assistant. Cambia el identificador de placa y deja que ESPHome genere la clave API:
esphome:
name: sensor-salon
friendly_name: Sensor salón
esp32:
board: esp32dev
framework:
type: esp-idf
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
logger:
level: INFO
api:
encryption:
key: !secret sensor_salon_api_key
ota:
- platform: esphome
password: !secret sensor_salon_ota_passwordEl guion delante de platform es imprescindible porque ota contiene una lista. La forma intermedia ota: platform: esphome, sin lista, tampoco es la sintaxis correcta.
Credenciales en secrets.yaml
wifi_ssid: "Nombre de tu red"
wifi_password: "Contraseña WiFi"
sensor_salon_api_key: "CLAVE_BASE64_GENERADA_POR_ESPHOME"
sensor_salon_ota_password: "contraseña-ota-larga-y-única"
sensor_salon_web_username: "admin-sensor-salon"
sensor_salon_web_password: "otra-contraseña-larga-y-única"secrets.yaml evita publicar las credenciales junto al YAML, pero no cifra el archivo dentro de tu sistema. No lo subas a Git ni lo compartas. La guía de seguridad de ESPHome recomienda claves API, contraseñas OTA y credenciales web diferentes para cada nodo. Solo las credenciales WiFi suelen compartirse.
Si administras muchos dispositivos, las sustituciones y packages de ESPHome permiten reutilizar la estructura sin duplicar secretos.
Métodos OTA disponibles: cuál debes utilizar
| Método | Uso normal | Seguridad y limitaciones |
|---|---|---|
platform: esphome | ESPHome Device Builder y CLI en una red local | Es el método preferente; utiliza autenticación por desafío y la contraseña no viaja directamente por la red |
platform: web_server | Subir manualmente un archivo desde el navegador o usar la ruta HTTP de la CLI | Necesita web_server y autenticación; la ruta OTA emplea HTTP Basic y debe limitarse a una red de confianza |
platform: http_request | El dispositivo descarga su propio firmware desde un servidor | Es una opción avanzada para nodos autónomos o MQTT; exige controlar servidor, binario, integridad y TLS |
| USB/serie | Primera instalación y recuperación | Requiere acceso físico, pero no depende de red, mDNS ni contraseña OTA |
En una instalación doméstica con Home Assistant no necesitas activar los tres métodos. La plataforma nativa de ESPHome suele ser suficiente y reduce la superficie expuesta.
OTA desde web_server: configuración actual
Desde ESPHome 2025.7, activar web_server ya no añade por sí solo la carga web de firmware. Debes configurar la plataforma explícitamente:
web_server:
port: 80
version: 3
auth:
username: !secret sensor_salon_web_username
password: !secret sensor_salon_web_password
type: basic
ota:
- platform: esphome
password: !secret sensor_salon_ota_password
- platform: web_serverLa autenticación Basic evita el acceso anónimo, pero no cifra las credenciales sobre HTTP. Utiliza esta opción únicamente dentro de una red doméstica de confianza o una VLAN IoT y no abras el puerto en el router. Si no necesitas subir firmware desde el navegador, elimina la plataforma web_server y conserva solo OTA nativo.
Cuando ambas plataformas están configuradas, la CLI prefiere la ruta nativa. En ESPHome actual puedes forzar la otra:
esphome upload sensor-salon.yaml --ota-platform web_server
esphome run sensor-salon.yaml --ota-platform esphomePara una carga manual desde el navegador selecciona firmware.ota.bin —también mostrado como formato OTA—, no firmware.factory.bin. La documentación de Web Server OTA detalla esta diferencia.
OTA mediante HTTP Request: para casos avanzados
Con platform: http_request el dispositivo actúa como cliente: descarga un archivo firmware.ota.bin desde un servidor y lo instala mediante una automatización. Resulta útil para dispositivos autónomos o basados únicamente en MQTT, incluso cuando están detrás de un cortafuegos.
http_request:
verify_ssl: true
ota:
- platform: http_requestEsto solo habilita el backend: todavía necesitas una acción de instalación, una URL, verificación de integridad y una estrategia segura de publicación. No desactives la validación TLS para hacer desaparecer un error sin entender el riesgo. Consulta la referencia HTTP Request OTA antes de usarlo en producción.
Cómo migrar desde la sintaxis OTA antigua
Si tu archivo todavía contiene este formato:
# Sintaxis anterior a ESPHome 2024.6: no usar en configuraciones nuevas
ota:
password: !secret ota_passwordcámbialo por:
ota:
- platform: esphome
password: !secret ota_password- Actualiza primero ESPHome Device Builder o la CLI.
- Haz una copia del YAML y de
secrets.yaml. - Modifica únicamente el bloque OTA y valida el archivo.
- Actualiza un dispositivo de prueba antes de desplegar el cambio en todos.
- Comprueba que vuelve a conectarse a Home Assistant y conserva entidades y nombre.
El vídeo original de Tecnoyfoto documenta el cambio inicial de 2024.6. Ten en cuenta que la separación de Web Server OTA y la compatibilidad SHA-256 llegaron después; para el código final utiliza siempre los bloques mostrados en esta guía.
Compatibilidad OTA desde ESPHome 2026.1
ESPHome 2026.1 eliminó la autenticación OTA MD5 y exige SHA-256. Si el dispositivo ya ejecuta 2026.1 o posterior, un Dashboard o CLI anterior a 2025.10 no podrá actualizarlo mediante contraseña. La solución es actualizar primero todas las herramientas desde las que instalas firmware.
También hay que planificar los downgrades: para regresar desde una versión 2026.1 o posterior a una anterior a 2025.10, la ruta documentada pasa primero por ESPHome 2025.12.x. Saltar directamente a una versión demasiado antigua puede obligarte a recuperar el dispositivo por USB.
Cómo actualizar desde el Dashboard o la CLI
- Comprueba que el nodo está en línea y que la señal WiFi es razonable.
- Valida y compila el YAML antes de iniciar la carga.
- Verifica el nombre y la dirección del dispositivo para no actualizar el nodo equivocado.
- Inicia la instalación y no cortes la alimentación.
- Espera a que reinicie, revise los registros y vuelva a aparecer disponible.
esphome config sensor-salon.yaml
esphome compile sensor-salon.yaml
esphome upload sensor-salon.yamlesphome run combina compilación, carga y registros. Para un cambio importante prefiero separar validación, compilación y subida: así sé exactamente en qué fase aparece un error.
Errores OTA frecuentes y soluciones
| Error o síntoma | Qué comprobar |
|---|---|
No se resuelve nombre.local | Consulta la IP en el router o los registros, comprueba mDNS y usa temporalmente use_address |
| Authentication failed | La contraseña de secrets.yaml debe coincidir con la que ya ejecuta el dispositivo; API y OTA no usan la misma credencial |
| Connection refused o timeout | Revisa WiFi, VLAN, cortafuegos y puertos: 3232 en ESP32 y 8266 en ESP8266 por defecto |
| Herramienta antigua no puede actualizar un nodo nuevo | Actualiza Dashboard y CLI a una versión compatible con SHA-256 |
| No hay espacio para OTA | Reduce el firmware, revisa el esquema de particiones y utiliza el archivo OTA correcto; quizá necesites USB |
| Reinicios durante la carga | Comprueba alimentación, señal WiFi, memoria disponible y estabilidad del firmware anterior |
| Arranca en bucle tras actualizar | Deja actuar el modo seguro y carga una configuración mínima o el firmware anterior |
use_address para localizar una IP antigua
Si has cambiado nombre o dirección y ESPHome intenta conectar al destino equivocado, puedes indicar temporalmente la IP que todavía utiliza el nodo:
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
use_address: 192.168.1.91Después de una actualización correcta, elimina use_address. Una reserva DHCP puede mantener direcciones predecibles sin escribir IP, puerta de enlace y subred en cada dispositivo. Si necesitas una configuración manual, consulta nuestra guía de WiFi en ESPHome.
Modo seguro: la red de recuperación de ESPHome
OTA activa automáticamente el soporte de Safe Mode. Tras varios fallos de arranque, ESPHome puede iniciar únicamente red, registro serie y plataformas OTA, dejando deshabilitados sensores y actuadores para que puedas cargar una corrección.
No desactives el modo seguro en un dispositivo instalado en un lugar difícil de alcanzar salvo que tengas una razón técnica concreta. Aun así, no es una garantía absoluta: si el firmware no cabe, la red no arranca o el esquema de particiones es incompatible, necesitarás acceso físico.
Lista de seguridad antes de actualizar
- ESPHome Dashboard y CLI actualizados.
- YAML y
secrets.yamlrespaldados. - Contraseña OTA única y fuera del archivo compartido.
- API nativa cifrada con una clave distinta.
web_serverdesactivado si no se utiliza o protegido si es necesario.- Dispositivos ESPHome nunca expuestos directamente a Internet.
- Prueba en un solo nodo antes de una actualización masiva.
- Acceso USB o plan de recuperación disponible.
Si vas a preparar tu primer nodo desde cero, la guía completa del ESP32 con ESPHome incluye una configuración base segura y los GPIO que debes evitar.
Preguntas frecuentes sobre OTA en ESPHome
¿Es obligatoria una IP estática para OTA?
No. ESPHome puede localizar el nodo por mDNS o por la dirección asignada mediante DHCP. Una reserva DHCP ayuda a diagnosticar problemas, pero OTA no exige una IP manual.
¿La clave API sirve como contraseña OTA?
No. La clave API cifra la comunicación con Home Assistant. La plataforma OTA nativa utiliza su propia contraseña y ambas deben ser únicas.
¿Puedo actualizar ESPHome desde fuera de casa?
No debes publicar los puertos OTA o web_server en Internet. Si necesitas administración remota, entra primero en tu red mediante una VPN correctamente configurada.
¿Qué archivo debo subir desde el navegador?
Utiliza firmware.ota.bin o el archivo descargado en formato OTA. El archivo factory está pensado para la primera instalación y no debe usarse en esta ruta.
Conclusión
La configuración recomendada para la mayoría de usuarios es sencilla: platform: esphome, una contraseña única en secrets.yaml, herramientas actualizadas y ningún puerto expuesto a Internet. Añade Web Server OTA o HTTP Request solo cuando tengas una necesidad real y entiendas el modelo de seguridad.
Fuentes técnicas consultadas: documentación oficial de Over-the-Air Updates, ESPHome OTA, Web Server OTA, HTTP Request OTA y Safe Mode.
Continúa leyendo
Siguiente guía relacionada · 7 min de lectura
Sustituciones y packages en ESPHome: guía práctica actualizada
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,…
Continuar con este artículo