GETTING STARTEDBY UNEXPECTED MAKER

Getting started with your board.

Welcome to your new Unexpected Maker board! This guide will help you connect it, explore its features and start creating your own projects.

Choose your MCU

Match the chip on your board. The connection, coding and recovery instructions below will change to suit.

Showing the ESP32-S3 guide.

Connect your ESP32-S3 board

  • TinyS3[D]
  • FeatherS3[D]
  • ProS3[D]
  • EdgeS3[D]
  • TinyS3
  • FeatherS3
  • ProS3
  • NanoS3
  • OMGS3
  • FeatherS3 Neo

Connect your UM ESP32-S3 board to your computer with a USB-C power and data cable.

Connecting OMGS3, NanoS3 or EdgeS3[D]

These modules do not have a USB socket on the board.

  • OMGS3 and NanoS3: use a carrier or your own circuit to connect a USB socket to the module’s D+, D−, 5 V and GND connections. Connect the computer to that socket with a USB data cable.
  • EdgeS3[D]: fit the module into a compatible EdgeS3[D] carrier with a USB connection, then connect the carrier to your computer.

Your board comes with CircuitPython pre-installed

A demo program is already installed and starts automatically when you power up the board.

If your board includes an RGB LED, you will see it cycling through the rainbow when powered up.

Use the CIRCUITPY drive

Your board appears on your computer as a USB drive named CIRCUITPY. It is the board’s own file system: copy files onto it and off it in Finder on macOS or File Explorer on Windows, just like a USB flash drive.

Each time your board powers up or resets, CircuitPython looks for code.py on the drive and runs it. On your new board, code.py contains a demo program; edit it or replace it with your own.

Edit files directly on the drive, or work on them on your computer and copy them across. Whenever a file on CIRCUITPY changes, CircuitPython reloads and runs code.py.

If you are new to CircuitPython, Adafruit’s Welcome to CircuitPython guide walks you through editing code and using the serial console.

Choose your language and tools

CircuitPython, MicroPython, Arduino, ESP-IDF, PlatformIO, Rust and more. Step-by-step setup for each one is on the Develop page.

CircuitPython

MicroPython

Arduino

ESP-IDF

PlatformIO

.NET nanoFramework

Rust

PHP

TinyGo

JavaScript

Lua

Erlang / Elixir

Explore languages and tools on the Develop page →

Flash new firmware

Switching to a different platform means installing different firmware. Erase the flash first: it removes the previous program, its settings and its filesystem.

These commands are for esptool 5.4.0, the latest release. Replace PORT with your board’s port. esptool documentation →

esptool --chip esp32s3 --port PORT erase-flash

Enter download mode

Download mode lets the computer install firmware without running the program already on your board. Close any serial monitor before uploading.

1Hold BOOT

Keep BOOT pressed.

2Tap RESET

Press and release RESET while still holding BOOT.

3Release BOOT

Select the download-mode port on your computer.

There is no LED signal to confirm download mode. Check the computer’s port list instead. On boards using the chip’s USB connection, a different serial port can appear after the button sequence.

If you manually put your board into download mode, press RESET after the upload finishes to start your code running. Open the port list again and select the port used by the running program.

Battery & power

Every Unexpected Maker board can run from a single-cell LiPo battery, and it charges the battery whenever USB or 5 V power is connected.

Choose and connect a battery

  • Use a compatible protected single-cell LiPo battery: 3.7 V nominal, 4.2 V fully charged.
  • Check positive and negative against the board markings. Matching connector shapes do not guarantee matching polarity. The battery input on all UM boards has reverse polarity protection, but other connected hardware could still be damaged, so be careful.
  • Connect only to the documented battery input or VBAT/GND pins. Do not connect a LiPo directly to 3V3 or 5V, and do not use multi-cell packs or non-rechargeable batteries on a charging input.

Your board’s pin reference shows where to connect the battery.

Charging and runtime

A battery with a larger capacity runs your board for longer, but takes longer to charge, because the board charges it at a fixed current.

How long a battery lasts also depends on how much current your project draws, how much it uses Wi-Fi, and whether it uses sleep modes.

When your board is powered only from the battery, there is no 5V output from the 5V header pin.

UM battery connections →Charging current →

Use your board’s helper libraries

Helper libraries give your code simple access to your board’s own hardware, such as its RGB LED, battery monitoring and, on Series[D] boards, the antenna switch. You call the helper instead of looking up pins and writing that code yourself.

Each platform has its own helper library. Choose the tab for the platform you use.

Restore the shipping files

