The FunHouse microcontroller ships running a full sensor test and DotStar swirl. The sensor data is shown on the display. It's lovely, but you probably had other plans for the board. As you start working with your board, you may want to return to the original code to begin again, or you may find your board gets into a bad state. Either way, this page has you covered.

You're probably used to seeing the HOUSEBOOT drive when loading CircuitPython or Arduino. The HOUSEBOOT drive is part of the UF2 bootloader, and allows you to drag and drop files, such as CircuitPython. However, on the ESP32-S2 the UF2 bootloader can become damaged.

Factory Reset Firmware UF2

If you have a bootloader still installed - which means you can double-click to get the HOUSEBOOT drive to appear, then you can simply drag this UF2 file over to the BOOT drive.

To enter bootloader mode, plug in the board into a USB cable with data/sync capability. Press the reset button once, wait till the RGB LED turns purple, then press the reset button again. Then drag this file over:

Your board is now back to its factory-shipped state! You can now begin again with your plans for your board.

Factory Reset and Bootloader Repair

What if you tried double-tapping the reset button, and you still can't get into the UF2 bootloader? Whether your board shipped without the UF2 bootloader, or something damaged it, this section has you covered.

There is no bootloader protection for the UF2 bootloader. That means it is possible to erase or damage the UF2 bootloader, especially if you upload an Arduino sketch to an ESP32-S2/S3 board that doesn't "know" there's a bootloader it should not overwrite!

It turns out, however, the ESP32-S2/S3 comes with a second bootloader: the ROM bootloader. Thanks to the ROM bootloader, you don't have to worry about damaging the UF2 bootloader. The ROM bootloader can never be disabled or erased, so its always there if you need it! You can simply re-load the UF2 bootloader from the ROM bootloader.

Completing a factory reset will erase your board's firmware which is also used for storing CircuitPython/Arduino/Files! Be sure to back up your data first.

There are two ways to do a factory reset and bootloader repair. The first is using WebSerial through a Chromium-based browser, and the second is using esptool via command line. We highly recommend using WebSerial through Chrome/Chromium.

The next section walks you through the prerequisite steps needed for both methods.

Download .bin and Enter Bootloader

Step 1. Download the factory-reset-and-bootloader.bin file

Save the following file wherever is convenient for you. You will need to access it from the WebSerial ESPTool.

Note that this file is approximately 3MB. This is not because the bootloader is 3MB, it is because the bootloader is near the end of the available flash. Most of the file is empty but its easier to program if you use a combined file.

Step 2. Enter ROM bootloader mode

Entering the ROM bootloader is easy. Complete the following steps.

Before you start, make sure your ESP32-S2/S3 is plugged into USB port to your computer using a data/sync cable. Charge-only cables will not work!

Turn on the On/Off switch - check that you see the OK light on so you know the board is powered, a prerequisite!

To enter the bootloader:

  1. Press and hold the BOOT/DFU button down. Don't let go of it yet!
  2. Press and release the Reset button. You should still have the BOOT/DFU button pressed while you do this.
  3. Now you can release the BOOT/DFU button.

No USB drive will appear when you've entered the ROM bootloader. This is normal!

Now that you've downloaded the .bin file and entered the bootloader, you're ready to continue with the factory reset and bootloader repair process. The next two sections walk you through using WebSerial and esptool.

The WebSerial ESPTool Method

We highly recommend using WebSerial ESPTool method to perform a factory reset and bootloader repair. However, if you'd rather use esptool via command line, you can skip this section.

This method uses the WebSerial ESPTool through Chrome or a Chromium-based browser. The WebSerial ESPTool was designed to be a web-capable option for programming ESP32-S2/S3 boards. It allows you to erase the contents of the microcontroller and program up to four files at different offsets.

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

Follow the steps to complete the factory reset.

If you're using Chrome 88 or older, see the Older Versions of Chrome section at the end of this page for instructions on enabling Web Serial.

Connect

You should have plugged in only the ESP32-S2/S3 that you intend to flash. That way there's no confusion in picking the proper port when it's time!

In the Chrome browser visit https://nabucasa.github.io/esp-web-flasher/. You should see something like the image shown.

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-S2/S3 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.

Erase the Contents

This will erase everything on your board! If you have access, and wish to keep any code, now is the time to ensure you've backed up everything.

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-S2/S3.

Do not disconnect after erasing! Immediately continue on to the next step!

Program the ESP32-S2/S3

