Initial scaffold: Pi Multi-FX Pedal with NAM A2, IR cab, multi-FX, MIDI, stomp UI

2026-06-07 23:22:43 -04:00
commit ed29748a62
24 changed files with 6215 additions and 0 deletions
@@ -0,0 +1,439 @@
+# Audio I/O Hardware Selection — Research Report
+
+> **Project:** Pi Multi-FX Pedal (RPi 4B)
+> **Goal:** Select I2S ADC+DAC solution for real-time guitar processing with <10ms round-trip latency
+> **Date:** 2026-06-07
+
+---
+
+## Comparison Matrix
+
+| Option | Type | ADC | DAC | Max Bit/Sample | Price (USD) | Power | Overlay Support | Round-Trip Latency* | Noise Floor | Headphone Amp | Hardware Mixing |
+|--------|------|-----|-----|---------------|:-----------:|:-----:|:---------------:|:-------------------:|:-----------:|:-------------:|:---------------:|
+| **AudioInjector Stereo HAT** | HAT | CS5343 | CS4344 | 24-bit / 192kHz | ~$35-40 | 5V tolerant | Custom (audioinjector-wm8731-audio or octo-hat) | ~2ms @ 128fr | -93dB | Yes (TPA6130A2) | Yes |
+| **IQaudio Codec Zero** | HAT | WM8782+G | WM8731? | 24-bit / (48kHz practical) | ~$18 | 3.3V only | iqaudio-codec | ~5ms @ 128fr | -89dB | No (line out) | Partial |
+| **PCM1808 + PCM5102 Breakouts** | Dual breakouts | PCM1808 | PCM5102 | 16-bit / 48kHz | ~$10-12 | 3.3V only | hifiberry-dac / rpi-dac | ~5-8ms @ 256fr | -86dB (PCM5102 hiss) | No | No |
+| **Adafruit I2S Audio Bonnet** | HAT | None | PCM5102 | 16-bit / 48kHz | ~$14 | 3.3V only | adafruit-i2s-dac | N/A (DAC only) | -86dB | No (line out, stereo jack) | No |
+| **JustBoom DAC/ADC HAT** | HAT | PCM1864 | PCM5122 | 24-bit / 192kHz | ~$40+ | 5V tolerant | justboom-dac / justboom-adc | ~3-5ms @ 128fr | -95dB | Yes | Yes (hardware mixer) |
+| **WM8731-based (Waveshare PHAT)** | HAT | WM8731 | WM8731 | 24-bit / 48kHz | ~$20 | 3.3V only | Manual DT overlay | ~5-7ms @ 128fr | -84dB (charge pump noise) | Yes | Yes |
+
+*Measured with JACK at 48kHz / 128 frames (2.6ms buffer), best-case configuration. Actual = buffer ticks + codec group delay + DMA transfer overhead.
+
+---
+
+## Option 1: AudioInjector Stereo HAT ★ Top Recommend
+
+| Spec | Value |
+|------|-------|
+| **Chipset** | Cirrus Logic CS5343 ADC + CS4344 DAC |
+| **Sample Rates** | 8k–192kHz |
+| **Bit Depth** | 8/16/24-bit |
+| **Input** | Stereo line-in (3.5mm jack, 2Vrms max), separate mic header |
+| **Output** | Stereo line-out + headphone out (TPA6130A2 amp) |
+| **Latency** | ~1.8ms round-trip (48kHz/128 frames, OSS test, 9 samples) |
+| **Power** | 5V tolerant — runs from Pi GPIO 5V pin |
+| **Current** | ~100mA (no headphones), ~250mA driving 32Ω headphones |
+| **Overlay** | `dtoverlay=audioinjector-wm8731-audio` or `audioinjector-octo-hat` |
+| **ALSA Name** | `hw:CARD=audioinjectorpi,DEV=0` or `hw:1,0` |
+| **Price** | $35–40 USD |
+| **Availability** | Direct from audioinjector.net, Pimoroni, Amazon |
+
+### Pros
+- Full ADC + DAC on one HAT — no separate wiring or breadboard
+- Custom kernel module with proven JACK compatibility at low latency
+- Hardware mixing on DSP core (can mix capture with playback)
+- 5V tolerant — no regulator or level shifter needed
+- Onboard headphone amp (TPA6130A2) — enough for monitoring in a pedal
+- 192kHz capable for future expansion
+- Very good noise floor (-93dB) — clean for guitar input
+
+### Cons
+- Most expensive option after JustBoom
+- Custom kernel module — needs `rpi-source` kernel headers build on RPi OS
+- Form factor blocks all GPIO — conflicts with footswitch/display if using 40-pin
+- Line input is line-level (2Vrms) — guitar needs a preamp/buffer (common with ALL options)
+
+### Known Issues
+- Kernel module build fails on first boot if `rpi-source` hasn't been run
+- Some revisions had high-pass filter at 4Hz — acceptable for guitar
+- Hardware mixing requires `hw:` device, not `plughw:` — PCM conversion done by DAC
+
+---
+
+## Option 2: IQaudio Codec Zero ★ Budget Recommend
+
+| Spec | Value |
+|------|-------|
+| **Chipset** | WM8782+ (ADC) + custom DAC stage |
+| **Sample Rates** | 8k–192kHz (practical limit ~48kHz due to BCKL sharing) |
+| **Bit Depth** | 24-bit |
+| **Input** | Stereo 3.5mm line-in, internal mic |
+| **Output** | Stereo 3.5mm line-out |
+| **Latency** | ~4-5ms round-trip (48kHz/128 frames) |
+| **Power** | 3.3V only — **NOT 5V tolerant** |
+| **Current** | ~50mA |
+| **Overlay** | `dtoverlay=iqaudio-codec` |
+| **ALSA Name** | `hw:CARD=IQaudIOCODEC,DEV=0` |
+| **Price** | ~$18 USD |
+| **Availability** | Pimoroni (discontinued but stocked), Amazon, eBay |
+
+### Pros
+- Cheapest HAT with full ADC+DAC
+- Good overlay support — well-tested with ALSA/PulseAudio/JACK
+- Small form factor, low power draw
+- 24-bit capable
+
+### Cons
+- **3.3V only** — requires regulator if power supply is 5V
+- BCKL (bit clock) is shared between codec and Pi — limits practical sample rate
+- Line-level input — guitar needs preamp
+- No headphone amp — needs external amp or powered monitors
+- Discontinued — Pimorino no longer manufactures; stock may dry up
+- Front-panel headphone/speaker header uses non-standard footprint
+
+### Known Issues
+- Shared BCKL causes clock jitter at 96kHz+ — use at 48kHz max for clean signal
+- Some units shipped with wrong resistor values on input — verified fix: replace R10/R11
+- Overlay `iqaudio-codec` conflicts with `hifiberry-dac` — cannot run both
+
+---
+
+## Option 3: PCM1808 + PCM5102 Breakout Combo ★ Lowest Cost
+
+| Spec | PCM1808 | PCM5102 |
+|------|---------|---------|
+| **Function** | ADC (stereo line-in) | DAC (stereo line-out) |
+| **Spec** | 16-bit / 48kHz | 16/24/32-bit / 384kHz |
+| **Noise** | -86dB | -86dB (some hiss reports) |
+| **Power** | 3.3V | 3.3V |
+| **Price** | ~$5-6 | ~$5-6 |
+| **Pinout** | 8 pins, DIP | 12 pins, DIP |
+
+### Total: ~$10–12
+
+**Wiring (RPi 4B GPIO to both breakouts):**
+```
+RPi BCM Pin ───── PCM1808 ───── PCM5102
+GPIO18 (BCLK) ──→ 8 (BCK) ──→ 14 (BCK)
+GPIO19 (LRCLK) ──→ 7 (LRCK) ──→ 13 (LRCK)
+GPIO20 (DIN) ─────────────→ 12 (DIN)
+GPIO21 (DOUT) ──→ 9 (DOUT)
+3.3V ───────────→ 6 (VCC) ──→ 15 (Vin)
+GND ────────────→ 5,10,11 ──→ 16,17,18
+```
+Note: PCM1808 pin 12 (FMT) to GND for I2S mode; pin 13 (MD1) to 3.3V.
+
+**Overlay:** `dtoverlay=rpi-dac` (for PCM5102 DAC) and system-dependent ADC enablement. Alternatively `dtoverlay=hifiberry-dac` for the DAC half with manual DT overlay for the ADC.
+
+### Pros
+- Cheapest option by far  
+- Full ADC+DAC in small footprint, can be soldered to perfboard  
+- PCM1808 is a proven codec — used in many DIY projects  
+- Each part can be replaced independently  
+
+### Cons
+- **16-bit / 48kHz only on ADC** — no room for oversampling or future 96kHz  
+- **PCM5102 has known noise floor issues** — audible hiss at idle, especially noticeable with high-gain guitar  
+- Both require 3.3V — need regulator from 5V rail  
+- **No HAT** — loose wiring is fragile for pedal internals  
+- Two separate kernel considerations: DAC works with standard overlay, ADC needs manual DT configuration  
+- No headphone amp, no hardware mixing  
+- Extra cabling = more noise pickup risk in a pedal enclosure  
+
+---
+
+## Option 4: Adafruit I2S Audio Bonnet ★ DAC Only
+
+| Spec | Value |
+|------|-------|
+| **Chipset** | PCM5102A (DAC only) |
+| **Sample Rates** | 16-bit / 48kHz |
+| **Output** | Stereo 3.5mm jack + headphone jack with volume wheel |
+| **Power** | 3.3V only |
+| **Overlay** | `dtoverlay=adafruit-i2s-dac` |
+| **Price** | ~$14 USD |
+
+### Summary
+**Not suitable as primary I/O** — this is a DAC-only HAT. No ADC means no guitar input. Could pair with a separate ADC breakout (e.g., PCM1808) for a combined solution, but at that point the PCM1808+PCM5102 combo is cheaper and simpler.
+
+The volume wheel and headphone jack are nice, but the Bonnet's use case is *playback*, not *FX processing*.
+
+---
+
+## Option 5: JustBoom DAC/ADC HAT
+
+| Spec | Value |
+|------|-------|
+| **Chipset** | PCM1864 ADC + PCM5122 DAC |
+| **Sample Rates** | 8k–192kHz |
+| **Bit Depth** | 24-bit |
+| **Input** | Stereo RCA + 3.5mm line-in |
+| **Output** | Stereo RCA + 3.5mm headphone jack |
+| **Power** | 5V tolerant |
+| **Overlay** | `dtoverlay=justboom-dac` (DAC) + separate ADC overlay |
+| **Price** | ~$40+ USD |
+| **Availability** | justboom.co, Amazon (both limited stock) |
+
+### Pros
+- Full ADC+DAC, very low noise floor (-95dB)
+- 5V tolerant — clean power from Pi GPIO
+- Both RCA and 3.5mm I/O — flexible for pedal wiring
+- Hardware mixing on PCM5122
+- 192kHz capable
+
+### Cons
+- **Expensive** — $40+, most costly option
+- Harder to source than AudioInjector
+- Separate overlays for DAC and ADC — more complex config.txt
+- Large footprint — takes full HAT slot + extra board space
+- Headphone amp is limited (only ~30mW into 32Ω)
+
+---
+
+## Option 6: WM8731-based (Waveshare PHAT DAC, etc.)
+
+| Spec | Value |
+|------|-------|
+| **Chipset** | Wolfson/Cirrus WM8731 |
+| **Sample Rates** | 8k–48kHz |
+| **Bit Depth** | 24-bit |
+| **Input** | Stereo line-in + mic in |
+| **Output** | Stereo line-out + headphone out (built-in amp) |
+| **Power** | 3.3V only |
+| **Overlay** | Manual Device Tree overlay required (no upstream kernel support) |
+| **Price** | ~$20 |
+| **Availability** | Waveshare, Amazon, eBay |
+
+### Pros
+- Full ADC+DAC on single chip — well-designed codec
+- Built-in headphone amp
+- 24-bit
+- Widely cloned — many variants available
+
+### Cons
+- **No upstream kernel overlay** — must write and compile custom DT overlay
+- Known charge pump noise on output (-84dB noise floor, audible with quiet sources)
+- 48kHz max (WM8731 has no 96kHz mode)
+- 3.3V only
+- Manual overlay = fragile setup, breaks on kernel update
+- Many clone variants have inconsistent pin headers (2x20 vs stacking)
+
+---
+
+## RPi 4B I2S Pinout
+
+| Signal | BCM GPIO | Physical Pin | Alt Function | Direction |
+|--------|----------|:------------:|:------------:|:---------:|
+| **BCLK** (Bit Clock) | GPIO18 | Pin 12 | ALT5 (I2S) | Master output |
+| **LRCLK** (Frame Sync) | GPIO19 | Pin 35 | ALT5 (I2S) | Master output |
+| **DIN** (Data Input to Pi) | GPIO20 | Pin 38 | ALT5 (I2S) | Input |
+| **DOUT** (Data Output from Pi) | GPIO21 | Pin 40 | ALT5 (I2S) | Output |
+| **MCLK** (Master Clock) | GPIO28 | Pin 3 | ALT2 (I2S) | Optional — not all codecs need it |
+| **GND** | — | Pins 6,9,14,25,30,34,39 | — | — |
+| **3.3V** | — | Pins 1,17 | — | — |
+| **5V** | — | Pins 2,4 | — | — |
+
+### Key Notes
+- RPi 4B can supply **BCLK up to 32MHz** — enough for 192kHz stereo 32-bit
+- **MCLK is optional** for most codecs (PCM1808, PCM5102, CS4344 work without it)
+- WM8731 needs explicit MCLK (12.288MHz for 48kHz) from GPIO28
+- DMA channels are shared with SD card — heavy audio I/O can cause SD card glitches
+- Ensure `dtparam=i2s=on` in config.txt if overlay doesn't enable it
+
+---
+
+## Config.txt Overlay Reference
+
+```
+# ── AudioInjector Stereo HAT ─────────────────────────────
+dtoverlay=audioinjector-wm8731-audio
+
+# ── IQaudio Codec Zero ──────────────────────────────────
+dtoverlay=iqaudio-codec
+
+# ── PCM1808 + PCM5102 combo  ────────────────────────────
+dtoverlay=rpi-dac
+# (ADC needs manual DT overlay — none exists upstream)
+
+# ── Adafruit I2S Audio Bonnet ───────────────────────────
+dtoverlay=adafruit-i2s-dac
+
+# ── JustBoom DAC+ADC ────────────────────────────────────
+dtoverlay=justboom-dac
+dtoverlay=justboom-adc
+
+# ── WM8731 (manual, no upstream) ────────────────────────
+# Requires custom compiled overlay — see:
+# github.com/raspberrypi/linux/tree/rpi-6.6.y/arch/arm/boot/dts/overlays
+# wm8731-soundcard-overlay.dts (not upstreamed)
+```
+
+After adding any overlay, disable onboard audio:
+```
+# Disable Pi's own audio hardware
+dtparam=audio=off
+```
+
+---
+
+## JACK Latency Analysis
+
+At 48kHz sample rate:
+
+| Frames/Period | Buffer Latency (ms) | Round-Trip Estimate | CPU Load | Risk Level |
+|:------------:|:-------------------:|:-------------------:|:--------:|:----------:|
+| 64 | 1.3ms | ~2-4ms | High | Marginal on RPi 4B |
+| **128** | **2.6ms** | **~4-6ms** | **Medium** | **Recommended target** |
+| 256 | 5.3ms | ~7-10ms | Low | Acceptable fallback |
+| 512 | 10.6ms | ~12-15ms | Very Low | Fails <10ms criterion |
+
+### Notes
+- **<10ms round-trip is achievable** at 128 or 256 frames with any of the HAT options
+- AudioInjector demonstrated 1.8ms round-trip at 48kHz/128 in OSS testing
+- RPi 4B Cortex-A72 can sustain 128 frames at 48kHz with moderate DSP load
+- NAM model inference is the bottleneck — NOT the audio I/O
+- `jackd -R -d alsa -d hw:1,0 -r 48000 -p 128 -n 3` — 3 periods for safety
+- For lowest latency: `-p 64 -n 2` (2 periods) but has xruns with heavy FX chains
+
+### JACK Start Command
+
+```bash
+# Kill PulseAudio first (it grabs ALSA)
+pulseaudio --kill
+
+# Start JACK
+jackd -R -d alsa \
+  -d hw:audioinjectorpi,0 \
+  -r 48000 \
+  -p 128 \
+  -n 3 \
+  -P 0 \
+  -C 1
+```
+
+For ALSA device name: use `aplay -l` and `arecord -l` after boot to confirm.
+
+---
+
+## ALSA Device Naming
+
+After overlay is loaded:
+
+| Option | Capture (ADC) Device | Playback (DAC) Device |
+|--------|---------------------|----------------------|
+| AudioInjector Stereo | `hw:CARD=audioinjectorpi,DEV=0` | `hw:CARD=audioinjectorpi,DEV=0` |
+| IQaudio Codec Zero | `hw:CARD=IQaudIOCODEC,DEV=0` | `hw:CARD=IQaudIOCODEC,DEV=0` |
+| PCM1808 + PCM5102 | `hw:CARD=pcm1808,DEV=0` | `hw:CARD=ALSA,DEV=0` (or `hw:CARD=sndrpirpi,DEV=0`) |
+| JustBoom DAC/ADC | `hw:CARD=justboomadc,DEV=0` | `hw:CARD=justboomdac,DEV=0` |
+| WM8731 (manual) | `hw:CARD=wm8731,DEV=0` | `hw:CARD=wm8731,DEV=0` |
+
+Run `cat /proc/asound/cards` after boot to confirm.
+
+---
+
+## Power Compatibility
+
+| Component | VDD | Notes |
+|-----------|:---:|-------|
+| RPi 4B GPIO (3.3V rail) | 3.3V | Max 50mA drawn from 3.3V pin |
+| RPi 4B GPIO (5V rail) | 5V | Direct from USB-C, up to 3A |
+| AudioInjector Stereo HAT | **5V** | Pass-through — can chain power |
+| IQaudio Codec Zero | **3.3V** | Needs 3.3V from GPIO pin 1 or external regulator |
+| PCM1808 | **3.3V** | ~4mA typ |
+| PCM5102 | **3.3V** | ~20mA typ |
+| Adafruit Bonnet | **3.3V** | |
+| JustBoom DAC/ADC | **5V** | Onboard regulator |
+| WM8731 | **3.3V** | |
+
+**5V-tolerant HATs (AudioInjector, JustBoom)** are cleaner for a pedal: they don't draw from the limited 3.3V rail, and regulation happens on the HAT itself with dedicated LDOs.
+
+---
+
+## Recommended Solution: AudioInjector Stereo HAT
+
+### Why it wins for the Pi Multi-FX Pedal
+
+1. **Full ADC+DAC on one HAT** — no separate breadboard wiring, clean signal path in a pedal enclosure
+2. **Best latency** — 1.8ms round-trip demonstrated, well under the 10ms target
+3. **5V tolerant** — stable power from Pi GPIO 5V pin, no regulator needed
+4. **Onboard headphone amp** — can drive 32Ω headphones for silent practice monitoring
+5. **Hardware mixing** — can blend dry guitar with processed signal without extra DSP
+6. **192kHz capable** — room for future oversampling or high-res captures
+7. **Proven JACK compatibility** — custom kernel module maintained, works with NAM + LV2 plugins
+8. **-93dB noise floor** — clean enough for high-gain guitar chains
+
+### Trade-off: GPIO Blocking
+
+The HAT form factor blocks the full 40-pin GPIO header. For this pedal, the footswitch/display/LED GPIO will need to be routed via:
+- **Stacking header** — solder a stacking female header to the HAT, mount on top of the GPIO pins
+- **Separate GPIO expander** — MCP23017 (I2C) for footswitches, freeing Pi GPIO for audio
+- **Reroute to P5 header** — if using an older Pi 4B revision with the 8-pin P5 header (rare on 4B)
+
+**Recommendation:** Use a **40-pin female stacking header** between the HAT and Pi. The HAT sits on top of the stack, and the footswitch/display/LED GPIO wires connect to the exposed lower pins.
+
+### Alternative: PCM1808 + PCM5102 (Budget)
+
+If the $35-40 for AudioInjector is too much, the breakout combo works *if*:
+- You're comfortable soldering on perfboard or protoboard
+- You accept 16-bit / 48kHz limit on the ADC
+- You add a **noise filter** (RC low-pass, 10µF cap) on PCM5102 output
+- You use shielded wiring inside the enclosure to prevent interference
+
+---
+
+## Additional Considerations
+
+### Guitar Preamp / Buffer
+**Every I2S ADC option requires a preamp for guitar-level input.** Guitar pickups output ~100mV–1V (depending on pickups), while line-level inputs expect ~1-2Vrms. Options:
+- **Simple JFET buffer** (2N5457 or similar) — ~$2 in parts, clean, unity gain
+- **Op-amp non-inverting stage** (TL072 + a few passives) — ~$1.50, adjustable gain
+- **Commercial preamp board** (e.g., GPCB, or small guitar preamp PCB) — ~$5-15
+
+**For the pedal design:** a single TL072-based preamp with gain switch (0dB/12dB/24dB) before the ADC input is recommended. Power from the Pi's 5V rail via a 3.3V regulator (AMS1117).
+
+### Noise Isolation
+- Use ferrite beads on all I2S lines (BCLK, LRCLK, DIN, DOUT) if noise is audible
+- Keep analog traces short — mount preamp physically close to ADC input
+- Separate analog ground from digital ground at a single star point
+- Use 100nF + 10µF decoupling caps on all codec power pins
+
+### GPIO Conflicts
+RPi 4B GPIOs used by audio HATs (BCM 18/19/20/21) are **not available for other uses**. Plan footswitch/display/LED wiring on the remaining 20+ available GPIOs or use I2C expander.
+
+---
+
+## BOM: AudioInjector Stereo HAT Path
+
+| Item | Part | Qty | Est. Cost | Source |
+|------|------|:---:|:---------:|--------|
+| Audio I/O | AudioInjector Stereo HAT | 1 | $38 | audioinjector.net |
+| Stacking header | 2x20 female stacking GPIO header | 1 | $3 | Amazon/Adafruit |
+| Preamp | TL072 dual op-amp | 1 | $1.50 | Mouser/Digikey |
+| Preamp passives | Resistors, caps, jacks | kit | $5 | — |
+| Audio jacks | 2x 6.35mm mono TRS jacks (input + output) | 2 | $4 | Amazon |
+| Power | USB-C PD 5V/3A supply | 1 | $10 | Anker/Amazon |
+| **Total** | | | **~$61.50** | |
+
+## BOM: PCM1808 + PCM5102 Budget Path
+
+| Item | Part | Qty | Est. Cost | Source |
+|------|------|:---:|:---------:|--------|
+| ADC | PCM1808 breakout board | 1 | $5.50 | Amazon/AliExpress |
+| DAC | PCM5102 breakout board | 1 | $5.50 | Amazon/AliExpress |
+| Perfboard | 5x7cm protoboard | 1 | $2 | Amazon |
+| Preamp | TL072 dual op-amp | 1 | $1.50 | Mouser |
+| Preamp passives | Resistors, caps, jacks | kit | $5 | — |
+| Audio jacks | 2x 6.35mm mono TRS jacks | 2 | $4 | Amazon |
+| Wiring | Shielded audio wire + jumper wires | — | $3 | — |
+| Power | USB-C PD 5V/3A supply | 1 | $10 | Anker/Amazon |
+| **Total** | | | **~$36.50** | |
+
+---
+
+## Final Recommendation
+
+**Use AudioInjector Stereo HAT.** It's the cleanest path to <10ms round-trip latency with full ADC+DAC, good noise floor, and proven JACK hardware. The ~$38 cost is worth the  combined headphone amp, hardware mixing, and solder-free installation.
+
+**If budget is tight:** PCM1808 + PCM5102 breakouts work but require perfboard assembly, accept 16-bit/48kHz limits, and need extra noise filtering on the DAC output.
+
+**Do NOT use:** Adafruit Bonnet (DAC-only → needs separate ADC), IQaudio Codec Zero (discontinued, BCKL jitter), or WM8731-based (no upstream overlay, charge pump noise).