The firmware and the files on CIRCUITPY are separate. Reinstalling firmware does not restore the UM demo, its helper module or the libraries it imports.

  1. Open the shipping-files folder for your board in the UM repository.
  2. Copy that folder’s contents to CIRCUITPY. Keep the helper beside code.py and keep the dependencies inside lib.
  3. Press RESET and open the serial console. If Python reports a missing module, copy that module from the same shipping-files folder.

Series[D] CircuitPython shipping files →Original S3 shipping files →

Select the antenna on TinyS3[D]

GPIO38 controls the switch: LOW selects onboard and HIGH selects external. This example selects the onboard antenna. Change False to True to select external.

import digitalio
import microcontroller

antenna = digitalio.DigitalInOut(microcontroller.pin.GPIO38)
antenna.switch_to_output(value=False)  # False: onboard. True: external.

The GPIO38 example is only for TinyS3[D]. For other Series[D] boards, use their helper.

Read the battery fuel gauge

The Series[D] CircuitPython shipping files include the MAX17048 driver in lib. Restore that folder along with the board helper.

For OMGS3, use the OMGS3 CircuitPython helper and its accompanying libraries from the OMGS3 shipping files in the S3 repository. Its fuel gauge is the same chip, but its board helper is separate from the Series[D] helpers.

Read the original TinyS3 battery voltage

With tinys3.py from the original TinyS3 shipping files on CIRCUITPY, save this as code.py and read the serial console. This example uses the original board’s voltage measurement; TinyS3[D] uses a fuel gauge instead.

import tinys3

print("USB power present:", tinys3.get_vbus_present())
print("Battery voltage:", tinys3.get_battery_voltage(), "V")

Series[D]: choose an antenna

The onboard antenna is selected by default. You can use Wi-Fi without fitting an external antenna or adding antenna-selection code. To use an external antenna, connect it to the u.FL socket and select it in your program. You can change back to the onboard antenna while the program is running.

With the UM SeriesD Helper in Arduino:

#include <UMSeriesD.h>

UMSeriesD umseriesd;

void setup() {
    umseriesd.begin();
    umseriesd.setAntennaExternal(true);  // true: external u.FL antenna, false: onboard
}

void loop() {
}

Read the battery fuel gauge

OMGS3, TinyS3[D], FeatherS3[D], ProS3[D] and EdgeS3[D] use a MAX17048 fuel gauge connected over I²C. It reports the battery voltage and estimates the remaining charge. The original TinyS3, FeatherS3 and ProS3 measure battery voltage through an ADC instead; their battery-reading code does not read a MAX17048.

With the UM SeriesD Helper in Arduino:

#include <UMSeriesD.h>

UMSeriesD umseriesd;

void setup() {
    Serial.begin(115200);
    umseriesd.begin();
}

void loop() {
    Serial.printf("Battery: %.2f V\n", umseriesd.getBatteryVoltage());
    delay(1000);
}

S3 Series[D] files and helpers →All UM S3 files →

If something isn’t working

The board powers up, but no serial port appears

Try a known data cable and a direct computer port. Disconnect attached hardware, then enter download mode. Download mode bypasses your installed program. If a port appears in download mode but disappears after RESET, check the installed firmware and its USB settings. If no port appears in either mode, try another cable and USB port, then check whether the computer detects a USB device at all. On Linux, check serial-device permissions. On Windows, inspect Device Manager for a device or driver error.

I can’t see a CIRCUITPY drive

CIRCUITPY appears when CircuitPython is running with its USB filesystem enabled. It is not expected while Arduino or MicroPython is running, or while the chip is in ROM download mode. A bootloader drive is a different drive. Check which firmware and mode you are using before attempting recovery.

Uploads fail or the port is busy

Close serial monitors, other IDEs and browser tabs connected to the board. Reselect the port after entering download mode. Check the MCU, board definition and firmware file. If transfers start but fail, try a shorter cable, direct USB connection or lower upload speed.

The upload finishes, but there’s no output

Press RESET, then check the port again. Set the monitor to the baud rate used by your program. For Arduino over USB, check USB CDC On Boot; for ESP-IDF, check the console channel. If the board repeatedly resets, verify its flash and PSRAM configuration and power supply.

The RGB LED or battery example does not work

Check the board revision, helper version and pin reference. Some boards need the LED supply or a second regulator enabled. NeoPixel and DotStar LEDs use different drivers. Battery examples must also match the hardware: an ADC voltage-reading example cannot read an I²C fuel gauge. Test with the matching UM example before changing wiring or pin definitions.

Visit the UM knowledge base →Ask the UM community →