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

mpremote documentation →

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 esp32 --port PORT erase-flash

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

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.

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.

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.

Visit the UM knowledge base →Ask the UM community →