Matthew: Add how-to guide

2026-08-23T23:53:24Z

Add how-to guide

New page

The Sandbox FV-1 Editor is a browser-based code editor, assembler and simulator for the Spin FV-1. Nothing is installed and nothing is uploaded — the assembler runs entirely in your browser.

Open it at [https://fv1.sandboxpedal.com fv1.sandboxpedal.com].

== Browser requirements ==

{| class="wikitable"
! What you want to do !! Browser
|-
| Write and assemble code || Any modern browser
|-
| Run the simulator || Any browser with AudioWorklet support
|-
| Save straight to hardware, or use a project folder || '''Chrome or Edge only'''
|}

Firefox and Safari do not implement the File System Access API, so they cannot write files to your pedal's drive. You can still assemble and download a HEX file by hand and copy it across yourself.

If Chrome refuses to talk to your hardware, see [[Troubleshooting]] for the site permission settings.

== The layout ==

The main window has a '''Source Input''' pane with the code editor and a '''Build Results''' pane underneath showing the assembled Intel HEX output. Three tabs along the edge open flyout panels:

* '''OPTIONS''' — editor preferences and hardware setup.
* '''HELP''' — the FV-1 instruction set reference.
* '''SIM''' — the [[Using the FV-1 simulator|built-in simulator]].

== Assembling code ==

Write or load your source, then press '''Assemble''' (or Alt+A on Windows, Ctrl+A on Mac).

Warnings and errors appear in the message area with the line number. The FV-1 has a hard limit of 128 instructions; anything shorter is padded out with NOPs automatically, so you do not need to fill the space yourself.

Once a build succeeds you can save it in several formats:

* '''Download HEX''' — Intel HEX, the format the programmer wants.
* '''Download Binary''' — raw <code>.bin</code>.
* '''Download C Headers''' — the program as a C array, for embedding in other firmware.
* '''Save Source…''' — your assembly source.

'''Load File…''' opens a source file from disk, and also offers four built-in examples: Pass-through, Delay, Chorus and Tremolo. These are a good starting point if you want something working in front of you before you start editing.

== Sending a build to the pedal ==

This is the part that needs Chrome or Edge.

# Open the '''OPTIONS''' panel.
# Under '''Hardware Options''', press '''Select Output Directory''' and choose your pedal's '''SANDBOX-FV1''' drive.
# Pick a destination from the '''Filename / Toggle Position''' grid. The buttons are labelled by physical switch position — ▲ is switch up, ● is middle, ▼ is down — with the slot number in the middle.
# Assemble, then press '''Download to Hardware''' (Alt+D / Ctrl+D).

The editor writes the HEX file into the drive under the right filename, the programmer picks it up, and the FV-1 reloads. See [[Programming an EEPROM with HEX files]] for what happens at the hardware end.

'''Download to Hardware''' stays greyed out until all three of a directory, a filename and a successful build are in place.

'''Clear Hardware''' (Alt+C / Ctrl+C) writes empty files over <code>0.hex</code> through <code>7.hex</code>, <code>all.hex</code> and <code>dump.txt</code>, wiping the slots. It only touches files that currently have content.

== Working from a project folder ==

'''Select Project Folder''' in the Editor Options section points the editor at a directory of source files, so you can move between the files of a multi-program project without opening each one through a file dialog.

== Editor options ==

* '''Large editor window''' — a taller code pane.
* '''Show editor mini-map''' — the Monaco overview strip down the right-hand side.
* '''Show full build results''' — verbose assembler output rather than just errors. Useful when you are debugging an instruction encoding.
* '''Theme''' — System, Light or Dark.

These preferences persist between sessions.

== Keyboard shortcuts ==

{| class="wikitable"
! Action !! Windows !! Mac
|-
| Find || Ctrl+F || ⌘+F
|-
| Replace || Ctrl+Shift+F || ⌘+⌥+F
|-
| Find next || F3 || F3
|-
| Assemble || Alt+A || ⌃+A
|-
| Download to Hardware || Alt+D || ⌃+D
|-
| Clear Hardware || Alt+C || ⌃+C
|}

== Running the editor locally ==

The web app must be served over HTTP. Opening <code>Assembler/index.html</code> as a <code>file://</code> page will not work — browsers block the audio engine the simulator needs from <code>file://</code> origins, and the directory and serial access need a secure context. <code>localhost</code> counts as secure, so any static file server will do:

<pre>
python3 -m http.server 8000 --directory Assembler
</pre>

Then open <code>http://localhost:8000</code>. If you prefer Node, <code>npx serve Assembler</code> works the same way.

== See also ==

* [[Writing your first FV-1 program]]
* [[Using the FV-1 simulator]]
* [[Programming an EEPROM with HEX files]]

[[Category:How-to]]

Using the Sandbox FV-1 Editor - Revision history

Matthew: Add how-to guide