Merge branch '28-reviving-completely-dead-battery-is-undocumented' into 'master'

Resolve "reviving completely dead battery is undocumented"

Closes #28

See merge request !30

A_Quick_Tour.rst

@@ -7,7 +7,7 @@ A Quick Tour
 
 This guide aims to help you get started with your Librem 5 phone by giving you a quick tour of the phone software.
 
-.. contents:
+.. contents::
    :local:
 
 The first thing you need to do after switching on your phone is to unlock it.

Setup.rst

@@ -66,7 +66,7 @@ It will turn off again when the phone is fully charged.
  #. Unplug the charger from the power outlet
  #. Unplug the USB cable from the phone
 
-For troubleshooting hints and tips, see the :ref:`librem_5_troubleshooting` section.
+To troubleshoot charging issues see the :ref:`librem_5_troubleshooting` section.
 
 Power on the Phone
 ------------------
@@ -79,3 +79,5 @@ Ensure that the screen is visible. Locate the power button.
    :alt: The location of the power button
 
 Hold down the power button until the indicator light appears green. The screen will light up shortly after.
+
+If the phone fails to power on then there may be an issue with the battery. See the :ref:`librem_5_troubleshooting` section to investigate further.

Troubleshooting.rst

-.. 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 battery status is shown on the lock screen. When the screen is unlocked, the battery status is shown in the status line at the top of the screen.
-
-.. _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
-~~~~~~~~~~~~~~~~~~~~
+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. Some problems and workarounds are specific to a particular model or iteration of the phone.
 
-.. note:: This is only relevant to phones from the Birch shipment.
+Choose the model of phone you are using:
 
-This procedure should charge the phone if the battery is not providing enough current:
+.. toctree::
+   :maxdepth: 1
 
- #. 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.
+   Troubleshooting/Charging
+   Troubleshooting/Reflashing
 
-There should be no need to remove the battery to perform this sequence of steps.
+These documents provide additional information that may help to diagnose problems:
 
-Reflashing the Phone
---------------------
+.. toctree::
+   :maxdepth: 1
 
-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.
+   Troubleshooting/LEDs
 
-This process is described in the `Reflashing the Phone`_ section of the `Librem 5 Developer Documentation`_.
+.. include:: /defs.txt

Troubleshooting/Charging.rst

+Charging Problems
+=================
+
+A number of problems can prevent the phone from charging. These include a poor cable connection, insufficient power, thermal regulation issues and discharged batteries. This page describes these problems and some of the diagnostic tests that can be used to overcome them.
+
+.. contents::
+   :local:
+
+Poor Cable Connection
+---------------------
+
+Power is supplied to the phone using a USB C cable. Although this connector can be inserted into the socket on the phone in either orientation -- it can be flipped over -- some cables do not supply power in both cases. If you experience problems with charging, it can be worth flipping the plug over and inserting it into the phone in the other orientation.
+
+Discharged Battery
+------------------
+
+If the battery is completely or almost completely discharged, the phone will not be able to stay powered for long enough to manage the charging process. Follow the :ref:`librem_5_troubleshooting_recharging` described below.
+
+Other Issues
+------------
+
+Problems due to thermal regulation and insufficient power can be diagnosed by examining the LED indicator light when a power supply is connected to the phone. See :ref:`librem_5_troubleshooting_leds` for further advice.
+
+.. _librem_5_troubleshooting_recharging:
+
+Recharging Procedure
+--------------------
+
+If your phone fails to charge, or discharges while connected to a power source during use, determine which version of the phone you have then follow the appropriate steps for the model of phone you have (Birch, Chestnut or Dogwood).
+
+.. _librem_5_troubleshooting_birch_recharging:
+
+Birch
+~~~~~
+
+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 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.
+
+.. _librem_5_troubleshooting_chestnut_recharging:
+
+Chestnut
+~~~~~~~~
+
+If your phone fails to charge, or discharges while connected to a power source during use, follow these steps:
+
+ #. Unplug the phone from the power supply.
+ #. Enable all kill switches to cut power to the modem, WLAN, camera and microphone.
+ #. :ref:`Remove the battery. <librem_5_battery>`
+ #. Press the Volume Up button and hold it.
+ #. Plug the provided USB C charger into the phone.
+ #. The indicator light should be red. |br|
+    If the light remains off, try repeating steps 1-5 but with the USB-C cable plugged into the phone in the opposite orientation.
+ #. Wait 1 second then release the Volume Up button.
+
+If the red LED is blinking insert the battery while the phone is powered. The LED should remain on, and should not blink.
+
+.. _librem_5_troubleshooting_dogwood_recharging:
+
+Dogwood
+~~~~~~~
+
+If your phone fails to charge, or discharges while connected to a power source during use, follow these steps:
+
+ #. Unplug the phone from the power supply.
+ #. Enable all kill switches to cut power to the modem, WLAN, camera and microphone.
+ #. :ref:`Remove the battery. <librem_5_battery>`
+ #. Press the Volume Up button and hold it.
+ #. Plug the provided USB C charger into the phone.
+ #. The indicator light should be red. |br|
+    If the light remains off, try repeating steps 1-5 but with the USB-C cable plugged into the phone in the opposite orientation.
+ #. Wait 1 second then release the Volume Up button.
+
+If the red LED is blinking insert the battery while the phone is powered. The LED should remain on, and should not blink.
+
+.. include:: /defs.txt

Troubleshooting/LEDs.rst

+.. _librem_5_troubleshooting_leds:
+
+LED Indicator Colors
+--------------------
+
+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>`            |
+|                    | 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 (red/green) | 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 battery status is shown on the lock screen. When the screen is unlocked, the battery status is shown in the status line at the top of the screen.
+
+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 recharging procedure for your phone:
+
+ * Birch: :ref:`librem_5_troubleshooting_birch_recharging`
+ * Dogwood: :ref:`librem_5_troubleshooting_dogwood_recharging`
+
+.. _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 for your phone:
+
+ * Birch: :ref:`librem_5_troubleshooting_birch_recharging`
+ * Dogwood: :ref:`librem_5_troubleshooting_dogwood_recharging`
+
+.. include:: /defs.txt

Troubleshooting/Reflashing.rst

+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`_.
+
+.. include:: /defs.txt