Crabbox is a single-binary RFID & GPIO-controlled jukebox for RaspberryPI

Crabbox is AI-assisted Rust implementation inspired by RPi-Jukebox-RFID.

Introduction

Several years ago I have built a jukebox for my son based on RPi-Jukebox-RFID.

Unfortunately, when SD card completely died I discovered that the software is stale and doesn't work even on bookworm (it is already Trixie era at the time of the writing). I engaged Codex to recreate the needed functionality from scratch.

Status

I run this on my son's Crabbox I device (see picture below).

Requirements

Crabbox targets RaspberryPi.

It is developed on Linux x64 and can be compiled for the pi using cross-rs.

Features

• GPIO support for player control
• RFID reader support (RC522)
• Named pipe support for command control.
• Web UI for playback control and queue/library visibility.

Commands, web UI, and control pipe

The player understands the following commands (case-insensitive). They can be sent from the web UI command box, the control pipe, or mapped to RFID tags/buttons:

• PLAY [glob] – rebuilds the queue (ordered) and starts playback. Optional glob filter matches full track paths.
• PLAYPAUSE [glob] – toggle pause/resume, or start a filtered queue if a glob is provided.
• SHUFFLE [glob] – rebuilds a shuffled queue (optionally filtered) and starts playback.
• STOP – stop playback and clear the current track.
• NEXT / PREV – move within the queue and play the next/previous track.
• VOLUMEUP / VOLUMEDOWN – adjust volume by the configured step.
• SHUTDOWN – stop playback, play the shutdown sound if configured, then request system shutdown.

To control via a named pipe:

1. Set [server].pipe in your config (e.g. pipe = "/tmp/crabbox.pipe"). Crabbox recreates this FIFO on startup.
2. Write one command per line to the pipe, for example:
   • printf "PLAY\n" > /tmp/crabbox.pipe
   • printf "SHUFFLE chill/*\n" > /tmp/crabbox.pipe
3. Optional globs match full file paths; use them to target genres, folders, or patterns.

Web UI

• Configure [server].web to set the listen address (e.g. 0.0.0.0:8080), then open that URL in a browser.
• The page shows the current track, queue (with the active track highlighted), and the full library list.
• Buttons provide play, play/pause, stop, next/prev, volume up/down, and shutdown controls.
• The command input accepts any of the commands above, including glob filters.

RFID and command mapping

• Enable the rpi feature and configure [rfid] with your RC522 pins (bus, irq, optional reset).
• Map tag IDs to command strings under top-level [tags], e.g. 0A1B2C3D = "PLAY", ABCD1234 = "SHUFFLE kids/*".
• RFID tags can trigger the same commands as the pipe or web UI; filters/globs work the same way. The last seen tag is shown on the web UI.

Configuration

• Create a TOML config file (see config.toml for an example) and point the service to it. At minimum you need one [[music]] directory and a [server] section.
• Build the binary with cargo build --release; the service example below assumes the binary lives at target/release/crabbox.
• Key fields:
  • [server].web — listen address for the web UI/API.
  • [server].pipe — FIFO path for local command control (set to null to disable).
  • [server].startup_sound / [server].shutdown_sound — optional sounds to play on boot/shutdown.
  • [rfid] — RC522 wiring (requires the rpi feature).
  • [tags] — global tag-to-command mappings (used by RFID or other tag sources).
  • [gpio] — all pins are optional; set the ones you wire (leave unset to disable GPIO input entirely).

Building

• Native dev builds: cargo check, cargo test, and cargo run -- server <config> (see Justfile targets check, test, server).
• Install native audio deps once on Debian/Ubuntu: sudo apt-get install libasound2-dev.
• Cross-compiling for Raspberry Pi (aarch64):
  1. Install cross: cargo install --locked cross.
  2. Build: cross build --target aarch64-unknown-linux-gnu --features rpi --release (see just build-rpi).
  3. The resulting binary lives at target/aarch64-unknown-linux-gnu/release/crabbox.

Run as a systemd user service

Place a unit file at ~/.config/systemd/user/crabbox.service (create the directory if it does not exist):

[Unit]
Description=Crabbox service
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=crabbox server /home/USER/.config/crabbox/config.toml
WorkingDirectory=/home/USER/crabbox
Restart=always
Environment=RUST_LOG=info

[Install]
WantedBy=default.target

• Replace /home/USER/... with the actual paths to your checkout, binary, and config.
• Reload systemd and start the service: systemctl --user daemon-reload then systemctl --user enable --now crabbox.service.
• View logs with journalctl --user -u crabbox -f. Stop or restart with systemctl --user stop|restart crabbox.service.
• To have the user service start at boot without logging in, enable lingering once: loginctl enable-linger $USER.

Contributing

AI-assisted code is welcome, with fiew common caveats:

• no huge PRs
• you read the code and verify it does what you asked it to

Crabbox mk I

GPIO Pinout

https://pinout.xyz/#

Name	GPIO	Pin
RFID SDA	GPIO 8	24
RFID SCK	GPIO 11	23
RFID MOSI	GPIO 10	19
RFID MISO	GPIO 9	21
RFID IRQ	GPIO 24	18
RFID GND		20
RFID RST	GPIO 25	22
RFID 3.3v		17
MiniAmp	GPIO 18	12
MiniAmp	GPIO 19	35
MiniAmp	GPIO 20	38
MiniAmp	GPIO 21	40
MiniAmp Mute	GPIO 16	36
MiniAmp Power off	GPIO 26	37
Vol Up	GPIO 5	29
Vol Down	GPIO 6	31
Prev	GPIO 22	15
Next	GPIO 23	16
Play/Pause	GPIO 27	13
Shut down	GPIO 3	5