ESP Web Tools: Flash an ESP32 From Your Browser

Flash an ESP32 from the browser with ESP Web Tools or esptool-js: how Web Serial, the manifest and the flash offsets work, with a real OpenGizmo manifest.

Published
Reading time
10 min
Category
Guides
A bearded man in a blue hoodie sits by a laptop whose browser shows an orange Install button and a 68% progress bar, with a USB cable running to an ESP32 board.

In short

ESP Web Tools flashes an ESP32 over Web Serial, in Chrome or Edge on an HTTPS page, from a manifest.json that lists each firmware part and its flash offset. OpenGizmo does the same with esptool-js.

Yes, you can flash an ESP32 from a web browser. ESP Web Tools, or any page built on Espressif's esptool-js, talks to the board through the Web Serial API: you open an HTTPS page in Chrome or Edge on a desktop, plug in a USB data cable, pick the serial port and press a button.

This guide explains how ESP Web Tools works (Web Serial, the manifest.json, the offsets), then shows how the three OpenGizmo devices use the same idea with a real manifest, hosted on a CDN. One detail first: OpenGizmo's site does not embed the ESP Web Tools button. It runs esptool-js directly, and I will show why.

The four steps of browser flashing: pick the USB port with Web Serial, identify the chip, choose its build in the manifest, write the parts at their offsets

How does ESP Web Tools work?

ESP Web Tools is an open-source web component from the ESPHome project (Open Home Foundation) that adds an install button for ESP8266 and ESP32 firmware to any web page. Its own site says it works by combining Web Serial, Improv Wi-Fi (optional) and a manifest that describes the firmware.

Wait, what is Web Serial? It is a browser API that lets a page read from and write to serial devices, including USB devices that expose a virtual serial port, which is what an ESP32 dev board does. The browser shows a port picker and you choose the port yourself, so a page cannot open a device behind your back.

Here is what happens when someone presses the button:

  1. The browser asks the user to pick a serial port.
  2. The tool connects to the chip's ROM bootloader and detects the chip. Per the docs, it then selects the right firmware variant from the manifest automatically.
  3. It downloads the parts of that build and writes each one at its offset.
  4. Optionally, it waits for Improv Serial to learn the device's state and offer Wi-Fi setup.

The flashing itself is not reinvented. As of November 2026, the ESP Web Tools package (version 10.5.x) depends on esptool-js, Espressif's JavaScript port of the esptool flasher, along with the Improv serial SDK. That is why the two tools behave alike.

Adding the button to your page takes two snippets, both from the official instructions: load the script, then place the element and point it at your 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>
Ln 3, Col 1UTF-8HTML

Which browsers support it, and why HTTPS?

Web Serial only exists in secure contexts, so the page with the button must be served over HTTPS. ESP Web Tools states this as a Web Serial requirement. The browser also has to implement the API, and that is the real limit.

BrowserWeb SerialNote
Chrome (desktop)Yes, from version 89esptool-js documents Chrome and Edge 89 or later
Edge (desktop)Yes, from version 89Mirrors Chrome in MDN's compatibility data
Chrome on AndroidYes, from version 148Versions 138 to 147 only saw Bluetooth serial ports
Firefox (desktop)Yes, from version 151MDN data. I have not tested it
Firefox on AndroidNoMDN data
Safari, any iOS browserNoMDN data. ESP Web Tools also says not iOS

The versions come from MDN's browser compatibility data as of November 2026, and MDN itself marks the feature as not Baseline. I only checked the OpenGizmo flasher's behavior in code, not in each browser. Its card shows "Cannot flash from this browser" when navigator.serial is missing or the page is not a secure context.

If you are on Safari or a phone, flash once with a tool installed on a computer: see Arduino IDE vs PlatformIO for ESP32, or for the ESP32-CAM, the ESP32-CAM-MB programmer guide.

How do you write the manifest and pick the offsets?

A manifest is a small JSON file that tells the flasher which firmware to install on which chip. Each build lists the files (parts) to write and the flash offset of each one. This is the smallest useful one, in the format from the ESP Web Tools docs:

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

Part paths are resolved relative to the manifest, and can also be full URLs on other hosts. The fields you are likely to meet:

KeyWhereWhat it does
name, versiontop levelShown in the UI. The name is compared with the firmware the device reports through Improv
builds[].chipFamilybuildESP8266, ESP32, ESP32-C2, ESP32-C3, ESP32-C5, ESP32-C6, ESP32-C61, ESP32-H2, ESP32-P4, ESP32-S2 or ESP32-S3
builds[].parts[]buildA file path and the integer flash offset to write it at
builds[].serialTypebuildcdc or uart: a separate build for native USB or a USB-UART bridge
new_install_prompt_erasetop leveltrue lets the user choose to erase everything on a new installation
new_install_improv_wait_timetop levelSeconds to wait for an Improv response after install (10 by default, 0 turns Improv off)
home_assistant_domain, funding_urltop levelOptional links shown after the install

