Matthew: Add how-to guide

2026-08-23T23:53:21Z

Add how-to guide

New page

The Sandbox programmer is an off-the-shelf RP2040 board running [https://circuitpython.org 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 [https://github.com/DisasterAreaDesigns/Sandbox-FV1 Sandbox-FV1 repository], in the <code>Firmware</code> folder.

== Which firmware folder do I want? ==

The repository contains two builds of the same programmer:

{| class="wikitable"
! Folder !! Use it for
|-
| <code>Firmware/src</code> || The programmer module fitted to a Sandbox pedal. This is the one most people want.
|-
| <code>Firmware/production programmer</code> || 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 ==

# Unplug the RP2040 board from everything.
# Hold down the '''BOOTSEL''' button on the board.
# While still holding BOOTSEL, plug the USB cable into your computer.
# 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 <code>.uf2</code> file onto the '''RPI-RP2''' drive. The repository ships a known-good build as <code>Firmware/firmware.uf2</code>; alternatively download the CircuitPython build for your specific board from [https://circuitpython.org/downloads 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:

* <code>boot.py</code>
* <code>code.py</code>
* <code>hardware_id.json</code>
* the <code>lib</code> folder

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

<code>hardware_id.json</code> 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. <code>boot.py</code> renames it at power-on.
* The board identifies itself over USB as ''Disaster Area Designs SandboxFV1''.

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

== What the two files do ==

<code>boot.py</code> 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 <code>0x1209</code>, PID <code>0x3811</code>). You never interact with it directly.

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

Note that <code>boot.py</code> 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 <code>screen</code>, <code>tio</code>, 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]]

[[Category:How-to]]

Installing the RP2040 programmer firmware - Revision history

Matthew: Add how-to guide