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

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

Add phone troubleshooting section

See merge request Librem5/developer.puri.sm!351
parents 720cdb09 1525ec43
......@@ -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
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
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.
......@@ -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
......
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