Fuel Gauges (Experimental API Stub Doc)¶
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 using a client allocated array of fuel_gauge_get_property
. This
array is then populated by values as according to its property_type field.
Caching¶
The Fuel Gauge API explicitly provides no caching for its clients.
API Reference¶
- group fuel_gauge_interface
Fuel Gauge Interface.
Defines
-
FUEL_GAUGE_AVG_CURRENT¶
Runtime Dynamic Battery Parameters Provide a 1 minute average of the current on the battery. Does not check for flags or whether those values are bad readings. See driver instance header for details on implementation and how the average is calculated. Units in uA negative=discharging
-
FUEL_GAUGE_CURRENT¶
Battery current (uA); negative=discharging
-
FUEL_GAUGE_CHARGE_CUTOFF¶
Whether the battery underlying the fuel-gauge is cut off from charge
-
FUEL_GAUGE_CYCLE_COUNT¶
Cycle count in 1/100ths (number of charge/discharge cycles)
-
FUEL_GAUGE_CONNECT_STATE¶
Connect state of battery
-
FUEL_GAUGE_FLAGS¶
General Error/Runtime Flags
-
FUEL_GAUGE_FULL_CHARGE_CAPACITY¶
Full Charge Capacity in uAh (might change in some implementations to determine wear)
-
FUEL_GAUGE_PRESENT_STATE¶
Is the battery physically present
-
FUEL_GAUGE_REMAINING_CAPACITY¶
Remaining capacity in uAh
-
FUEL_GAUGE_RUNTIME_TO_EMPTY¶
Remaining battery life time in minutes
-
FUEL_GAUGE_RUNTIME_TO_FULL¶
Remaining time in minutes until battery reaches full charge
-
FUEL_GAUGE_SBS_MFR_ACCESS¶
Retrieve word from SBS1.1 ManufactuerAccess
-
FUEL_GAUGE_STATE_OF_CHARGE¶
Absolute state of charge (percent, 0-100) - expressed as % of design capacity
-
FUEL_GAUGE_TEMPERATURE¶
Temperature in 0.1 K
-
FUEL_GAUGE_VOLTAGE¶
Battery voltage (uV)
-
FUEL_GAUGE_COMMON_COUNT¶
Reserved to demark end of common fuel gauge properties
-
FUEL_GAUGE_CUSTOM_BEGIN¶
Reserved to demark downstream custom properties - use this value as the actual value may change over future versions of this API
-
FUEL_GAUGE_PROP_MAX¶
Reserved to demark end of valid enum properties
Typedefs
-
typedef int (*fuel_gauge_get_property_t)(const struct device *dev, struct fuel_gauge_get_property *props, size_t props_len)¶
Fetch a battery fuel-gauge property.
- Param dev:
Pointer to the battery fuel-gauge device
- Param props:
pointer to array of fuel_gauge_get_property struct where the property struct field is set by the caller to determine what property is read from the fuel gauge device into the fuel_gauge_get_property struct’s value field.
- Param props_len:
number of properties in props array
- Return:
return=0 if successful, return < 0 if getting all properties failed, return > 0 if some properties failed where return=number of failing properties.
-
typedef int (*fuel_gauge_set_property_t)(const struct device *dev, struct fuel_gauge_set_property *props, size_t props_len)¶
Set a battery fuel-gauge property.
- Param dev:
Pointer to the battery fuel-gauge device
- Param props:
pointer to array of fuel_gauge_set_property struct where the property struct field is set by the caller to determine what property is written to the fuel gauge device from the fuel_gauge_get_property struct’s value field.
- Param props_len:
number of properties in props array
- Return:
return=0 if successful, return < 0 if setting all properties failed, return > 0 if some properties failed where return=number of failing properties.
-
struct fuel_gauge_get_property¶
- #include <fuel_gauge.h>
Public Members
-
uint16_t property_type¶
Battery fuel gauge property to get
-
int status¶
Negative error status set by callee e.g. -ENOTSUP for an unsupported property
-
int avg_current¶
FUEL_GAUGE_AVG_CURRENT
-
bool cutoff¶
FUEL_GAUGE_CUTOFF
-
int current¶
FUEL_GAUGE_CURRENT
-
uint32_t cycle_count¶
FUEL_GAUGE_CYCLE_COUNT
-
uint32_t flags¶
FUEL_GAUGE_FLAGS
-
uint32_t full_charge_capacity¶
FUEL_GAUGE_FULL_CHARGE_CAPACITY
-
uint32_t remaining_capacity¶
FUEL_GAUGE_REMAINING_CAPACITY
-
uint32_t runtime_to_empty¶
FUEL_GAUGE_RUNTIME_TO_EMPTY
-
uint32_t runtime_to_full¶
FUEL_GAUGE_RUNTIME_TO_FULL
-
uint16_t sbs_mfr_access_word¶
FUEL_GAUGE_SBS_MFR_ACCESS
-
uint8_t state_of_charge¶
FUEL_GAUGE_STATE_OF_CHARGE
-
uint16_t temperature¶
FUEL_GAUGE_TEMPERATURE
-
int voltage¶
FUEL_GAUGE_VOLTAGE
-
union fuel_gauge_get_property.[anonymous] value¶
Property field for getting
-
uint16_t property_type¶
-
struct fuel_gauge_set_property¶
- #include <fuel_gauge.h>
Public Members
-
uint16_t property_type¶
Battery fuel gauge property to set
-
int status¶
Negative error status set by callee e.g. -ENOTSUP for an unsupported property
-
uint16_t sbs_mfr_access_word¶
FUEL_GAUGE_SBS_MFR_ACCESS
-
union fuel_gauge_set_property.[anonymous] value¶
Property field for setting
-
uint16_t property_type¶
-
struct battery_driver_api¶
- #include <fuel_gauge.h>
-
FUEL_GAUGE_AVG_CURRENT¶