Installing the RP2040 programmer firmware

The Sandbox programmer is an off-the-shelf RP2040 board running CircuitPython plus a few files from the Sandbox repository. Once it is set up, programming an FV-1 pedal is a matter of dragging a HEX file onto a USB drive — there is no driver to install and no programming application to run.

This guide covers installing the firmware. For day-to-day use, see Programming an EEPROM with HEX files.

What you need

• An RP2040 board. We use a Waveshare RP2040-Zero for its small size and USB-C port, but a Raspberry Pi Pico or a clone will also work.
• A USB cable that carries data. Charge-only cables are a common cause of "nothing happens when I plug it in".
• The firmware files from the Sandbox-FV1 repository, in the Firmware folder.

Which firmware folder do I want?

The repository contains two builds of the same programmer:

Folder	Use it for
Firmware/src	The programmer module fitted to a Sandbox pedal. This is the one most people want.
Firmware/production programmer	A standalone bench programmer with an SSD1306 OLED and a button, for programming EEPROMs in quantity.

Both share the same file layout and the same HEX file rules. The production build adds the OLED status display.

Step 1: Put the board into bootloader mode

1. Unplug the RP2040 board from everything.
2. Hold down the BOOTSEL button on the board.
3. While still holding BOOTSEL, plug the USB cable into your computer.
4. Release the button.

A removable drive named RPI-RP2 will appear on your computer. If it does not, the cable is the first thing to suspect.

Step 2: Install CircuitPython

Drag the CircuitPython .uf2 file onto the RPI-RP2 drive. The repository ships a known-good build as Firmware/firmware.uf2; alternatively download the CircuitPython build for your specific board from circuitpython.org.

The board reboots on its own as soon as the copy finishes — the RPI-RP2 drive disappearing is expected and is how you know it worked. A new drive named CIRCUITPY appears in its place.

Step 3: Copy the Sandbox files

Copy these four items from the firmware folder onto the CIRCUITPY drive:

• boot.py
• code.py
• hardware_id.json
• the lib folder

If your computer asks whether to merge or replace the contents of lib, say yes. CircuitPython ships its own lib folder and the Sandbox libraries need to sit alongside whatever is already there.

hardware_id.json is what lets the web editor recognise the drive as a real Sandbox target, so do not skip it.

Step 4: Confirm it worked

Eject the drive and re-plug the board. Two things should change:

• The drive is now named SANDBOX-FV1 instead of CIRCUITPY. boot.py renames it at power-on.
• The board identifies itself over USB as Disaster Area Designs SandboxFV1.

If you still see CIRCUITPY, boot.py did not run. Check that it is in the root of the drive and not inside a subfolder.

What the two files do

boot.py runs once at power-on, before anything else. It sets the drive label, enables the USB drive, and sets the USB manufacturer and product identity (VID 0x1209, PID 0x3811). You never interact with it directly.

code.py is the main loop. It watches the I²C bus for an EEPROM and the drive for HEX files, and programs the chip when it finds both.

Note that boot.py remounts the filesystem read-only to the board's own code. Your computer keeps write access, which is exactly what makes drag-and-drop programming work.

Reading the serial console

For detailed logs — validation results, byte dumps, the reason a write failed — open the board's serial REPL with a terminal program such as screen, tio, PuTTY or the Mu editor. Every action the loop takes is printed there. This is the fastest way to diagnose a write that goes red for no obvious reason.

See also

• Programming an EEPROM with HEX files
• Building the FV-1 Sandbox pedal
• Troubleshooting