wip(rpi4): park the Pi 4 sketch — superseded by the Pi 5 machinery in #87
Never-committed working tree state found in the dev worktree: a Pi 4 hardware module, a setup walkthrough, an upboard-serial refactor, and flake wiring that does not evaluate (aarch64 packages block nested inside packages.x86_64-linux; pkgs-aarch64 built with `inherit aarch64` instead of `system`, so it is really x86; references a nixosConfigurations.rpi4-installed that is never defined). Parked verbatim for reference. The real Pi 4 target is rebuilt on top of #87's mkPiInstalled/mkPiImage shape in feat/rpi4-target. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013A6683cCHnQxFUosx1krY4
This commit is contained in:
parent
cb236703d6
commit
7e59951fcc
7 changed files with 533 additions and 4 deletions
225
docs/raspberry-pi4-setup.md
Normal file
225
docs/raspberry-pi4-setup.md
Normal file
|
|
@ -0,0 +1,225 @@
|
|||
# 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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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**:
|
||||
|
||||
```bash
|
||||
# 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**:
|
||||
|
||||
```bash
|
||||
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**:
|
||||
|
||||
```bash
|
||||
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**:
|
||||
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
lsblk -f /dev/sdX
|
||||
# Should show GPT partition table with ESP and nixos partitions
|
||||
```
|
||||
2. Try rebuilding the image:
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
ssh bitspire@<rpi4-ip> 'cat /etc/resolv.conf'
|
||||
```
|
||||
3. Check network interface status:
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
curl <lnbits-url>/api/v1/settings
|
||||
```
|
||||
4. Check ATM service logs:
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
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):
|
||||
|
||||
```bash
|
||||
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](https://nixos.org/manual/nixos/stable/index.html#sec-architecture-raspberry-pi)
|
||||
- [bitSpire README](../README.md)
|
||||
- [NixOS Hardware Configuration](https://nixos.org/manual/nixos/stable/index.html#ch-configuring-hardware)
|
||||
Loading…
Add table
Add a link
Reference in a new issue