12cbfcf397
Based on review of the similar charger driver API, it's been demonstrated from the community that embedding a per value property type when fetching properties. Separating off the property types from the property values themselves also allow an array of property types to declared as static const. Break up fuel_gauge_property struct into a fuel_gauge_prop_val union and a fuel_gauge_prop_t property type as inputs into fuel gauge API functions. Signed-off-by: Aaron Massey <aaronmassey@google.com>
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
|