Skip to main content

​
Hardware preflight check

Run scripts/preflight.sh after first boot to verify hardware is enumerated correctly: 
sudo bash scripts/preflight.sh
The script performs three checks: 
--- Memory & CMA Check ---
MemTotal: ...
CmaTotal: ...  CmaFree: ...

--- PCIe Link Check (Axelera) ---
LnkCap: ...
LnkSta: ...

--- Udev Symlink Check ---
✅ /dev/gps0 -> /dev/ttyAMA1
✅ /dev/axelera0 -> /dev/xdma0
✅ /dev/cruiser-iot -> /dev/ttyUSB0
If any symlink shows ❌ MISSING, see the Axelera or udev sections below.

​
Re-entering the chroot

To re-enter the image chroot after flashing (e.g., to set passwords or fix configs): 
BTRFS_OPTS="compress=zstd,space_cache=v2,noatime"
MOUNT_ROOT="/mnt/rpi5-root"
ROOT_DEV=/dev/sdX2
ESP_DEV=/dev/sdX1

sudo mount -o "${BTRFS_OPTS},subvol=@"     "$ROOT_DEV" "$MOUNT_ROOT"
sudo mount -o "${BTRFS_OPTS},subvol=@boot" "$ROOT_DEV" "${MOUNT_ROOT}/boot"
sudo mount                                  "$ESP_DEV"  "${MOUNT_ROOT}/boot/efi"
for mp in proc sys dev dev/pts run; do
    sudo mount --bind "/${mp}" "${MOUNT_ROOT}/${mp}"
done
sudo arch-chroot "$MOUNT_ROOT"

​
Common issues

The script checks for required tools at startup. If it exits with [ FAIL ] Missing dependency: <cmd>, install the missing package:
# Arch host
sudo pacman -S parted dosfstools btrfs-progs arch-install-scripts qemu-user-static

# Debian/Ubuntu host
sudo apt install parted dosfstools btrfs-progs arch-install-scripts qemu-user-static
Also confirm qemu-aarch64-static is present at /usr/bin/qemu-aarch64-static:
ls -l /usr/bin/qemu-aarch64-static
The script intentionally leaves root passwordless. After building/flashing, re-enter the chroot and set a password before first boot:
sudo arch-chroot /mnt/rpi5-root
passwd
exit
If you see this warning during the build:
[ WARN ] No authorized_keys found at /home/user/.ssh/id_ed25519.pub
[ WARN ] Early SSH rescue will not work without authorized_keys
Fix it by copying your public key into the image before flashing:
sudo cp ~/.ssh/id_ed25519.pub /mnt/rpi5-root/etc/dropbear/authorized_keys
sudo chmod 600 /mnt/rpi5-root/etc/dropbear/authorized_keys
Then rebuild the initramfs (dracut must re-embed the key).
During the image build you may see:
[ WARN ] chattr +C failed — swap.img may have CoW issues; set nodatacow mount option
This is non-fatal. The nodatacow mount option in /etc/fstab for the @swap subvolume achieves the same result. Verify the fstab entry includes nodatacow:
UUID=<id>  /swap  btrfs  compress=zstd,space_cache=v2,noatime,subvol=@swap,nodatacow  0  0
PCIe must be explicitly enabled in config.txt. Check /boot/efi/config.txt on the ESP:
cat /boot/efi/config.txt | grep pcie
It must contain:
dtparam=pciex1=on
If missing, add it and reboot. PCIe devices will then enumerate after the UEFI handoff.
NVMe is disabled by default in config.txt. Uncomment or add:
dtparam=nvme=on
Then reboot. The NVMe drive will appear as /dev/nvme0n1.
Check that the Metis udev rules are installed:
ls /etc/udev/rules.d/99-axelera-metis.rules
If missing, re-run metis-setup.sh or install the rule manually and trigger udev:
sudo udevadm control --reload-rules
sudo udevadm trigger
ls /dev/axelera0
Also verify the Metis PCIe device is enumerated:
lspci | grep -i axelera
If nothing appears, check dtparam=pciex1=on in config.txt.
  1. Check /dev/axelera0 exists: ls /dev/axelera0
  2. Check the frigate user is in the axelera group: groups frigate
  3. Check Frigate container logs: docker logs frigate or journalctl -u frigate
  4. Verify the detector config in /etc/frigate/config.yml: 
    detectors:
  axelera_metis:
    type: axelera
    device: /dev/axelera0
  5. Confirm the container has device access: the Docker Compose entry must include devices: - /dev/axelera0:/dev/axelera0
Ensure the kernel cmdline includes console=ttyAMA0,115200. Check your GRUB config:
cat /boot/grub/grub.cfg | grep console
Also verify enable_uart=1 is in /boot/efi/config.txt. Connect your serial adapter to the UART debug header on the Exaviz Cruiser carrier at 115200 8N1.
Updating pieeprom (RPi EEPROM bootloader):
sudo rpi-eeprom-update -a
sudo reboot
Updating RPI_EFI.fd (UEFI firmware): Download from worproject/rpi5-uefi releases and replace on the ESP:
sudo cp RPI_EFI.fd /boot/efi/
sudo reboot
Do not remove config.txt from the ESP during this process.

Build docs developers (and LLMs) love

Get started for freeTalk to us