ESP Web Tools: flashear un ESP32 desde el navegador

Flashea un ESP32 desde el navegador con ESP Web Tools o esptool-js: cómo funcionan Web Serial, el manifest y los offsets, con un manifest real de OpenGizmo.

Publicado
Tiempo de lectura
11 min
Categoría
Guías
Un hombre con barba y sudadera azul está junto a una laptop cuyo navegador muestra un botón Install naranja y una barra al 68 %, con un cable USB hasta una placa ESP32.

En resumen

ESP Web Tools flashea un ESP32 por Web Serial, en Chrome o Edge y desde una página HTTPS, con un manifest.json que lista cada parte del firmware y su offset. OpenGizmo hace lo mismo con esptool-js.

Sí, puedes flashear un ESP32 desde el navegador. ESP Web Tools, o cualquier página construida sobre esptool-js de Espressif, habla con la placa mediante la Web Serial API: abres una página HTTPS en Chrome o Edge en un equipo de escritorio, conectas un cable USB de datos, eliges el puerto serie y pulsas un botón.

En esta guía te explico cómo funciona ESP Web Tools (Web Serial, el manifest.json, los offsets) y luego cómo los tres dispositivos de OpenGizmo usan la misma idea, con un manifest real alojado en una CDN. Un detalle antes de empezar: la web de OpenGizmo no incrusta el botón de ESP Web Tools. Usa esptool-js directamente, y te cuento por qué.

Los cuatro pasos del flasheo desde el navegador: elegir el puerto USB con Web Serial, identificar el chip, elegir su build en el manifest y escribir las partes en sus offsets

¿Cómo funciona ESP Web Tools?

ESP Web Tools es un componente web de código abierto del proyecto ESPHome (Open Home Foundation) que añade a cualquier página un botón para instalar firmware en ESP8266 y ESP32. Su propia web dice que funciona combinando Web Serial, Improv Wi-Fi (opcional) y un manifest que describe el firmware.

Espera, ¿qué es Web Serial? Es una API del navegador que permite a una página leer y escribir en dispositivos serie, incluidos los USB que exponen un puerto serie virtual, que es lo que hace una placa de desarrollo ESP32. El navegador muestra un selector de puerto y lo eliges tú, así que una página no puede abrir un dispositivo a tus espaldas.

Esto es lo que pasa cuando alguien pulsa el botón:

  1. El navegador pide al usuario que elija un puerto serie.
  2. La herramienta se conecta al bootloader ROM del chip y lo detecta. Según la documentación, después elige automáticamente del manifest la variante de firmware correcta.
  3. Descarga las partes de esa build y escribe cada una en su offset.
  4. Opcionalmente, espera a Improv Serial para conocer el estado del dispositivo y ofrecer la configuración del Wi-Fi.

El flasheo en sí no se ha reinventado. A noviembre de 2026, el paquete de ESP Web Tools (versión 10.5.x) depende de esptool-js, el port a JavaScript de esptool de Espressif, además del SDK serie de Improv. Por eso las dos herramientas se comportan de forma parecida.

Añadir el botón a tu página lleva dos fragmentos de código, ambos de las instrucciones oficiales: cargas el script, luego pones el elemento y lo apuntas a tu manifest.

index.html
index.html
<script type="module" src="https://unpkg.com/esp-web-tools@10/dist/web/install-button.js?module"></script>

<esp-web-install-button manifest="https://example.com/firmware/manifest.json"></esp-web-install-button>
Lín. 3, col. 1UTF-8HTML

¿Qué navegadores lo admiten y por qué HTTPS?

Web Serial solo existe en contextos seguros, así que la página con el botón debe servirse por HTTPS. ESP Web Tools lo indica como requisito de Web Serial. Además, el navegador tiene que implementar la API, y ese es el límite real.

NavegadorWeb SerialNota
Chrome (escritorio)Sí, desde la versión 89esptool-js documenta Chrome y Edge 89 o posterior
Edge (escritorio)Sí, desde la versión 89Igual que Chrome en los datos de compatibilidad de MDN
Chrome en AndroidSí, desde la versión 148Las versiones 138 a 147 solo veían puertos serie Bluetooth
Firefox (escritorio)Sí, desde la versión 151Datos de MDN. No lo he probado
Firefox en AndroidNoDatos de MDN
Safari, cualquier navegador en iOSNoDatos de MDN. ESP Web Tools también dice que iOS no

