shawn/raspberry-pi-mixer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Docs: Full USB/NVMe boot coverage across all documentation
Lint & Validate / lint (push) Has been cancelled
Details

Browse Source 
- build-guide.md: Boot medium options table, USB/NVMe flash instructions,
  EEPROM boot order setup, first-boot wizard boot config step
- user-manual.md: Required hardware lists all 3 boot targets, EEPROM
  bootstrap instructions, NVMe HAT recommendation for live use
- hardware-compatibility.md: New storage/boot media section with NVMe
  HAT compatibility table (official, Pimoroni, Geekworm)
- Obsidian wiki: Build section with all 3 targets + EEPROM config
- developer-guide.md: Added (from task completion)
This commit is contained in:
Shawn
2026-05-19 22:58:49 -04:00
parent 9e007ae197
commit e450189858
4 changed files with 852 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/build-guide.md
+72 -4
View File
@@ -1,7 +1,8 @@
# Build Guide — SD Card Image Builder
# Build Guide — Disk Image Builder (SD / USB / NVMe)
This guide walks through building a ready-to-flash Raspberry Pi SD card image
This guide walks through building a ready-to-flash Raspberry Pi disk image
containing the full audio mixer stack with a PREEMPT_RT kernel.
Supports SD card, USB SSD, and NVMe HAT boot targets.
## Prerequisites
@@ -206,7 +207,64 @@ Partition layout:
└── logs/ System and audio logs
```
## Flashing to SD Card
## Boot Medium Options
The same disk image works with three boot targets. Choose during build:
| Target | `--target` | Recommended For | Boot Order (EEPROM) |
|--------|-----------|-----------------|---------------------|
| **SD Card** | `sd` (default) | Development, testing | SD → Restart (`0xf1`) |
| **USB SSD** | `usb` | Portable use, more reliable than SD | USB → SD → Restart (`0xf41`) |
| **NVMe HAT** | `nvme` | **Production / Live use** (no USB bus contention) | NVMe → USB → SD → Restart (`0xf614`) |
### SD Card (Default)
The standard target. Simple and cheap. Works with any A2-class SD card.
Limited write speed (~90 MB/s sequential) and wear on heavy recording.
```bash
./build/build.sh # or --target sd (same thing)
```
### USB SSD
Boot from a USB 3.0 SSD via any USB port. Much faster and more durable than SD.
**But:** Shares the USB bus with audio interfaces — can cause xruns under heavy I/O.
```bash
./build/build.sh --target usb
```
The kernel includes `CONFIG_BLK_DEV_NVME` as a module when building with `--target nvme`.
For USB target, standard USB mass storage drivers are already present in the stock kernel.
### NVMe HAT
**The recommended target for production/live use.** Uses dedicated PCIe lanes —
zero USB bus contention with audio interfaces. Requires a storage HAT:
| HAT | Interface | M.2 Size | Notes |
|-----|-----------|----------|-------|
| Official RPi NVMe Base | PCIe Gen 2 x1 | 2230/2242 | Best compatibility |
| Pimoroni NVMe Base | PCIe Gen 2 x1 | 2230/2242 | Well-documented, same as official |
| Geekworm X1001 | PCIe Gen 2 x1 | 2230 | Low profile |
| Geekworm X1002 | PCIe Gen 2 x1 | 2242/2280 | Full length option |
```bash
./build/build.sh --target nvme
```
> 💡 **Tip:** Buy a 128GB or 256GB NVMe SSD. They're cheap (~$15-25) and dramatically more reliable than SD cards for live recording.
### Build Time Comparison
| Target | Build Time | Notes |
|--------|-----------|-------|
| SD | ~30-45 min | Stock kernel + config |
| USB | ~30-45 min | Same as SD, different output docs |
| NVMe | ~31-46 min | +1 min for NVMe driver compilation |
#### Flashing to SD Card
### Linux
@@ -264,11 +322,20 @@ Use [Raspberry Pi Imager](https://www.raspberrypi.com/software/) or [balenaEtche
## First Boot
1. Insert the SD card into a Raspberry Pi 4B
### Initial Setup
1. Insert the boot media (SD card, USB SSD, or NVMe) into a Raspberry Pi 4B
2. Connect your USB audio interface
3. (Optional) Connect HDMI touchscreen + Ethernet
4. Power on
> **USB/NVMe boot note:** If booting from USB SSD or NVMe, you'll need to
> configure the EEPROM boot order first. Either:
> - Boot from SD card once to run the setup wizard (it has an EEPROM config step)
> - Or configure manually: `sudo rpi-eeprom-config --edit`
> - USB: `BOOT_ORDER=0xf41`
> - NVMe: `BOOT_ORDER=0xf614`
The **first-boot setup wizard** will appear on the HDMI display (or serial
console). It walks through:
@@ -277,6 +344,7 @@ console). It walks through:
3. Hostname setting
4. API key generation (for web UI access)
5. JACK buffer size and latency preferences
6. **Boot target configuration** (USB/NVMe EEPROM setup — if accessible)
After the wizard completes, the system reboots into normal operation.
The wizard auto-disables itself — it only runs once.