Reflashing_the_Phone.rst 4.33 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-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 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106
.. 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

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:

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

The phone needs to be put in the correct boot mode.

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

 #. Take out the battery **and** disconnect the USB C cable.
 #. While holding the Volume Up button, insert the battery.
 #. 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.

Flash the Image
---------------

107 108 109 110 111
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:
112 113 114 115 116 117 118 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

Now power cycle the phone by removing the USB C and battery. Then install the battery first before plugging in the USB C cable to a power source.

Your phone should now be running the latest image.

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

.. include:: /links.txt