Populate wiki with full documentation including USB/NVMe boot options

2026-05-19 23:07:19 -04:00
parent a37a193507
commit 9492cdd324
5 changed files with 215 additions and 0 deletions
@@ -0,0 +1,38 @@
+# API Reference
+
+## REST API (Port 8080)
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/health` | GET | Health check |
+| `/api/channels` | GET | List all channels |
+| `/api/channels/{id}` | GET | Channel state |
+| `/api/channels/{id}` | PUT | Update channel (fader, mute, solo, pan) |
+| `/api/routing` | GET | Routing matrix |
+| `/api/routing` | PUT | Update routing |
+| `/api/transport` | GET | Transport state |
+| `/api/transport/play` | POST | Start playback |
+| `/api/transport/stop` | POST | Stop |
+| `/api/transport/record` | POST | Toggle record |
+| `/api/plugins` | GET | List plugins |
+| `/api/scenes` | GET | List scenes/snapshots |
+| `/api/scenes/{id}` | POST | Recall scene |
+
+## WebSocket (ws://host:8080/ws)
+
+Real-time bi-directional state sync. Messages are JSON:
+
+```json
+{"type": "fader_move", "channel": 3, "value": 0.75}
+{"type": "state_sync", "channels": [...], "meters": {...}}
+```
+
+## OSC (UDP Port 9000)
+
+| Address | Args | Description |
+|---------|------|-------------|
+| `/channel/{id}/fader` | f | Set fader level |
+| `/channel/{id}/mute` | i | Set mute |
+| `/channel/{id}/pan` | f | Set pan |
+| `/transport/play` | — | Start play |
+| `/transport/stop` | — | Stop |
@@ -0,0 +1,34 @@
+# Audio Stack Configuration
+
+## Target Configuration
+
+| Parameter | Value |
+|-----------|-------|
+| Sample rate | 48 kHz |
+| Buffer size | 128 frames (~2.7ms) |
+| Periods | 3 |
+| JACK priority | 70 (server) / 80 (clients) |
+| IRQ priority | 95 (USB/xHCI) |
+| CPU isolation | cores 1-3 for audio, core 0 for system |
+| Round-trip latency | 5-8ms |
+| Max channels | 16-18 @ 48kHz/24-bit |
+
+## Kernel Command Line
+
+```
+console=tty1 quiet loglevel=3 threadirqs nohz_full=1-3 rcu_nocbs=1-3 isolcpus=1-3 usbcore.autosuspend=-1 fsck.mode=skip
+```
+
+## Services
+
+- `jackd.service` — JACK2 audio server (auto-start)
+- `mixer-api.service` — REST/WebSocket/OSC API
+- `mixer-ui.service` — Touchscreen UI (Kivy)
+- `cpu-performance.service` — CPU governor lock
+- `mixer-firstboot.service` — Setup wizard (disables after first run)
+
+## ALSA Configuration
+
+- `snd-usb-audio` loaded as module
+- `alsa-usb.conf` in `/etc/modprobe.d/` for USB audio quirk handling
+- Default device: `hw:USB` (configured by first-boot wizard)
@@ -0,0 +1,55 @@
+# Build Instructions
+
+## Quick Start
+
+```bash
+git clone https://gitea.ourpad.casa/shawn/raspberry-pi-mixer.git
+cd raspberry-pi-mixer
+```
+
+### Dependencies
+
+```bash
+sudo apt install wget xz-utils dosfstools e2fsprogs qemu-user-static parted git
+# Optional (PREEMPT_RT kernel):
+sudo apt install gcc-aarch64-linux-gnu build-essential flex bison libssl-dev bc rsync
+```
+
+## Build Modes
+
+| Command | Description | Time |
+|---------|-------------|------|
+| `./build/build.sh` | Full build with PREEMPT_RT kernel | 30-45 min |
+| `./build/build.sh --skip-kernel` | Quick build, stock kernel | 10-15 min |
+| `./build/build.sh --target usb` | Build for USB SSD boot | 30-45 min |
+| `./build/build.sh --target nvme` | Build for NVMe HAT (NVMe driver included) | +1 min |
+| `./build/build.sh --kernel-only` | Only build RT kernel | 10-15 min |
+
+## Flashing
+
+### SD Card
+```bash
+sudo dd if=build/out/rpi-audio-mixer-*.img of=/dev/mmcblk0 bs=4M status=progress conv=fsync
+```
+
+### USB SSD
+```bash
+sudo dd if=build/out/rpi-audio-mixer-*.img of=/dev/sda bs=4M status=progress conv=fsync
+# Then on Pi: sudo rpi-eeprom-config --edit → BOOT_ORDER=0xf41
+```
+
+### NVMe HAT
+```bash
+sudo dd if=build/out/rpi-audio-mixer-*.img of=/dev/nvme0n1 bs=4M status=progress conv=fsync
+# Then on Pi: sudo rpi-eeprom-config --edit → BOOT_ORDER=0xf614
+```
+
+## First Boot
+
+The setup wizard runs automatically and configures:
+1. Audio interface detection
+2. WiFi network
+3. Hostname
+4. API key
+5. JACK buffer/latency
+6. **EEPROM boot order** (USB/NVMe option)
@@ -0,0 +1,55 @@
+# Hardware Reference
+
+## Raspberry Pi
+
+| Model | Status |
+|-------|--------|
+| Pi 4B (8GB) | ✅ Primary target |
+| Pi 4B (4GB) | ✅ Supported |
+| Pi 5 | ⚠️ Untested |
+| Pi 3B+ | ❌ USB 2.0 only |
+
+## Storage / Boot Media
+
+| Media | Target | Bus | Recommendation |
+|-------|--------|-----|----------------|
+| A2 SD Card | `--target sd` | SDIO | Dev/testing |
+| USB 3.0 SSD | `--target usb` | USB 3.0 | Portable use |
+| NVMe SSD + HAT | `--target nvme` | PCIe | **Production** |
+
+### NVMe HATs
+
+| HAT | Size | Price |
+|-----|------|-------|
+| Official RPi NVMe Base | 2230/2242 | ~€15 |
+| Pimoroni NVMe Base | 2230/2242 | ~€15 |
+| Geekworm X1001 | 2230 | ~€12 |
+| Geekworm X1002 | 2242/2280 | ~€15 |
+
+## USB Audio Interfaces
+
+| Interface | I/O | Status |
+|-----------|-----|--------|
+| Behringer UMC1820 | 18/20 | ✅ Verified |
+| Behringer UMC404HD | 4/4 | ✅ Verified |
+| Focusrite Scarlett 18i20 (3rd Gen) | 18/20 | ✅ Verified |
+| MOTU M4 | 4/4 | ✅ Verified |
+| RME Babyface Pro FS | 12/12 | ✅ Verified |
+| Zoom UAC-8 | 8/8 | ✅ Verified |
+| Behringer XR18 | 18/18 | ✅ Verified |
+
+## Displays
+
+| Display | Connection | Status |
+|---------|-----------|--------|
+| Official RPi 7" Touch | DSI | ✅ Verified |
+| Waveshare 5" HDMI | HDMI + USB touch | ✅ Verified |
+| Waveshare 7" HDMI | HDMI + USB touch | ✅ Verified |
+
+## MIDI Controllers
+
+All USB class-compliant MIDI controllers work. Tested with:
+- Behringer X-Touch One
+- FaderFox UC4
+- Arturia BeatStep Pro
+- Korg nanoKONTROL2
@@ -0,0 +1,33 @@
+# Raspberry Pi Real-Time Audio Mixer
+
+> A custom Linux distribution for Raspberry Pi 4B (8GB) that turns it into a professional digital mixer with VST/LV2 plugin support, touchscreen UI, web/mobile control, MIDI, recording, and streaming.
+
+## Quick Links
+
+- [[Build-Instructions]] — Build your own SD/USB/NVMe image from source
+- [[Audio-Stack-Configuration]] — JACK2, ALSA, PREEMPT_RT kernel tuning reference
+- [[Hardware-Reference]] — Tested USB audio interfaces, NVMe HATs, displays, MIDI controllers
+- [[API-Reference]] — REST, WebSocket, and OSC API documentation
+
+## Features
+
+- **Low-latency audio** — PREEMPT_RT kernel + JACK2, 5-8ms round-trip at 48kHz/128 samples
+- **Multi-channel routing** — 16-18 channels to USB audio interface
+- **Plugin host** — Carla with LV2, VST3, Neural Amp Modeler support
+- **Touchscreen UI** — Kivy-based local display (5-7 inch)
+- **Web app** — Mobile-responsive mixer surface
+- **MIDI control** — Learn mode, clock sync, HID discovery
+- **Recording** — Multi-track WAV with session management
+- **Streaming** — GStreamer H.264 audio/video pipeline
+
+## Boot Options
+
+The same image supports three boot targets:
+
+| Media | Build Flag | Recommendation |
+|-------|-----------|----------------|
+| SD Card | `--target sd` (default) | Development/testing |
+| USB SSD | `--target usb` | Portable, but shares USB bus with audio |
+| NVMe HAT | `--target nvme` | **Production** — PCIe, no bus contention |
+
+See [[Build-Instructions]] for full build and flash guide.