From a1f40882295b41f02f57392dfadace558042653f Mon Sep 17 00:00:00 2001 From: Shawn Date: Tue, 9 Jun 2026 00:36:25 -0400 Subject: [PATCH] docs: full install instructions for Focusrite test + effect list --- README.md | 182 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 133 insertions(+), 49 deletions(-) diff --git a/README.md b/README.md index d169921..d8c3120 100644 --- a/README.md +++ b/README.md @@ -1,97 +1,181 @@ # Pi Multi-FX Pedal 🎸 -A real-time guitar multi-FX pedal running on **Raspberry Pi 4B** with: +A real-time guitar multi-FX pedal running on **Raspberry Pi 4B** with **32 DSP effects**, **NAM A2 neural amp modeling**, **IR cab simulation**, **4-Cable Method** routing, and a **web UI** on `pedal.local:8080`. -- **NAM A2** neural amp modeling β€” load and switch between capture profiles -- **IR cab simulator** β€” impulse response convolution for cabinet simulation -- **Multi-FX chain** β€” noise gate, compressor, overdrive/distortion, EQ, modulation (chorus/flanger/phaser/tremolo), delay, reverb -- **MIDI in/out** β€” foot controller, expression pedal, preset switching via Program Change -- **Stomp-friendly UI** β€” footswitches, RGB LEDs, OLED display, tuner +## Quick Install (Focusrite 2i2 Test) -## Architecture +Get the pedal running on a fresh RPi with a Focusrite 2i2 in under 10 minutes. -``` -Guitar β†’ I2S ADC β†’ JACK Audio β†’ DSP Pipeline β†’ I2S DAC β†’ Amp/Headphones - β”‚ - β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” - β”‚ NAM LV2 Plugin β”‚ - β”‚ (neural amp sim) β”‚ - β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ - β”‚ IR Convolver LV2 β”‚ - β”‚ (cabinet sim) β”‚ - β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ - β”‚ LV2 FX Chain β”‚ - β”‚ (mod/delay/verb) β”‚ - β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +### 1. OS Setup + +Start with **Raspberry Pi OS Lite (64-bit)** or **DietPi**. + +Configure hostname, enable SSH, and connect to WiFi: + +```bash +sudo hostnamectl set-hostname pedal +# Or on DietPi: use dietpi-config ``` -## Signal Chain +### 2. System Packages +```bash +sudo apt update && sudo apt upgrade -y +sudo apt install -y \ + git python3 python3-pip python3-venv python3-dev \ + jackd2 libjack-jackd2-dev \ + libsndfile1-dev \ + cmake build-essential \ + avahi-daemon # for pedal.local mDNS ``` -Input β†’ Gate β†’ Comp β†’ Boost β†’ NAM Amp β†’ IR Cab β†’ EQ β†’ Mod β†’ Delay β†’ Reverb β†’ Volume β†’ Output - β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ - β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ - β”Œβ”€β”€β”€β”€β”΄β”€β”€β”€β” β”Œβ”€β”΄β”€β”€β” β”Œβ”€β”€β”΄β”€β”€β”€β” β”Œβ”€β”΄β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”΄β”€β”€β” β”Œβ”€β”΄β”€β”€β” β”Œβ”€β”€β”΄β”€β”€β” β”Œβ”€β”€β”€β”΄β”€β”€β” β”Œβ”€β”€β”€β”΄β”€β”€β” β”Œβ”€β”€β”΄β”€β”€β”€β” - β”‚Noise β”‚ β”‚Dyn β”‚ β”‚Drive β”‚ β”‚Neural β”‚ β”‚IR β”‚ β”‚EQ β”‚ β”‚Mod β”‚ β”‚Delay β”‚ β”‚Reverbβ”‚ β”‚Masterβ”‚ - β”‚Gate β”‚ β”‚Compβ”‚ β”‚Boost β”‚ β”‚Amp β”‚ β”‚Cab β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚Volumeβ”‚ - β””β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”˜ + +### 3. Clone the Repo + +```bash +git clone https://gitea.ourpad.casa/shawn/pi-multifx-pedal.git ~/projects/pi-multifx-pedal +cd ~/projects/pi-multifx-pedal ``` +### 4. Python Environment + +```bash +python3 -m venv .venv +source .venv/bin/activate +pip install --upgrade pip +pip install -r requirements.txt +``` + +> **Note:** `neural-amp-modeler` needs PyTorch. On RPi 4B aarch64: +> ```bash +> pip install torch --index-url https://download.pytorch.org/whl/nightly/cpu +> ``` + +### 5. Focusrite-Specific Config + +Kill PulseAudio (it grabs USB audio): + +```bash +pulseaudio --kill +``` + +Verify Focusrite is detected: + +```bash +aplay -l +# Look for: card 1: USB Audio [Scarlett 2i2 USB], device 0 +arecord -l +# Look for same +``` + +Copy the mono test config: + +```bash +mkdir -p ~/.pedal +cp etc/config-focusrite-mono.yaml ~/.pedal/config.yaml +``` + +### 6. Run the Pedal + +```bash +cd ~/projects/pi-multifx-pedal +source .venv/bin/activate +python3 main.py +``` + +### 7. Open the Web UI + +From any device on the same network: +- **Browser:** http://pedal.local:8080 +- Or use the IP: http://192.168.x.x:8080 + +### 8. Wire It Up + +**Mono mode (standard pedal):** +``` +Guitar jack β†’ Focusrite Input 1 (front) +Focusrite Output 1 (rear) β†’ Amp +``` + +**4CM mode (four cable method):** +``` +Guitar β†’ Focusrite Input 1 +Amp FX Send β†’ Focusrite Input 2 +Focusrite Output 1 β†’ Amp Input (Send) +Focusrite Output 2 β†’ Amp FX Return (Output) +``` + +Then switch config: +```bash +cp etc/config-focusrite-4cm.yaml ~/.pedal/config.yaml +``` + +Toggle 4CM on/off from the Settings page in the web UI. + ## Hardware | Component | Spec | |-----------|------| | **SBC** | Raspberry Pi 4B (2GB+ RAM) | -| **Audio I/O** | I2S DAC + ADC (e.g. PCM1808 + PCM5102, or an Audio HAT) | +| **Audio I/O** | I2S DAC + ADC (PCM1808 + PCM5102 custom HAT, or USB via Focusrite 2i2) | | **Footswitches** | 3-6 momentary soft-touch (e.g. MXR-style) | | **LEDs** | RGB WS2812B or APA102 per footswitch + status LEDs | -| **Display** | 128x64 OLED SSD1306 (I2C) or small TFT | +| **Display** | 128x64 OLED SSD1306 (I2C) or 5" DSI touch | | **MIDI** | 5-pin DIN in/out via UART + optoisolator | | **Power** | 5V/3A USB-C (with buck for 3.3V rail) | | **Enclosure** | 1590BB or 3D-printed custom | +## 32 Effects + +| Category | Effects | +|----------|---------| +| **Dynamics** | Noise Gate, Compressor, Expander, De-esser, Transient Shaper, Sidechain Compressor | +| **Drive** | Boost, Overdrive, Distortion, Fuzz, Bitcrusher, Wavefolder, Rectifier | +| **Amp + Cab** | NAM Amp Model (any .nam file), IR Cab Sim (any .wav) | +| **Modulation** | Chorus, Flanger, Phaser, Tremolo, Vibrato, Ring Mod, Auto-Wah, Envelope Filter, Rotary Speaker, Uni-Vibe, Auto-Pan, Stereo Widener | +| **Time** | Delay, Ping-pong Delay, Multi-tap Delay, Reverse Delay, Tape Echo, Reverb, Shimmer Reverb, Early Reflections, Looper | +| **Pitch** | Octaver, Detune, Harmonizer, Whammy, Pitch Shifter | +| **Filter** | EQ, Parametric EQ, High-Pass, Low-Pass, Band-Pass, Notch, Formant, Wah | +| **Utility** | Volume, Tuner | + ## Project Structure ``` β”œβ”€β”€ src/ β”‚ β”œβ”€β”€ dsp/ Audio processing pipeline -β”‚ β”‚ β”œβ”€β”€ pipeline.py FX chain orchestration +β”‚ β”‚ β”œβ”€β”€ pipeline.py FX chain orchestration (mono + 4CM split) β”‚ β”‚ β”œβ”€β”€ ir_loader.py IR convolution engine β”‚ β”‚ β”œβ”€β”€ nam_host.py NAM model loading & inference -β”‚ β”‚ └── level.py Input/output level + tuner β”‚ β”œβ”€β”€ midi/ MIDI subsystem β”‚ β”‚ β”œβ”€β”€ handler.py MIDI event parse & dispatch -β”‚ β”‚ └── presets.py PC β†’ preset mapping +β”‚ β”œβ”€β”€ presets/ Preset system +β”‚ β”‚ β”œβ”€β”€ manager.py Save/load/bank/preset CRUD + 4CM routing +β”‚ β”‚ └── types.py Preset & chain data model + FXType enum β”‚ β”œβ”€β”€ ui/ Hardware UI layer β”‚ β”‚ β”œβ”€β”€ footswitch.py Debounced GPIO input β”‚ β”‚ β”œβ”€β”€ leds.py RGB LED controller β”‚ β”‚ └── display.py OLED display manager -β”‚ β”œβ”€β”€ presets/ Preset system -β”‚ β”‚ β”œβ”€β”€ manager.py Save/load/bank/preset CRUD -β”‚ β”‚ └── types.py Preset & chain data model +β”‚ β”œβ”€β”€ web/ Web UI (FastAPI + WebSocket) +β”‚ β”‚ β”œβ”€β”€ server.py REST + WebSocket endpoints +β”‚ β”‚ β”œβ”€β”€ templates/ Jinja2 HTML pages +β”‚ β”‚ └── static/ CSS + JS β”‚ └── system/ System integration β”‚ β”œβ”€β”€ audio.py ALSA/JACK/I2S configuration -β”‚ └── setup.py First-boot setup scripts +β”‚ └── config.py YAML config loader +β”œβ”€β”€ etc/ Config file templates β”œβ”€β”€ scripts/ Build & utility scripts β”œβ”€β”€ tests/ Tests -β”œβ”€β”€ docs/ Documentation +β”œβ”€β”€ docs/ Documentation + test plans └── hardware/ KiCad/PCB schematics ``` -## Development Quick Start +## Development ```bash -# Clone -git clone https://gitea.ourpad.casa/shawn/pi-multifx-pedal.git -cd pi-multifx-pedal - -# Install dependencies -pip install -r requirements.txt - -# Run tests +# Tests +source .venv/bin/activate python -m pytest tests/ -v + +# All 306+ tests should pass ``` -## Status - Early development β€” initial scaffold. \ No newline at end of file