Congratulations!

If you are visiting this page, it’s likely you are a proud owner of a new Unexpected Maker ESP32-S3 board - congratulations!

We’ve put together this getting started guide to help you get familiar with your new ESP32-S3 board, and showcase some of the main features of the boards.

If you don’t already own a ESP32-S3 board from Unexpected Maker, you can buy one from here!

Hooking it up!

All you need to do to get started is to plug your board into your computer using a USB-C Power + Data cable.

Your ESP32-S3 board ships with CircuitPython pre-installed and has some hello world code on it that runs when you power it up.

Once it starts up, you'll see a USB drive appear in your filesystem called CIRCUITPY and on the drive, you'll find a file named code.py that is currently running on your board. If you are new to CircuitPython, or would like to level up your CircuitPython skills, please check out Adafruit's Welcome to CircuitPython learn guide.

Regarding CircuitPython, Please Note!

The ESP32-S3 is brand spanking new, and support for the MCU in CircuitPython (and other development environments) is very early. The version of CircuitPython that ships on your new board is likely an early alpha and though it's usable on your board, it might have some unknown bugs or be missing some of the newer features of the ESP32-S3. Keep your eyes on the CircuitPython downloads page for your board to see if newer updates are available. The CircuitPython dev team are super active!

Powering From Battery

Your ESP32-S3 boards comes with support for using a battery to power your projects as well as the ability to charge your battery off the USB connector (or 5V pin if you are using an external 5V power supply).

The TinyS3 comes with a separate JST PH connector that you can solder onto the bottom of the board, as well as a VBAT header pin next to a GND pin to allow you to connect a battery via the headers.

The FeatherS3 and ProS3 come with a battery connector on the board. The FeatherS3 has a JST PH connector and the ProS3 has a PicoBlade connector. Both also a VBAT header pin next to a GND pin to allow you to connect a battery via the headers.

You can use any size, single cell Li-Po battery to power your ESP32-S3 boards. Obviously, the larger the mAH rating of the battery, the longer it will last.

Please use LiPo-Batteries with charge protection included on them. Most hobby RC batteries do not have over discharge protection, and if a battery discharges too much, it can damage it and it might never be able to hold a proper charge again.

NOTE: When connecting a battery to your ESP32-S3 board, please check the polarity of the battery, as not every battery is wired the same way. The IC I use for charging does have in-built reverse voltage protection, but it’s better not to tempt fate!

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 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 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")

Examples use the tinys3.py helper library, but each board has it's own helper - feathers3.py & pros3.py

Coding Platforms

You are able to develop on your ESP32-S3 in a variety of languages and platforms. Right now it's Espressif IDF, Arduino, CircuitPython and MicroPython. But other interesting languages are becoming available as well, like RUST and Go (TinyGO).

For more information about each of the platforms available for your ESP32-S3 boards, please see the PLATFORMS section specific to your board.

Re-Flashing 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:

  • Press and hold the [BOOT] button down
  • Click the [RESET] button
  • Release the [BOOT] button

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:

  • Click [RESET]
  • When the RGB LED is turns purple, click [BOOT]

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.

Shape 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.

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 he [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 for flashing/re-flashing, you'll want to add:
build_flags = -DARDUINO_USB_MODE=1
To your config, which is the equivalent of 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.