Interfaces for fuel gauges. More...

Topics
	Devicetree battery helpers
	Fuel Gauge Driver Backend API
	Fuel gauge backend emulator APIs
	Fuel gauge backend emulator APIs.

Files
file	fuel_gauge.h
	Main header file for fuel gauge driver API.

Data Structures
union	fuel_gauge_prop_val
	Property field to value/type union. More...
struct	sbs_gauge_manufacturer_name
struct	sbs_gauge_device_name
struct	sbs_gauge_device_chemistry

Macros
#define	SBS_GAUGE_MANUFACTURER_NAME_MAX_SIZE 20
	Data structures for reading SBS buffer properties.
#define	SBS_GAUGE_DEVICE_NAME_MAX_SIZE 20
#define	SBS_GAUGE_DEVICE_CHEMISTRY_MAX_SIZE 4

Typedefs
typedef uint16_t	fuel_gauge_prop_t

Enumerations

enum fuel_gauge_prop_type {
FUEL_GAUGE_AVG_CURRENT = 0 , FUEL_GAUGE_CURRENT , FUEL_GAUGE_CHARGE_CUTOFF , FUEL_GAUGE_CYCLE_COUNT ,
FUEL_GAUGE_CONNECT_STATE , FUEL_GAUGE_FLAGS , FUEL_GAUGE_FULL_CHARGE_CAPACITY , FUEL_GAUGE_PRESENT_STATE ,
FUEL_GAUGE_REMAINING_CAPACITY , FUEL_GAUGE_RUNTIME_TO_EMPTY , FUEL_GAUGE_RUNTIME_TO_FULL , FUEL_GAUGE_SBS_MFR_ACCESS ,
FUEL_GAUGE_ABSOLUTE_STATE_OF_CHARGE , FUEL_GAUGE_RELATIVE_STATE_OF_CHARGE , FUEL_GAUGE_TEMPERATURE , FUEL_GAUGE_VOLTAGE ,
FUEL_GAUGE_SBS_MODE , FUEL_GAUGE_CHARGE_CURRENT , FUEL_GAUGE_CHARGE_VOLTAGE , FUEL_GAUGE_STATUS ,
FUEL_GAUGE_DESIGN_CAPACITY , FUEL_GAUGE_DESIGN_VOLTAGE , FUEL_GAUGE_SBS_ATRATE , FUEL_GAUGE_SBS_ATRATE_TIME_TO_FULL ,
FUEL_GAUGE_SBS_ATRATE_TIME_TO_EMPTY , FUEL_GAUGE_SBS_ATRATE_OK , FUEL_GAUGE_SBS_REMAINING_CAPACITY_ALARM , FUEL_GAUGE_SBS_REMAINING_TIME_ALARM ,
FUEL_GAUGE_MANUFACTURER_NAME , FUEL_GAUGE_DEVICE_NAME , FUEL_GAUGE_DEVICE_CHEMISTRY , FUEL_GAUGE_CURRENT_DIRECTION ,
FUEL_GAUGE_STATE_OF_CHARGE_ALARM , FUEL_GAUGE_LOW_VOLTAGE_ALARM , FUEL_GAUGE_HIGH_VOLTAGE_ALARM , FUEL_GAUGE_LOW_CURRENT_ALARM ,
FUEL_GAUGE_HIGH_CURRENT_ALARM , FUEL_GAUGE_LOW_TEMPERATURE_ALARM , FUEL_GAUGE_HIGH_TEMPERATURE_ALARM , FUEL_GAUGE_LOW_GPIO_ALARM ,
FUEL_GAUGE_HIGH_GPIO_ALARM , FUEL_GAUGE_GPIO_VOLTAGE , FUEL_GAUGE_ADC_MODE , FUEL_GAUGE_CC_CONFIG ,
FUEL_GAUGE_STATE_OF_HEALTH , FUEL_GAUGE_THERM_VOLTAGE_UV , FUEL_GAUGE_COMMON_COUNT , FUEL_GAUGE_CUSTOM_BEGIN ,
FUEL_GAUGE_PROP_MAX = UINT16_MAX
}

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.
int	fuel_gauge_get_props (const struct device dev, const fuel_gauge_prop_t props, union fuel_gauge_prop_val *vals, size_t len)
	Fetch multiple battery fuel-gauge properties.
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.
int	fuel_gauge_set_props (const struct device dev, const fuel_gauge_prop_t props, const union fuel_gauge_prop_val *vals, size_t len)
	Set a battery fuel-gauge 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.
int	fuel_gauge_battery_cutoff (const struct device *dev)
	Have fuel gauge cutoff its associated battery.

Detailed Description

Interfaces for fuel gauges.

Since: 3.3

Version: 0.8.0

Macro Definition Documentation

◆ SBS_GAUGE_DEVICE_CHEMISTRY_MAX_SIZE

#define SBS_GAUGE_DEVICE_CHEMISTRY_MAX_SIZE 4

