nRF Fuel Gauge library

Algorithm for battery state-of-charge estimation ("fuel gauge"). More...

Data Structures
struct	battery_model
	Secondary cell (rechargeable) battery model parameters. More...
struct	battery_model_primary
	Primary cell (non-rechargeable) battery model parameters. More...
struct	nrf_fuel_gauge_state_info
	Library state information. Useful for debugging. More...
struct	nrf_fuel_gauge_config_parameters
	Configuration parameters. More...
struct	nrf_fuel_gauge_init_parameters
	Library init parameter struct. More...
union	nrf_fuel_gauge_ext_state_info_data
	State info data type used for additional information. More...

Macros
#define	NRF_FUEL_GAUGE_DEFAULT_INIT_PARAMETERS_PRIMARY(_v0, _i0, _t0, _battery_model)
	Helper macro to get basic initialization parameters for primary cell variant.
#define	NRF_FUEL_GAUGE_DEFAULT_INIT_PARAMETERS_SECONDARY(_v0, _i0, _t0, _battery_model)
	Helper macro to get basic initialization parameters for secondary cell variant.

Enumerations
enum	nrf_fuel_gauge_variant_type { NRF_FUEL_GAUGE_VARIANT_PRIMARY , NRF_FUEL_GAUGE_VARIANT_SECONDARY }
enum	nrf_fuel_gauge_charge_state {   NRF_FUEL_GAUGE_CHARGE_STATE_IDLE , NRF_FUEL_GAUGE_CHARGE_STATE_TRICKLE , NRF_FUEL_GAUGE_CHARGE_STATE_CC , NRF_FUEL_GAUGE_CHARGE_STATE_CC_LIMITED ,   NRF_FUEL_GAUGE_CHARGE_STATE_CV , NRF_FUEL_GAUGE_CHARGE_STATE_COMPLETE }
	Charger state enum. More...
enum	nrf_fuel_gauge_ext_state_info_type {   NRF_FUEL_GAUGE_EXT_STATE_INFO_VBUS_CONNECTED , NRF_FUEL_GAUGE_EXT_STATE_INFO_VBUS_DISCONNECTED , NRF_FUEL_GAUGE_EXT_STATE_INFO_CHARGE_STATE_CHANGE , NRF_FUEL_GAUGE_EXT_STATE_INFO_CHARGE_CURRENT_CORRECTION ,   NRF_FUEL_GAUGE_EXT_STATE_INFO_DISCHARGE_CURRENT_CORRECTION , NRF_FUEL_GAUGE_EXT_STATE_INFO_CHARGE_CURRENT_LIMIT , NRF_FUEL_GAUGE_EXT_STATE_INFO_TERM_CURRENT , NRF_FUEL_GAUGE_EXT_STATE_INFO_BATTERY_REPLACED }
	State info type used for informing the library of external factors and events. More...

Functions
int	nrf_fuel_gauge_config_params_default_get (struct nrf_fuel_gauge_config_parameters *params)
	Initialize configuration parameter structure to default values.
int	nrf_fuel_gauge_config_params_current_get (struct nrf_fuel_gauge_config_parameters *params)
	Initialize configuration parameter structure to the currently used values.
int	nrf_fuel_gauge_state_compatible_check (const void *state, size_t state_size)
	Check if the provided state is compatible with the current library version.
int	nrf_fuel_gauge_init (const struct nrf_fuel_gauge_init_parameters *parameters, float *v0)
	Initialize the nRF Fuel Gauge library.
int	nrf_fuel_gauge_process (float v, float i, float T, float t_delta, float *soc, struct nrf_fuel_gauge_state_info *state)
	Process battery measurement values.
int	nrf_fuel_gauge_soc_get (float *soc)
	Get predicted state-of-charge value.
int	nrf_fuel_gauge_tte_get (float *tte)
	Get predicted "time-to-empty" discharge duration.
int	nrf_fuel_gauge_ttf_get (float *ttf)
	Get predicted "time-to-full" charging duration.
int	nrf_fuel_gauge_soh_get (float *soh)
	Get predicted battery state-of-health (SOH) as a percentage of modeled battery capacity.
int	nrf_fuel_gauge_idle_set (float v, float T, float i_avg)
	Put library into the idle state.
int	nrf_fuel_gauge_state_get (void *state, size_t size)
	Retrieve library state data.
int	nrf_fuel_gauge_ext_state_update (enum nrf_fuel_gauge_ext_state_info_type type, union nrf_fuel_gauge_ext_state_info_data *data)
	Optional function to inform library of external events and factors.
int	nrf_fuel_gauge_config_params_adjust (const struct nrf_fuel_gauge_config_parameters *params)
	Update configuraton parameters.

Variables
const char *	nrf_fuel_gauge_version
	Version number of nRF Fuel Gauge library in format "x.y.z".
const char *	nrf_fuel_gauge_build_date
	Build date of nRF Fuel Gauge library.
enum nrf_fuel_gauge_variant_type	nrf_fuel_gauge_variant
	Build variant of nRF Fuel Gauge library.
const size_t	nrf_fuel_gauge_state_size
	Size of the internal state memory used by nRF Fuel Gauge library.

Detailed Description

Algorithm for battery state-of-charge estimation ("fuel gauge").

The algorithm determines the predicted state-of-charge (SOC) based on the following data: specific model of the battery type used in the application along with measurements of battery voltage, current, and temperature. The SOC is a value between 0% and 100%.

The algorithm can dynamically make an assessment of the battery state-of-health (SOH) for secondary cell batteries. SOH is a percentage value of the modelled battery capacity. A new battery is expected to have a SOH value close to 100%. As the battery ages, the SOH value will decrease.

The SOH estimation is based on observing full charge cycles, and will improve over time. To facilitate the SOH estimate, the iteration rate can be increased while charging. For example to a rate around 2 Hz to 5 Hz. When nrf_fuel_gauge_config_parameters::soh_estimate_enable is set, the library will automatically estimate and apply the SOH value to the SOC estimate. The SOH estimate can be retrieved using nrf_fuel_gauge_soh_get, and overridden using nrf_fuel_gauge_config_params_adjust.

Note

As this library has two variants, make sure to use a battery model that matches the configured variant: primary cell (non-rechargeable) or secondary cell (rechargeable).

Current and voltage measurements do not have to be made at a certain interval. However, the two values should be measured as closely as possible in time.