51 lines
1.5 KiB
ReStructuredText
51 lines
1.5 KiB
ReStructuredText
.. _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
|