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

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

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

Callback API for getting a fuel_gauge buffer property.

See fuel_gauge_get_buffer_property() for argument description

Enums

enum fuel_gauge_property

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_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 (mA)

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

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, 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. The props array maintains the same order of properties as it was given.
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.

int fuel_gauge_get_buffer_prop(const struct device *dev, struct fuel_gauge_get_buffer_property *prop, void *dst, size_t dst_len)

Fetch a battery fuel-gauge buffer property.

Parameters:

dev – Pointer to the battery fuel-gauge device
prop – pointer to single fuel_gauge_get_buffer_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 dst field.
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

struct fuel_gauge_get_property

#include <fuel_gauge.h>

Public Members

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

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

uint16_t sbs_remaining_capacity_alarm: FUEL_GAUGE_SBS_REMAINING_CAPACITY_ALARM

uint16_t sbs_remaining_time_alarm: FUEL_GAUGE_SBS_REMAINING_TIME_ALARM

union fuel_gauge_get_property.[anonymous] value: Property field for getting

struct fuel_gauge_set_property

#include <fuel_gauge.h>

Public Members

fuel_gauge_prop_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_remaining_capacity_alarm: FUEL_GAUGE_SBS_REMAINING_CAPACITY_ALARM

uint16_t sbs_remaining_time_alarm: FUEL_GAUGE_SBS_REMAINING_TIME_ALARM

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

#include <fuel_gauge.h>

Buffer properties are separated due to size

Public Members

fuel_gauge_prop_t property_type: Battery fuel gauge property to get

int status: Negative error status set by callee e.g. -ENOTSUP for an unsupported property

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>