Skip to content

Installation

Prerequisites

Before running the installer:

  • Raspberry Pi with Raspberry Pi OS 64-Bit with PI Desktop (Debian-based), internet access, and sudo.
  • Hardware wired (or ready to wire): PN5180 NFC + NAU7802 scale + display
  • Existing Bambuddy server URL + API key (for SpoolBuddy-only mode), or plan to run full mode on the Pi

Use the install script from the Bambuddy repository:

curl -fsSL https://raw.githubusercontent.com/maziggy/bambuddy/refs/heads/dev/spoolbuddy/install/install.sh -o install.sh
chmod +x install.sh
sudo ./install.sh

The installer configures:

  • SPI + I2C and required boot overlays
  • System packages and Python venv
  • SpoolBuddy daemon service (spoolbuddy.service)
  • Touch kiosk environment (labwc + Chromium autostart + splash setup)
  • Optional local Bambuddy service (full mode)

Installation Modes

For mode selection details and tradeoffs, see Deployment Modes.

Unattended Examples

# SpoolBuddy-only mode
sudo ./install.sh --mode spoolbuddy --bambuddy-url http://192.168.1.100:8000 --api-key bb_xxx --yes

# Full local mode
sudo ./install.sh --mode full --port 8000 --yes

First Boot After Install

A reboot is required after installation for:

  • SPI/I2C and boot config changes
  • kiosk auto-login/session startup
  • splash/initramfs changes
sudo reboot

Hardware Validation

After rebooting, confirm your hardware is wired and detected correctly:

# SPI devices present
ls /dev/spidev0.*

# I2C bus 1 present
ls /dev/i2c-1

# NAU7802 visible on bus 1 (0x2A)
sudo i2cdetect -y 1

Then run SpoolBuddy diagnostics:

sudo /opt/bambuddy/spoolbuddy/venv/bin/python /opt/bambuddy/spoolbuddy/scripts/pn5180_diag.py
sudo /opt/bambuddy/spoolbuddy/venv/bin/python /opt/bambuddy/spoolbuddy/scripts/scale_diag.py

If you installed full mode, create an API key in Bambuddy → Settings → API Keys, then update /opt/bambuddy/spoolbuddy/.env with SPOOLBUDDY_API_KEY=bb_xxx and restart the service (sudo systemctl restart spoolbuddy).

Service Management

# SpoolBuddy service status
sudo systemctl status spoolbuddy

# Follow SpoolBuddy logs
sudo journalctl -u spoolbuddy -f

If you installed full mode:

sudo systemctl status bambuddy
sudo journalctl -u bambuddy -f

Verify the Setup

  1. Open Bambuddy in a browser.
  2. Open the kiosk route on the Pi: /spoolbuddy.
  3. Confirm the device appears online in SpoolBuddy.
  4. Place a known tag on the reader and confirm detection.
  5. Check live scale value changes.

If hardware appears offline, run the hardware diagnostics above.

Common Pitfalls

  • Wrong raw script URL path (use .../bambuddy/main/install/install.sh)
  • Missing API key in SpoolBuddy-only mode
  • I2C bus 0 not enabled (dtparam=i2c_vc=on)
  • SPI CS overlay missing (dtoverlay=spi0-0cs)
  • NFC/scale permissions not applied because reboot was skipped

\"Can't reach Bambuddy. Retrying…\" on the kiosk

The kiosk shows this when it can't check its API key because Bambuddy, or Bambuddy's database, isn't answering, for example while the database is out of connections or failing over. The key is kept and the kiosk keeps trying, starting after 2 seconds and backing off to once a minute. It shows SpoolBuddy again as soon as Bambuddy answers, with no reboot needed. Only an answer from Bambuddy sends the kiosk to the login page: a key that is invalid or expired, or whose owner has been deactivated. In the last case the key is kept, so reactivating the owner and rebooting the kiosk brings it back.