.. include:: defs.txt

.. _librem_5_troubleshooting:

Troubleshooting
===============

This section describes problems that users may encounter with the phone's software and hardware. It also provides ways to diagnose these problems and some workarounds and solutions. Where problems and workarounds are specific to a particular model or iteration of the phone, this is mentioned in the relevant section.

.. contents::
   :local:

Problems common to more than one iteration of the phone's hardware are covered on this page. Problems specific to one revision will be covered on the page for that revision where appropriate.

LED Colors and Charging Problems
--------------------------------

The phone's indicator light uses different light emitting diodes (LEDs) to display different colors *during boot-up* to indicate which tasks the phone is performing and may flash to report problems. The table below explains the meaning of these colors.

+------------------+--------------------------------------------------------+
| Color            | Description                                            |
+==================+========================================================+
| Red              | The phone is charging.                                 |
+------------------+--------------------------------------------------------+
| Red (flashing)   | There is a problem with charging. |br|                 |
|                  | :ref:`See below <librem_5_troubleshooting_charging>`   |
|                  | for advice.                                            |
+------------------+--------------------------------------------------------+
| Green            | The U-Boot bootloader has started running.             |
+------------------+--------------------------------------------------------+
| Green (flashing) | A boot-loop in the bootloader. |br|                    |
|                  | :ref:`See below <librem_5_troubleshooting_boot_loop>`  |
|                  | for advice.                                            |
+------------------+--------------------------------------------------------+
| Yellow           | The bootloader has started the kernel but there is     |
|                  | insufficient power to continue. |br|                   |
|                  | :ref:`See below <librem_5_troubleshooting_kernel>`     |
|                  | for advice.                                            |
+------------------+--------------------------------------------------------+

Once the phone has started the operating system the red LED is *currently not used* to indicate charging. See the charge indicator at the top of the display for the battery status and charge level.

.. _librem_5_troubleshooting_charging:

Red
~~~

.. note:: Ensure that you use the charger supplied with the phone as this can supply 10 W of power.

A lit red indicator light with no flashing indicates that the phone is charging normally.

If the light flashes red once per second, there is a problem with the charge controller. Contact Purism support for further guidance.

.. _librem_5_troubleshooting_boot_loop:

Green
~~~~~

A flashing green light is a symptom of the bootloader starting followed by a reset as a result of insufficient power. This is usually the result of a battery charging issue. Follow the steps below to work around the problem:

 #. Hold down the Volume Up button for 5 seconds to enable trickle-charging.
 #. Once the light stops flashing, unplug then replug the power supply.
 #. Let the battery charge for an hour or more.
 #. Unplug the USB cable from the phone.
 #. Hold down the power button for 15 seconds.
 #. The light should appear green.
 #. Plug in the USB charging cable.

If the above steps do not help, try the steps in the :ref:`librem_5_troubleshooting_recharging` section below.

.. _librem_5_troubleshooting_kernel:

Yellow
~~~~~~

If the light is yellow, the bootloader is trying to load the kernel but has already determined that there is insufficient power to succeed for one of the following reasons:

 * The battery voltage is low and the USB C cable was not plugged in before the bootloader ran the USB power check.
 * The battery voltage is low and so is the USB charging current.
 * The battery voltage is zero and the USB current is too low.

Try disabling the modem and WLAN by pushing their kill switches in the down positions, towards the center of the phone.

Follow the charging procedure in the :ref:`librem_5_troubleshooting_recharging` section below.

.. _librem_5_troubleshooting_recharging:

Recharging Procedure
~~~~~~~~~~~~~~~~~~~~

.. note:: This is only relevant to phones from the Birch shipment.

This procedure should charge the phone if the battery is not providing enough current:

 #. Unplug the phone from the power supply.
 #. Press the Volume Up button and hold it.
 #. Press and hold the power button for 16 seconds while keeping the Volume Up button held.
 #. After 16 seconds has passed, release the power button.
 #. Wait 1 second then release the Volume Up button.
 #. Plug in the provided USB C charger into the phone.
 #. The indicator light should be red. |br|
    If the light is red then the battery is charging. Continue to step 8. |br|
    If the light remains off, try repeating steps 1-6.
 #. When the red light turns off the battery is fully charged.
 #. After the red light turns off, unplug the charger, then press and hold the power button for 15 to 18 seconds until you see a green light.
 #. Release the power button and the phone should boot up.

There should be no need to remove the battery to perform this sequence of steps.

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 process is described in the `Reflashing the Phone`_ section of the `Librem 5 Developer Documentation`_.
