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 fuel_gauge_get_prop(), or fetched in a batch using fuel_gauge_get_props().

Properties are set by the client one at a time using fuel_gauge_set_prop(), or set in a batch using 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 fuel_gauge_battery_cutoff() function.

Caching

The Fuel Gauge API explicitly provides no caching for its clients.

API Reference

group fuel_gauge_interface

Fuel Gauge Interface.

Since: 3.3
Version: 0.1.0

Defines

SBS_GAUGE_MANUFACTURER_NAME_MAX_SIZE: Data structures for reading SBS buffer properties.

SBS_GAUGE_DEVICE_NAME_MAX_SIZE

SBS_GAUGE_DEVICE_CHEMISTRY_MAX_SIZE

Typedefs

typedef uint16_t fuel_gauge_prop_t

typedef int (*fuel_gauge_get_property_t)(const struct device *dev, fuel_gauge_prop_t prop, union fuel_gauge_prop_val *val)

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, fuel_gauge_prop_t prop, union fuel_gauge_prop_val val)

Callback API for setting a fuel_gauge property.

See fuel_gauge_set_property() for argument description

typedef int (*fuel_gauge_get_buffer_property_t)(const struct device *dev, fuel_gauge_prop_t prop_type, void *dst, size_t dst_len)

Callback API for getting a fuel_gauge buffer property.

See fuel_gauge_get_buffer_property() for argument description

typedef int (*fuel_gauge_battery_cutoff_t)(const struct device *dev)

Callback API for doing a battery cutoff.

See fuel_gauge_battery_cutoff() for argument description

Enums

enum fuel_gauge_prop_type

Values:

enumerator FUEL_GAUGE_AVG_CURRENT = 0

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

enumerator FUEL_GAUGE_BATTERY_CUTOFF: Used to cutoff the battery from the system - useful for storage/shipping of devices.

enumerator FUEL_GAUGE_CURRENT: Battery current (uA); negative=discharging.

enumerator FUEL_GAUGE_CHARGE_CUTOFF: Whether the battery underlying the fuel-gauge is cut off from charge.

enumerator FUEL_GAUGE_CYCLE_COUNT: Cycle count in 1/100ths (number of charge/discharge cycles)

enumerator FUEL_GAUGE_CONNECT_STATE: Connect state of battery.

enumerator FUEL_GAUGE_FLAGS: General Error/Runtime Flags.

enumerator FUEL_GAUGE_FULL_CHARGE_CAPACITY: Full Charge Capacity in uAh (might change in some implementations to determine wear)

enumerator FUEL_GAUGE_PRESENT_STATE: Is the battery physically present.

enumerator FUEL_GAUGE_REMAINING_CAPACITY: Remaining capacity in uAh.

enumerator FUEL_GAUGE_RUNTIME_TO_EMPTY: Remaining battery life time in minutes.

enumerator FUEL_GAUGE_RUNTIME_TO_FULL: Remaining time in minutes until battery reaches full charge.

enumerator FUEL_GAUGE_SBS_MFR_ACCESS: Retrieve word from SBS1.1 ManufactuerAccess.

enumerator FUEL_GAUGE_ABSOLUTE_STATE_OF_CHARGE: Absolute state of charge (percent, 0-100) - expressed as % of design capacity.

enumerator FUEL_GAUGE_RELATIVE_STATE_OF_CHARGE: Relative state of charge (percent, 0-100) - expressed as % of full charge capacity.

enumerator FUEL_GAUGE_TEMPERATURE: Temperature in 0.1 K.

enumerator FUEL_GAUGE_VOLTAGE: Battery voltage (uV)

enumerator FUEL_GAUGE_SBS_MODE: Battery Mode (flags)

enumerator FUEL_GAUGE_CHARGE_CURRENT: Battery desired Max Charging Current (uA)

enumerator FUEL_GAUGE_CHARGE_VOLTAGE: Battery desired Max Charging Voltage (uV)

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

enumerator FUEL_GAUGE_DESIGN_CAPACITY: Design Capacity (mAh or 10mWh)

enumerator FUEL_GAUGE_DESIGN_VOLTAGE: Design Voltage (mV)

enumerator FUEL_GAUGE_SBS_ATRATE: AtRate (mA or 10 mW)

enumerator FUEL_GAUGE_SBS_ATRATE_TIME_TO_FULL: AtRateTimeToFull (minutes)

enumerator FUEL_GAUGE_SBS_ATRATE_TIME_TO_EMPTY: AtRateTimeToEmpty (minutes)

enumerator FUEL_GAUGE_SBS_ATRATE_OK: AtRateOK (boolean)

enumerator FUEL_GAUGE_SBS_REMAINING_CAPACITY_ALARM: Remaining Capacity Alarm (mAh or 10mWh)

enumerator FUEL_GAUGE_SBS_REMAINING_TIME_ALARM: Remaining Time Alarm (minutes)

enumerator FUEL_GAUGE_MANUFACTURER_NAME: Manufacturer of pack (1 byte length + 20 bytes data)

enumerator FUEL_GAUGE_DEVICE_NAME: Name of pack (1 byte length + 20 bytes data)

enumerator FUEL_GAUGE_DEVICE_CHEMISTRY: Chemistry (1 byte length + 4 bytes data)

enumerator FUEL_GAUGE_COMMON_COUNT: Reserved to demark end of common fuel gauge properties.

enumerator 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.

