The latest development version of this page may be more current than this released 3.3.0 version.

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

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

struct battery_driver_api¶: #include <fuel_gauge.h>