Bloop Box Multi Flasher

A command-line tool that prepares and flashes Raspberry Pi SD cards for bloop-box deployments. You give it a config file describing your fleet, and it writes one card per client, each with its own credentials and hostname. Target hardware is the Raspberry Pi Zero 2 W (arm64).

The tool flashes the stock Raspberry Pi OS Lite image unchanged and injects per-client config into the FAT boot partition (/boot/firmware). All Linux-side setup runs on the first boot via cloud-init, so there are no loop mounts and no ext4 write support needed.

Requires Raspberry Pi OS Trixie or newer, where cloud-init is available. The tool downloads the current raspios_lite_arm64_latest image, which is Trixie.

How it works

For each card the tool:

1. Flashes the cached OS image to the SD card.
2. Writes the cloud-init files (user-data, network-config, meta-data), the two .deb packages, and hardware settings in config.txt into the boot partition.

On first boot the device creates the pi user, joins Wi-Fi, installs both packages, writes the bloop-box state files, configures audio, and reboots into a running bloop-box service.

Installation

Download a pre-built binary from the GitHub Releases page. Pick the build for your platform, extract it, and run it directly.

macOS note: the binaries are not signed or notarized, so Gatekeeper refuses to run them at first. Clear the quarantine flag after extracting:

xattr -d com.apple.quarantine bloop-box-multi-flasher

Building from source

If you're developing or need a build for an unlisted platform, build it with Rust (stable):

cargo build --release

The binary lands at target/release/bloop-box-multi-flasher.

Requirements

• Elevated privileges to write the card: sudo on Linux and macOS, Administrator on Windows.
• A bloop-box data .deb you build for your assets (see bloop-box-data-example). The bloop-box client package is downloaded automatically from GitHub releases.

Usage

There are two subcommands: init to create a config, flash to write the cards.

# Create config.toml interactively (or copy and edit config.example.toml)
bloop-box-multi-flasher init

# Flash the configured cards
sudo bloop-box-multi-flasher flash --config config.toml

init

init walks you through every setting with live validation and writes config.toml. You can enter clients one by one, paste them as CSV directly into the terminal, or load them from a CSV file with one id,secret per row.

Options:
  -o, --output <OUTPUT>  Where to write the generated configuration [default: config.toml]
      --force            Overwrite the output file without asking if it already exists

flash

flash starts by letting you multi-select which clients to flash (all selected by default), so several people can split one config across machines and each take a subset. Downloads (the OS image and the bloop-box package) are cached and reused on later runs; override the location with --cache-dir.

For each card you pick the target drive from a list and confirm before it's erased. After writing, each card is read back and compared against the image to catch cards that accept writes but don't store them; pass --no-verify to skip this. A failed card can be retried or skipped without affecting the others.

Options:
  -c, --config <CONFIG>        Path to the TOML configuration file [default: config.toml]
      --cache-dir <CACHE_DIR>  Directory to cache downloads (OS image and bloop-box package)
      --no-verify              Skip reading each card back to verify it matches the written image
      --allow-non-removable    Also offer non-removable drives (dangerous; some card readers need it)
      --max-drive-size <GB>    Hide drives larger than this from the picker [default: 256]

Configuration

See config.example.toml for a documented template. Key points:

• nfc_uids are config-tag UIDs, each a hex string decoding to 4, 7, or 10 bytes.
• asset_deb_path points at your local data .deb.
• At least one entry in ssh_authorized_keys is required; password login is disabled on flashed devices.
• Each [[clients]] id becomes the hostname bloop-box-<id>, so use letters, digits, and internal hyphens only. Ids must be unique.

Optional settings:

• bloop_box_version pins the client release to flash (e.g. v5.1.0), so everyone sharing the config flashes the same version. Omit for the latest.

Two optional advanced settings:

• bloop_box_conf_path writes a custom /etc/bloop-box.conf onto every device. Use it only for non-reference hardware; omit it for the package defaults.
• root_ca_cert_path points at the PEM certificate of a private CA. It's installed into each device's trust store on first boot. Needed when your server's TLS certificate doesn't chain to a publicly trusted CA; the client verifies the server against the system certificate store.

What lands on the device

On first boot, cloud-init sets up:

• The pi user with your SSH keys and passwordless sudo. SSH is enabled, key-only login, password authentication off.
• Wi-Fi via NetworkManager from the [wifi] settings.
• SPI, I2C, the I2S audio overlay, and the activity LED enabled in config.txt.
• The engine.state (config NFC UIDs) and network.state (server connection and this client's credentials) files, owned by the bloop-box service user.
• Both .deb packages, installed in order (data package first, since the client depends on it).

The device then reboots into a running bloop-box service.

Platform support

Tested end-to-end on Linux and macOS (where drives are enumerated via diskutil, images are written through the raw /dev/rdiskN device for full speed, and finished cards are ejected). On Windows the tool locks and dismounts the card's volumes before writing and uses sector-aligned I/O throughout, but has seen less real-world testing than the other platforms.