clawdie-iso/FLASHING.md

Flashing the Clawdie Operator USB

Published Clawdie operator USB artifacts are compressed:

clawdie-quindecim-0.2.29.img.xz

Default policy:

Downloaded .img.xz  -> stream xz directly into dd
Build-local .img    -> plain dd is OK
Always write to the whole USB disk, never to a partition

The compressed streaming path avoids storing both the 6+ GB compressed image and the much larger 28 GB raw image.

---

Safety Checklist

Before writing:

1. Verify the checksum.
2. Identify the USB disk carefully.
3. Unmount any mounted partitions from that USB stick.
4. Write to the whole disk device:
   • Linux: /dev/sdX, /dev/nvmeXnY, etc.
   • FreeBSD: /dev/daX, etc.
5. Do not write to a partition such as /dev/sdX1, /dev/da0p1, or /dev/da0s1.

A wrong device name can destroy the host OS or another data disk.

---

Linux: Flash a Downloaded .img.xz

Find the USB disk:

lsblk -o NAME,SIZE,MODEL,TRAN,MOUNTPOINTS

Download with resume and retries:

curl -fL --continue-at - --retry 5 --retry-delay 5 --progress-bar -O \
  https://osa.smilepowered.org/downloads/iso/clawdie-quindecim-0.2.29.img.xz
curl -fL --retry 5 --retry-delay 5 -O \
  https://osa.smilepowered.org/downloads/iso/clawdie-quindecim-0.2.29.img.xz.sha256

Verify the downloaded artifact:

sha256sum -c clawdie-quindecim-0.2.29.img.xz.sha256

Unmount mounted USB partitions if needed:

sudo umount /dev/sdX* 2>/dev/null

Flash by streaming xz into dd:

set -o pipefail 2>/dev/null || true
xz -dc clawdie-quindecim-0.2.29.img.xz | sudo dd of=/dev/sdX bs=4M status=progress conv=fsync
sync

Replace /dev/sdX with the actual whole USB disk.

---

FreeBSD: Flash a Downloaded .img.xz

Find the USB disk:

camcontrol devlist
gpart show

Download with resume and retries:

curl -fL --continue-at - --retry 5 --retry-delay 5 --progress-bar -O \
  https://osa.smilepowered.org/downloads/iso/clawdie-quindecim-0.2.29.img.xz
curl -fL --retry 5 --retry-delay 5 -O \
  https://osa.smilepowered.org/downloads/iso/clawdie-quindecim-0.2.29.img.xz.sha256

Verify the downloaded artifact:

HASH=$(awk '{print $1}' clawdie-quindecim-0.2.29.img.xz.sha256)
sha256 -c "$HASH" clawdie-quindecim-0.2.29.img.xz

If sha256sum is installed, this GNU-style form is also OK:

sha256sum -c clawdie-quindecim-0.2.29.img.xz.sha256

Unmount mounted USB partitions if needed:

sudo umount /dev/daXs* 2>/dev/null

Flash by streaming xz into dd:

xz -dc clawdie-quindecim-0.2.29.img.xz | sudo dd of=/dev/daX bs=1M status=progress conv=fsync
sync

Replace /dev/daX with the actual whole USB disk.

---

Windows: Flash with Rufus or balenaEtcher

No decompression step needed — both tools read .img.xz directly.

1. Download both files (same folder):
   • clawdie-quindecim-0.2.29.img.xz
   • clawdie-quindecim-0.2.29.img.xz.sha256
2. (Recommended) verify the checksum in PowerShell:

   (Get-FileHash .\clawdie-quindecim-0.2.29.img.xz -Algorithm SHA256).Hash.ToLower()
   # compare against the value in the .sha256 file
   

3. Rufus: open Rufus → SELECT the .img.xz → choose the USB drive under "Device" → START. Rufus decompresses and writes in one step. (Use "DD Image" mode if prompted.) balenaEtcher: Flash from file → pick the .img.xz → Select target → Flash.
4. Write to the whole USB device, not a partition. This erases the drive.

If your flasher is old and rejects .xz, extract first with 7-Zip (≥21.07) to get the raw .img, then flash that.

---

If You Already Have an Uncompressed .img

For a local build artifact that already exists as a raw image:

Linux

sudo dd if=clawdie-quindecim-0.2.29.img of=/dev/sdX bs=4M status=progress conv=fsync
sync

FreeBSD

sudo dd if=clawdie-quindecim-0.2.29.img of=/dev/daX bs=1M status=progress conv=fsync
sync

Only unxz first if you specifically need the raw file for inspection or reuse:

unxz -k clawdie-quindecim-0.2.29.img.xz

---

Optional: Wipe Old Labels Before Reflashing

Old images can leave stale metadata near the end of the USB stick. If the live USB later reports unexpected labels, wipe the whole stick before reflashing.

Linux

Inspect first:

sudo wipefs -n /dev/sdX
sudo fdisk -l /dev/sdX

Then wipe only after confirming /dev/sdX is the USB stick:

sudo sgdisk --zap-all /dev/sdX
sudo dd if=/dev/zero of=/dev/sdX bs=16M status=progress conv=fsync
sync

FreeBSD

Inspect first:

gpart show /dev/daX

Then wipe only after confirming /dev/daX is the USB stick:

sudo gpart destroy -F /dev/daX
sudo dd if=/dev/zero of=/dev/daX bs=16M status=progress conv=fsync
sync

Some sticks may not have a partition table at inspection time; that is fine. The important rule is to confirm the target disk before destructive commands.