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

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.