fuel_gauge.h File Reference

#include <stdint.h>

Data Structures
struct	pbl_fuel_gauge_ocv_point
	Battery state-of-charge estimation for a single Li-ion/Li-po cell. More...
struct	pbl_fuel_gauge_cell
	The cell, as its description gives it. More...
struct	pbl_fuel_gauge_config
struct	pbl_fuel_gauge_meas
	A battery measurement. Voltage and current should be sampled together. More...
struct	pbl_fuel_gauge_state
	State that survives a reboot, see pbl_fuel_gauge_state_get(). More...
struct	pbl_fuel_gauge
	Fuel gauge instance, treat as opaque. More...

Enumerations
enum	pbl_fuel_gauge_charge_state { PBL_FUEL_GAUGE_DISCHARGING , PBL_FUEL_GAUGE_CHARGING_CC , PBL_FUEL_GAUGE_CHARGING_CV , PBL_FUEL_GAUGE_CHARGE_COMPLETE }

Functions
int	pbl_fuel_gauge_init (struct pbl_fuel_gauge *fg, const struct pbl_fuel_gauge_config *config, const struct pbl_fuel_gauge_meas *meas, const struct pbl_fuel_gauge_state *saved)
	Initializes the fuel gauge.
float	pbl_fuel_gauge_update (struct pbl_fuel_gauge *fg, const struct pbl_fuel_gauge_meas *meas, float dt, enum pbl_fuel_gauge_charge_state charge_state)
	Processes a measurement taken dt seconds after the previous one.
float	pbl_fuel_gauge_soc_get (const struct pbl_fuel_gauge *fg)
int	pbl_fuel_gauge_tte_get (const struct pbl_fuel_gauge *fg, uint32_t *seconds)
int	pbl_fuel_gauge_ttf_get (const struct pbl_fuel_gauge *fg, uint32_t *seconds)
void	pbl_fuel_gauge_state_get (const struct pbl_fuel_gauge *fg, struct pbl_fuel_gauge_state *state)

---

Data Structure Documentation

pbl_fuel_gauge_ocv_point

struct pbl_fuel_gauge_ocv_point

Battery state-of-charge estimation for a single Li-ion/Li-po cell.

The library has no OS dependencies. The estimator is selected at build time; its header defines struct pbl_fuel_gauge_estimator (its parameters) and struct pbl_fuel_gauge_estimator_state. See docs/libraries/fuel_gauge/index.md.

Units are SI throughout: V, A, s, degrees Celsius, Ah. Current is positive when the battery discharges. A point of the open-circuit voltage curve.

Data Fields
float	soc	State of charge, 0 (empty) to 1 (full).
float	v	Open-circuit voltage at rest and 25 C [V].

pbl_fuel_gauge_cell

struct pbl_fuel_gauge_cell

The cell, as its description gives it.

Data Fields
float	capacity_ah	Charge between the full and the empty point at 25 C [Ah].
const struct pbl_fuel_gauge_ocv_point *	ocv	Strictly increasing in both SOC and voltage, from SOC 0 to SOC 1.
uint8_t	ocv_count
float	r0	Series resistance at 25 C [ohm].

pbl_fuel_gauge_config

struct pbl_fuel_gauge_config

Data Fields
const struct pbl_fuel_gauge_cell *	cell
const struct pbl_fuel_gauge_estimator *	estimator
float	term_current	Charger termination current [A], used for time-to-full.
float	term_voltage	Charger termination voltage [V], used for time-to-full.

pbl_fuel_gauge_meas

struct pbl_fuel_gauge_meas

A battery measurement. Voltage and current should be sampled together.

Data Fields
float	i	Current, positive when discharging [A].
float	t	Cell temperature [C].
float	v	Terminal voltage [V].

pbl_fuel_gauge_state

struct pbl_fuel_gauge_state

State that survives a reboot, see pbl_fuel_gauge_state_get().

Data Fields
float	avg_charge	Exponentially weighted charge and time for the average current.
float	avg_time
struct pbl_fuel_gauge_estimator_state	estimator
uint32_t	model_id	Checksum of the cell, the estimator and the state layout the state was produced with.
float	soc_reported	Reported SOC, see pbl_fuel_gauge_update().

pbl_fuel_gauge

struct pbl_fuel_gauge

Fuel gauge instance, treat as opaque.

Data Fields
enum pbl_fuel_gauge_charge_state	charge_state
const struct pbl_fuel_gauge_config *	config
struct pbl_fuel_gauge_meas	last
struct pbl_fuel_gauge_state	state

Enumeration Type Documentation

pbl_fuel_gauge_charge_state

enum pbl_fuel_gauge_charge_state

Enumerator
PBL_FUEL_GAUGE_DISCHARGING
PBL_FUEL_GAUGE_CHARGING_CC	Constant current, including trickle charge.
PBL_FUEL_GAUGE_CHARGING_CV
PBL_FUEL_GAUGE_CHARGE_COMPLETE	The charger terminated: the battery is full.

Function Documentation

pbl_fuel_gauge_init()

int pbl_fuel_gauge_init	(	struct pbl_fuel_gauge *	fg,
		const struct pbl_fuel_gauge_config *	config,
		const struct pbl_fuel_gauge_meas *	meas,
		const struct pbl_fuel_gauge_state *	saved
	)

Initializes the fuel gauge.

Without saved, or when saved belongs to another cell or estimator, or disagrees with the voltage by too much (another battery, or a long time without power), the SOC starts from the open-circuit voltage implied by meas.

Returns

1 when saved was used, 0 when starting from the voltage, -EINVAL for an invalid configuration.

pbl_fuel_gauge_soc_get()

float pbl_fuel_gauge_soc_get

(

const struct pbl_fuel_gauge *

fg

)

Returns

the estimated SOC, 0 to 1, without the reporting constraints.

pbl_fuel_gauge_state_get()

void pbl_fuel_gauge_state_get	(	const struct pbl_fuel_gauge *	fg,
		struct pbl_fuel_gauge_state *	state
	)

pbl_fuel_gauge_tte_get()

int pbl_fuel_gauge_tte_get	(	const struct pbl_fuel_gauge *	fg,
		uint32_t *	seconds
	)

Parameters

	fg	fuel gauge.
[out]	seconds	time until empty at the average discharge current.

Returns

0 on success, -ENODATA while charging or while the average is not settled yet.

pbl_fuel_gauge_ttf_get()

int pbl_fuel_gauge_ttf_get	(	const struct pbl_fuel_gauge *	fg,
		uint32_t *	seconds
	)

Parameters

	fg	fuel gauge.
[out]	seconds	time until the charger terminates.

Returns

0 on success, -ENODATA when not charging or not settled yet.

pbl_fuel_gauge_update()

float pbl_fuel_gauge_update	(	struct pbl_fuel_gauge *	fg,
		const struct pbl_fuel_gauge_meas *	meas,
		float	dt,
		enum pbl_fuel_gauge_charge_state	charge_state
	)

Processes a measurement taken dt seconds after the previous one.

Returns

the reported SOC [%]. Once the estimate has settled, it does not rise while discharging nor drop while charging, so corrections from the voltage are only shown when they move in the direction the battery is going.