Reflashing the Phone

This guide describes how to reflash the system image on your Librem 5 phone from a workstation, using a USB-A to USB-C cable.

Overview

To erase the existing image on the internal eMMC and install a new image, you need to download the following items:

  • An appropriate version of the uuu tool.
  • Scripts from the librem5-devkit-tools repository.
  • The latest system image from the the Purism CI server.
  • The latest U-Boot image from the the Purism CI server.

Then you will need to run the flashing script to reflash the phone’s system software.

These steps are covered in the sections below.

Download the Flashing Scripts

Files from the librem5-devkit-tools repository are responsible for downloading the image files and transferring them to the phone. Other scripts are used to help with building tools.

In a terminal, clone the librem5-devkit-tools repository before proceeding:

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

The librem5-devkit-tools directory will be created. Make this directory the current directory:

cd librem5-devkit-tools

You are now ready to install uuu.

Install uuu

Note

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

If you are using PureOS on your workstation, install uuu by opening a terminal and entering the following command:

sudo apt install uuu

You can obtain a uuu package for other Debian-based systems from PureOS amber-updates. Make sure that you download the correct package for your workstation’s architecture – typically amd64.

On non-Debian Linux distributions, run the build_uuu.sh script from the current directory to download, build and install the tool:

./scripts/build_uuu.sh -i

You can omit the -i option if you do not want to install the tool – in that case you will need to make sure that the build/mfgtools/uuu directory is on the run path.

Download the System and U-Boot Images

Create the files directory:

mkdir -p files

In a web browser, go to the Image Builds page on the CI server and download the latest next librem5 amber-phone image, which is provided as an librem5.img.xz file, into the files directory, then decompress it:

xz -d files/librem5.img.xz

Go to the U-Boot Librem 5 Builds page and download the last successful build, provided as an u-boot-librem5.imx file, into the files directory.

Prepare the Phone

The phone needs to be put in the correct boot mode. The phone itself will not provide an indication of the boot mode – the workstation is used to check this.

Ensure that the phone is switched off.

Not doing these steps in this order could cause the flashing to fail:

  1. Disconnect the USB C cable.
  2. Press and hold the Volume Up button. Keep it pressed.
  3. Press and hold the power button for 16 seconds.
  4. Release the the power button.
  5. Release the Volume Up button.
  6. Plug one end of the USB C cable into your workstation.
  7. Plug the other end of the USB C cable into the phone.

The phone should now be visible on the workstation if you run lsusb or a similar tool:

$ lsusb | grep NXP

This should report the following kind of output:

Bus 003 Device 024: ID 1fc9:012b NXP Semiconductors

If the phone is reported in this way then you can proceed to flash the image.

Note

Some USB-C cables may need to be plugged into the phone with a particular orientation. If the instructions above do not appear to work, try flipping the USB-C end of the cable over and replugging it into the phone.

Flash the Image

You should now be ready to flash a new image.

This will erase the contents of the phone’s eMMC, including user data.

First, check that everything is ready:

  • Check that the librem5-devkit-tools directory is the current directory.
  • The current directory should contain a files directory containing the librem5.img and u-boot-librem5.imx files.

Run the uuu tool to process the uuu_scripts/flash_librem5.lst script:

$ uuu uuu_scripts/flash_librem5.lst

Successful output will look something like this:

uuu (Universal Update Utility) for nxp imx chips -- libpureos/1.2.91+0git6b465-62-g9c56e46

Success 1    Failure 0

Remove the USB C cable and hold down the power button for 15-18 seconds to reset the phone.

Your phone should now be running the latest image.