Reflashing_the_Phone.rst 4.74 KB
Newer Older
1 2 3
Reflashing the Phone
====================

4
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.
5

6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71
.. contents::
   :local:

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:

.. code:: bash

   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:

.. code:: bash

   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:

.. code:: bash

   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:

.. code:: bash

   ./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:

.. code:: bash

   mkdir -p files

David Boddie's avatar
David Boddie committed
72
In a web browser, go to the `Image Builds`_ page on the CI server and download the latest **plain librem5 amber-phone** image, which is provided as an ``librem5.img.xz`` file, into the ``files`` directory, then decompress it:
73 74 75 76 77 78 79 80 81 82

.. code:: bash

   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
-----------------

83
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.
84

David Boddie's avatar
David Boddie committed
85
Ensure that the phone is switched off.
86

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

89
 #. Disconnect the USB C cable.
David Boddie's avatar
David Boddie committed
90
 #. Press and hold the Volume Up button. Keep it pressed.
91
 #. Press and hold the power button for 16 seconds.
David Boddie's avatar
David Boddie committed
92
 #. Release the the power button.
David Boddie's avatar
David Boddie committed
93
 #. Release the Volume Up button.
94 95 96 97 98 99 100 101 102 103 104 105 106 107 108
 #. Plug one end of the USB C cable into your workstation.
 #. 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:

.. code:: bash

   $ 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.

109 110
.. 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.

111 112 113
Flash the Image
---------------

114 115 116 117 118
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:
119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134

 * 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:

.. code:: bash

   $ 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

135
Remove the USB C cable and hold down the power button for 15-18 seconds to reset the phone.
136 137 138 139 140 141

Your phone should now be running the latest image.

.. _`PureOS amber-updates`: https://software.pureos.net/package/bin/amber-updates/uuu

.. include:: /links.txt