bitspire/docs/raspberry-pi4-setup.md

Raspberry Pi 4 bitSpire Setup Guide

This document describes how to build and deploy bitSpire to a Raspberry Pi 4.

Hardware Requirements

• Board: Raspberry Pi 4 (4GB or 8GB RAM recommended for Electron)
• Storage: 32GB+ SD card (or external SSD via USB for better reliability)
• Power: 5V 3A+ power supply (Pi 4 can draw up to 3A at 5V)
• Cooling: Passive heatsinks or active fan for 24/7 operation
• Network: Ethernet connection recommended for stability

Building the Disk Image

cd /home/padreug/dev/bitspire/bitspire/dev

# Build the Raspberry Pi 4 disk image (aarch64)
nix build .#disk-image-rpi4

# The image will be at: result/nixos.img

Flashing to SD Card

# Replace /dev/sdX with your SD card device (NOT your main disk!)
# Verify first: lsblk -f /dev/sdX

sudo dd if=result/nixos.img of=/dev/sdX bs=4M status=progress conv=fsync && sync

# Sync to ensure all writes are flushed
sync

Important: Always verify the target device before flashing!

First-Time Deployment

1. Boot the Raspberry Pi 4

1. Insert the SD card into the Raspberry Pi 4.
2. Connect Ethernet cable.
3. Power on the device.
4. You should see Raspberry Pi firmware boot messages.
5. The kiosk screen shows "ATM unavailable — needs provisioning".

2. Provision LNbits Credentials

From your development machine:

LNBITS_SERVER_PUBKEY=$(docker logs <lnbits-container> 2>&1 | \
  grep -oP 'Public key \(share this\):\s*\K[a-f0-9]{64}' | tail -1)

RELAY_URL=ws://<dev-lan-ip>:5001/nostrrelay/test \
LNBITS_SERVER_PUBKEY="$LNBITS_SERVER_PUBKEY" \
ATM_PRIVATE_KEY=$(openssl rand -hex 32) \
bash deploy/nixos/provision-atm.sh <rpi4-ip> 22

Important: Save the generated ATM_PRIVATE_KEY — it's required to preserve the ATM's identity and wallet balance.

3. Verify Connection

After provisioning completes:

ssh bitspire@<rpi4-ip> 'cat /var/lib/bitspire/.env'

You should see the environment variables are set correctly. The kiosk should connect to LNbits over nostr-transport and show the live UI after a few seconds.

Re-Flashing (Preserving Identity)

To preserve the ATM's identity and transaction history when reflashing:

1. Backup from the running Raspberry Pi:

# From the Raspberry Pi
mkdir -p ~/rpi4-backup-$(date +%Y%m%d)
cp /var/lib/bitspire/.env ~/rpi4-backup-$(date +%Y%m%d)/
cp /var/lib/bitspire/state.db ~/rpi4-backup-$(date +%Y%m%d)/

2. Copy backups to dev box:

scp bitspire@<rpi4-ip>:~/rpi4-backup-*/.env ~/rpi4-backup-*/
scp bitspire@<rpi4-ip>:~/rpi4-backup-*/state.db ~/rpi4-backup-*/

3. Re-flash the SD card:

nix build .#disk-image-rpi4
sudo dd if=result/nixos.img of=/dev/sdX bs=4M status=progress conv=fsync && sync

4. Re-provision from backups:

set -a; source ~/rpi4-backup-<date>/.env; set +a

ATM_PRIVATE_KEY=$VITE_ATM_PRIVATE_KEY \
LNBITS_SERVER_PUBKEY=$VITE_LNBITS_SERVER_PUBKEY \
RELAY_URL=$VITE_RELAY_URL \
bash deploy/nixos/provision-atm.sh <rpi4-ip> 22

Hardware-Specific Notes

Storage

• SD cards are slower and have limited write cycles. For production, consider an external SSD via USB 3.0 for better reliability.
• Use high-quality SD cards with good endurance ratings.
• Avoid frequent rewrites to the same sectors.

Power

• The Raspberry Pi 4 can draw up to 3A at 5V during heavy load (Electron startup).
• Use a reliable power supply rated for at least 5V 3A.
• Avoid using USB hubs that don't provide sufficient power.

Thermal

• The Pi 4 runs warm, especially under load with Electron.
• Ensure adequate cooling for 24/7 operation:
  • Passive heatsinks on the SoC and RAM
  • Or a small active fan blowing air over the board
• Consider removing the metal case for better airflow in hot environments.

Console

• The serial console is available at /dev/ttyAMA0 (PL011 UART) at 115200 baud.
• Useful for debugging boot issues.
• Not required for normal operation.

Swap

• A 2GB swapfile is enabled by default to prevent hard-freeze under memory pressure.
• Consider increasing this on 4GB models if you expect heavy load.

Troubleshooting

Boot fails

Symptoms: Pi doesn't boot or shows errors.

Solutions:

1. Verify SD card is properly flashed:

   lsblk -f /dev/sdX
   # Should show GPT partition table with ESP and nixos partitions
   

2. Try rebuilding the image:

   nix build .#disk-image-rpi4
   

3. Check power supply and connections.

No network connectivity

Symptoms: Cannot SSH to the Pi or connect to LAN.

Solutions:

1. Verify Ethernet cable is connected and the Pi's lights show activity.
2. Check /etc/resolv.conf after boot:

   ssh bitspire@<rpi4-ip> 'cat /etc/resolv.conf'
   

3. Check network interface status:

   ssh bitspire@<rpi4-ip> 'ip a'
   

ATM doesn't connect to LNbits

Symptoms: Kiosk shows "ATM unavailable" or no connection.

Solutions:

1. Verify environment variables are set:

   ssh bitspire@<rpi4-ip> 'cat /var/lib/bitspire/.env'
   

2. Check for typos in VITE_RELAY_URL and VITE_LNBITS_SERVER_PUBKEY.
3. Verify LNbits is running and accessible:

   curl <lnbits-url>/api/v1/settings
   

4. Check ATM service logs:

   ssh bitspire@<rpi4-ip> 'sudo journalctl -u bitspire -n 50'
   

Electron fails to start

Symptoms: Service logs show Electron crash or OOM (out of memory).

Solutions:

1. Check memory usage:

   ssh bitspire@<rpi4-ip> 'free -h'
   

2. On 4GB models, close other processes to free up RAM.
3. Consider increasing the swapfile size in /var/lib/bitspire/.env.

Building Live ISO for Testing

To build a live USB bootable ISO for testing (without installing):

nix build .#iso-rpi4

# The ISO will be at: result/*.iso

Configuration Files

• Hardware config: deploy/nixos/hardware/raspberry-pi4.nix
• Base config: deploy/nixos/configuration.nix
• Service module: deploy/nixos/bitspire-atm.nix
• Provisioning script: deploy/nixos/provision-atm.sh

References

• NixOS on Raspberry Pi
• bitSpire README
• NixOS Hardware Configuration