Thistle OTA Update on Raspberry Pi 5

Root Filesystem A/B OTA Update on Raspberry Pi 5 with headless image prep (Raspberry Pi OS Bookworm)

This guide shows how to perform Thistle OTA on a Raspberry Pi 5. Start with a quick file‑update path (no A/B). Optionally, pre‑partition a Raspberry Pi OS image to add a rootfsB partition and pre‑enable headless SSH/Wi‑Fi before flashing.

Raspberry Pi 5 uses a Pi firmware boot chain loading from the FAT boot partition. For OTA A/B, set the bootloader in the Thistle config to RaspberryPi. Depending on the distro, the boot partition may be mounted at /boot or /boot/firmware.

Board setup (vendor/community docs)

• Official imaging: Raspberry Pi Imager (“Use custom” supports local images)
• General microSD flashing workflow: Prepare microSD

Quick path: File updates (no A/B)

Use Thistle’s file‑update mode to ship signed files and app bundles without changing partitions.

1. Download tools

• Workstation (TRH):

VER=1.5.0
curl -LO https://downloads.thistle.tech/embedded-client/$VER/trh-$VER-x86_64-unknown-linux-musl.gz
gunzip trh-$VER-x86_64-unknown-linux-musl.gz
chmod +x trh-$VER-x86_64-unknown-linux-musl && ln -sf trh-$VER-x86_64-unknown-linux-musl trh

• Device (TUC on RPi5, aarch64):

# On the device (SSH or serial)
VER=1.5.0
curl -LO https://downloads.thistle.tech/embedded-client/$VER/tuc-$VER-aarch64-unknown-linux-musl.gz
gunzip tuc-$VER-aarch64-unknown-linux-musl.gz
chmod +x tuc-$VER-aarch64-unknown-linux-musl
sudo mv tuc-$VER-aarch64-unknown-linux-musl /usr/local/bin/tuc

2. Initialize and release a simple file update on the workstation

export THISTLE_TOKEN=$(cat)   # paste token, Enter, then Ctrl-D
./trh init --persist="/boot"

mkdir -p example && echo "hello from thistle" > example/app
./trh prepare --target=./example --file-base-path=/opt/example
./trh release

3. Copy config to device and run client

# On workstation — change host/user to what you configured when imaging
scp config.json <user>@<rpi-host-or-ip>:/tmp/tuc-config.json

# On device
sudo mv /tmp/tuc-config.json /boot/tuc-config.json
sudo tuc -c /boot/tuc-config.json

That’s it! File updates are fetched, verified, and installed atomically. Continue below only if you need rootfs A/B for boot‑time rollback.

Optional: Headless image prep (Raspberry Pi OS Bookworm, 64‑bit)

Prepare a Raspberry Pi OS image before flashing: create rootfsB, enable SSH, preconfigure Wi‑Fi, and set hostname. Docker is optional; any live Linux works.

1. Download the image

mkdir -p ~/rpi-img && cd ~/rpi-img
# Example: Raspberry Pi OS Lite (64‑bit) .img(.xz). Decompress if needed
# Use Raspberry Pi Imager or download a current Bookworm Lite image manually
# and set rpi5.img accordingly.
# e.g., with a downloaded file named 2025-05-13-raspios-bookworm-arm64-lite.img.xz
curl -LO https://downloads.raspberrypi.com/raspios_lite_arm64/images/2025-05-13/2025-05-13-raspios-bookworm-arm64-lite.img.xz
xz -d 2025-05-13-raspios-bookworm-arm64-lite.img.xz
mv 2025-05-13-raspios-bookworm-arm64-lite.img rpi5.img

2. Start a Linux environment in Docker (optional)

docker run --rm -it --privileged -v "$PWD":/work ubuntu:24.04 bash

Inside the container:

apt-get update
apt-get install -y parted e2fsprogs kpartx util-linux
cd /work

3. Expand image size & map partitions

truncate -s +8G rpi5.img                      # add 8 GiB free space
losetup -Pf --show rpi5.img                   # e.g. /dev/loop0
kpartx -av /dev/loop0                         # maps /dev/mapper/loop0p1, loop0p2

4. Resize rootfs (p2) to 6 GiB (example)

e2fsck -f /dev/mapper/loop0p2
resize2fs /dev/mapper/loop0p2 5900M   # adjust larger if your image requires more space
parted -s /dev/loop0 unit GiB resizepart 2 6
e2fsck -f /dev/mapper/loop0p2
resize2fs /dev/mapper/loop0p2

5. Create & format rootfsB

parted -s /dev/loop0 -a optimal mkpart primary ext4 6GiB 100%
kpartx -a /dev/loop0
mkfs.ext4 -F -L rootfsB /dev/mapper/loop0p3

6. Enable headless SSH + Wi‑Fi

Mount rootfs and boot partitions:

mkdir -p /mnt/root /mnt/boot
mount /dev/mapper/loop0p2 /mnt/root
mount /dev/mapper/loop0p1 /mnt/boot

