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

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

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 battery_driver_api

#include <fuel_gauge.h>