1.. _fuel_gauge_api:
2
3Fuel Gauge
4##########
5
6The fuel gauge subsystem exposes an API to uniformly access battery fuel gauge devices. Currently,
7only reading data is supported.
8
9Note: This API is currently experimental and this doc will be significantly changed as new features
10are added to the API.
11
12Basic Operation
13***************
14
15Properties
16==========
17
18Fundamentally, a property is a quantity that a fuel gauge device can measure.
19
20Fuel gauges typically support multiple properties, such as temperature readings of the battery-pack
21or present-time current/voltage.
22
23Properties are fetched by the client one at a time using :c:func:`fuel_gauge_get_prop`, or fetched
24in a batch using :c:func:`fuel_gauge_get_props`.
25
26Properties are set by the client one at a time using :c:func:`fuel_gauge_set_prop`, or set in a
27batch using :c:func:`fuel_gauge_set_props`.
28
29Battery Cutoff
30==============
31
32Many fuel gauges embedded within battery packs expose a register address that when written to with a
33specific payload will do a battery cutoff. This battery cutoff is often referred to as ship, shelf,
34or sleep mode due to its utility in reducing battery drain while devices are stored or shipped.
35
36The fuel gauge API exposes battery cutoff with the :c:func:`fuel_gauge_battery_cutoff` function.
37
38Caching
39=======
40
41The Fuel Gauge API explicitly provides no caching for its clients.
42
43
44.. _fuel_gauge_api_reference:
45
46API Reference
47*************
48
49.. doxygengroup:: fuel_gauge_interface
50.. doxygengroup:: fuel_gauge_emulator_backend
51