beacon-buildroot/AGENTS.md

Beacon CM4 — Agent Quick Reference

Full docs: beacon-buildroot/README.md

Device

• Login: user / beacon (sudo passwordless; root login disabled)
• MAC: d8:3a:dd:a8:9a:40 — IP is DHCP, changes on reboot
• Find IP: CM4=$(ip neigh show dev enp0s31f6 | awk '/d8:3a:dd:a8:9a:40/{print $1; exit}')
• SSH: sshpass -p beacon ssh user@$CM4 — use -tt for rauc commands
• File transfer: scp broken on Dropbear → use ssh 'sudo tee /upload/file >/dev/null' < localfile
• UART: picocom -b 115200 /dev/ttyUSB0 — user handles power cycling manually

Build

cd ~/repos/buildroot-beacon
make -C rpi-buildroot-fork O=$(pwd)/output BR2_EXTERNAL=$(pwd)/beacon-buildroot -j$(nproc)

Flash (secure-boot CM4)

Bridge EMMC_DISABLE jumper + connect USB, then:

bash beacon-buildroot/scripts/flash-cm4-sb.sh        # auto-detect
bash beacon-buildroot/scripts/flash-cm4-sb.sh /dev/sda  # explicit

Script auto-signs usbboot/secure-boot-msd/boot.img with private.pem if needed.

OTA Update

# Transfer bundle
sshpass -p beacon ssh user@$CM4 'sudo tee /upload/rootfs.raucb >/dev/null' \
  < output/images/rootfs.raucb
# Install + reboot
sshpass -p beacon ssh -tt user@$CM4 'sudo rauc install /upload/rootfs.raucb && sudo reboot'
# After reboot: find new IP, then MUST mark-good or slot rolls back
sshpass -p beacon ssh -tt user@$CM4 'sudo rauc status mark-good && rauc status'

Key gotchas

• lsblk not on target — use cryptsetup status data to check /data
• rauc needs -tt on Dropbear or output is silently dropped
• mark-good is required after every OTA reboot
• /data is LUKS2 (AES-XTS-256, OTP key) — untouched by RAUC, self-heals on bad header
• private.pem at repo root — never regenerate it