Commit dc5f9d95 authored by David Boddie's avatar David Boddie
Browse files

Reorganize phone info, add reflashing guide

parent 99ed0cb3
......@@ -17,3 +17,15 @@ A package is available that is designed to help set up a development environment
apt install librem5-dev-tools
Installing this package should cause additional packages to be installed, containing tools and resources for application development.
.. _librem_5_troubleshooting:
Troubleshooting
---------------
This section provides information for developers who need to investigate a problem with a Librem 5 phone and want to diagnose it. It contains some useful starting points for investigation and instructions for performing tasks that may be needed to help with testing.
.. toctree::
Phone/Troubleshooting/Reflashing_the_Phone
Phone/Troubleshooting/Reinstalling_Core_Apps
.. _librem_5_troubleshooting:
Troubleshooting
===============
This section provides information for developers who need to investigate a problem with a Librem 5 phone and want to diagnose it. It contains some useful starting points for investigation and instructions for performing tasks that may be needed to help with testing.
.. toctree::
Troubleshooting/Reflashing_the_Phone
Troubleshooting/Reinstalling_Core_Apps
Reflashing the Phone
====================
To erase the existing image on the internal eMMC and install a new image, you need to download the appropriate version of the ``uuu`` tool and related scripts.
This guide describes how to reflash the system image on your Librem 5 phone from a workstation, using a USB C cable.
Download the `librem5-devkit-tools`_
.. 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
---------------
You should now be ready to flash a new image. 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:
.. 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
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment