API documentation
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(float i_cc, 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:
i_cc – Constant charge current [A].
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(float a, float b, float c, float d)
Update runtime parameters.
Parameter details purposefully not documented.
- Parameters:
a – New a parameter value.
b – New b parameter value.
c – New c parameter value.
d – New d parameter value.
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.
-
int nrf_fuel_gauge_init(const struct nrf_fuel_gauge_init_parameters *parameters, float *v0)