Editing Programming an EEPROM with HEX files

Once the [[Installing the RP2040 programmer firmware|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 ==

# Plug the RP2040 board into USB.  A drive named '''SANDBOX-FV1''' appears.
# Connect the target 24LC32A EEPROM to the I<sup>2</sup>C pins.
# Drop a HEX file onto the drive, named for the slot you want (<code>0.hex</code> … <code>7.hex</code>, or <code>all.hex</code>).
# 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.

{| class="wikitable"
! Filename !! EEPROM address !! Notes
|-
| <code>0.hex</code> || <code>0x0000</code> || On a Sandbox pedal this slot is bypass
|-
| <code>1.hex</code> || <code>0x0200</code> ||
|-
| <code>2.hex</code> || <code>0x0400</code> ||
|-
| <code>3.hex</code> || <code>0x0600</code> || Also the destination for any unrecognised filename
|-
| <code>4.hex</code> || <code>0x0800</code> ||
|-
| <code>5.hex</code> || <code>0x0A00</code> ||
|-
| <code>6.hex</code> || <code>0x0C00</code> ||
|-
| <code>7.hex</code> || <code>0x0E00</code> ||
|}

A file with any other name is written to <code>0x0600</code> — 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:

{| class="wikitable"
! !! Right switch up !! Right switch down
|-
! Left switch up
| <code>2.hex</code> || <code>6.hex</code>
|-
! Left switch middle
| <code>3.hex</code> || <code>7.hex</code>
|-
! Left switch down
| <code>1.hex</code> || <code>5.hex</code>
|}

The [[Using the Sandbox FV-1 Editor|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 <code>all.hex</code>):

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

'''Full-image files''' (<code>all.hex</code>):

* Exactly '''1025 lines'''.
* Address range '''0x000–0xFFF''' — the whole 4096-byte chip.
* The EEPROM is cleared to <code>0xFF</code> first, then written from <code>0x0000</code>.
* If <code>all.hex</code> 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:'''

{| class="wikitable"
! 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):

* <code>No target / Connect EEPROM</code> — nothing detected on the I<sup>2</sup>C bus.
* <code>EEPROM found / Waiting for .hex</code> — ready.
* <code>Complete / Waiting for .hex</code> — 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 <code>2.hex</code> 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 <code>0.hex.programmed</code>.  It is purely a record and is safe to delete.

== Common failures ==

{| class="wikitable"
! Symptom !! Likely cause
|-
| Stuck on <code>Connect EEPROM</code> || EEPROM not seen on I<sup>2</sup>C.  Check wiring and that the chip answers at address <code>0x50</code>.
|-
| <code>BAD LINE COUNT</code> || Not 129 lines (single slot) or 1025 lines (<code>all.hex</code>).
|-
| <code>BAD ADDR RANGE</code> || The HEX addresses do not match the expected range for that slot.
|-
| Red blink at startup || I<sup>2</sup>C 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 <code>._</code> 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]]

[[Category:How-to]]