SnapDog OS

SnapDog OS is a custom, minimal Buildroot-based Linux distribution that turns a Raspberry Pi with an I2S soundcard (DAC) into a dedicated, appliance-like audio receiver. It boots in seconds, connects to your network automatically, and requires zero command-line configuration.

Caution

Alpha Release: SnapDog OS is currently under active development. For production installations, we recommend using standard Raspberry Pi OS with the SnapDog .deb client package.

---

Supported Hardware

SnapDog OS is compiled as a 64-bit (aarch64) image running a minimal Linux 6.6 LTS kernel. The following boards are fully supported:

• Raspberry Pi 5 / 500
• Raspberry Pi 4 / 400
• Raspberry Pi 3 / 3+
• Raspberry Pi Zero 2 W

---

1. Installation & First Boot

Download SnapDog OS

Select and download the custom system image for your Raspberry Pi board:

Hardware Board Model	Target Architecture	Latest Stable Image
Raspberry Pi 5 / 500	64-bit (aarch64)	Download Image (.img.gz)
Raspberry Pi 4 / 400	64-bit (aarch64)	Download Image (.img.gz)
Raspberry Pi 3 / 3+ / Zero 2 W	64-bit (aarch64)	Download Image (.img.gz)

Flashing the Image

1. Download the appropriate image file from the table above.
2. Open Raspberry Pi Imager.
3. Under OS, choose “Use custom” and select the downloaded .img.gz file.
4. Select your SD card and write.

Caution

CLI Warning: If flashing via dd in the terminal, double-check your output target (of=/dev/sdX or /dev/rdiskN) to prevent overwriting your main system drive.

Setting Up Wi-Fi & Initial Boot

1. Insert the written SD card into your Raspberry Pi and power it on.
2. If no Ethernet cable is connected, the board automatically spawns a setup Wi-Fi network:
   • SSID: SnapDog-XXXX (where XXXX represents the last 4 characters of your client’s MAC address).
   • Password: snapdog123
3. Connect to the setup Wi-Fi using your phone or laptop.
4. Your device will automatically open a Captive Portal configuration wizard. 5. Enter your home Wi-Fi details, select your SnapDog server (auto-discovered via mDNS), and select your I2S DAC model. Click Save—the Pi will reboot and join your home network.

Note

For manual client targeting, setting audio latency offsets, or forcing ALSA soundcard modes using the command-line utility directly, consult the CLI Reference.

---

2. Web UI Device Management

Once the Pi is connected to your local network, you can access the configuration dashboard at http://<hostname>.local (or via its IP address) on port 80. The interface is served by a lightweight Rust Axum daemon called snapdog-ctrl:

• Dashboard: Live view of the client hostname, network connections, system load, and uptime.
• Network: Change between Wi-Fi and Ethernet configurations, configure static IPs, or join new wireless networks.
• Audio: Select your I2S DAC overlay (e.g., HiFiBerry, Allo Boss, JustBoom) from the visual list.
• Client Control: Specify the target SnapDog server manually, test playback, configure latency offsets (to synchronize with other rooms), and set default startup volumes.
• Updates: Check for OTA updates, select update tracks (stable vs. beta), and configure update maintenance windows.

---

3. Architecture & Security

SnapDog OS is designed as a secure, robust audio appliance.

Partition Layout & Read-Only Rootfs

To prevent flash memory wear and SD card corruption from sudden power loss, the root filesystem is mounted strictly read-only. All mutable configurations are symbolically linked to a dedicated, writeable /data partition.

Partition	Size	Type	Mount Point	Purpose
1	256 MB	FAT32	/boot	Bootloader, kernel, DTBs, config.txt
2	1 GB	EXT4	/ (slot A)	System Root filesystem (Read-Only)
3	1 GB	EXT4	/ (slot B)	Alternative Root filesystem (Read-Only)
4	128 MB+	EXT4	/data	Persistent writable settings (Wi-Fi, updates)

Dual A/B System Updates (RAUC)

System updates use standard .raucb signed bundles:

• Background Check: Daily automated update checks verify signature certificates and verify partition integrity.
• A/B Rollbacks: Updates install to the inactive slot. On reboot, the bootloader attempts to launch the new kernel. If the system fails to boot successfully 3 times, the bootloader automatically rolls back to the previous stable partition.

Security Hardening

• No Default Access: SSH is disabled by default. When enabled, it is restricted to public-key authentication only (keys uploaded via Web UI).
• Root Password: Challenge-gated root password setups, easily managed through snapdog-ctrl.

Next Steps

CLI Reference Check command-line switches, volume mixer flags, and soundcard overrides for speaker boards.

Direct Installation Deploy the core SnapDog server daemon natively to distribute audio streams.