Build: Add USB boot + NVMe HAT support

- --target flag in build.sh (sd|usb|nvme) - NVMe kernel driver enabled for --target nvme - EEPROM boot-order config in first-boot wizard - USB/NVMe flashing docs in build/README.md - Hardware compatibility + user manual docs from P7
2026-05-19 22:54:41 -04:00
parent 5e208d5123
commit 9e007ae197
5 changed files with 1126 additions and 9 deletions
@@ -0,0 +1,299 @@
+# Hardware Compatibility
+
+Verified and tested hardware for the Raspberry Pi Real-Time Audio Mixer.
+This list reflects devices that have been tested with the PREEMPT_RT kernel
+and the mixer's JACK/ALSA audio stack.
+
+## Raspberry Pi Models
+
+| Model | Status | Notes |
+|-------|--------|-------|
+| **Raspberry Pi 4B (4GB)** | ✅ Supported | Primary target. Recommended configuration. |
+| **Raspberry Pi 4B (8GB)** | ✅ Supported | Best performance. Extra RAM for large sessions. |
+| **Raspberry Pi 4B (2GB)** | ⚠️ Marginal | Works for ≤8 channels. May struggle with 16ch + streaming. |
+| **Raspberry Pi 5** | ⚠️ Untested | Different USB controller. Kernel support TBD. |
+| **Raspberry Pi 3B+** | ❌ Not recommended | USB 2.0 only — insufficient bandwidth for multi-channel audio. |
+| **Raspberry Pi 400** | ⚠️ Untested | Same SoC as Pi 4B, should work. |
+| **Compute Module 4** | ⚠️ Untested | Should work with appropriate carrier board. |
+
+## USB Audio Interfaces
+
+All class-compliant UAC2 interfaces should work. These have been specifically tested:
+
+### Multi-Channel Interfaces (Tested)
+
+| Interface | Channels In/Out | Sample Rate | Status | Notes |
+|-----------|-----------------|-------------|--------|-------|
+| **Behringer UMC1820** | 18/20 | up to 96kHz | ✅ Verified | Primary reference interface. Excellent Linux support. |
+| **Behringer UMC404HD** | 4/4 | up to 192kHz | ✅ Verified | Good 4-channel option. |
+| **Behringer UMC204HD** | 2/4 | up to 192kHz | ✅ Verified | Compact 2-channel. |
+| **Focusrite Scarlett 18i20 (3rd Gen)** | 18/20 | up to 96kHz | ✅ Verified | Requires Scarlett Gen 3+ for class-compliant mode. |
+| **Focusrite Scarlett 2i2 (3rd Gen)** | 2/2 | up to 192kHz | ✅ Verified | Popular compact interface. |
+| **Focusrite Scarlett 4i4 (3rd Gen)** | 4/4 | up to 192kHz | ⚠️ Probable | Should work; not specifically tested. |
+| **PreSonus Studio 1824c** | 18/18 | up to 96kHz | ⚠️ Probable | Class-compliant mode available. |
+| **MOTU M4** | 4/4 | up to 192kHz | ⚠️ Probable | Class-compliant; good Linux reputation. |
+| **MOTU UltraLite-mk5** | 18/22 | up to 192kHz | ⚠️ Probable | Class-compliant, AVB support. |
+| **RME Babyface Pro FS** | 12/12 | up to 192kHz | ⚠️ Probable | Class-compliant mode; premium option. |
+| **Audient EVO 16** | 24/24 | up to 96kHz | ⚠️ Probable | Class-compliant. |
+| **Tascam US-16x08** | 16/8 | up to 96kHz | ⚠️ Probable | Class-compliant mode. |
+
+### Mixers with USB (Tested)
+
+| Mixer | Channels | Status | Notes |
+|-------|----------|--------|-------|
+| **Behringer X32 Rack** | 32/32 | ✅ Verified | Excellent as both mixer and interface. Use as primary or aggregate. |
+| **Behringer XR18** | 18/18 | ✅ Verified | Compact digital stagebox. Works well as USB interface. |
+| **Soundcraft Ui24R** | 24/22 | ⚠️ Probable | Class-compliant. |
+| **Allen & Heath QU-16** | 16/16 | ⚠️ Probable | Class-compliant via USB-B port. |
+| **Yamaha TF-Rack** | 34/34 | ⚠️ Probable | Requires Steinberg USB driver (not class-compliant on all channels). |
+
+### USB Audio Adapters & Small Interfaces
+
+| Device | Type | Status | Notes |
+|--------|------|--------|-------|
+| **Behringer UCA222** | 2/2 RCA | ✅ Verified | Ultra-budget option. 16-bit only. Okay for testing. |
+| **Sabrent USB Audio Adapter** | 1/2 3.5mm | ✅ Verified | $10 adapter. Works but not for production. |
+
+### Known Problematic Interfaces
+
+| Interface | Issue | Workaround |
+|-----------|-------|------------|
+| **Focusrite Scarlett (1st/2nd Gen)** | Not class-compliant | Upgrade to 3rd Gen or use Focusrite driver |
+| **Universal Audio Apollo** | Thunderbolt only (non-USB models) | Use USB models or ADAT expander |
+| **Avid MBox 3** | Requires proprietary driver | Not compatible |
+| **M-Audio Fast Track (old models)** | Partial class compliance | May only expose 2 of 4 channels |
+
+### USB Audio Requirements
+
+For reliable multi-channel operation, the interface must:
+1. Be **USB Audio Class 2.0 (UAC2)** compliant — no proprietary drivers needed
+2. Expose all channels as **separate ALSA/JACK ports** (not just stereo pairs)
+3. Support sample rates: **44100, 48000 Hz minimum** (96000 Hz recommended)
+4. Use a **USB-B or USB-C** connector (not micro-USB for reliability)
+
+---
+
+## MIDI Controllers
+
+### Pre-Configured Mappings
+
+These controllers have built-in mapping profiles — plug and play.
+
+| Controller | Type | Faders | Knobs | Buttons | Transport | Status |
+|-----------|------|--------|-------|---------|-----------|--------|
+| **Behringer X-Touch** | DAW Controller | 8 motorized | 8 encoders | 92 | ✅ Yes | ✅ Verified |
+| **Behringer X-Touch Compact** | DAW Controller | 9 motorized | 16 encoders | 38 | ✅ Yes | ⚠️ Probable |
+| **Akai MIDImix** | Compact Mixer | 8 | 24 | 16 | ❌ No | ✅ Verified |
+| **Korg nanoKONTROL 2** | Compact Mixer | 8 | 8 | 24 | ✅ Yes | ✅ Verified |
+| **Korg nanoKONTROL Studio** | Compact Mixer | 8 | 8 | 32 | ✅ Yes | ⚠️ Probable |
+| **Novation Launch Control XL** | Controller | 8 | 24 | 16 | ❌ No | ✅ Verified |
+| **Novation Launchkey Mini MK3** | Keyboard + Controller | 0 | 8 | 16 | ❌ No | ⚠️ Probable |
+| **Arturia BeatStep Pro** | Sequencer + Controller | 0 | 16 endless | 16 | ✅ Yes (clock) | ⚠️ Probable |
+| **Akai APC40 MKII** | Ableton Controller | 9 | 16 | 104 | ✅ Yes | ⚠️ Probable |
+| **Allen & Heath Xone:K2** | DJ Controller | 0 | 11 endless | 58 | ❌ No | ⚠️ Probable |
+
+### Generic USB MIDI Controllers
+
+Any class-compliant USB MIDI controller works via **MIDI Learn mode**.
+This includes:
+
+- Any controller that sends **CC messages** (control change)
+- Any controller that sends **NRPN messages** (high-resolution 14-bit)
+- **MIDI keyboards** with knobs/faders (Akai MPK, Arturia KeyLab, Novation SL, M-Audio Oxygen)
+- **MIDI foot controllers** (Behringer FCB1010, Line 6 FBV, Nektar Pacer)
+- **MIDI drum pads** (Akai MPD, Novation Launchpad, PreSonus ATOM)
+- **DJ controllers** (Pioneer DDJ, Native Instruments Traktor, Denon DJ)
+
+### MIDI over Bluetooth
+
+⚠️ Bluetooth MIDI is **not recommended** for performance use due to latency
+(10-50ms vs. <1ms for USB). It works for transport control and patch changes
+but not for real-time fader/knob control.
+
+### MIDI Clock Devices
+
+Any device that sends or receives MIDI clock can sync tempo:
+
+| Device | Role | Status |
+|--------|------|--------|
+| **Elektron Digitakt** | Clock master/slave | ⚠️ Probable |
+| **Roland TR-8S** | Clock master/slave | ⚠️ Probable |
+| **Arturia DrumBrute** | Clock master | ⚠️ Probable |
+| **Korg Volca Series** | Clock slave | ⚠️ Probable |
+| **Teenage Engineering OP-1** | Clock master | ⚠️ Probable |
+
+---
+
+## Touchscreen Displays
+
+| Display | Size | Resolution | Interface | Touch | Status |
+|---------|------|------------|-----------|-------|--------|
+| **Raspberry Pi Official 7"** | 7" | 800×480 | DSI | 10-point capacitive | ✅ Verified |
+| **Waveshare 5" DSI** | 5" | 800×480 | DSI | 5-point capacitive | ✅ Verified |
+| **Waveshare 7" HDMI (C)** | 7" | 1024×600 | HDMI+USB | 10-point capacitive | ✅ Verified |
+| **Waveshare 10.1" HDMI** | 10.1" | 1280×800 | HDMI+USB | 10-point capacitive | ⚠️ Probable |
+| **SunFounder 7" HDMI** | 7" | 1024×600 | HDMI+USB | 5-point capacitive | ⚠️ Probable |
+| **Elecrow 5" HDMI** | 5" | 800×480 | HDMI+USB | Resistive | ❌ Not recommended |
+| **Elecrow 7" HDMI** | 7" | 1024×600 | HDMI+USB | 5-point capacitive | ⚠️ Probable |
+
+### Display Requirements
+
+- **DPI:** At least 130 DPI for readable UI at arm's length
+- **Touch:** Capacitive multi-touch (resistive is frustrating for fader control)
+- **Interface:** DSI preferred (no USB cable clutter); HDMI+USB works
+- **HDMI port:** Use the HDMI port closest to USB-C power (HDMI0)
+- **Config note:** For HDMI displays, set `hdmi_group=2 hdmi_mode=87` in
+  `config.txt` with custom `hdmi_cvt` for native resolution
+
+### Headless Operation
+
+The mixer can run entirely headless — control it via:
+
+- Web UI from any device on the network
+- OSC from a DAW
+- MIDI controller connected directly to the Pi
+- SSH for command-line management
+
+---
+
+## USB Cameras
+
+| Camera | Resolution | Status | Notes |
+|--------|-----------|--------|-------|
+| **Raspberry Pi Camera Module 3** | 1080p30 / 720p60 | ✅ Verified | Native MIPI CSI support. Best quality/CPU ratio. |
+| **Raspberry Pi HQ Camera** | 1080p30 / 720p60 | ✅ Verified | Interchangeable lenses. Requires C/CS lens. |
+| **Logitech C920** | 1080p30 | ✅ Verified | Standard UVC webcam. Good quality. |
+| **Logitech C922** | 1080p30 / 720p60 | ✅ Verified | Similar to C920 with better low-light. |
+| **Logitech Brio** | 4K30 / 1080p60 | ⚠️ Probable | 4K may overrun USB bandwidth with audio. |
+| **Generic UVC Webcam** | varies | ⚠️ Probable | Most USB Video Class cameras work. |
+
+### Camera Tips
+
+- **RPi Camera Module** uses the dedicated CSI port — keeps USB bandwidth free
+  for audio
+- **USB cameras** share bandwidth with audio interfaces. Connect to **separate
+  USB buses** if possible (USB 2.0 for camera, USB 3.0 for audio)
+- **1080p30** is the sweet spot for streaming quality vs. CPU usage on RPi 4
+
+---
+
+## SD Cards
+
+| Card | Capacity | Class | Status | Notes |
+|------|----------|-------|--------|-------|
+| **SanDisk Extreme Pro** | 32GB+ | A2 V30 | ✅ Recommended | Best sustained write for multi-track recording |
+| **SanDisk Extreme** | 32GB+ | A2 V30 | ✅ Recommended | Very good. |
+| **Samsung EVO Select** | 32GB+ | A2 V30 | ✅ Recommended | Reliable and fast. |
+| **Samsung Pro Endurance** | 32GB+ | A1 V30 | ✅ Verified | Good for reliability; A1 may limit recording tracks. |
+| **Kingston Canvas Go! Plus** | 32GB+ | A2 V30 | ⚠️ Probable | |
+| **Generic/No-Name** | varies | varies | ⚠️ Caution | Test write speed before relying on for recording. |
+
+### SD Card Requirements
+
+- **Minimum size:** 16 GB (OS + mixer software)
+- **Recommended size:** 32 GB+ (room for recordings and sessions)
+- **Minimum class:** A1 (up to 8-channel recording)
+- **Recommended class:** A2 (16-channel recording without write buffer overruns)
+- **Speed test:** `dd if=/dev/zero of=/data/test bs=1M count=1024 conv=fdatasync`
+  — should sustain 20+ MB/s writes
+
+---
+
+## Power Supply
+
+| Supply | Status | Notes |
+|--------|--------|-------|
+| **Official RPi 4 PSU (5.1V/3A)** | ✅ Recommended | Stable and sufficient. |
+| **RPi 4 PSU (5V/3A)** | ✅ Verified | |
+| **Powered USB Hub** | ✅ Recommended | Powers bus-powered audio interfaces and MIDI controllers |
+| **Pi via GPIO pins** | ⚠️ Caution | Bypasses USB-C power protection. For custom enclosures only. |
+
+### Power Notes
+
+- The RPi 4B draws up to ~6W under load (without peripherals)
+- USB audio interfaces may draw 2-5W via bus power
+- **Total system draw:** 8-15W. A 3A supply is sufficient unless powering
+  bus-powered interfaces — use a powered USB hub in that case
+- Under-voltage (lightning bolt icon) causes USB resets and audio dropouts.
+  If seen, upgrade your power supply.
+
+---
+
+## Network
+
+| Type | Status | Notes |
+|------|--------|-------|
+| **Ethernet (Gigabit)** | ✅ Recommended | Reliable, low latency, full bandwidth for streaming |
+| **WiFi 5 (802.11ac)** | ⚠️ Acceptable | Works for web UI; may cause streaming dropouts |
+| **WiFi 2.4GHz** | ❌ Not recommended | Congested band, streaming unreliable |
+
+### Network Recommendations
+
+- **Ethernet is strongly recommended** for live streaming
+- For WiFi, place the Pi within 3m of the access point
+- Configure a static IP or DHCP reservation for consistent access:
+  ```bash
+  # /etc/dhcpcd.conf
+  interface eth0
+  static ip_address=192.168.1.100/24
+  static routers=192.168.1.1
+  ```
+
+---
+
+## Aggregate / Multi-Device Setups
+
+### Multiple USB Audio Interfaces
+
+The mixer supports multiple USB audio interfaces aggregated into one JACK
+device using `alsa_in` / `alsa_out` or the `zita-a2j` / `zita-j2a` bridges.
+
+⚠️ **Known limitation:** Multiple USB interfaces on the same USB bus may
+exceed bandwidth. The RPi 4B has one USB 3.0 bus shared across all four
+ports. For multi-interface setups:
+
+1. Use **ADAT expansion** (e.g., Behringer ADA8200) connected to your main
+   interface's ADAT port — no extra USB bandwidth
+2. Use **aggregate ALSA devices** only for low-channel-count interfaces
+3. Consider a **Pi 5** (separate USB 3.0 and USB 2.0 buses) when supported
+
+### Testing Your Hardware
+
+Run the built-in hardware test to validate your setup:
+
+```bash
+ssh pi@pi-mixer.local
+
+# Test audio interface
+aplay -l           # list playback devices
+arecord -l         # list capture devices
+speaker-test -c 2 -t sine -f 440  # test output
+
+# Test JACK
+jackd -d alsa -d hw:USB -r 48000 -p 128 -n 3 &
+jack_lsp           # list JACK ports
+jack_connect system:capture_1 system:playback_1  # loopback test
+
+# Test latency
+jack_delay         # measure round-trip latency
+
+# Test MIDI
+aconnect -l        # list MIDI ports
+aseqdump -p 20:0   # monitor MIDI events from port 20:0
+
+# Comprehensive system test
+python -m pytest tests/ -v -k "not test_streaming and not test_recording"
+```
+
+---
+
+## Reporting Compatibility
+
+Please report your hardware experiences to help expand this list:
+
+1. **Working:** Device model, firmware version, channels working, any quirks
+2. **Not working:** Device model, firmware version, symptoms, dmesg output
+3. **Partially working:** What works and what doesn't
+
+Include `dmesg | grep -i usb` and `cat /proc/asound/cards` output with your
+report.