The WebSerial ESPTool was designed to be a web-capable option for programming ESP32-S2 boards. It allows you to erase the contents of the microcontroller and program up to 4 files at different offsets.

This tool is a good alternative to folks who cannot run Python on their computer or are having difficulty installing or using

Enabling Web Serial

You will have to use the Chrome browser for this to work, Safari and Firefox, etc are not supported because we need Web Serial and only Chrome is supporting it to the level needed.

At the time of this tutorial, you'll need to enable the Serial API, which is really easy.

Visit  chrome://flags from within Chrome. Find and enable the Experimental Web Platform features


Restart Chrome


Before you can use the tool, you will need to put your board in bootloader mode and connect. Here are the steps:

In the Chrome browser visit You should see something like the image shown.

Enter the ROM bootloader by holding down the BOOT0 button while clicking Reset.

Press the Connect button in the top right of the web browser. You will get a pop up asking you to select the COM or Serial port.

Remember, you should remove all other USB devices so only the ESP32 board is attached, that way there's no confusion over multiple ports!

On some systems, such as MacOS, there may be additional system ports that appear in the list.

The Javascript code will now try to connect to the ROM bootloader. It may timeout for a bit until it succeeds. On success, you will see that it is Connected and will print out a unique MAC address identifying the board along with other information that was detected.

Once you have successfully connected, the command toolbar will appear.

Erasing the Contents

If you would like to erase the entire flash area so that you can start with a clean slate, you can use the erase feature. We recommend doing this if you are having issues.

To erase the contents, click the Erase button. You will be prompted whether you want to continue. Click OK to continue or if you changed your mind, just click cancel.

You'll see "Erasing flash memory. Please wait..." This will eventually be followed by "Finished." and the amount of time it took to erase.

Do not disconnect! Immediately continue on to programming the ESP32.

Program the ESP32

You can click on Choose a file... from any of the available buttons. It will only attempt to program buttons with a file and a unique location. Then select the Adafruit CircuitPython BIN files (not the UF2 file!)

Verify that the Offset box next to the file location you used is 0x0.

Once you choose a file, the button text will change to match your filename. You can then select the Program button to start flashing.

A progress bar will appear and after a minute or two, you will have written the firmware. Press the Reset button to get out of the ROM bootloader and you should see a MAGTAGBOOT drive (METROS2BOOT for the Metro) appear in your computer file explorer/finder.

You're now ready to copy the CircuitPython UF2 on to the drive which will set up CircuitPython!

After using the tool, press the reset button to get out of bootloader mode and launch the new firmware!

This guide was first published on Nov 10, 2020. It was last updated on 2022-07-27 15:06:38 -0400.

This page (Web Serial ESPTool) was last updated on Aug 16, 2022.

Text editor powered by tinymce.