rk1/FLASHING.md

Flashing the image to RK1 eMMC

Flashing destroys the selected target. Boot the RK1 from another device first (for example NVMe), or attach the eMMC through an appropriate loader/USB mode. Never overwrite the device that currently contains /.

Identify every disk by path, size, model, and serial:

findmnt /
lsblk -o NAME,PATH,SIZE,MODEL,SERIAL,TRAN,TYPE,MOUNTPOINTS

The eMMC will usually be a whole /dev/mmcblkN device, but the number is not a promise. The helper deliberately refuses partitions such as /dev/mmcblk0p1, non-MMC disks, mounted descendants, and active swap. Repeat the resolved target path in --confirm:

cd /home/ubuntu/rk1-media-image
sudo ./scripts/flash-emmc.sh \
  --image dist/rk1-media-20260817-r4-trixie-vendor-6.1.115-turing-rk1-emmc.img.xz \
  --target /dev/mmcblkN \
  --confirm /dev/mmcblkN

The helper performs four checks around the destructive write:

1. validates the XZ stream and adjacent SHA-256 file;
2. checks target type, capacity, mounts, and swap;
3. streams the 4 GiB raw image with a flushed direct write;
4. decompresses it again while reading the target back byte-for-byte.

Only remove power after it reports that read-back verification passed. Then shut down, remove or reprioritize the temporary boot disk, attach Ethernet and HDMI, turn on the TV/input, and boot the eMMC.

If the carrier exposes RK1 eMMC through a different flashing workflow, the .img.xz is a normal whole-disk image. A trusted imager can use it directly; retain the same checksum and target-identification discipline.

Keep boot on eMMC and move root to NVMe

The RK1 still needs its boot payload and /boot on eMMC. Once the appliance has finished first-boot provisioning, identify the NVMe by its exact model and serial, then run the helper included in revision r4:

findmnt -no SOURCE,FSTYPE /
lsblk -e7 -o NAME,PATH,SIZE,TYPE,FSTYPE,MOUNTPOINTS,MODEL,SERIAL
sudo test -e /var/lib/rk1-media/provisioned && echo PROVISIONED

sudo rk1-media-migrate-root-to-nvme \
  --target /dev/nvme0n1 \
  --serial EXACT_SERIAL_FROM_LSBLK

This destroys every existing partition on only the confirmed target NVMe. It does not repartition the eMMC or rewrite U-Boot. The helper stops Kodi and package-update jobs, performs the Armbian sd-mode root copy, checks the new filesystem and boot configuration independently, and prints MIGRATION_VALIDATED only after the rollback-sensitive writes have synced. Reboot immediately after that result:

sudo systemctl reboot
findmnt -no SOURCE,FSTYPE /
findmnt /boot
findmnt /media/boot-media

To return to the intact eMMC root while the NVMe-rooted system is still reachable:

sudo cp -a /boot/armbianEnv.txt.pre-nvme /boot/armbianEnv.txt
sudo cmp /boot/armbianEnv.txt.pre-nvme /boot/armbianEnv.txt
sudo sync
sudo systemctl reboot

Never use armbian-install --boot split-emmc for this rollback-preserving migration; that mode repartitions both devices.