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 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_SBS_MODE: Battery Mode (flags)

FUEL_GAUGE_CHARGE_CURRENT: Battery desired Max Charging Current (mA)

FUEL_GAUGE_CHARGE_VOLTAGE: Battery desired Max Charging Voltage (mV)

FUEL_GAUGE_STATUS: Alarm, Status and Error codes (flags)

FUEL_GAUGE_DESIGN_CAPACITY: Design Capacity (mAh or 10mWh)

FUEL_GAUGE_DESIGN_VOLTAGE: Design Voltage (mV)

FUEL_GAUGE_SBS_ATRATE: AtRate (mA or 10 mW)

FUEL_GAUGE_SBS_ATRATE_TIME_TO_FULL: AtRateTimeToFull (minutes)

FUEL_GAUGE_SBS_ATRATE_TIME_TO_EMPTY: AtRateTimeToEmpty (minutes)

FUEL_GAUGE_SBS_ATRATE_OK: AtRateOK (boolean)

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)

Callback API for getting a fuel_gauge property.

See fuel_gauge_get_property() for argument description

typedef int (*fuel_gauge_set_property_t)(const struct device *dev, struct fuel_gauge_set_property *props, size_t props_len)

Callback API for setting a fuel_gauge property.

See fuel_gauge_set_property() for argument description

Functions

int fuel_gauge_get_prop(const struct device *dev, struct fuel_gauge_get_property *props, size_t props_len)

Fetch a battery fuel-gauge property.

Parameters:

dev – Pointer to the battery fuel-gauge device
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.
props_len – number of properties in props array

Returns:

return=0 if successful, return < 0 if getting all properties failed, return > 0 if some properties failed where return=number of failing properties.

int fuel_gauge_set_prop(const struct device *dev, struct fuel_gauge_set_property *props, size_t props_len)

Set a battery fuel-gauge property.

Parameters:

dev – Pointer to the battery fuel-gauge device
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.
props_len – number of properties in props array

Returns:

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_CHARGE_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

uint16_t sbs_mode: FUEL_GAUGE_SBS_MODE

uint16_t chg_current: FUEL_GAUGE_CHARGE_CURRENT

uint16_t chg_voltage: FUEL_GAUGE_CHARGE_VOLTAGE

uint16_t fg_status: FUEL_GAUGE_STATUS

uint16_t design_cap: FUEL_GAUGE_DESIGN_CAPACITY

uint16_t design_volt: FUEL_GAUGE_DESIGN_VOLTAGE

int16_t sbs_at_rate: FUEL_GAUGE_SBS_ATRATE

uint16_t sbs_at_rate_time_to_full: FUEL_GAUGE_SBS_ATRATE_TIME_TO_FULL

uint16_t sbs_at_rate_time_to_empty: FUEL_GAUGE_SBS_ATRATE_TIME_TO_EMPTY

bool sbs_at_rate_ok: FUEL_GAUGE_SBS_ATRATE_OK

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

uint16_t sbs_mode: FUEL_GAUGE_SBS_MODE

int16_t sbs_at_rate: FUEL_GAUGE_SBS_ATRATE

union fuel_gauge_set_property.[anonymous] value: Property field for setting

struct fuel_gauge_driver_api: #include <fuel_gauge.h>