enumerator FUEL_GAUGE_PROP_MAX = UINT16_MAX: Reserved to demark end of valid enum properties.

Functions

int fuel_gauge_get_prop(const struct device *dev, fuel_gauge_prop_t prop, union fuel_gauge_prop_val *val)

Fetch a battery fuel-gauge property.

Parameters:

dev – Pointer to the battery fuel-gauge device
prop – Type of property to be fetched from device
val – pointer to a union fuel_gauge_prop_val where the property is read into from the fuel gauge device.

Returns:

0 if successful, negative errno code if failure.

int fuel_gauge_get_props(const struct device *dev, fuel_gauge_prop_t *props, union fuel_gauge_prop_val *vals, size_t len)

Fetch multiple battery fuel-gauge properties.

The default implementation is the same as calling fuel_gauge_get_prop() multiple times. A driver may implement the get_properties field of the fuel gauge driver APIs struct to override this implementation.

Parameters:

dev – Pointer to the battery fuel-gauge device
props – Array of the type of property to be fetched from device, each index corresponds to the same index of the vals input array.
vals – Pointer to array of union fuel_gauge_prop_val where the property is read into from the fuel gauge device. The vals array is not permuted.
len – number of properties in props & vals array

Returns:

0 if successful, negative errno code of first failing property

int fuel_gauge_set_prop(const struct device *dev, fuel_gauge_prop_t prop, union fuel_gauge_prop_val val)

Set a battery fuel-gauge property.

Parameters:

dev – Pointer to the battery fuel-gauge device
prop – Type of property that’s being set
val – Value to set associated prop property.

Returns:

0 if successful, negative errno code of first failing property

int fuel_gauge_set_props(const struct device *dev, fuel_gauge_prop_t *props, union fuel_gauge_prop_val *vals, size_t len)

Set a battery fuel-gauge property.

Parameters:

dev – Pointer to the battery fuel-gauge device
props – Array of the type of property to be set, each index corresponds to the same index of the vals input array.
vals – Pointer to array of union fuel_gauge_prop_val where the property is written the fuel gauge device. The vals array is not permuted.
len – number of properties in props array

Returns:

return=0 if successful. Otherwise, return array index of failing property.

int fuel_gauge_get_buffer_prop(const struct device *dev, fuel_gauge_prop_t prop_type, void *dst, size_t dst_len)

Fetch a battery fuel-gauge buffer property.

Parameters:

dev – Pointer to the battery fuel-gauge device
prop_type – Type of property to be fetched from device
dst – byte array or struct that will hold the buffer data that is read from the fuel gauge
dst_len – the length of the destination array in bytes

Returns:

return=0 if successful, return < 0 if getting property failed, return 0 on success

int fuel_gauge_battery_cutoff(const struct device *dev)

Have fuel gauge cutoff its associated battery.

Parameters:

dev – Pointer to the battery fuel-gauge device

Returns:

return=0 if successful and battery cutoff is now in process, return < 0 if failed to do battery cutoff.

union fuel_gauge_prop_val

#include <fuel_gauge.h>

Property field to value/type union.

Public Members

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 absolute_state_of_charge: FUEL_GAUGE_ABSOLUTE_STATE_OF_CHARGE.

uint8_t relative_state_of_charge: FUEL_GAUGE_RELATIVE_STATE_OF_CHARGE.

uint16_t temperature: FUEL_GAUGE_TEMPERATURE.

int voltage: FUEL_GAUGE_VOLTAGE.

uint16_t sbs_mode: FUEL_GAUGE_SBS_MODE.

uint32_t chg_current: FUEL_GAUGE_CHARGE_CURRENT.

uint32_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.

uint16_t sbs_remaining_capacity_alarm: FUEL_GAUGE_SBS_REMAINING_CAPACITY_ALARM.

uint16_t sbs_remaining_time_alarm: FUEL_GAUGE_SBS_REMAINING_TIME_ALARM.

struct sbs_gauge_manufacturer_name: #include <fuel_gauge.h>

struct sbs_gauge_device_name: #include <fuel_gauge.h>

struct sbs_gauge_device_chemistry: #include <fuel_gauge.h>

struct fuel_gauge_driver_api

#include <fuel_gauge.h>

Public Members

fuel_gauge_get_property_t get_property

Note: Historically this API allowed drivers to implement a custom multi-get/set property function, this was added so drivers could potentially optimize batch read with their specific chip.

However, it was removed because of no existing concrete case upstream. If this need is demonstrated, we can add this back in as an API field.

group fuel_gauge_emulator_backend

Fuel gauge backend emulator APIs.

Functions

int emul_fuel_gauge_set_battery_charging(const struct emul *target, uint32_t uV, int uA)

Set charging for fuel gauge associated battery.

Set how much the battery associated with a fuel gauge IC is charging or discharging. Where voltage is always positive and a positive or negative current denotes charging or discharging, respectively.

Parameters:

target – Pointer to the emulator structure for the fuel gauge emulator instance.
uV – Microvolts describing the battery voltage.
uA – Microamps describing the battery current where negative is discharging.

Return values:

0 – If successful.
-EINVAL – if mV or mA are 0.

int emul_fuel_gauge_is_battery_cutoff(const struct emul *target, bool *cutoff)

Check if the battery has been cut off.

Parameters:

target – Pointer to the emulator structure for the fuel gauge emulator instance.
cutoff – Pointer to bool storing variable.

Return values:

0 – If successful.
-ENOTSUP – if not supported by emulator.