.. _fuel_gauge_api:

Fuel Gauge
##########

The fuel gauge subsystem exposes an API to uniformly access battery fuel gauge devices. Currently,
only reading data is supported.

Note: This API is currently experimental and this doc will be significantly changed as new features
are added to the API.

Basic Operation
***************

Properties
==========

Fundamentally, a property is a quantity that a fuel gauge device can measure.

Fuel gauges typically support multiple properties, such as temperature readings of the battery-pack
or present-time current/voltage.

Properties are fetched by the client one at a time using :c:func:`fuel_gauge_get_prop`, or fetched
in a batch using :c:func:`fuel_gauge_get_props`.

Properties are set by the client one at a time using :c:func:`fuel_gauge_set_prop`, or set in a
batch using :c:func:`fuel_gauge_set_props`.

Battery Cutoff
==============

Many fuel gauges embedded within battery packs expose a register address that when written to with a
specific payload will do a battery cutoff. This battery cutoff is often referred to as ship, shelf,
or sleep mode due to its utility in reducing battery drain while devices are stored or shipped.

The fuel gauge API exposes battery cutoff with the :c:func:`fuel_gauge_battery_cutoff` function.

Caching
=======

The Fuel Gauge API explicitly provides no caching for its clients.


.. _fuel_gauge_api_reference:

API Reference
*************

.. doxygengroup:: fuel_gauge_interface
.. doxygengroup:: fuel_gauge_emulator_backend