# Beacon CM4 Agent Cheat Sheet

## Automated Flash (jumper bridged, fully scripted)

**One command** — bridge the EMMC_DISABLE jumper, then run from repo root:
```bash
cd ~/repos/buildroot-beacon
./beacon-buildroot/scripts/flash-cm4.sh
```
The script:
1. Builds `usbboot/rpiboot` from source if not already compiled
2. Runs `rpiboot -d mass-storage-gadget64` to expose eMMC over USB
3. Auto-detects the CM4 USB block device (~7.3 GiB)
4. Unmounts any auto-mounted partitions
5. Flashes `output/images/sdcard.img.xz` via `bmaptool` (sparse, fast)
6. Prints "Flash complete — remove jumper and power-cycle"

Override device explicitly if auto-detect picks wrong disk:
```bash
./beacon-buildroot/scripts/flash-cm4.sh /dev/sda
```

## UART Console (interactive)

UART probe on GPIO14 (TX) / GPIO15 (RX), 115200 baud:
```bash
picocom -b 115200 /dev/ttyUSB1
# or with log capture:
picocom -b 115200 --logfile /tmp/uart-$(date +%s).log /dev/ttyUSB1
```
Exit: `Ctrl-A Ctrl-X`

## UART Log Capture (non-interactive, agent-readable)

Use `socat` — truly headless, no terminal required, clean line endings:
```bash
# Start BEFORE power-cycling the CM4:
socat -u /dev/ttyUSB1,b115200,rawer,crnl OPEN:/tmp/uart-boot.log,creat,trunc &
# Stop capture after boot is done:
kill %1
# Read the log:
cat /tmp/uart-boot.log
```
**Notes**:
- `picocom` backgrounded with `&` gets stopped by job control (SIGTTOU) — do not use it headlessly
- `cat /dev/ttyUSB1` with `stty raw` produces garbled output — do not use it

## SSH Access

Login: `user` / `beacon`  (root login disabled — use `sudo su -`)
```bash
# Find CM4 IP (DHCP, changes on reboot):
ip neigh show dev enp0s31f6 | grep e4:5f:01:e9:13:96
# SSH:
sshpass -p beacon ssh user@<cm4-ip>
```
**Note**: Dropbear has no sftp-server — `scp` does NOT work. Transfer files via stdin pipe:
```bash
sshpass -p beacon ssh user@<cm4-ip> 'sudo tee /upload/rootfs.raucb > /dev/null' < output/images/rootfs.raucb
```

## OTA Update (fully scripted from host)

```bash
CM4=10.11.0.xx  # find via: ip neigh show dev enp0s31f6

# 1. Transfer bundle (~51 MB, ~5s on LAN):
sshpass -p beacon ssh user@$CM4 'sudo tee /upload/rootfs.raucb > /dev/null' \
  < output/images/rootfs.raucb

# 2. Install:
sshpass -p beacon ssh user@$CM4 'rauc install /upload/rootfs.raucb'

# 3. Reboot into slot B:
sshpass -p beacon ssh user@$CM4 'sudo reboot'

# 4. After reboot (new IP — find again with ip neigh):
sshpass -p beacon ssh user@$CM4_NEW 'rauc status mark-good && rauc status'
```
**Note**: ports 8080 and 9090 are taken by other host services — do NOT use HTTP for OTA.

## RAUC Status

```bash
sshpass -p beacon ssh user@<cm4-ip> 'rauc status'
sudo fw_printenv | grep BOOT_
```

## Rescue Mode

Short GPIO4 (pin 7) to GND (pin 9) on 40-pin header during power-on.

## Secure Boot Provision (Milestone 2)

```bash
update-pieeprom.sh -k private.pem
rpiboot -d secure-boot-recovery
```
**rpi secure boot private key**: use `/buildroot-beacon/private.pem` — do NOT generate a fresh one. RAUC has its own key; keep both alongside each other.