First-time flashing

Most of the time you never touch this page: standalone devices update over WiFi, loader devices update by USB drag-and-drop. But one USB flash is needed:

• on a brand-new, blank board that has no RFX firmware yet,
• when switching a device between standalone and loader mode (they use different flash layouts), or
• as the last-resort recovery if a device won’t boot at all.

If your device arrived pre-flashed, skip this page and go straight to the quickstart for your mode.

Before you start: pick a deployment mode

Each device runs in exactly one of two modes, chosen at flash time because they lay out the chip’s flash differently:

	Standalone	Loader
Firmware updates	Over WiFi, from the web dashboard	Drag a .uf2 onto a USB drive
Needs WiFi?	Yes (to update)	No
Recovery from a bad image	USB reflash	Automatic — the loader catches it
Quickstart	Standalone	Loader

Rule of thumb: prop lives on WiFi and you like wireless updates → standalone. No reliable WiFi, or you want the bulletproof recovery path → loader.

Caution

Flashing a new layout erases the device’s on-chip data drive — show.json, config.json, fonts, sounds. If the device has been used before, plug it in and copy those files off the USB drive first. Boards that keep data on a removable SD card are unaffected — the card isn’t touched.

What you’ll need

• A data-capable USB cable (some cables are charge-only — if no device shows up on your computer, try another cable)

• The firmware image(s) for your board and chosen mode

• esptool, the standard command-line flasher for ESP32 chips. With Python installed:

  pip install esptool

1. Put the board in download mode

The chip has a built-in, unbrickable download mode in ROM:

1. Hold the BOOT button down.
2. While holding it, press and release RESET.
3. Release BOOT.

The screen (if any) stays dark — that’s normal. The board is now waiting for a flasher over USB. Button locations vary by board; check your board’s page under Boards.

Note

This hold-BOOT-through-reset gesture is different from the loader’s tap-RESET-then-BOOT update gesture. Download mode talks only to esptool; no USB drive appears.

2. Find the serial port

• Windows: open Device Manager → Ports (COM & LPT) → note the COM number (e.g. COM5).
• macOS/Linux: it appears as /dev/cu.usbmodem* / /dev/ttyACM0 (or similar).

You can also let esptool guess by omitting --port — it scans for the chip.

3. Erase and flash

First erase the chip (this is what wipes the old layout — and the data drive, see the warning above):

esptool.py --chip esp32s3 --port COM5 erase_flash

Then write the firmware image for your board and mode:

esptool.py --chip esp32s3 --port COM5 write_flash 0x0 <your-image>.bin

When it finishes, press RESET (or unplug/replug) to boot the new firmware.

4. What happens next

• Standalone mode: the device boots the show and brings up WiFi — a fresh device starts its own rfx-setup network for configuration. Continue with the Standalone quickstart, step 2.
• Loader mode: with no app installed yet, the freshly-flashed loader sits in drive mode showing the rfx-boot USB drive. Drag your app’s firmware.uf2 onto it. Continue with the Loader quickstart.
• Restore your data: copy your backed-up show.json, config.json, and assets back onto the device’s data drive (or web dashboard → Files tab once it’s on WiFi). SD-card boards need nothing — the card was never touched.

If flashing fails

• No port appears: try another USB cable (data-capable) and another port; redo the download-mode button sequence — the timing matters less than the order (hold BOOT through the RESET press).
• esptool errors mid-write: run erase_flash again and retry. Download mode is in ROM — you cannot brick the board from here, so it’s always safe to try again.
• Still stuck? See Troubleshooting or your board’s page under Boards.