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.
- Autor
Mauro Brambilla- Publicado
- Tiempo de lectura
- 11 min
- Categoría
- Guías

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é.

¿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:
- El navegador pide al usuario que elija un puerto serie.
- 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.
- Descarga las partes de esa build y escribe cada una en su offset.
- 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.
<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>¿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.
| Navegador | Web Serial | Nota |
|---|---|---|
| Chrome (escritorio) | Sí, desde la versión 89 | esptool-js documenta Chrome y Edge 89 o posterior |
| Edge (escritorio) | Sí, desde la versión 89 | Igual que Chrome en los datos de compatibilidad de MDN |
| Chrome en Android | Sí, desde la versión 148 | Las versiones 138 a 147 solo veían puertos serie Bluetooth |
| Firefox (escritorio) | Sí, desde la versión 151 | Datos de MDN. No lo he probado |
| Firefox en Android | No | Datos de MDN |
| Safari, cualquier navegador en iOS | No | Datos 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:
{
"name": "My Firmware",
"version": "1.0.0",
"builds": [
{
"chipFamily": "ESP32-S3",
"parts": [
{
"path": "merged-firmware.bin",
"offset": 0
}
]
}
]
}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:
| Clave | Dónde | Qué hace |
|---|---|---|
| name, version | nivel superior | Se muestran en la interfaz. El nombre se compara con el firmware que el dispositivo comunica por Improv |
| builds[].chipFamily | build | ESP8266, ESP32, ESP32-C2, ESP32-C3, ESP32-C5, ESP32-C6, ESP32-C61, ESP32-H2, ESP32-P4, ESP32-S2 o ESP32-S3 |
| builds[].parts[] | build | La ruta de un archivo y el offset de flash entero en el que escribirlo |
| builds[].serialType | build | cdc o uart: una build aparte para USB nativo o para un puente USB-UART |
| new_install_prompt_erase | nivel superior | true deja que el usuario elija borrar todo en una instalación nueva |
| new_install_improv_wait_time | nivel superior | Segundos de espera de una respuesta de Improv tras instalar (10 por defecto, 0 desactiva Improv) |
| home_assistant_domain, funding_url | nivel superior | Enlaces 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.
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.binLas 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.
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
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):
{
"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
}
]
}
]
}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:
- Llama a
navigator.serial.requestPort()y se conecta con esptool-js a 115200 baudios, lo que identifica el chip. - Descarga el manifest con
cache: 'no-store', para que una versión nueva aparezca al instante. - Busca la build cuyo
chipFamilycoincide 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. - Descarga las cuatro partes una por una, resolviendo cada ruta respecto a la URL del manifest.
- Llama a
writeFlashconflashMode,flashFreqyflashSizeen'keep',eraseAll: falseycompress: true. - 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.jsdel 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.

¿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:
- Compila el firmware y reúne sus partes con sus offsets (o un solo archivo unido en el offset 0 para ESP Web Tools).
- Sube las partes y un
manifest.jsonque las liste a un host HTTPS, con cabeceras CORS si no es el mismo sitio de la página. - Añade el fragmento
<script>y<esp-web-install-button>de arriba a una página HTTPS, con la URL del manifest. - 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.
- 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:

- Lee
VERSIONy se detiene si el tag ya existe o si la versión de la aplicación web es distinta. - Ejecuta las pruebas de la aplicación web y las pruebas nativas del firmware, y luego compila el firmware.
- Ejecuta package_firmware.py, que le pide a PlatformIO las imágenes de flash y sus offsets (
pio project metadata) y escribemanifest.json. - Crea una release de GitHub con las partes, cuyas notas incluyen un comando esptool para flashear por USB.
- Sube las partes con
Cache-Control: public, max-age=31536000, immutabley después el manifest conmax-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 ves | Causa probable | Qué probar |
|---|---|---|
| Botón desactivado, o 'No se puede flashear desde este navegador' | Navegador sin Web Serial, o la página no usa HTTPS | Usa Chrome o Edge en escritorio, por HTTPS o localhost |
| El selector de puerto no muestra ningún dispositivo | Cable USB solo de carga, o la placa no se detecta | Usa un cable de datos y otro puerto USB, y recarga la página |
| Falla la conexión, no se reciben datos serie | El chip no está en modo descarga, o el enlace USB es inestable | Mira 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 chip | Añ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 incorrecta | Abre la URL de cada parte en una pestaña |
| No se puede leer el manifest, con un error de CORS en la consola | La CDN no permite el origen de tu página | Envía Access-Control-Allow-Origin para tu dominio |
| El flasheo termina pero la placa se queda en el bootloader | No hay un pulso de reinicio real tras flashear | Desenchufa 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.
Autor
Mauro Brambilla¿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.