Programming the microcontroller can be done with up to four files at different locations, but with the board-specific factory-reset.bin file, which you should have downloaded under Step 1 on this page, you only need to use one file.

Click on the first Choose a file.... (The tool will only attempt to program buttons with a file and a unique location.) Then, select the *-factory-reset.bin file you downloaded in Step 1 that matches your board.

Verify that the Offset box next to the file location you used is (0x) 0.

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

A progress bar will appear and after a minute or two, you will have written the firmware.

Once completed, you can skip down to the section titled Reset the Board.

The esptool Method (for advanced users)

If you used WebSerial ESPTool, you do not need to complete the steps in this section!

Once you have entered ROM bootloader mode, you can then use Espressif's esptool program to communicate with the chip! esptool is the 'official' programming tool and is the most common/complete way to program an ESP chip.

Install ESPTool.py

You will need to use the command line / Terminal to install and run esptool.

You will also need to have pip and Python installed (any version!).

Install the latest version using pip (you may be able to run pip without the 3 depending on your setup):

pip3 install --upgrade esptool

Then, you can run:

esptool.py

Make sure you are running esptool v3.0 or higher, which adds ESP32-S2/S3 support.

Test the Installation

Run esptool.py in a new terminal/command line and verify you get something like the below:

Connect

Run the following command, replacing the identifier after --port with the COMxx, /dev/cu.usbmodemxx or /dev/ttySxx you found above.

esptool.py --port COM88 chip_id

You should get a notice that it connected over that port and found an ESP32-S2/S3.

Installing the Bootloader

Run this command and replace the serial port name with your matching port and the file you just downloaded

esptool.py --port COM88 write_flash 0x0 tinyuf2_combo.bin

Don't forget to change the --port name to match.

There might be a bit of a 'wait' when programming, where it doesn't seem like it's working. Give it a minute, it has to erase the old flash code which can cause it to seem like it's not running.

You'll finally get an output like this:

Once completed, you can continue to the next section.

Reset the board

Now that you've reprogrammed the board, you need to reset it to continue. Click the reset button to launch the new firmware.

The display will show the FunHouse sensor data, and the DotStar LEDs will light up in a rainbow swirl.

You've successfully returned your board to a factory reset state!

Older Versions of Chrome

As of chrome 89, Web Serial is already enabled, so this step is only necessary on older browsers.

We suggest updating to Chrome 89 or newer, as Web Serial is enabled by default.

If you must continue using an older version of Chrome, follow these steps to enable Web Serial.

If you receive an error like the one shown when you visit the WebSerial ESPTool site, you're likely running an older version of Chrome.

You must be using Chrome 78 or later to use Web Serial.

To enable Web Serial in Chrome versions 78 through 88:

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

The Flash an Arduino Sketch Method

This section outlines flashing an Arduino sketch onto your ESP32-S2/S3 board, which automatically installs the UF2 bootloader as well.

Arduino IDE Setup

If you don't already have the Arduino IDE installed, the first thing you will need to do is to download the latest release of the Arduino IDE. ESP32-S2/S3 requires version 1.8 or higher. Click the link to download the latest.

After you have downloaded and installed the latest version of Arduino IDE, you will need to start the IDE and navigate to the Preferences menu. You can access it from the File > Preferences menu in Windows or Linux, or the Arduino > Preferences menu on OS X.

The Preferences window will open.

In the Additional Boards Manager URLs field, you'll want to add a new URL. The list of URLs is comma separated, and you will only have to add each URL once. The URLs point to index files that the Board Manager uses to build the list of available & installed boards.

Copy the following URL.

https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_dev_index.json

Add the URL to the the Additional Boards Manager URLs field (highlighted in red below).

Click OK to save and close Preferences.

In the Tools > Boards menu you should see the ESP32 Arduino menu. In the expanded menu, it should contain the ESP32 boards along with all the latest ESP32-S2 boards.

Now that your IDE is setup, you can continue on to loading the sketch.

Load the Blink Sketch

In the Tools > Boards menu you should see the ESP32 Arduino menu. In the expanded menu, look for the menu option for the Adafruit FunHouse, and click on it to choose it.

Open the Blink sketch by clicking through File > Examples > 01.Basics > Blink.

Once open, click Upload from the sketch window.

Once successfully uploaded, the little red LED will begin blinking once every second. At that point, you can now enter the bootloader.

This guide was first published on Apr 20, 2021. It was last updated on 2022-07-27 15:06:29 -0400.

This page (Factory Reset) was last updated on Aug 05, 2022.

Text editor powered by tinymce.