Create a USB Installation¶
This writes a libretouch image to a USB drive. The drive holds the whole system — the device's internal flash is not touched — so it is the way to run libretouch on a device you want to leave otherwise as it is.
Booting the finished drive is covered in Development setups; this page only produces it.
Warning: Writing an image erases the entire drive. Identify the target device carefully — naming the wrong one destroys whatever is on it, and on a desktop machine that can be a system disk.
Check your device has a USB-A socket first. Several SoundTouch models have only the micro-USB service port and cannot boot from a drive at all; on those, use USB RNDIS network boot instead. See USB ports.
What you need¶
A USB drive and a Linux host. Any size works; the image is small and the root filesystem is not expanded to fill the drive.
The image¶
Build the machine you intend to boot, then look in
build/deploy-ti/images/<machine>/ for two files:
libretouch-image-<machine>.rootfs.wic.xz the compressed disk image
libretouch-image-<machine>.rootfs.wic.bmap its block map
Both are symlinks to the newest timestamped build. There is no uncompressed
.wic; the build does not produce one.
The image contains two partitions, and they are what the bootloader expects:
| Partition | Filesystem | Contents |
|---|---|---|
1, labelled boot |
FAT16 | uImage, initramfs.bin, and a device tree for every supported board |
2, labelled root |
ext4 | the root filesystem |
The first partition's MBR type byte says 0x0c (FAT32 LBA) while the filesystem
mkfs.fat actually creates is FAT16, at both partition sizes the machines use.
U-Boot's fatload reads the boot sector rather than the type byte, so it does
not care, and neither should you — but tools that trust the partition type will
report FAT32.
Identify the drive¶
Insert the drive and list the block devices:
lsblk -o NAME,SIZE,TYPE,TRAN,MODEL,MOUNTPOINTS
The drive is the disk whose TRAN is usb and whose size matches. Confirm it
before continuing — dmesg | tail names the device that was just attached, and
ls -l /dev/disk/by-id/usb-* gives a name that identifies the drive itself
rather than the order it was plugged in.
If the desktop mounted any partition of the drive, unmount it — but leave the drive plugged in:
sudo umount /dev/sdX?
sdX stands for the drive throughout. Replace it, and write to the whole
device (/dev/sdb), never to a partition (/dev/sdb1).
Write it¶
With bmaptool, which reads the .bmap beside the image, skips unwritten
blocks and checksums what it wrote:
sudo bmaptool copy libretouch-image-<machine>.rootfs.wic.xz /dev/sdX
Keep the .bmap file next to the .wic.xz; bmaptool finds it by name. Copy
the image elsewhere on its own and it falls back to writing every block, which
still works but is slower and unverified.
Without bmaptool:
xzcat libretouch-image-<machine>.rootfs.wic.xz | sudo dd of=/dev/sdX bs=4M conv=fsync status=progress
Either way, wait for the command to return before removing the drive.
Check the result¶
Re-read the partition table and confirm both partitions are there with the expected labels:
sudo blockdev --rereadpt /dev/sdX
lsblk -o NAME,SIZE,FSTYPE,LABEL /dev/sdX
Two partitions should appear, boot (vfat) and root (ext4). If only one
does, or the labels are missing, the write did not complete — do it again
rather than trying to boot it.
To check the boot partition holds what the bootloader will ask for:
sudo mount /dev/sdX1 /mnt
ls /mnt
sudo umount /mnt
uImage and initramfs.bin should be there, alongside <variant>_<module>.dtb
for each supported board and a common_<module>.dtb per module. The bootloader
loads the one matching the board it is running on, so a drive written this way
boots any supported device.