torvalds/GuitarPedal: a digital pedal built around an RP2354A and a TI codec

What the pedal is, and who the repository is for

This is a digital guitar pedal built around an RP2354A and a TI audio codec, with all effects computed in software on a core of its own. The repository is not a product. It is the source tree behind one physical pedal, published under GPL-2.0, and it assumes you are comfortable with embedded C, a cross-compiler, and a soldering iron.

The README describes an earlier version that carried a 128x128 OLED and two rotary encoders. That is gone. The stated reason is blunt: editing seventeen effects through a small screen and two knobs was never going to be pleasant, and the author says he is not known for UI design. The pedal now has one knob, one stomp switch and three WS2812B LEDs. Deep editing moved to a browser, where a screen already exists.

That decision defines the audience. If you want to tweak a pedal on a dark stage with your foot, this is not aimed at you. If you want a pedal whose parameters are edited from a laptop over USB MIDI, and you are willing to build the board to get one, the tree is complete enough to do that.

Effects, Audio and Firmware: how the tree is split

The layout is the interesting part. Effects are not buried in the firmware. The README states they live in Effects/, one file per effect, because three separate things are built from them: the firmware, the test bench, and the web app's controls. A change to an effect therefore reaches the pedal and the editor without being written twice.

Audio/ holds the DSP the effects are assembled from: biquads, envelope followers, LFOs, and the audio loop itself. The bench compiles those same files, so what gets measured is the pedal's own arithmetic rather than a reimplementation of it. Firmware/ contains everything else that runs on the device: USB, MIDI, scenes, and the board pin maps. WebMIDI/ is the browser app. scripts/ runs the effect generator, the math tables, and checks that refuse a firmware image doing something the audio core should not. Validation/ holds the test suite.

The bench is the mechanism worth understanding. Validation/bench builds the pedal's audio core as a host program that takes float samples on stdin and returns them on stdout, using the same single_sample(), the same effect headers and the same compiler flags as the firmware. The README is explicit 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. That is what makes host-only testing credible here.

Building the firmware and flashing the unified board

The README says the firmware has only ever been built on Linux, though it should be possible on macOS or Windows if you work out the platform requirements. You need git, make, python3 and cmake, plus a 32-bit ARM cross-build environment. On Linux the README names arm-none-eabi-binutils-cs, arm-none-eabi-gcc-cs and arm-none-eabi-newlib. The pico-sdk and tinyusb libraries are submodules and are built automatically.

The build will not guess which board the tree is about. You write it once into board.local, and the README gives this sequence:

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

unified is the current one-board pedal; split is the older modular pair. If you skip the board.local step the configure stops and tells you, which the README calls the intended behaviour. The result is build/pedal-unified.uf2, with .elf and .bin alongside it. Artifacts are named per board on purpose, so there is no pedal.uf2 to grab by mistake. make split or make all-boards build the other board without changing what the tree is about.

Getting the image onto the pedal needs BOOTSEL mode. The README gives two routes. If the pedal is running and plugged in, send it MIDI CC 20 with value 126 and it reboots into BOOTSEL:

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

Otherwise hold the knob in while you plug it in. On this board the rotary encoder's switch doubles as BOOTSEL, routed through a Schottky diode so QSPI traffic cannot fake pulling it low. That route still works on a pedal too broken to enumerate. Either way a USB mass storage device appears and you copy the file to it. If picotool is installed with USB support (the pico-sdk build only produces a cut-down version without it), make flash builds and flashes the board in board.local.

make check, check-biquad and the tests that need a pedal

Validation is split by what it needs. make check runs the part that requires no hardware: 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. make check-effects pushes signals through the effects themselves, using the bench described above.

make check-analysis is separate from check because it re-runs every sweep on every page under Documentation/effects, which is slow. Its job is to keep those per-effect pages honest: the README states that every curve on them is a measurement, and that this target re-measures and reports when one has stopped being true.