#include <zephyr/drivers/fuel_gauge.h>

◆ SBS_GAUGE_DEVICE_NAME_MAX_SIZE

#define SBS_GAUGE_DEVICE_NAME_MAX_SIZE 20

#include <zephyr/drivers/fuel_gauge.h>

◆ SBS_GAUGE_MANUFACTURER_NAME_MAX_SIZE

#define SBS_GAUGE_MANUFACTURER_NAME_MAX_SIZE 20

#include <zephyr/drivers/fuel_gauge.h>

Data structures for reading SBS buffer properties.

Typedef Documentation

◆ fuel_gauge_prop_t

typedef uint16_t fuel_gauge_prop_t

#include <zephyr/drivers/fuel_gauge.h>

Enumeration Type Documentation

◆ fuel_gauge_prop_type

enum fuel_gauge_prop_type

#include <zephyr/drivers/fuel_gauge.h>

Enumerator
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_ABSOLUTE_STATE_OF_CHARGE	Absolute state of charge (percent, 0-100) - expressed as % of design capacity.
FUEL_GAUGE_RELATIVE_STATE_OF_CHARGE	Relative state of charge (percent, 0-100) - expressed as % of full charge 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 (uA).
FUEL_GAUGE_CHARGE_VOLTAGE	Battery desired Max Charging Voltage (uV).
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_SBS_REMAINING_CAPACITY_ALARM	Remaining Capacity Alarm (mAh or 10mWh).
FUEL_GAUGE_SBS_REMAINING_TIME_ALARM	Remaining Time Alarm (minutes).
FUEL_GAUGE_MANUFACTURER_NAME	Manufacturer of pack (1 byte length + 20 bytes data).
FUEL_GAUGE_DEVICE_NAME	Name of pack (1 byte length + 20 bytes data).
FUEL_GAUGE_DEVICE_CHEMISTRY	Chemistry (1 byte length + 4 bytes data).
FUEL_GAUGE_CURRENT_DIRECTION	Battery current direction (flags).
FUEL_GAUGE_STATE_OF_CHARGE_ALARM	Remaining state of charge alarm (percent, 0-100).
FUEL_GAUGE_LOW_VOLTAGE_ALARM	Low Cell Voltage Alarm (uV).
FUEL_GAUGE_HIGH_VOLTAGE_ALARM	High Cell Voltage Alarm (uV).
FUEL_GAUGE_LOW_CURRENT_ALARM	Low Cell Current Alarm (uA).
FUEL_GAUGE_HIGH_CURRENT_ALARM	High Cell Current Alarm (uA).
FUEL_GAUGE_LOW_TEMPERATURE_ALARM	Low Cell Temperature Alarm (dK).
FUEL_GAUGE_HIGH_TEMPERATURE_ALARM	High Cell Temperature Alarm (dK).
FUEL_GAUGE_LOW_GPIO_ALARM	Low GPIO Voltage Alarm (uV).
FUEL_GAUGE_HIGH_GPIO_ALARM	High GPIO Voltage Alarm (uV).
FUEL_GAUGE_GPIO_VOLTAGE	GPIO Voltage (uV).
FUEL_GAUGE_ADC_MODE	ADC Mode (flags).
FUEL_GAUGE_CC_CONFIG	Coulomb Counter Config (flags).
FUEL_GAUGE_STATE_OF_HEALTH	State of Health (SoH) (percent, 0-100).
FUEL_GAUGE_THERM_VOLTAGE_UV	Thermistor Voltage Sense reading (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.

Function Documentation

◆ fuel_gauge_battery_cutoff()

int fuel_gauge_battery_cutoff ( const struct device * dev )

#include <zephyr/drivers/fuel_gauge.h>

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.

◆ fuel_gauge_get_buffer_prop()

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

#include <zephyr/drivers/fuel_gauge.h>

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

◆ fuel_gauge_get_prop()

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

#include <zephyr/drivers/fuel_gauge.h>

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.

◆ fuel_gauge_get_props()

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

#include <zephyr/drivers/fuel_gauge.h>

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

◆ fuel_gauge_set_prop()

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

#include <zephyr/drivers/fuel_gauge.h>

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

◆ fuel_gauge_set_props()

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

#include <zephyr/drivers/fuel_gauge.h>

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.

Topics

Files

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ SBS_GAUGE_DEVICE_CHEMISTRY_MAX_SIZE

◆ SBS_GAUGE_DEVICE_NAME_MAX_SIZE

◆ SBS_GAUGE_MANUFACTURER_NAME_MAX_SIZE

Typedef Documentation

◆ fuel_gauge_prop_t

Enumeration Type Documentation

◆ fuel_gauge_prop_type

Function Documentation

◆ fuel_gauge_battery_cutoff()

◆ fuel_gauge_get_buffer_prop()

◆ fuel_gauge_get_prop()

◆ fuel_gauge_get_props()

◆ fuel_gauge_set_prop()

◆ fuel_gauge_set_props()