initial commit

USAGE_GUIDE.md

@@ -0,0 +1,108 @@
+# 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.
+
+## Building the System
+
+1. Clone or navigate to your Buildroot repository:
+
+```bash
+cd ../buildroot
+```
+
+2. Configure Buildroot to use our external tree:
+
+```bash
+make BR2_EXTERNAL=../auracaster-system raspberrypi3_swupdate_defconfig
+```
+
+3. Build the system (this will take some time):
+
+```bash
+make
+```
+
+## Flashing to SD Card
+
+1. Insert your SD card into your computer
+
+2. Run the flashing script with sudo:
+
+```bash
+cd ../auracaster-system
+sudo ./flash_sdcard.sh
+```
+
+3. Follow the prompts to select your SD card device
+
+## 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:
+
+```bash
+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:
+
+```bash
+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):
+
+```bash
+# 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