Programming an EEPROM with HEX files

Once the programmer firmware is installed, writing a new algorithm to your pedal means copying a file onto a USB drive. There is no software to launch and no driver to install.

Quick version

1. Plug the RP2040 board into USB. A drive named SANDBOX-FV1 appears.
2. Connect the target 24LC32A EEPROM to the I²C pins.
3. Drop a HEX file onto the drive, named for the slot you want (0.hex … 7.hex, or all.hex).
4. Watch the LED: dim blue while writing, green on success, blinking red on error.

On success the programmer pulses the FV-1's control pin so the chip reloads immediately. You do not need to power-cycle the pedal.

Naming the file

The filename is not cosmetic — it is how you choose which of the eight FV-1 program slots gets written.

Filename	EEPROM address	Notes
0.hex	0x0000	On a Sandbox pedal this slot is bypass
1.hex	0x0200
2.hex	0x0400
3.hex	0x0600	Also the destination for any unrecognised filename
4.hex	0x0800
5.hex	0x0A00
6.hex	0x0C00
7.hex	0x0E00

A file with any other name is written to 0x0600 — program 3. That is deliberate: program 3 is the slot the FV-1 selects when no toggle switches are fitted to the PCB, so a bare board with a single algorithm on it just works.

Toggle switch positions

If your pedal has the two toggle switches fitted, the switch positions map to slots like this:

	Right switch up	Right switch down
Left switch up	2.hex	6.hex
Left switch middle	3.hex	7.hex
Left switch down	1.hex	5.hex

The editor shows the same grid, so you can pick the physical switch position you want rather than remembering slot numbers.

File format rules

The programmer validates every file before it writes anything. A file that fails validation is rejected outright — it will not half-program your chip.

Single-slot files (anything except all.hex):

• Exactly 129 lines.
• Address range 0x000–0x1FF — 512 bytes, which is one FV-1 program.

Full-image files (all.hex):

• Exactly 1025 lines.
• Address range 0x000–0xFFF — the whole 4096-byte chip.
• The EEPROM is cleared to 0xFF first, then written from 0x0000.
• If all.hex is present it is processed first and alone. Other HEX files dropped in the same batch are skipped that cycle, so do not mix a full image with single slots.

These line counts are what the assembler produces naturally. If your file is the wrong length, it almost certainly did not come from an FV-1 assembler.

Reading the status indicators

RGB LED:

Colour	Meaning
Off	Idle, waiting
Dim blue	Writing
Green	Write succeeded
Blinking red	Error — check the serial console for the reason

OLED display (production programmer only):

• No target / Connect EEPROM — nothing detected on the I²C bus.
• EEPROM found / Waiting for .hex — ready.
• Complete / Waiting for .hex — the last write succeeded.

After about 20 seconds of inactivity a screensaver bounces an "FV-1 PROG" label around the display. Press the button to dismiss it; it is not an error state.

Re-flashing the same file

The programmer remembers which files it has already handled in the current session, so dropping an unchanged 2.hex a second time does nothing. To force a re-flash, disconnect and reconnect the EEPROM — that clears the processed list.

After a successful write the programmer also creates a marker file such as 0.hex.programmed. It is purely a record and is safe to delete.

Common failures

Symptom	Likely cause
Stuck on Connect EEPROM	EEPROM not seen on I2C. Check wiring and that the chip answers at address 0x50.
BAD LINE COUNT	Not 129 lines (single slot) or 1025 lines (all.hex).
BAD ADDR RANGE	The HEX addresses do not match the expected range for that slot.
Red blink at startup	I2C bus locked, or no EEPROM present during the initial scan.
File copied, nothing happens	The file is a dotfile, is zero bytes, or was already processed this session.

A zero-byte HEX file is ignored but still marked as processed. This is how the editor's Clear Hardware button works — it writes empty files over the slots.

macOS users: Finder likes to write hidden ._ companion files onto removable drives. The programmer ignores dotfiles, so these are harmless.

See also

• Installing the RP2040 programmer firmware
• Using the Sandbox FV-1 Editor
• Troubleshooting