The offsets depend on the chip and on how you built the firmware. For a firmware split into four files, the ESP-IDF documentation puts the second-stage bootloader at 0x1000 on the ESP32 and at 0x0 on the ESP32-S3. The S3 page also puts the partition table at 0x8000 by default. In the PlatformIO builds I ship, the boot_app0 image goes at 0xE000 and the app at 0x10000. Never guess: read them from your build, as the next section does.

Do you need a merged firmware file?

For an ESP32 built with ESP-IDF 4 or later, the ESP Web Tools docs say you do. The reason they give: when the four files are installed with the esptool command, esptool patches the flash frequency, size and mode to match the target device, and ESP Web Tools cannot do that on the fly. So you build one image with merge_bin and list it at offset 0.

Merge the four parts (command from the ESP Web Tools docs)
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

Separate parts can also work: the example manifest in the ESP Web Tools README lists four files, with a bootloader named bootloader_dout_40m.bin whose flash settings were already chosen at build time. The merge is the documented route when you start from a normal build. The docs add two caveats: use dout when your memory type is opi_opi or opi_qspi, and override qio or qout to dio. The merged file has a price worth knowing about. The esptool documentation says that in the raw format the gaps between files are filled with 0xFF bytes, the value of erased flash. A merged image therefore covers the whole range from the bootloader to the app, including the settings area between the partition table and boot_app0. Keep that in mind for the update section.

How does OpenGizmo flash from the browser without the web component?

Each OpenGizmo project page has a firmware card that is not the ESP Web Tools element. It is the component app/components/projects/FlashFirmware.vue in the site's source, which imports ESPLoader and Transport from esptool-js (version 0.7.1 in the site's package.json) and reads a manifest in the ESP Web Tools format. So the format is shared, and only the front end differs.

Open-source ESP32 + MAX7219 project
Gizmo Ticker

A WiFi-connected crypto display built with an ESP32, a MAX7219 LED matrix, and a Nuxt 4 web app for browser-based setup and configuration.

  • Live crypto ticker
  • MAX7219 LED matrix
  • Web-based setup
Check it out

Here is the real manifest the Gizmo Ticker card reads, at https://cdn.opengizmo.dev/gizmo-ticker/manifest.json (fetched on November 14, 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
        }
      ]
    }
  ]
}
Ln 28, Col 1UTF-8JSON

The offsets are decimal, as JSON requires: 32768 is 0x8000, 57344 is 0xE000, 65536 is 0x10000. The Gizmo Reolink Switch manifest has the same four parts on the same chip. The Gizmo Camera manifest has "chipFamily": "ESP32" and its bootloader at 4096 (0x1000), matching the ESP-IDF page above. The other offsets are the same.

One key in these manifests is for the official component only: new_install_prompt_erase: false. The OpenGizmo card never reads it. ESP Web Tools would treat false as its default, which is to erase all data on a new installation.

When you press Flash firmware, the card does this, in this order:

  1. Calls navigator.serial.requestPort() and connects with esptool-js at 115200 baud, which identifies the chip.
  2. Downloads the manifest with cache: 'no-store', so a new release shows up at once.
  3. Looks for the build whose chipFamily equals the detected chip name. If there is none, it stops with "This firmware is not built for the connected chip", so an ESP32 image never lands on an ESP32-S3.
  4. Downloads the four parts one by one, resolving each path against the manifest URL.
  5. Calls writeFlash with flashMode, flashFreq and flashSize set to 'keep', eraseAll: false and compress: true.
  6. Resets the board.

Why not use the web component? I can point to three things in the code, and I did not try the official button with these manifests, so I can't say how it would behave:

  • The four parts stay separate. With 'keep', esptool-js leaves the bootloader's header as the build made it, so no merge step is needed. And the parts skip the settings area, which a merged file would overwrite.
  • A reset fix. A comment in the site's app/utils/hardReset.js says esptool-js only releases RTS, which does nothing when the line is already released, as it is over the chip's own USB on the ESP32-S3. The board then stayed in the bootloader until unplugged. The site passes its own reset: DTR released, RTS held for 100 ms, then released.
  • A tailored card. It shows the version before flashing, four stages (connect, download, flash, reboot), a log, the release notes of the version it installs, and translated messages.

The firmware has no Improv support: I found no Improv code in the three repositories. The first Wi-Fi setup goes through a captive portal instead. The Wi-Fi provisioning comparison covers Improv against the alternatives, and the captive portal fix guide covers the portal.

The Gizmo Ticker's four flash parts and their offsets, with the settings area at 0x9000 left alone

What is the shortest path to your own install page?

Here is the whole job in order, for your own firmware:

  1. Build the firmware and collect its parts with their offsets (or one merged file at offset 0 for ESP Web Tools).
  2. Upload the parts and a manifest.json that lists them to an HTTPS host, with CORS headers if it is not the page's own site.
  3. Add the <script> and <esp-web-install-button> snippet above to an HTTPS page, with the manifest URL.
  4. Open the page in Chrome or Edge on a desktop, plug in the board with a data cable, press the button and pick the port.
  5. Check that the board boots your firmware and that the page offers the right build for each chip you list.

