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-S2 guide.
Connect your ESP32 board
- TinyPICO
- TinyPICO Nano
- TinyPICO[D]
Plug your TinyPICO into your computer with a USB power and data cable that fits its connector. TinyPICO boards have either Micro-USB or USB-C, depending on the version; TinyPICO[D] uses USB-C.
Connecting TinyPICO Nano
TinyPICO Nano has no USB socket. Use a carrier or a USB breakout connected to the Nano’s USB data and power connections. Current TinyPICO Nano boards include the USB-to-serial chip on the module.
Your board comes with MicroPython pre-installed
MicroPython on the ESP32 doesn’t appear as a USB drive. You reach it over the board’s USB serial port, which gives you the Python prompt and lets you copy files on and off the board.
On Windows the port is named COM followed by a number; on macOS and Linux it appears as a serial device. If you’re unsure which port is your board, unplug it and reconnect it: the port that disappears and returns is the one to select.
Each time your board powers up or resets, MicroPython runs boot.py and then main.py, if they are on the board. On your new board, main.py contains a demo program; edit it or replace it with your own.
Connect to your board
Use whichever tool you prefer:
- mpremote, MicroPython’s own command-line tool. Install it, open the Python prompt, and copy files onto the board:
pipx install mpremote mpremote connect PORT repl mpremote connect PORT fs cp main.py :main.py - Any serial terminal at 115200 baud, for the Python prompt.
- An editor with MicroPython support, such as Thonny. Select MicroPython (ESP32) and your board’s port.
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.
MicroPython
Arduino
ESP-IDF
PlatformIO
.NET nanoFramework
Rust
PHP
TinyGo
JavaScript
Lua
Erlang / Elixir
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 esp32 --port PORT erase-flashDownload mode is automatic
TinyPICO, TinyPICO[D] and TinyPICO Nano have circuitry that puts the ESP32 into download mode automatically when your flashing tool starts an upload. There are no buttons to press.
Close any serial monitor that is using the board’s port, so the flashing tool can open it. When flashing finishes, the board resets and runs the new firmware.
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.
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.
TinyPICO revisions differ: older boards use a DotStar RGB LED, while Series[D] adds an RF switch and fuel gauge. Use the helper and pin reference for your revision rather than copying LED or battery code from an older TinyPICO.
Start with the examples in the board’s repository linked below. Copy the helper beside code.py and its dependencies into lib.
| Your board | Helper module | What it gives you |
|---|---|---|
| TinyPICO | tinypico | DotStar RGB LED, battery voltage, charging state, deep sleep |
| TinyPICO[D] | tinypicod | RGB LED power, battery voltage and charge level from the fuel gauge, USB power detection, antenna switch, deep sleep |
| TinyPICO Nano | None needed: no onboard LED or battery sensing | — |
Use it
The helper is built into the UM MicroPython firmware for your board, so there’s nothing to install. Import it by name, for example import tinypico.
| Your board | Arduino helper | Install from |
|---|---|---|
| TinyPICO | TinyPICO Helper Library | Library Manager |
| TinyPICO[D] | UM SeriesD Helper | Library Manager |
| TinyPICO Nano | None needed: no onboard LED or battery sensing | — |
Install it
Open Tools → Manage Libraries, search for the library name and click Install.
What it gives you
- TinyPICO Helper Library: DotStar RGB LED power, colour and brightness; battery voltage; charging state
- UM SeriesD Helper: RGB LED power, colour and brightness; battery voltage from the fuel gauge; USB power (VBUS) detection; antenna switch: onboard or external
Examples
After installing, open File → Examples and choose the library. Start with the LED example to confirm the library matches your board.
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.
On TinyPICO[D], GPIO12 controls the antenna switch: LOW selects onboard and HIGH selects external. This applies to the D board; the original TinyPICO has no software antenna switch.
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
TinyPICO[D] uses a MAX17048 fuel gauge connected over I²C. It reports the battery voltage and estimates the remaining charge. The original TinyPICO measures battery voltage through an ADC instead; its battery-reading code does not read a MAX17048.
Use the MAX17048 driver with the I²C pins marked SCL and SDA on your board’s pin reference. Connect a battery before checking its readings; USB power alone does not provide a battery state-of-charge measurement.
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);
}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. Check the USB-to-serial bridge driver for your board. On Linux, check serial-device permissions. On Windows, inspect Device Manager for a device or driver error.
I can’t see a CIRCUITPY drive
That is expected on ESP32. Use a serial tool for MicroPython or CircuitPython’s web workflow to manage files. The presence of a serial port without a drive does not mean the board is faulty.
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. Use the USB-to-serial port and ensure your program writes to the expected UART. 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.
Connect your ESP32-S2 board
- TinyS2
- FeatherS2
- FeatherS2 Neo
Plug your TinyS2, FeatherS2 or FeatherS2 Neo into your computer with a USB-C power and data cable.
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.
CIRCUITPYYour board’s USB drive
code.pyThe program running on your board
lib/Libraries used by your program
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
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 esp32s2 --port PORT erase-flashEnter 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.
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.
Use the helper for your exact S2 board. FeatherS2 and FeatherS2 Neo have different onboard hardware; examples for the Neo matrix are not interchangeable with the single RGB LED on other boards. Follow the board example when enabling an LED supply or a second regulator.
Start with the examples in the board’s repository linked below. Copy the helper beside code.py and its dependencies into lib.
| Your board | Helper module | What it gives you |
|---|---|---|
| TinyS2 | tinys2 | RGB LED power, battery voltage, USB power detection, deep sleep |
| FeatherS2 | feathers2 | Blue LED, ambient light sensor, LDO2 power, DotStar colour wheel, deep sleep |
| FeatherS2 Neo | feathers2neo | RGB LED power, LED matrix power, battery voltage, USB power detection, deep sleep |
Use it
The helper is built into the UM MicroPython firmware for your board, so there’s nothing to install. Import it by name, for example import tinys2.
| Your board | Arduino helper | Install from |
|---|---|---|
| FeatherS2 | FeatherS2 Helper Library | GitHub: feathers2 |
| FeatherS2 Neo | FeatherS2 Helper Library | GitHub: feathers2 |
| TinyS2 | TinyS2 Helper Library | GitHub: tinys2 |
Install it
These libraries aren’t in Library Manager. Download the repository from GitHub, copy the library folder into your Arduino libraries folder, then restart Arduino IDE.
What it gives you
- FeatherS2 Helper Library: DotStar RGB LED power, colour and brightness
- TinyS2 Helper Library: RGB LED power, colour and brightness; battery voltage; USB power (VBUS) detection
Examples
After installing, open File → Examples and choose the library. Start with the LED example to confirm the library matches your board.
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.
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.
CIRCUITPYYour board’s USB drive
code.pyThe program running on your board
lib/Libraries used by your program
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
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-flashEnter 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.
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.
- Open the shipping-files folder for your board in the UM repository.
- Copy that folder’s contents to CIRCUITPY. Keep the helper beside
code.pyand keep the dependencies insidelib. - 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")| Your board | Helper module | What it gives you |
|---|---|---|
| TinyS3 | tinys3 | RGB LED power, battery voltage, USB power detection |
| FeatherS3 | feathers3 | Blue LED, ambient light sensor, LDO2 power, battery voltage, USB power detection |
| ProS3 | pros3 | LDO2 power, battery voltage, USB power detection |
| NanoS3 | nanos3 | RGB LED power |
| OMGS3 | omgs3 | RGB LED power, battery voltage and charge level from the fuel gauge, USB power detection |
| FeatherS3 Neo | feathers3neo | Blue LED, ambient light sensor, LDO2 power, battery voltage, USB power detection |
| TinyS3[D] | tinys3d | RGB LED power, battery voltage and charge level from the fuel gauge, USB power detection, antenna switch, deep sleep |
| FeatherS3[D] | feathers3d | Blue LED, ambient light sensor, LDO2 power, battery voltage and charge level from the fuel gauge, USB power detection, antenna switch |
| ProS3[D] | pros3d | LDO2 power, battery voltage and charge level from the fuel gauge, USB power detection, antenna switch |
| EdgeS3[D] | edges3d | Battery voltage and charge level from the fuel gauge, antenna switch |
Use it
The helper is built into the UM MicroPython firmware for your board, so there’s nothing to install. Import it by name, for example import tinys3.
| Your board | Arduino helper | Install from |
|---|---|---|
| TinyS3, FeatherS3, ProS3, NanoS3, OMGS3, FeatherS3 Neo | UMS3 Helper | Library Manager |
| TinyS3[D], FeatherS3[D], ProS3[D], EdgeS3[D] | UM SeriesD Helper | Library Manager |
Install it
Open Tools → Manage Libraries, search for the library name and click Install.
What it gives you
- Both libraries: RGB LED power, colour and brightness; battery voltage; USB power (VBUS) detection; LDO2 power on ProS3 and FeatherS3 boards; blue LED and light sensor on FeatherS3 boards
- UMS3 Helper: 7×7 LED matrix power on FeatherS3 Neo
- UM SeriesD Helper: antenna switch, onboard or external. EdgeS3[D] has no RGB LED.
Examples
After installing, open File → Examples and choose the library. Start with the LED example to confirm the library matches your board.
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);
}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.
Connect your ESP32-C6 board
- TinyC6
- TinyC6[D]
Plug your TinyC6 or TinyC6[D] into your computer with a USB-C power and data cable.
Connect to your board
ESP32-C6 has no native USB, so your board doesn’t appear as a USB drive. You reach it over the board’s USB serial port, which gives you the Python prompt and lets you copy files on and off the board.
On Windows the port is named COM followed by a number; on macOS and Linux it appears as a serial device. If you’re unsure which port is your board, unplug it and reconnect it: the port that disappears and returns is the one to select.
TinyC6[D]: MicroPython pre-installed
Each time your board powers up or resets, MicroPython runs boot.py and then main.py, if they are on the board. On your new board, main.py contains a demo program; edit it or replace it with your own.
Use whichever tool you prefer:
- mpremote, MicroPython’s own command-line tool:
pipx install mpremote mpremote connect PORT repl mpremote connect PORT fs cp main.py :main.py - Any serial terminal at 115200 baud, for the Python prompt.
- An editor with MicroPython support, such as Thonny with MicroPython (ESP32) selected.
TinyC6: CircuitPython pre-installed
Each time your board powers up or resets, CircuitPython looks for code.py on the board and runs it. On your new board, code.py contains a demo program; edit it or replace it with your own.
Use whichever tool you prefer:
- Any serial terminal at 115200 baud, for the Python prompt.
- CircuitPython’s web workflow, to edit and copy files over Wi-Fi.
- An editor with CircuitPython support, such as Thonny with CircuitPython (generic) selected.
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
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 esp32c6 --port PORT erase-flashEnter 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.
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.
TinyC6 and TinyC6[D] have different battery and antenna hardware. Use the matching board files: Series[D] has an I²C fuel gauge and a software antenna switch. S3 helper modules and old TinyC6 ADC examples are not substitutes for the D revision.
Start with the examples in the board’s repository linked below. Copy the helper beside code.py and its dependencies into lib.
| Your board | Helper module | What it gives you |
|---|---|---|
| TinyC6 | tinyc6 | RGB LED power, battery voltage, USB power detection |
| TinyC6[D] | tinyc6d | RGB LED power, battery voltage and charge level from the fuel gauge, USB power detection, antenna switch, deep sleep |
Use it
The helper is built into the UM MicroPython firmware for your board, so there’s nothing to install. Import it by name, for example import tinyc6d.
| Your board | Arduino helper | Install from |
|---|---|---|
| TinyC6[D] | UM SeriesD Helper | Library Manager |
| TinyC6 | No Arduino helper | — |
Install it
Open Tools → Manage Libraries, search for the library name and click Install.
What it gives you
- UM SeriesD Helper: RGB LED power, colour and brightness; battery voltage from the fuel gauge; USB power (VBUS) detection; antenna switch: onboard or external
Examples
After installing, open File → Examples and choose the library. Start with the LED example to confirm the library matches your board.
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.
On TinyC6[D], the switch is connected to XIO0 on the I²C I/O expander. LOW selects onboard and HIGH selects external. XIO0 is not the MCU’s GPIO0: use the TinyC6[D] expander helper to change it.
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
TinyC6[D] uses a MAX17048 fuel gauge connected over I²C. It reports the battery voltage and estimates the remaining charge. The original TinyC6 measures battery voltage through an ADC instead; its battery-reading code does not read a MAX17048.
Use the MAX17048 driver with the I²C pins marked SCL and SDA on your board’s pin reference. Connect a battery before checking its readings; USB power alone does not provide a battery state-of-charge measurement.
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);
}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
That is expected on ESP32-C6. Use a serial tool for MicroPython or CircuitPython’s web workflow to manage files. The presence of a serial port without a drive does not mean the board is faulty.
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.