Flashing Code Onto Your Board

From time to time, you might want to try out different programming languages on your ESP32-S3 board, or you might just want to update the version of CircuitPython or MicroPython you are using. To achieve this, you'll need to learn how to put your board into different boot modes.

Getting into DOWNLOAD Mode

Putting your board into Download Mode will force your board to restart in the CDC bootloader mode and enumerate a new serial device (COM port for Windows users). Form there you can flash the board using that serial port.

This mode is used to flash a new version of the UF2 bootloader, or a new version of MicroPython onto your board, or even to flash some IDF or Arduino Code, if you are not enabling the native USB on boot-up.

To get your board into Download mode:
There is no visual cue on the board that it is in Download mode, but you should now see a new serial device appear.

Getting into UF2 Bootloader Mode

Putting your board into UF2 Bootloader will force your board to restart and present you with a USB mass storage device in your file explorer - assuming you have the UF2 bootloader still installed and you have not stomped it by flashing Arduino, MicroPython or IDF code on the board.

All Unexpected maker ESP32-S3 boards ship with CircuitPython and the UF2 Bootloader installed by default.

To get your board into UF2 bootloader mode:
You should now be in the UF2 bootloader mode. You will then see the RGB LED on your board turn green once the filesystem is mounted.

Flashing in the Arduino IDE

When using the Arduino IDE for development, there are a few things you need to be aware of.

The Unexpected Maker ESP32-S3 boards leverage the native USB inside the S3 chip and do not use an external SerialUART chip like older ESP32 boards did. This means you need to enable the CDC on boot option in the Arduino IDE tools menu to ensure the native USB is enabled when your code runs.

Please also select the USB OTG (TinyUSB) option and ensure you have selected the correct UM Board definition from the boards list:

UM Tinys3, UM FeatherS3 & UM ProS3

NOTE! There is a ROM Mask bug in the current ESP32-S3 silicon that prevents the flashing process from resetting the board after flashing has finished, which means for now, you need to manually press the [RESET] button after flashing to manually reset the board so your code start running. Updated silicon from Espressif will fix this issue hopefully!

Using PlatformIO

When using the PlatformIO for development, to enable the native USB (TinyUSB) for flashing/re-flashing, you'll want to add:

build_flags =
	'-D ARDUINO_USB_MODE=0'
	'-D ARDUINO_USB_CDC_ON_BOOT=1'

To your platformio.ini, which is the equivalent of setting TinyUSB Mode and enabling the Enable the CDC on boot option in the Arduino IDE.

NOTE! As PlatformIO leverages the Arduino ESP32 Core, it also suffers from the same issue where your board cannot be automatically restarted after being flashed, and will require you to manually press the [RESET] button yourself to get your code to start.

Helper Libraries

I have put together helper libraries for CircuitPython, MicroPython & Arduino to help you access certain functions of your ESP32-S3 board in an easy way.

The Arduino Helper Library is downloaded from the library manager within the Arduino IDE. Please search for the library called UMS3 Helper

The MicroPython version of the helper is compiled into the firmware itself, where as the CircuitPython version is sitting in the filesystem on your board.

The included CircuitPython code that runs when your board powers up uses the helper library to do certain things, like cycle the RGB LED, turn the RGB LED power on (or the second LDO if the board is a FeatherS3 or ProS3) and it shows you how much Flash and RAM you have free.

You can also use the helper library to see if there is 5V power present:

import tinys3
print(f"5V present? {tinys3.get_vbus_present()}")

Or check the battery voltage if one is connected:

import tinys3
print(f"VBAT voltage is {tinys3.get_battery_voltage()}v")

For MicroPython or CircuitPython, use the tinys3.py, feathers3.py & pros3.py helper library for each board, and for Arduino, there's one helper library for all 3 boards.