Fuel Gauge Interface

Fuel Gauge Interface. More...

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
struct	fuel_gauge_driver_api

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
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.
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.
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.
typedef int(*	fuel_gauge_battery_cutoff_t) (const struct device *dev)
	Callback API for doing a battery cutoff.

Enumerations
enum	fuel_gauge_prop_type {   FUEL_GAUGE_AVG_CURRENT = 0 , FUEL_GAUGE_BATTERY_CUTOFF , 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_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, fuel_gauge_prop_t *props, union fuel_gauge_prop_val *vals, size_t len)
	Fetch multiple battery fuel-gauge properies.
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, fuel_gauge_prop_t *props, 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

Fuel Gauge Interface.

Since

3.3

Version

0.1.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_battery_cutoff_t

fuel_gauge_battery_cutoff_t

#include <zephyr/drivers/fuel_gauge.h>

Callback API for doing a battery cutoff.

See fuel_gauge_battery_cutoff() for argument description

fuel_gauge_get_buffer_property_t

fuel_gauge_get_buffer_property_t

#include <zephyr/drivers/fuel_gauge.h>

Callback API for getting a fuel_gauge buffer property.

See fuel_gauge_get_buffer_property() for argument description

fuel_gauge_get_property_t

fuel_gauge_get_property_t

#include <zephyr/drivers/fuel_gauge.h>

Callback API for getting a fuel_gauge property.

See fuel_gauge_get_property() for argument description

fuel_gauge_prop_t

typedef uint16_t fuel_gauge_prop_t

#include <zephyr/drivers/fuel_gauge.h>

fuel_gauge_set_property_t

fuel_gauge_set_property_t

#include <zephyr/drivers/fuel_gauge.h>

Callback API for setting a fuel_gauge property.

See fuel_gauge_set_property() for argument description

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_BATTERY_CUTOFF	Used to cutoff the battery from the system - useful for storage/shipping of devices.
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_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,
		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 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

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,
		fuel_gauge_prop_t *	props,
		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.