a) Enable SSH at boot (RPi OS mechanism)

# An empty file named 'ssh' in the boot (FAT) partition enables SSH on first boot
: > /mnt/boot/ssh

b) Configure Wi‑Fi (wpa_supplicant via boot)

cat > /mnt/boot/wpa_supplicant.conf <<'EOF'
country=US
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1

network={
    ssid="YOUR_SSID"
    psk="YOUR_PASSWORD"
}
EOF

c) (Optional) Pre‑create a user for headless login

On recent Raspberry Pi OS releases, a user is required. Either use Raspberry Pi Imager’s customization to set username/password, or add userconf.txt to the boot partition with a SHA‑512 hashed password:

# Replace 'pi' and the hash accordingly. Generate hash with: echo 'mypassword' | openssl passwd -6 -stdin
echo 'pi:$6$REDACTED_HASH' > /mnt/boot/userconf.txt

d) Set hostname

echo "rpi5" | tee /mnt/root/etc/hostname >/dev/null
# Ensure /etc/hosts maps 127.0.1.1 to the hostname
sed -i 's/^127.0.1.1.*/127.0.1.1\trpi5/' /mnt/root/etc/hosts || echo "127.0.1.1\trpi5" >> /mnt/root/etc/hosts

Unmount and clean up:

umount /mnt/boot /mnt/root
kpartx -dv /dev/loop0
losetup -d /dev/loop0
exit

7. Flash to SD

• Using Raspberry Pi Imager: select “Use custom” and choose rpi5.img.
• Or on macOS:

diskutil list                         # locate your SD (e.g., /dev/disk3)
diskutil unmountDisk /dev/diskN       # replace diskN with your SD identifier
sudo dd if=rpi5.img of=/dev/rdiskN bs=4m status=progress
sync

8. First boot

• Partitions:
  • p1 → boot (FAT)
  • p2 → rootfs (6 GiB ext4)
  • p3 → rootfsB (ext4, label rootfsB)
• SSH enabled automatically if ssh file present
• Wi‑Fi auto‑connects if wpa_supplicant.conf was provided
• Hostname set to rpi5 (unless changed)

Login:

ssh <user>@rpi5.local
# or: ssh <user>@<rpi-ip>

Thistle Tools

On the workstation and the device, download TRH/TUC as appropriate, then export your Project Access Token on the workstation.

# Workstation: TRH (prepare/release)
VER=1.5.0
curl -LO https://downloads.thistle.tech/embedded-client/$VER/trh-$VER-x86_64-unknown-linux-musl.gz
gunzip trh-$VER-x86_64-unknown-linux-musl.gz
chmod +x trh-$VER-x86_64-unknown-linux-musl && ln -sf trh-$VER-x86_64-unknown-linux-musl trh

# Device: TUC (install)
# Use the user/host you configured; example uses mDNS hostname
# Note: Use the aarch64 binary for 64‑bit images. If you chose a 32‑bit image,
# use the armv7 binary instead.
ssh <user>@rpi5.local 'VER=1.5.0; curl -LO https://downloads.thistle.tech/embedded-client/$VER/tuc-$VER-aarch64-unknown-linux-musl.gz && gunzip tuc-$VER-aarch64-unknown-linux-musl.gz && chmod +x tuc-$VER-aarch64-unknown-linux-musl && sudo mv tuc-$VER-aarch64-unknown-linux-musl /usr/local/bin/tuc && tuc --help | head -n 3'

# Workstation: Project token for TRH
export THISTLE_TOKEN=$(cat)

Initialize and Prepare Rootfs Release

./trh init --persist="/boot"
./trh prepare --target=myrootfs.img
./trh release

Device Configuration

Create tuc-config.json (adjust paths if your boot is /boot/firmware):

{
  "name": "rpi5",
  "persistent_directory": "/boot",
  "public_keys": ["<YOUR_PUBLIC_KEY>"],
  "bootloader": "RaspberryPi",
  "part_a": "/dev/mmcblk0p2",
  "part_b": "/dev/mmcblk0p3"
}

Copy configuration to the board and persist under /boot:

scp tuc-config.json <user>@rpi5.local:/tmp/
ssh <user>@rpi5.local 'sudo cp /tmp/tuc-config.json /boot/tuc-config.json'

Run Update

ssh <user>@rpi5.local
sudo tuc -c /boot/tuc-config.json

The device installs to the inactive slot and reboots. After reboot, run the client again to latch‑in the update.

Notes and Tips

• If your distro mounts the boot partition at /boot/firmware, point persistent_directory there.
• For headless provisioning on Bookworm, Raspberry Pi Imager customization is the simplest route (set SSH, Wi‑Fi, user, hostname). Manual ssh + wpa_supplicant.conf still works and is widely documented.
• For more background on headless setup nuances on Bookworm vs Bullseye, see community articles (e.g., first‑run mechanisms and userconf.txt).