Flashing the System Image

The main purpose of the image included on the eMMC is factory testing, therefore it’s strongly recommended to flash an up-to-date one immediately.

The scripts mentioned in this section can be obtained from the librem5-devkit-tools repository.

Install uuu

Note

The uuu tool requires a 64-bit host to run and is packaged as an amd64 binary.

The NXP mfgtool uuu is required to boot a board that has no bootloader or is otherwise “bricked”.

You can obtain a uuu package for Debian-based systems from the Purism CI server or build uuu from source.

To install the package, run the dpkg tool in the following way:

sudo dpkg -i uuu_1.2.91_amd64.deb

The precise .deb package file name may differ from the one given above. Version 1.2.91 or later is recommended.

Download the Flashing Scripts

Files from the librem5-devkit-tools repository are responsible for the downloading of the image files, and for coordinating their transfers to the devkit. If you want to flash an image by hand instead of using the scripts, please consult the Flashing an Image by Hand guide.

Clone the librem5-devkit-tools repository before proceeding:

git clone https://source.puri.sm/Librem5/librem5-devkit-tools.git

You should now have everything you need to download and flash a new image.

Flash the Image

Note

If your workstation cannot provide the necessary power for this process you may need a USB 3 powered hub between the host and the development board.

Put the “Boot Mode” switch in the USB position. Attach the development board to a USB C or USB 3 port on the host that is capable of providing 900mA of current. The HID device should appear in the output of the lsusb command, like this:

Bus 001 Device 005: ID 1fc9:012b NXP Semiconductors

The librem5-devkit-flash-image script will download and flash the newest available rootfs and U-Boot images. You may need to install some Python modules before running the script. On Debian 9 (Stretch), Ubuntu 18.04 LTS (Bionic Beaver) and later, this command should install these modules:

sudo apt-get -y install python3-jenkins python3-tqdm python3-yaml

Now you can proceed with the flashing, using the script as shown below to download temporary copies of U-Boot, kernel and the base system, before flashing them on the board. Use the --skip-cleanup and --dir command line options to keep the downloaded files after flashing.

This will erase everything on the board’s eMMC:

cd librem5-devkit-tools
export PATH=$PATH:/path-to-your-workspace/mfgtools-build/uuu/
./scripts/librem5-flash-image --board devkit

If you use the --dir option to download the files into a directory and --skip-cleanup to keep them after flashing, you can re-flash the eMMC using the same files by entering the download directory and running uuu. For example, this is how you would download the files to the ~/Downloads directory and flash the eMMC.

This will erase everything on the board’s eMMC:

cd librem5-devkit-tools
export PATH=$PATH:/path-to-your-workspace/mfgtools-build/uuu/
./scripts/librem5-flash-image --board devkit --dir ~/Downloads --skip-cleanup

It can also be useful to use the --skip-flash if you only want to download the files without flashing the eMMC.

If you need to re-flash the eMMC with the same image later, you can just use uuu directly, assuming you still have the image file:

# Re-flash the eMMC later:
cd ~/Downloads
uuu flash_devkit.lst

It may be useful to keep a local archive of images that you have flashed for testing purposes, and to allow you to return to a previous image.

Next Steps

Go to the Booting for the First Time section to prepare the board for booting.