auracaster-os/USAGE_GUIDE.md

Auracaster System - Quick Start Guide

This guide walks you through building the Auracaster system, flashing it to an SD card, and performing an A/B update.

Prerequisites

Before building, install the required packages (for Ubuntu/Debian):

sudo apt update && sudo apt install -y build-essential git rsync bc python3 unzip file wget cpio libssl-dev libncurses5-dev flex bison libelf-dev device-tree-compiler u-boot-tools libgnutls28-dev

Building the System

1. Clone or navigate to your Buildroot repository:

cd ../buildroot

2. Configure Buildroot to use our external tree:

make BR2_EXTERNAL=../auracaster-system raspberrypi3_swupdate_defconfig

3. Build the system (this will take some time):

make

Flashing to SD Card

1. Insert your SD card into your computer

2. Run the flashing script with sudo:

cd ../auracaster-system
sudo ./flash_sdcard.sh

3. Follow the prompts to select your SD card device

Flashing an Image from a Remote SSH Host

If your SD card image was created on a remote host (e.g., 192.168.50.3), you can copy it to your local machine and then flash it to your SD card. For example, if the image is located at /home/user/output.img on the remote host:

You can do this in a single command (replace user, the image path, and /dev/mmcblk0 as needed):

ssh user@192.168.50.3 "cat /mnt/nvme/repos/buildroot/output/images/sdcard.img" | sudo dd of=/dev/mmcblk0 bs=4M status=progress conv=fsync oflag=direct

WARNING: Double-check the device path (/dev/mmcblk0) to avoid overwriting the wrong disk!

Initial Boot

1. Insert the SD card into your Raspberry Pi 3
2. Connect Ethernet and power
3. Wait for the system to boot (1-2 minutes)
4. Discover the IP address (check your router or use nmap -sP 192.168.1.0/24)
5. The system will be initially running from partition A

Creating an Update Package

1. Create a simple update package:

cd example
./create-update-package.sh

2. This creates auracaster-update.swu which would update the inactive partition (B)

Applying the Update

1. Access the SWUpdate web interface in your browser:

http://<raspberry-pi-ip>:8080

2. You should see the Auracaster System Update interface
3. Select "Choose File" and pick the auracaster-update.swu file
4. Click "Upload" to start the update process
5. The progress bar will show the update status
6. Once complete, you'll see "Update successful"

Verifying the Update

1. Reboot the system (either through the web interface or SSH)
2. After reboot, the system will now be running from partition B
3. You can verify this by checking the system status:

swupdate-ab-helper --status

Testing Automatic Fallback

If you want to test the automatic fallback mechanism:

1. SSH into the system
2. Make the active partition unbootable (for testing purposes only):

# Corrupt kernel on the currently active partition
swupdate-ab-helper --toggle
reboot

3. The system will attempt to boot from the now-corrupt partition
4. After 3 failed attempts, it will automatically fall back to the previous partition

Tips and Troubleshooting

• Network Issues: If you can't access the web interface, check your network connection and firewall settings
• Update Failures: Check for errors in the swupdate logs: journalctl -u swupdate
• Manual Partition Toggle: You can manually switch between partitions: swupdate-ab-helper --toggle && reboot
• Checking Update Status: Run swupdate-check status to see current system status

Next Steps

• Create your own custom update packages
• Modify the web interface to include your branding
• Implement secure updates with cryptographic signatures