The rest want hardware. make check-hw needs a signal generator. make check-analog needs a patch cable from the pedal's output back to 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. make check-loop needs two pedals patched into each other. If you are evaluating the project without a board, make check is the honest ceiling, and it exercises the MIDI path and the biquad sweep rather than the analog chain.

The hardware is a KiCad project, not a kit

Hardware/ contains the kicad files plus supporting items such as the 3D printed insert and the enclosure drill rules. The current design is Hardware/usb-stomp, with the RP2354A and a TI TAC5242 codec sitting directly on the board. The README describes it as the whole pedal: no cable, no daughtercards, no connectors in between.

The board carries a 1/4" input jack, a 1/4" output jack, a third 1/4" jack for an expression pedal or remote stomp switch, MIDI in and out on 3.5mm Type A TRS jacks (out through a 5V buffer, in through an optocoupler), USB-C, a 9V guitar pedal power jack, one rotary encoder with a switch under it, one stomp switch, and three addressable WS2812B LEDs.

The MIDI and expression jacks are the genuinely new part. The README notes the older boards had nowhere to put them, and the expression jack in particular wants two ADC pins that the old MCU board was already using. That is a constraint you inherit: if you want expression control, you are building the current board, not adapting an older one.

This section is also where the project is least finished. There is no BOM walkthrough, no assembly order, and no statement of what the board costs to have made. The drill rules and the printed insert imply a mechanical design exists, but the README does not document a build of it.

Where the documentation stops

The README itself says Documentation remains a very optimistic name for a directory. That is not modesty. There is no user manual, no description of what the seventeen effects are, and no parameter reference in the README. The per-effect pages under Documentation/effects exist and are backed by measurements, but the README does not enumerate them.

Board support is narrower than the Makefile suggests. BOARDS lists split, unified and minimal, yet the README only describes unified as the current one-board pedal and split as the older modular pair. It does not say what minimal is for. If you intend to build minimal, the repository does not tell you what you are getting.

Platform support is a stated assumption rather than a tested fact. The README says macOS and Windows should be possible if you figure out the platform requirements, and that Linux is the only platform the firmware has been built on. Treat the other two as unverified.

Finally, there is no release history in the repository metadata, and the README does not document a rollback path for a flashed image. Recovery depends on BOOTSEL, which is why the knob-held-at-plug-in route matters: it is the one that works when the firmware will not enumerate.

How this differs from a Daisy Seed or a Spin FV-1 build

The closest comparison is a Daisy Seed style board, where a microcontroller module with an audio codec is sold as a unit and you write effects against a vendor HAL. GuitarPedal inverts that. The RP2354A and the TAC5242 sit directly on the pedal board, so there is no module to buy and no HAL between your effect code and the codec registers. You take on the board design and the register-level work.

Against a Spin FV-1, the split is starker. The FV-1 is a fixed-function DSP with a small instruction set and onboard converters; effects are written to its constraints. Here the effects are C compiled for a Cortex-M33 core, and the DSP primitives in Audio/ are ordinary source you can read and change. The cost is that nothing is constrained for you, and the arithmetic is yours to get right, which is exactly why Validation/bench compiles the real audio core instead of a model.

A third option is a general purpose board running a host-based effects stack. That gives you a large ecosystem and a screen, but the audio path runs through a general purpose OS. GuitarPedal keeps the audio loop on a core of its own, and the trade is that editing happens over USB MIDI from a browser rather than on the device.

Editorial conclusion

Adopt it if you can build a Cortex-M33 firmware with make and cmake, and if you want a pedal whose effects, DSP and test bench all compile from the same files. Do not adopt it if you need a finished product with a manual: the README says Documentation is a very optimistic name for a directory, and the hardware is a KiCad design you have to fabricate. Before ordering boards, read Hardware/usb-stomp, confirm your toolchain provides arm-none-eabi-gcc, and run make check to see which host-side tests pass on your machine.

Frequently asked questions

Official sources

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