GuitarPedal keeps its board choice in a file, not in the cmake cache

The board name lives in a file so a wiped build directory cannot change it

There is more than one board this tree can be built for, and the build will not pick for you. The choice is written once, by hand, into `board.local`, and the Makefile reads it directly:

BOARDS := split unified minimal
BOARD := $(shell cat board.local 2>/dev/null)

The reason it is a file rather than a cmake cache variable is given at the top of the Makefile: blowing away `build/` should not silently change which board the tree is about. A cached cmake variable lives in the build directory, so deleting that directory would quietly reset it, and the fix would be a working build for hardware you do not own. The setup sequence is short:

	git clone https://github.com/torvalds/GuitarPedal.git
	cd GuitarPedal
	echo unified > board.local
	make prep
	make

Note the asymmetry in the board list. The page describes two of the three names in that variable: `unified` is the current one board pedal, `split` is the older modular pair of boards. `minimal` appears in the Makefile as a build target and nowhere in the explanation.

Every artifact is named for its board, so pedal.uf2 cannot be grabbed by mistake

A plain `make` produces `build/pedal-unified.uf2` along with the `.elf` and the `.bin`, and the naming is deliberate rather than incidental. As the Makefile puts it, nothing flashes `build/pedal.elf` because there is no such file on purpose: every artifact is named for the board it belongs to. That removes the most common way to end up with the wrong firmware on a pedal, which is a generic filename grabbed from the wrong directory. The other board is an explicit target, `make split`, and `make all-boards` builds both, so spot checking the old hardware does not require changing the setting the tree is about. Two more targets exist for a different job: `usb-device` runs cmake from scratch into `build/` and then builds, and `flash` depends on `build` but guards itself:

flash: build
	@test -n "$(BOARD)" || { echo "no board.local - see 'make prep'"; exit 1; }
	picotool load build/pedal-$(BOARD).elf && picotool reboot

Flashing without a board file stops with a message pointing at `make prep`.

Three ways to reach BOOTSEL, one of them for a pedal too broken to enumerate

Getting a `.uf2` onto the board needs it in BOOTSEL mode, and there are two manual routes plus one scripted. If the pedal is running and plugged in, a MIDI message reboots it into BOOTSEL by itself:

	amidi -l                          # find which card the pedal is
	amidi -p hw:5,0 -S "B0 14 7E"     # ...and that 5 is mine, not yours

The message is MIDI CC 20 with value 126, and the device number in the example is explicitly the author's rather than yours, which is why the first command exists. The second route needs no firmware cooperation at all: hold the knob while you plug it in. On this board the rotary encoder's switch doubles as BOOTSEL through a Schottky diode, placed so that QSPI traffic cannot fake pulling the line low, and that is the route that still works on a pedal too broken to enumerate. The older boards had a proper BOOTSEL button, but it sat on the small MCU daughtercard, which is convenient on a bench and useless once the thing is screwed into a box. Either way a USB mass storage device appears and the file is copied to it.

One board, one encoder with a switch, and a codec sitting on the MCU

These days there is a single board, and `Hardware/usb-stomp` puts the RP2354A and the TI TAC5242 codec directly on it, with no cable, no daughtercards and no connectors in between. The connectors are a quarter inch input jack and output jack, plus a third quarter inch jack for an expression pedal or a remote stomp switch, MIDI in and out on 3.5mm Type A TRS jacks, USB-C and the usual 9V power jack. MIDI out goes through a 5V buffer and MIDI in through an optocoupler, described as the arrangement MIDI has always wanted. Control is one rotary encoder with a switch underneath it and one stomp switch, with three addressable WS2812B LEDs for indication. The MIDI jacks and the expression jack are called out as the genuinely new things, and the reason is pin budget rather than taste: the expression jack wants two ADC pins, and those are exactly the pins the old MCU board was already spending on something else. The kicad files, the 3D printed insert and the enclosure drill rules are all in the same directory.

The test bench compiles the pedal's own audio core, not a model of it

