.. include:: /urls.rst

.. _librem_14_battery_charging_thresholds:

Battery Charging Thresholds
===========================

The Librem 14 implements a TI BQ battery charge controller which controls the charge voltage and current and monitors the system voltage.
The Librem EC firmware manages the battery charge parameters to maximize battery longevity.


.. _librem_14_battery_user_space:

User Space Control
------------------

To control the battery charging process the `Librem EC ACPI driver <ec_acpi_dkms_>`_ exposes some files to the virtual ``sys`` filesystem at:

``/sys/class/power_supply/BAT0``

The files that contain the battery charging thresholds are in the files:

* ``charge_control_end_threshold``
* ``charge_control_start_threshold``

Thresholds are given in percent of battery capacity.
If the battery state percentage goes below the ``charge_control_start_threshold`` a new charge cycle will start and charge the battery until the charge percentage reaches ``charge_control_end_threshold``.


.. _librem_14_battery_start_stop_thresholds:

Setting Starting and Stopping Thresholds
----------------------------------------

If the battery percentage falls below the start threshold and then a new charge is started, charging will stop when the battery reaches the end threshold percentage.

.. important::

   The `end threshold always has to be higher than the start threshold <https://source.puri.sm/firmware/librem-ec/-/blob/master/src/board/purism/common/battery.c?ref_type=heads#L53>`_ (it can't even be the same value as the start threshold), or else the EC will not accept the new setting.

The starting charging threshold can be set like so:

.. code-block:: bash

  echo 40 | sudo tee /sys/class/power_supply/BAT0/charge_control_start_threshold

The ending charging threshold can be set like so:

.. code-block:: bash

  echo 95 | sudo tee /sys/class/power_supply/BAT0/charge_control_end_threshold


.. _librem_14_battery_start_stop_charging:

Manually Starting and Stopping Charge
-------------------------------------

Using the thresholds a charge cycle can be kicked off or stopped manually.
For starting set the end threshold to the desired full percentage and set the start threshold to anything higher than the current charge percentage.
For stopping set the stop threshold to something below the current battery charge percentage.

Once the charge start threshold percentage is undercut and the charger is connected, then the "should charge" flag is set and a new charge cycle starts.
The charge cycle stops once the charge end threshold is reached
Once the charge percentage is above the start threshold again, you can also stop the charge cycle by briefly pulling the charger from the system which will reset the "should charge" flag.

Examples:

Force-start a new charge cycle:

.. code-block:: bash

   echo 100 | sudo tee /sys/class/power_supply/BAT0/charge_control_end_threshold
   echo 99 | sudo tee /sys/class/power_supply/BAT0/charge_control_start_threshold

Force-stop a running charge cycle

.. important::

   The `EC will not accept a start threshold below 20% <https://source.puri.sm/firmware/librem-ec/-/blob/master/src/board/purism/common/battery.c?ref_type=heads#L37>`_.

.. code-block:: bash

   echo 20 | sudo tee /sys/class/power_supply/BAT0/charge_control_end_threshold
   echo 21 | sudo tee /sys/class/power_supply/BAT0/charge_control_start_threshold

To set more reasonable values after forcing either:

.. code-block:: bash

   echo 95 | sudo tee /sys/class/power_supply/BAT0/charge_control_end_threshold
   echo 50 | sudo tee /sys/class/power_supply/BAT0/charge_control_start_threshold