Las versiones salen de los datos de compatibilidad de navegadores de MDN a noviembre de 2026, y la propia MDN marca la función como no Baseline. Solo he comprobado el comportamiento del flasheador de OpenGizmo en el código, no en cada navegador. Su tarjeta muestra "No se puede flashear desde este navegador" cuando falta navigator.serial o la página no es un contexto seguro.

Si usas Safari o un teléfono, flashea una vez con una herramienta instalada en una computadora: mira Arduino IDE vs PlatformIO para ESP32 o, para la ESP32-CAM, la guía del programador ESP32-CAM-MB.

¿Cómo se escribe el manifest y se eligen los offsets?

Un manifest es un pequeño archivo JSON que le dice al flasheador qué firmware instalar en qué chip. Cada build lista los archivos (partes) que hay que escribir y el offset de flash de cada uno. Este es el más pequeño que sirve, en el formato de la documentación de ESP Web Tools:

manifest.json
manifest.json
{
  "name": "My Firmware",
  "version": "1.0.0",
  "builds": [
    {
      "chipFamily": "ESP32-S3",
      "parts": [
        {
          "path": "merged-firmware.bin",
          "offset": 0
        }
      ]
    }
  ]
}
Lín. 15, col. 1UTF-8JSON

Las rutas de las partes se resuelven respecto al manifest y también pueden ser URL completas en otros hosts. Los campos que más te vas a encontrar:

ClaveDóndeQué hace
name, versionnivel superiorSe muestran en la interfaz. El nombre se compara con el firmware que el dispositivo comunica por Improv
builds[].chipFamilybuildESP8266, ESP32, ESP32-C2, ESP32-C3, ESP32-C5, ESP32-C6, ESP32-C61, ESP32-H2, ESP32-P4, ESP32-S2 o ESP32-S3
builds[].parts[]buildLa ruta de un archivo y el offset de flash entero en el que escribirlo
builds[].serialTypebuildcdc o uart: una build aparte para USB nativo o para un puente USB-UART
new_install_prompt_erasenivel superiortrue deja que el usuario elija borrar todo en una instalación nueva
new_install_improv_wait_timenivel superiorSegundos de espera de una respuesta de Improv tras instalar (10 por defecto, 0 desactiva Improv)
home_assistant_domain, funding_urlnivel superiorEnlaces opcionales que se muestran tras la instalación

Los offsets dependen del chip y de cómo compilaste el firmware. Para un firmware dividido en cuatro archivos, la documentación de ESP-IDF coloca el bootloader de segunda etapa en 0x1000 en el ESP32 y en 0x0 en el ESP32-S3. La página del S3 también coloca la tabla de particiones en 0x8000 por defecto. En las builds de PlatformIO que publico, la imagen boot_app0 va en 0xE000 y la app en 0x10000. Nunca los adivines: léelos de tu build, como hace la siguiente sección.

¿Necesitas un archivo de firmware unido (merged)?

Para un ESP32 compilado con ESP-IDF 4 o posterior, la documentación de ESP Web Tools dice que sí. El motivo que dan: cuando los cuatro archivos se instalan con el comando esptool, esptool ajusta la frecuencia, el tamaño y el modo de la flash al dispositivo de destino, y ESP Web Tools no puede hacerlo sobre la marcha. Así que creas una sola imagen con merge_bin y la listas en el offset 0.

Une las cuatro partes (comando de la documentación de ESP Web Tools)
esptool --chip esp32 merge_bin -o merged-firmware.bin --flash_mode dio --flash_freq 40m --flash_size 4MB 0x1000 bootloader.bin 0x8000 partitions.bin 0xe000 boot.bin 0x10000 your_app.bin

