API documentation

Header file: include/nrf_fuel_gauge.h
group nrf_fuel_gauge

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

Note

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.

Functions

int nrf_fuel_gauge_init(const struct nrf_fuel_gauge_init_parameters *parameters, float *v0)

Initialize the nRF Fuel Gauge library.

Parameters:

  • parameters – [in] Pointer to the parameter structure.

  • v0 – [out] Adjusted battery voltage (optional, for logging purposes).

Return values:

  • 0 – Initialization successful.

  • -22 – Initialization failed due to invalid parameters.

float nrf_fuel_gauge_process(float v, float i, float T, float t_delta, struct nrf_fuel_gauge_state_info *state)

Process battery measurement values.

Parameters:

  • v – Measured battery voltage [V].

  • i – Measured battery current [A].

  • T – Measured battery temperature [C].

  • t_delta – Time delta since previous processed measurement [s].

  • state – Pointer to state info struct (optional, set to null to ignore).

Return values:

Predicted – state-of-charge [%].

float nrf_fuel_gauge_tte_get(void)

Get predicted “time-to-empty” discharge duration.

Time-to-empty is calculated based on the discharge rate. It may be NAN.

Return values:

Predicted – time-to-empty [s].

float nrf_fuel_gauge_ttf_get(bool cc_charging, float i_term)

Get predicted “time-to-full” charging duration.

Time-to-full is calculated based on the charge rate. It may be NAN.

Parameters:

  • cc_charging – True if ongoing charging is in constant current (CC) state. Otherwise false.

  • i_term – Termination current [A].

Return values:

Predicted – time-to-full [s].

void nrf_fuel_gauge_idle_set(float v, float T, float i_avg)

Put library into the idle state.

Informing the library of idle states helps improve predictions when there are periods of low activity and no new battery measurements. If this function is not called, discharge current in low power states may be over-estimated. For example, consider a system that enters a state where only the low frequency oscillator is running to generate a wakeup sometime later. To minimize the power usage during this period, no battery measurements are made. The idle current is likely to be too low to accurately measure dynamically, but it is known ahead of time. Using this function with the expected average current will help the library more accurately predict the power drain during the idle, low-power period. When activity is resumed, use nrf_fuel_gauge_process as normal.

Note

Make sure this function is called from the same context as nrf_fuel_gauge_process.

Parameters:

  • v – Measured battery voltage in volts [V].

  • T – Measured battery temperature in centigrades [C].

  • i_avg – Expected average current in idle state in amperes [A].

void nrf_fuel_gauge_param_adjust(const struct nrf_fuel_gauge_runtime_parameters *params)

Update runtime parameters.

Parameter details purposefully not documented.

Parameters:

  • params – New parameter values.

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.

struct battery_model
#include <nrf_fuel_gauge.h>

Battery model parameters.

Parameter details purposefully not documented.

struct nrf_fuel_gauge_state_info
#include <nrf_fuel_gauge.h>

Library state information. Useful for debugging.

Public Members

float yhat

Predicted voltage.

float r0

Battery resistance.

float T_truncated

Truncated temperature. This state is used when the measured temperature falls outside the modeled range.

struct nrf_fuel_gauge_config_parameters
#include <nrf_fuel_gauge.h>

Optional static configuration parameters.

Parameter details purposefully not documented.

struct nrf_fuel_gauge_runtime_parameters
#include <nrf_fuel_gauge.h>

Optional runtime configuration parameters.

Parameter details purposefully not documented.

struct nrf_fuel_gauge_init_parameters
#include <nrf_fuel_gauge.h>

Library init parameter struct.

Public Members

float v0

Initial voltage in volts [V].

float i0

Initial current in amperes [A].

float t0

Initial temperature in centigrades [C].

const struct battery_model *model

Battery model

const struct nrf_fuel_gauge_config_parameters *opt_params

Optional configuration parameters. Set to NULL to use default values.