The reason the effect tests are worth running is stated precisely, and the precision matters. `Validation/bench` builds the pedal's actual audio core as a program on your machine: the same `single_sample()`, the same effect headers and the same compiler flags, with float samples going in on stdin and coming back on stdout. The claim is that it is not a model of the signal path, it is the signal path, with the two register blocks the audio core touches replaced by ordinary memory. So the bench can only differ from the hardware in the two places where hardware registers stand in for memory, and a measurement taken there is a measurement of the pedal's own arithmetic rather than of a reimplementation of it. That is also why the `Audio` directory sits outside the firmware: it holds the DSP the effects are built from, biquads, envelope followers and LFOs, plus the audio loop itself, and the bench compiles those same files.

Nine check targets, split by whether you own a pedal

The test suite is divided by what it needs plugged in. `make check` runs everything host only: the MIDI packetiser, whether the web app still loads and still draws the right conclusions, and a sweep that asks every biquad in the pedal where it actually landed. `make check-biquad` is that sweep alone, and `make check-effects` pushes signals through the effects themselves. `make check-analysis` is the other host only target, and its job is keeping the per effect pages under `Documentation/effects` honest, because every curve on those pages is a measurement and this re-measures them and reports when one has stopped being true. It is deliberately not part of `make check`, since it re-runs every sweep on every page and is slow. The hardware targets are more specific still: `make check-hw` needs a signal generator, `make check-analog` needs a patch cable from the pedal's output back into its own input, `make check-bench` asks whether a real board agrees with the host build, `make check-hwtone` sweeps the tone stack the codec runs in its own biquads, and `make check-loop` wants two pedals patched into each other.

Seventeen effect files, built by three different consumers

The `Effects` directory holds the seventeen effects, one file each, and the reason they are not inside the firmware is structural. Three different things are built from them: the firmware, the test bench and the web app's controls. Keeping them at the top level is what lets all three compile the same source rather than three copies drifting apart, and the web app is the reason editing moved off the pedal in the first place. An earlier version had a small OLED screen and a couple of rotary encoders, and that is gone; seventeen effects through a 128x128 screen and two knobs was not going to work, so the pedal is down to one knob and one stomp switch and deep editing happens in a browser app talking over USB MIDI. `Firmware` holds USB, MIDI, scenes and the board pin maps, `WebMIDI` is the editor, `Validation` is the suite, and `scripts` carries the effect generator, the math tables and the checks that refuse a firmware image doing something the audio core should not. `Documentation` is, in the page's own words, a very optimistic name for a directory.

The firmware has only ever been built on Linux

Platform support is stated as an expectation rather than a fact. The firmware has only been built on Linux, and building it on MacOS or Windows should be possible if you figure out the platform requirements. What is portable is the tool list: git, make, python3 and cmake, regardless of platform, plus a 32-bit arm cross build environment, which on Linux means arm-none-eabi-binutils-cs, arm-none-eabi-gcc-cs and arm-none-eabi-newlib. The two library dependencies, `pico-sdk` and `tinyusb`, are git submodules and `make prep` fetches exactly those two by name. The Makefile is explicit about the third submodule it leaves alone: `nRF54/nrf` is the Nordic SDK, described as a quarter of a gigabyte on its own before west resolves it, and nobody building a `.uf2` should pay for the radio's toolchain, so it is bought separately with `make -C nRF54 fetch`. Flash and `.uf2` copies need no tooling at all, and `make flash` is available only if picotool was installed with USB support, since the pico-sdk build produces a cut down version without it.

Editorial conclusion

GuitarPedal suits someone who wants the whole signal path in source, down to the effect files and the register blocks, and who has a 32 bit arm cross toolchain and a board to flash. Before building, write board.local, because the Makefile reads it to decide what a bare make produces and the configure step stops if it is missing. Read the Makefile board list rather than the page, since it names a third target the text leaves unexplained. If you only want to evaluate the effects, the host bench compiles the pedal's own audio core and needs no hardware at all, which is the cheapest way to judge whether the seventeen effects are worth a board.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-2.0
3. README
4. torvalds/GuitarPedal on GitHub