Las partes separadas también pueden funcionar: el manifest de ejemplo del README de ESP Web Tools lista cuatro archivos, con un bootloader llamado bootloader_dout_40m.bin cuyos ajustes de flash ya se habían elegido al compilar. Unir es la ruta documentada cuando partes de una build normal. La documentación añade dos advertencias: usa dout cuando tu tipo de memoria sea opi_opi u opi_qspi, y cambia qio o qout por dio. El archivo unido tiene un precio que conviene conocer. La documentación de esptool dice que en el formato raw los huecos entre archivos se rellenan con bytes 0xFF, el valor de la flash borrada. Una imagen unida cubre, por tanto, todo el rango desde el bootloader hasta la app, incluida la zona de ajustes entre la tabla de particiones y boot_app0. Tenlo presente para la sección de actualizaciones.

¿Cómo flashea OpenGizmo desde el navegador sin el componente web?

Cada página de proyecto de OpenGizmo tiene una tarjeta de firmware que no es el elemento de ESP Web Tools. Es el componente app/components/projects/FlashFirmware.vue del código fuente del sitio, que importa ESPLoader y Transport de esptool-js (versión 0.7.1 en el package.json del sitio) y lee un manifest en el formato de ESP Web Tools. El formato es, pues, el mismo; solo cambia el front end.

Proyecto open source ESP32 + MAX7219
Gizmo Ticker

Un display de criptomonedas con Wi-Fi, construido con un ESP32, una matriz LED MAX7219 y una aplicación web Nuxt 4 para configurarlo desde el navegador.

  • Ticker cripto en tiempo real
  • Matriz LED MAX7219
  • Configuración desde el navegador
Echar un vistazo

Este es el manifest real que lee la tarjeta del Gizmo Ticker, en https://cdn.opengizmo.dev/gizmo-ticker/manifest.json (descargado el 14 de noviembre de 2026):

manifest.json
manifest.json
{
  "name": "Gizmo Ticker",
  "version": "v1.2.0",
  "new_install_prompt_erase": false,
  "builds": [
    {
      "chipFamily": "ESP32-S3",
      "parts": [
        {
          "path": "v1.2.0/release-bootloader.bin",
          "offset": 0
        },
        {
          "path": "v1.2.0/release-partitions.bin",
          "offset": 32768
        },
        {
          "path": "v1.2.0/release-boot_app0.bin",
          "offset": 57344
        },
        {
          "path": "v1.2.0/release-firmware.bin",
          "offset": 65536
        }
      ]
    }
  ]
}
Lín. 28, col. 1UTF-8JSON

Los offsets son decimales, como exige JSON: 32768 es 0x8000, 57344 es 0xE000, 65536 es 0x10000. El manifest del Gizmo Reolink Switch tiene las mismas cuatro partes en el mismo chip. El manifest de la Gizmo Camera tiene "chipFamily": "ESP32" y su bootloader en 4096 (0x1000), como indica la página de ESP-IDF de antes. Los demás offsets son iguales.

Una clave de estos manifests es solo para el componente oficial: new_install_prompt_erase: false. La tarjeta de OpenGizmo nunca la lee. ESP Web Tools trataría false como su valor por defecto, que es borrar todos los datos en una instalación nueva.

Cuando pulsas Flashear firmware, la tarjeta hace esto, por este orden:

  1. Llama a navigator.serial.requestPort() y se conecta con esptool-js a 115200 baudios, lo que identifica el chip.
  2. Descarga el manifest con cache: 'no-store', para que una versión nueva aparezca al instante.
  3. Busca la build cuyo chipFamily coincide con el nombre del chip detectado. Si no hay ninguna, se detiene con "Este firmware no está compilado para el chip conectado", así que una imagen de ESP32 nunca acaba en un ESP32-S3.
  4. Descarga las cuatro partes una por una, resolviendo cada ruta respecto a la URL del manifest.
  5. Llama a writeFlash con flashMode, flashFreq y flashSize en 'keep', eraseAll: false y compress: true.
  6. Reinicia la placa.

