Merge branch 'add-phone-troubleshooting-section' into 'master'

Add phone troubleshooting section

See merge request Librem5/developer.puri.sm!351

Development_Environment/Phone.rst

@@ -3,12 +3,9 @@
 Setting up the Phone
 ====================
 
-.. note:: This section is subject to updates and revisions prior to the phone's
-          release.
+.. note:: This section is subject to updates and revisions.
 
-This section should describe the steps needed to set up the Librem 5 phone for
-application development. This includes any preparations related to the
-hardware, such as connecting USB cables and ensuring that the phone is powered.
+This section describes the steps needed to set up the Librem 5 phone for application development. For troubleshooting advice, see the :ref:`librem_5_troubleshooting` section.
 
 Software
 --------
@@ -20,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

Development_Environment/Phone/Troubleshooting/Reflashing_the_Phone.rst

+Reflashing the Phone
+====================
+
+This guide describes how to reflash the system image on your Librem 5 phone from a workstation, using a USB C cable.
+
+.. 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

Development_Environment/Phone/Troubleshooting/Reinstalling_Core_Apps.rst

+Reinstalling Core Applications
+==============================
+
+Users are encouraged to install the software they prefer on the phone.
+
+If you accidentally uninstall the core applications on the phone, perhaps as a result of installing alternative or additional software, you can reinstall them from a terminal with the following command:
+
+.. code:: bash
+
+   sudo apt install librem5-gnome-base
+
+This will ask for confirmation before reinstalling the core apps. It may also uninstall any problematic software that caused the core apps to be uninstalled in the first place.

links.txt

@@ -104,6 +104,7 @@
 .. _HdyTitleBar : https://developer.puri.sm/projects/libhandy/unstable/HdyTitleBar.html
 .. _`How to create a GTK application using Python`: https://belmoussaoui.com/2019/05/13/how-to-create-a-gtk-application-using-python-part-1/
 .. _`iio-sensor-proxy`: https://github.com/hadess/iio-sensor-proxy
+.. _`Image Builds`: https://arm01.puri.sm/job/Images/job/Image%20Build/
 .. _`journalctl man page`: https://www.freedesktop.org/software/systemd/man/journalctl.html
 .. _`KDE Community`: https://www.kde.org
 .. _`KDE project`: https://www.kde.org
@@ -158,6 +159,7 @@
 .. _`Scalable Vector Graphics`: https://www.w3.org/TR/SVG/
 .. _`Sidebar lists`: https://developer.gnome.org/hig/stable/sidebar-lists.html.en
 .. _`Squeekboard`: https://source.puri.sm/Librem5/squeekboard
+.. _`U-Boot Librem 5 Builds`: https://arm01.puri.sm/job/u-boot_builds/job/uboot_librem5_build/
 .. _`Using GtkApplication`: https://developer.gnome.org/GtkApplication/
 .. _`Using GSettings`: https://developer.gnome.org/GSettings/
 .. _`Virtboard`: https://source.puri.sm/Librem5/virtboard/blob/master/README.md