Flashing the firmware

The firmware is plain C++ on the Arduino core, built and uploaded entirely from the terminal with arduino-cli. There's no Arduino IDE involved.

Before the daily workflow, make sure the board is visible:

make ports

You should see something like /dev/cu.usbmodem14101 (macOS), /dev/ttyACM0 (Linux), or COM5 (Windows) tagged with esp32:esp32:esp32c3. The trailing digits vary by machine and USB port — match on the usbmodem / ttyACM / COM prefix and the esp32c3 tag, not the exact number. If nothing shows up, see Troubleshooting.

Daily workflow

The repo's Makefile wraps every common operation. The port is auto-detected; you only need PORT=... if you have multiple boards plugged in.

The first build takes ~30 seconds. Subsequent rebuilds are 2–5 seconds (arduino-cli caches aggressively).

When you run make monitor you'll land on a line like:

Connecting to /dev/cu.usbmodem101. Press CTRL-C to exit.

That's it — you're connected. The monitor stays attached and streams the board's serial output; hit Ctrl-C when you want to detach.

Wiping the board

make clean only deletes the host-side build folder — it doesn't touch the chip. To wipe the board itself (the app, plus saved NVS data like wifi credentials), use make erase:

make erase

It finds esptool on your PATH — or falls back to the copy bundled with the ESP32 core, so there's nothing extra to install — frees the serial port if the gochi daemon is holding it, and chip-erases the flash. The board is blank afterwards; run make flash to put the firmware back.

OLED I²C address

The SSD1306 modules in the kit speak to address 0x3C. A small number of clones use 0x3D instead. If the screen wakes up black after a successful flash, run the I²C scanner sketch (one terminal command):

make flash SKETCH=examples/i2c_scan

Then make monitor — you'll see the address printed. If it's 0x3D, edit firmware/src/config.h and change OLED_I2C_ADDR to match.

Force download mode

The ESP32-C3 SuperMini occasionally won't enter the bootloader on its own. Symptoms:

• make flash hangs at "Connecting...___"
• make ports shows the board, but uploads time out

Fix:

You only have to do this once per power-cycle; after a successful upload the board reboots into your code and accepts future flashes normally.

Flashing on Linux / WSL2

Flashing from a native Linux host is straightforward. WSL2 is a lightweight VM with its own kernel, so USB serial devices need extra plumbing that a native host doesn't. Pick your environment:

make ports          # confirm the board shows up, e.g. /dev/ttyACM0
make flash          # autodetects PORT; pass PORT=/dev/ttyACM0 if you have several boards

sudo usermod -aG dialout $USER

pip install --user clang-format   # apt alternative: sudo apt install clang-format

# Windows PowerShell (Admin) — one time:
winget install usbipd

# Each session: find the board, bind once, then attach.
usbipd list                                  # note the ESP32's BUSID, e.g. 2-4
usbipd bind   --busid 2-4                     # one-time per device
usbipd attach --wsl --busid 2-4 --auto-attach # --auto-attach survives re-enumeration

sudo modprobe cdc_acm            # once per boot

sudo chmod 666 /dev/ttyACM0
make flash

echo 'KERNEL=="ttyACM[0-9]*", MODE="0666"' | sudo tee /etc/udev/rules.d/99-ttyacm.rules
sudo udevadm control --reload-rules

# Windows (Admin):
usbipd attach --wsl --busid 2-4 --auto-attach

# WSL:
sudo modprobe cdc_acm           # once per boot
# Hold BOOT, tap RESET, release BOOT  (puts board in download mode)
ls /dev/ttyACM*                 # confirm /dev/ttyACM0 is present & stable
sudo chmod 666 /dev/ttyACM0
make flash

Editor setup (optional but nice)

Any editor with clangd support gets full code intelligence — completion, go-to-definition, inline errors — via the compile_commands.json generated by make db.

VS Code users can install the clangd extension and it works out of the box. Other editors with clangd support work similarly — point them at compile_commands.json and treat .ino files as C++.

Troubleshooting