battery
=======

.. py:module:: battery

.. autoapi-nested-parse::

   Hardware-independent interpretation of fuel gauge readings.



Attributes
----------

.. autoapisummary::

   battery.CHARGING
   battery.DISCHARGING
   battery.STABLE
   battery.STATE_LABELS
   battery.RATE_DEADBAND
   battery.AWAKE_EXIT_RATE
   battery.FULL_PERCENT


Functions
---------

.. autoapisummary::

   battery.charge_state
   battery.on_external_power
   battery.format_status
   battery.as_dict


Module Contents
---------------

.. py:data:: CHARGING
   :value: 'charging'


.. py:data:: DISCHARGING
   :value: 'discharging'


.. py:data:: STABLE
   :value: 'stable'


.. py:data:: STATE_LABELS

.. py:data:: RATE_DEADBAND
   :value: 0.1


.. py:function:: charge_state(rate)

   Classify a charge rate in percent per hour.


.. py:data:: AWAKE_EXIT_RATE
   :value: -1.5


.. py:data:: FULL_PERCENT
   :value: 99.0


.. py:function:: on_external_power(rate, awake=False, usb=None, percent=None)

   Whether the board runs on USB power.

   `usb` is the reading of a VBUS sense pin (see board.usb_power) and
   decides if available. Otherwise the fuel gauge decides: awake mode
   starts while the battery is charging, or while it is full (`percent`
   from FULL_PERCENT) and stable, as a full battery on USB is not
   charged. A "stable" battery below that is on battery: in the
   deep-sleep cycle the discharge is below the gauge's resolution and
   reads as 0. Once awake, the mode ends only on a clear discharge
   (AWAKE_EXIT_RATE), which awake mode on battery soon produces. The
   gauge averages over minutes, so changes show up with that delay.


.. py:function:: format_status(percent, voltage, rate)

   One-line human-readable battery status.


.. py:function:: as_dict(percent, voltage, rate)

   Battery readings as a JSON-friendly dict.