The WebSerial ESPTool was designed to be a web-capable option for programming Espressif ESP family microcontroller boards that have a serial based ROM bootloader. It allows you to erase the contents of the microcontroller and program up to 4 files at different offsets.
For boards that lack native USB, like the ESP32 or ESP32-C3 microcontroller, this is how any firmware like CircuitPython .bin files can be loaded. There is no drag-and-drop to a folder option for these boards.
For boards with native USB, like ESP32-S2, -S3, etc. this is how the UF2 bootloader .bin file can be loaded. Once the UF2 bootloader is on, firmware like CircuitPython .uf2 files can be drag-and-dropped to a BOOT folder.
This tool is a good alternative for folks who cannot run Python esptool.py on their computer or are having difficulty installing or using esptool.py
You will have to use the Chrome or Chromium-based browser for this to work. For example, Edge and Opera are Chromium. Safari and Firefox, etc are not supported - they have not implemented Web Serial!
Connecting
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 https://adafruit.github.io/Adafruit_WebSerial_ESPTool/. You should see something like the image shown.
For all ESP32-family boards, you can enter the ROM bootloader by holding down the BOOT button while clicking RST.
If you have an ESP32 board without BOOT (say because its an original ESP32, not -S2 or -S3, etc) you can skip this step because there's an auto-boot circuit.
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. Look for something with ESP32, JTAG Loader, SLAB, or FTDI in the name.
Remember, you should remove all other USB devices so only the target 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.
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 ESP Microcontroller.
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 .bin file(s) - 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.
For boards lacking native USB, like the ESP32 and ESP32-C3, no folder will show up after pressing reset. If CircuitPython firmware was loaded, the REPL can be accessed over a serial COM port.
For other boards, like ESP32-S2, -S3, etc., a BOOT folder should show up. A CircuitPython UF2 file can now be copied over to the BOOT folder, after which the CIRCUITPY folder should then show up.