¿Por qué no usar el componente web? Puedo señalar tres cosas en el código, y no he probado el botón oficial con estos manifests, así que no puedo decirte cómo se comportaría:

  • Las cuatro partes siguen separadas. Con 'keep', esptool-js deja la cabecera del bootloader tal como la generó la build, así que no hace falta ningún paso de unión. Y las partes se saltan la zona de ajustes, que un archivo unido sobrescribiría.
  • Un arreglo del reinicio. Un comentario en app/utils/hardReset.js del sitio dice que esptool-js solo libera RTS, lo cual no hace nada cuando la línea ya está liberada, como ocurre con el USB propio del chip en el ESP32-S3. La placa se quedaba en el bootloader hasta que la desenchufabas. El sitio pasa su propio reinicio: DTR liberado, RTS mantenido 100 ms y luego liberado.
  • Una tarjeta a medida. Muestra la versión antes de flashear, cuatro etapas (conectar, descargar, flashear, reiniciar), un log, las notas de la versión que instala y mensajes traducidos.

El firmware no tiene soporte de Improv: no encontré código de Improv en los tres repositorios. La primera configuración del Wi-Fi pasa en cambio por un portal cautivo. La comparativa de métodos de provisioning Wi-Fi cubre Improv frente a las alternativas, y la guía para arreglar el portal cautivo cubre el portal.

Las cuatro partes que flashea el Gizmo Ticker y sus offsets, con la zona de ajustes en 0x9000 intacta

¿Cuál es el camino más corto hasta tu propia página de instalación?

Este es todo el trabajo, en orden, para tu propio firmware:

  1. Compila el firmware y reúne sus partes con sus offsets (o un solo archivo unido en el offset 0 para ESP Web Tools).
  2. Sube las partes y un manifest.json que las liste a un host HTTPS, con cabeceras CORS si no es el mismo sitio de la página.
  3. Añade el fragmento <script> y <esp-web-install-button> de arriba a una página HTTPS, con la URL del manifest.
  4. Abre la página en Chrome o Edge en un equipo de escritorio, conecta la placa con un cable de datos, pulsa el botón y elige el puerto.
  5. Comprueba que la placa arranca tu firmware y que la página ofrece la build correcta para cada chip que listes.

¿Dónde alojar el firmware y qué pasa con CORS?

Puedes alojar el manifest y las partes en el mismo sitio que la página de instalación, y entonces no hace falta configurar CORS. OpenGizmo los guarda en una CDN (cdn.opengizmo.dev, respaldada por un bucket de Cloudflare R2 en el workflow de publicación), así que el navegador hace peticiones entre orígenes distintos. En ese caso, ESP Web Tools te dice que envíes Access-Control-Allow-Origin: https://domain-of-your-website.com.

Lo comprobé el 14 de noviembre de 2026 pidiendo el manifest del Ticker con Origin: https://opengizmo.dev: la respuesta incluía access-control-allow-origin: https://opengizmo.dev y vary: Origin, y una petición preflight devolvió 204 con access-control-allow-methods: GET. La CDN solo permite el origen del sitio, no *. Prueba la tuya con curl -I -H "Origin: https://your.site" <manifest-url>.

¿Cómo publicas una versión nueva sin perder los ajustes de Wi-Fi?

Guarda los archivos de cada versión en su propia carpeta, no los modifiques nunca y mueve el manifest al final. El workflow de publicación de OpenGizmo lo hace así, con una ejecución manual desde main:

Un navegador muestra la memoria flash escrita en cuatro partes naranjas mientras una parte gris queda bloqueada e intacta, con una XIAO conectada por USB-C

  1. Lee VERSION y se detiene si el tag ya existe o si la versión de la aplicación web es distinta.
  2. Ejecuta las pruebas de la aplicación web y las pruebas nativas del firmware, y luego compila el firmware.
  3. Ejecuta package_firmware.py, que le pide a PlatformIO las imágenes de flash y sus offsets (pio project metadata) y escribe manifest.json.
  4. Crea una release de GitHub con las partes, cuyas notas incluyen un comando esptool para flashear por USB.
  5. Sube las partes con Cache-Control: public, max-age=31536000, immutable y después el manifest con max-age=60.

Subir el manifest al final significa que la web solo ofrece una versión subida por completo, y una caché de un minuto hace que una release aparezca en menos de un minuto. Las cabeceras que vi el 14 de noviembre de 2026 coinciden con esto.