Where do you host the firmware, and what about CORS?

You can host the manifest and the parts on the same site as the install page, which needs no CORS setup. OpenGizmo keeps them on a CDN (cdn.opengizmo.dev, backed by a Cloudflare R2 bucket in the release workflow), so the browser makes cross-origin requests. ESP Web Tools tells you to send Access-Control-Allow-Origin: https://domain-of-your-website.com in that case.

I checked it on November 14, 2026 by requesting the Ticker manifest with Origin: https://opengizmo.dev: the response carried access-control-allow-origin: https://opengizmo.dev and vary: Origin, and a preflight request returned 204 with access-control-allow-methods: GET. The CDN allows only the site's origin, not *. Test your own with curl -I -H "Origin: https://your.site" <manifest-url>.

How do you release a new version without losing Wi-Fi settings?

Keep each version's files in their own folder, never change them, and move the manifest last. OpenGizmo's release workflow does this on a manual run from main:

A browser shows the flash memory being written in four orange parts while one grey part stays locked and untouched, with a XIAO board on USB-C

  1. Reads VERSION and stops if the tag exists or the web app version differs.
  2. Runs the web app tests and the native firmware tests, then builds the firmware.
  3. Runs package_firmware.py, which asks PlatformIO for the flash images and their offsets (pio project metadata) and writes manifest.json.
  4. Creates a GitHub release with the parts, whose notes give an esptool command for flashing over USB.
  5. Uploads the parts with Cache-Control: public, max-age=31536000, immutable, then the manifest with max-age=60.

Uploading the manifest last means the website only offers a version that is fully uploaded, and a one-minute cache means a release shows up within a minute. The headers I saw on November 14, 2026 match this.

The settings survive because of what is not written. The projects use the huge_app.csv partition table, in which the Arduino core defines nvs at 0x9000 (0x5000 bytes) and otadata at 0xE000. The four parts do not cover the nvs region (0x9000 to 0xDFFF), and eraseAll is false, so the Preferences data lives on. That follows from the offsets and the code. I did not measure a flash before and after. The partition table guide explains the layout, and the OTA comparison explains why these devices update over USB, as they have no second app slot.

With the official component, read the erase rule: ESP Web Tools erases all data on a new installation unless new_install_prompt_erase is true and the user declines. It offers a new installation when it cannot detect the device's current firmware, or when the detected firmware does not match the manifest name.

What breaks most often?

Most failures are the cable, the port or the browser, not the firmware. Work down this table, changing one thing at a time.

What you seeLikely causeWhat to try
Button disabled, or 'Cannot flash from this browser'Browser without Web Serial, or the page is not HTTPSUse Chrome or Edge on a desktop, over HTTPS or localhost
Port picker shows no deviceCharge-only USB cable, or the board is not detectedUse a data cable and another USB port, then reload the page
Connecting fails, no serial data receivedThe chip is not in download mode, or the USB link is flakySee the 'Failed to connect' guide
'This firmware is not built for the connected chip'The manifest has no build for that chip familyAdd a build for it, or use the right board
'Firmware download failed with status 404'A part path in the manifest is wrongOpen each part URL in a tab
Manifest cannot be read, with a CORS error in the consoleThe CDN does not allow your page's originSend Access-Control-Allow-Origin for your domain
Flash finishes but the board sits in the bootloaderNo real reset pulse after flashingUnplug and replug; a custom hard reset like the one above fixes it

For the third row, Failed to Connect to ESP32: No Serial Data Received walks through boot mode, cables and drivers. The error texts in the table are the ones in the OpenGizmo card's translation file, and your own page will say something else.

Where does browser flashing stop?

Browser flashing gives you a page where anyone with Chrome or Edge, a cable and a board can install your firmware in a minute, with the settings kept and a version number on screen. We covered the pieces: Web Serial over HTTPS, a manifest of parts and offsets (merged for ESP Web Tools, or four parts with esptool-js), CORS if the files live elsewhere, and a release that uploads the manifest last.

Three limits remain. It only covers wired flashing; for updates over Wi-Fi see the OTA methods comparison. Browser support outside Chrome and Edge is thin as of November 2026, and I tested none of it. And I only described the official component from its docs and source, not from my own use. If you want to see the whole thing working, the Gizmo Ticker build guide flashes a board from start to finish, and the three project pages each have the card.

Frequently asked questions

Find quick answers to the most common questions about this topic.

Yes. A page that uses ESP Web Tools or esptool-js talks to the board through the Web Serial API, so you only need a data USB cable and Chrome or Edge on a desktop. The page must be served over HTTPS. You pick the serial port, and the firmware is written from the browser.

Published

Ready to build your own gizmo?

Pick an open-source ESP32 project and follow its step-by-step guide, from the parts list and wiring to the firmware and the first boot.

Read also

Explore categories