Los ajustes sobreviven por lo que no se escribe. Los proyectos usan la tabla de particiones huge_app.csv, en la que el core de Arduino define nvs en 0x9000 (0x5000 bytes) y otadata en 0xE000. Las cuatro partes no cubren la región nvs (de 0x9000 a 0xDFFF) y eraseAll es false, así que los datos de Preferences se conservan. Eso se deduce de los offsets y del código: no medí una flash antes y después. La guía de la tabla de particiones explica la distribución, y la comparativa de OTA explica por qué estos dispositivos se actualizan por USB, ya que no tienen un segundo slot de aplicación.

Con el componente oficial, lee bien la regla de borrado: ESP Web Tools borra todos los datos en una instalación nueva, salvo que new_install_prompt_erase sea true y el usuario rechace. Ofrece una instalación nueva cuando no puede detectar el firmware actual del dispositivo, o cuando el firmware detectado no coincide con el name del manifest.

¿Qué falla con más frecuencia?

La mayoría de los fallos son del cable, del puerto o del navegador, no del firmware. Recorre esta tabla de arriba abajo, cambiando una sola cosa cada vez.

Lo que vesCausa probableQué probar
Botón desactivado, o 'No se puede flashear desde este navegador'Navegador sin Web Serial, o la página no usa HTTPSUsa Chrome o Edge en escritorio, por HTTPS o localhost
El selector de puerto no muestra ningún dispositivoCable USB solo de carga, o la placa no se detectaUsa un cable de datos y otro puerto USB, y recarga la página
Falla la conexión, no se reciben datos serieEl chip no está en modo descarga, o el enlace USB es inestableMira la guía de 'Failed to connect'
'Este firmware no está compilado para el chip conectado'El manifest no tiene una build para esa familia de chipAñade una build para él, o usa la placa correcta
'La descarga del firmware falló con el estado 404'La ruta de una parte en el manifest es incorrectaAbre la URL de cada parte en una pestaña
No se puede leer el manifest, con un error de CORS en la consolaLa CDN no permite el origen de tu páginaEnvía Access-Control-Allow-Origin para tu dominio
El flasheo termina pero la placa se queda en el bootloaderNo hay un pulso de reinicio real tras flashearDesenchufa y vuelve a enchufar; un hard reset propio como el de arriba lo arregla

Para la tercera fila, Failed to Connect to ESP32: No Serial Data Received repasa el modo de arranque, los cables y los drivers. Los textos de error de la tabla son los del archivo de traducciones de la tarjeta de OpenGizmo, y tu propia página dirá otra cosa.

¿Dónde se acaba el flasheo desde el navegador?

El flasheo desde el navegador te da una página donde cualquiera con Chrome o Edge, un cable y una placa puede instalar tu firmware en un minuto, con los ajustes conservados y un número de versión en pantalla. Hemos visto las piezas: Web Serial sobre HTTPS, un manifest de partes y offsets (unido para ESP Web Tools, o cuatro partes con esptool-js), CORS si los archivos están en otro sitio y una release que sube el manifest al final.

Quedan tres límites. Solo cubre el flasheo por cable; para actualizar por Wi-Fi mira la comparativa de métodos OTA. El soporte de navegadores fuera de Chrome y Edge es escaso a noviembre de 2026, y no he probado ninguno. Y el componente oficial solo lo he descrito a partir de su documentación y su código, no de haberlo usado yo. Si quieres ver todo funcionando, la guía de montaje del Gizmo Ticker flashea una placa de principio a fin, y las tres páginas de proyecto tienen cada una la tarjeta.

Preguntas frecuentes

Encuentra respuestas rápidas a las preguntas más comunes sobre este tema.

Sí. Una página que usa ESP Web Tools o esptool-js habla con la placa mediante la Web Serial API, así que solo necesitas un cable USB de datos y Chrome o Edge en un equipo de escritorio. La página debe servirse por HTTPS. Eliges el puerto serie y el firmware se escribe desde el navegador.

Publicado

¿Listo para montar tu propio gizmo?

Elige un proyecto open source con ESP32 y sigue su guía paso a paso, desde la lista de componentes y el cableado hasta el firmware y el primer arranque.

Lee también

Explora las categorías