nrf_fuel_gauge: Update nrf_fuel_gauge to v1.0.0

Update nrf_fuel_gauge to v1.0.0, which adds support for
primary cell batteries, and brings other improvements.

Signed-off-by: Audun Korneliussen <[email protected]>

nrf_fuel_gauge/CHANGELOG.rst

@@ -9,6 +9,32 @@ Changelog
 
 All notable changes to this project are documented on this page.
 
+Main branch
+***********
+
+Changes
+=======
+
+* Updated to library version 1.0.0.
+* Simplified the :c:func:`nrf_fuel_gauge_process` function, as vbus state information is now gathered through the :c:func:`nrf_fuel_gauge_ext_state_update` function.
+* Simplified the :c:func:`nrf_fuel_gauge_ttf_get` function, as charger state information is now gathered through the :c:func:`nrf_fuel_gauge_ext_state_update` function.
+* Simplified the use of the :c:func:`nrf_fuel_gauge_param_adjust` function by allowing parameters to be set to "nan" to indicate that they should not be adjusted.
+
+Added
+=====
+
+* Support for primary cell (non-recheargable) batteries.
+* Battery models for Alkaline AA, Alkaline AAA, Alkaline coin cell LR44, and Lithium-manganese dioxide coin cell CR2032 batteries.
+* A new :c:func:`nrf_fuel_gauge_ext_state_update` function to inform the library about external state changes.
+  Such changes includes charger state, vbus connection status, and current measurement correction.
+* A functionality to retrieve and restore the library state, using the :c:func:`nrf_fuel_gauge_state_get` function and state member of the :c:struct:`nrf_fuel_gauge_init_parameters` structure.
+* A new member in the :c:struct:`nrf_fuel_gauge_state_info` structure to determine the current measurement value used after corrections.
+* A new member in the :c:struct:`nrf_fuel_gauge_state_info` structure to determine the state-of-charge value before it is rounded off.
+  The rounding off only applies to primary cell batteries.
+* A new member in the :c:struct:`nrf_fuel_gauge_state_info` structure to determine the state-of-charge value before it is rounded off.
+  The rounding off only applies to primary cell batteries.
+* New undocumented members in the :c:struct:`nrf_fuel_gauge_config_parameters` structure, intended for future adjustability.
+
 nRF Connect SDK v2.8.0
 **********************
 

nrf_fuel_gauge/CMakeLists.txt

@@ -15,4 +15,11 @@ if(NOT EXISTS ${NRF_FUEL_GAUGE_DIR})
 endif()
 
 zephyr_include_directories(include)
-target_link_libraries(app PRIVATE ${NRF_FUEL_GAUGE_DIR}/libnrf_fuel_gauge.a)
+
+if(CONFIG_NRF_FUEL_GAUGE_VARIANT_PRIMARY_CELL)
+  target_link_libraries(app PRIVATE ${NRF_FUEL_GAUGE_DIR}/libnrf_fuel_gauge_primary.a)
+elseif(CONFIG_NRF_FUEL_GAUGE_VARIANT_SECONDARY_CELL)
+  target_link_libraries(app PRIVATE ${NRF_FUEL_GAUGE_DIR}/libnrf_fuel_gauge.a)
+else()
+  message(FATAL_ERROR "Invalid nRF Fuel Gauge variant selection")
+endif()

nrf_fuel_gauge/Kconfig

@@ -7,3 +7,19 @@
 config NRF_FUEL_GAUGE
 	bool "Enable nRF Fuel Gauge library"
 	select REQUIRES_FULL_LIBC
+
+if NRF_FUEL_GAUGE
+
+choice NRF_FUEL_GAUGE_VARIANT
+	prompt "nRF Fuel Gauge variant"
+	default NRF_FUEL_GAUGE_VARIANT_SECONDARY_CELL
+
+config NRF_FUEL_GAUGE_VARIANT_PRIMARY_CELL
+	bool "Primary cell"
+
+config NRF_FUEL_GAUGE_VARIANT_SECONDARY_CELL
+	bool "Secondary cell"
+
+endchoice
+
+endif # NRF_FUEL_GAUGE

nrf_fuel_gauge/README.rst

@@ -10,7 +10,10 @@ nRF Fuel Gauge library
 nRF Fuel Gauge processes battery measurements made by Power Management ICs (PMICs) and provides a state-of-charge (SOC) prediction, along with other metrics.
 The library is meant for use with devices from the Nordic nPM Family of PMICs.
 For the most accurate results, use a battery model that matches the battery used in the product.
-A battery model can be derived using the nPM Powerup App in `nRF Connect for Desktop`_ and `nPM1300 Evaluation Kit`_.
+
+The library supports primary cell (non-rechargeable) and secondary cell (rechargeable) batteries.
+Several primary cell battery models are included in the library, such as Alkaline AA, Alkaline AAA, Alkaline coin cell LR44, and Lithium-manganese dioxide coin cell CR2032 batteries.
+Secondary cell battery models can be derived using the nPM Powerup App in `nRF Connect for Desktop`_ and `nPM1300 Evaluation Kit`_.
 
 See :ref:`fuel_gauge_api` for detailed usage.
 

nrf_fuel_gauge/include/nrf_fuel_gauge.h

@@ -23,18 +23,29 @@
  * measurements of battery voltage, current, and temperature.
  * The SOC is a value between 0% and 100%.
  *
+ * @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).
+ *
  * @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.
  */
 
 #include <stdbool.h>
+#include <stdint.h>
 #include <stddef.h>
 
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+enum nrf_fuel_gauge_variant_type {
+	/** Primary cell (non-rechargeable) battery variant. */
+	NRF_FUEL_GAUGE_VARIANT_PRIMARY,
+	/** Secondary cell (rechargeable) battery variant. */
+	NRF_FUEL_GAUGE_VARIANT_SECONDARY,
+};
+
 /**
  * @brief Version number of nRF Fuel Gauge library in format "x.y.z".
  */
@@ -45,6 +56,16 @@ extern const char *nrf_fuel_gauge_version;
  */
 extern const char *nrf_fuel_gauge_build_date;
 
+/**
+ * @brief Build variant of nRF Fuel Gauge library.
+ */
+extern const enum nrf_fuel_gauge_variant_type nrf_fuel_gauge_variant;
+
+/**
+ * @brief Size of the internal state memory used by nRF Fuel Gauge library.
+ */
+extern const size_t nrf_fuel_gauge_state_size;
+
 /**
  * @brief Secondary cell (rechargeable) battery model parameters.
  *
@@ -67,6 +88,31 @@ struct battery_model {
 	char name[64];
 };
 
+/**
+ * @brief Primary cell (non-rechargeable) battery model parameters.
+ *
+ * @details Parameter details purposefully not documented.
+ */
+struct battery_model_primary {
+	float param_4[201];
+	float param_3[201];
+	float param_1[201];
+	float param_5[201];
+	float param_6[201];
+	float param_2[88];
+	float param_8[88];
+	float param_7[88];
+	float param_13[201];
+	float param_14[201];
+	float param_12;
+	float param_15;
+	float param_16;
+	signed char param_17[20];
+	float param_18[2];
+	float param_19;
+	char name[64];
+};
+
 /**
  * @brief Library state information. Useful for debugging.
  */
@@ -79,6 +125,10 @@ struct nrf_fuel_gauge_state_info {
 	 * the modeled range.
 	 */
 	float T_truncated;
+	/** Corrected battery current. */
+	float i_corrected;
+	/** Raw state-of-charge value, not rounded off. */
+	float soc_raw;
 };
 
 /**
@@ -94,9 +144,12 @@ struct nrf_fuel_gauge_config_parameters {
 	float neta3;
 	float beta1;
 	float beta2;
-	/**@brief Minimum duration of battery charge/discharge before TTE becomes available [s] */
+	float gating;
+	float volt_drop;
+	uint8_t vk_buffer_length;
+	/* Minimum duration of battery charge/discharge before TTE becomes available [s] */
 	float tte_min_time;
-	/**@brief Reset threshold for TTE calculation. If short-term state-of-charge gradient differs
+	/* Reset threshold for TTE calculation. If short-term state-of-charge gradient differs
 	 * from the long-term state-of-charge by this factor or more, the TTE state is reset.
 	 */
 	float tte_reset_threshold;
@@ -108,10 +161,17 @@ struct nrf_fuel_gauge_config_parameters {
  * @details Parameter details purposefully not documented.
  */
 struct nrf_fuel_gauge_runtime_parameters {
+	/* Set to NAN to ignore. */
 	float a;
+	/* Set to NAN to ignore. */
 	float b;
+	/* Set to NAN to ignore. */
 	float c;
+	/* Set to NAN to ignore. */
 	float d;
+	/* Primary cell: when true, do not let state-of-charge increase.
+	 * Secondary cell: parameter not used.
+	 */
 	bool discard_positive_deltaz;
 };
 
@@ -126,26 +186,99 @@ struct nrf_fuel_gauge_init_parameters {
 	/** Initial temperature in centigrades [C]. */
 	float t0;
 	/** Pointer to static battery model. The model is not copied and must be kept valid. */
-	const struct battery_model *model;
+	union {
+		/** Secondary cell battery model, when using secondary cell variant of library. */
+		const struct battery_model *model;
+		/** Primary cell battery model, when using primary cell variant of library. */
+		const struct battery_model_primary *model_primary;
+	};
 	/** Optional configuration parameters. Set to NULL to use default values. */
 	const struct nrf_fuel_gauge_config_parameters *opt_params;
+	/** Optional state memory, previously retrieved using @ref nrf_fuel_gauge_state_get.
+	 *  When used, fuel gauge resumes from this state, and all other parameters are ignored.
+	 *  Set to NULL when not used.
+	 */
+	const void *state;
+};
+
+/**
+ * @brief Charger state enum.
+ *
+ * @details The library uses this (optional) information to improve predictions.
+ *
+ * @note Time-to-full (TTF) prediction requires this information.
+ */
+enum nrf_fuel_gauge_charge_state {
+	/** Charger not active. */
+	NRF_FUEL_GAUGE_CHARGE_STATE_IDLE,
+	/** Trickle charging. */
+	NRF_FUEL_GAUGE_CHARGE_STATE_TRICKLE,
+	/** Constant current charging at charger current limit. */
+	NRF_FUEL_GAUGE_CHARGE_STATE_CC,
+	/** Constant current charging, limited by vbus. */
+	NRF_FUEL_GAUGE_CHARGE_STATE_CC_VBUS_LIMITED,
+	/** Constant voltage charging. */
+	NRF_FUEL_GAUGE_CHARGE_STATE_CV,
+	/** Charging completed. */
+	NRF_FUEL_GAUGE_CHARGE_STATE_COMPLETE,
+};
+
+/**
+ * @brief State info type used for informing the library of external factors and events.
+ *
+ * @details The library uses this (optional) information to improve predictions.
+ */
+enum nrf_fuel_gauge_ext_state_info_type {
+	/** VBUS/USB has been connected to supply external power */
+	NRF_FUEL_GAUGE_EXT_STATE_INFO_VBUS_CONNECTED,
+	/** VBUS/USB has been disconnected */
+	NRF_FUEL_GAUGE_EXT_STATE_INFO_VBUS_DISCONNECTED,
+	/** Change in charger state (as determined by charger device) */
+	NRF_FUEL_GAUGE_EXT_STATE_INFO_CHARGE_STATE_CHANGE,
+	/** Multiply current by this factor when charging */
+	NRF_FUEL_GAUGE_EXT_STATE_INFO_CHARGE_CURRENT_CORRECTION,
+	/** Multiply current by this factor when discharging */
+	NRF_FUEL_GAUGE_EXT_STATE_INFO_DISCHARGE_CURRENT_CORRECTION,
+	/** Specify the charge current limit used by the charger */
+	NRF_FUEL_GAUGE_EXT_STATE_INFO_CHARGE_CURRENT_LIMIT,
+	/** Specify the termination current used by the charger */
+	NRF_FUEL_GAUGE_EXT_STATE_INFO_TERM_CURRENT,
+};
+
+/**
+ * @brief State info data type used for additional information.
+ */
+union nrf_fuel_gauge_ext_state_info_data {
+	/* Change in charge state */
+	enum nrf_fuel_gauge_charge_state charge_state;
+	/** Factor used for current measurement correction */
+	float current_correction_factor;
+	/** Battery charge current limit [A] */
+	float charge_current_limit;
+	/** Battery charge termination current [A] */
+	float charge_term_current;
 };
 
 /**
  * @brief Initialize optional configuration parameters to default values.
  *
- * @param[out] opt_params Pointer to the parameter structure.
+ * @param opt_params Pointer to the parameter structure.
  */
 void nrf_fuel_gauge_opt_params_default_get(struct nrf_fuel_gauge_config_parameters *opt_params);
 
 /**
  * @brief Initialize the nRF Fuel Gauge library.
  *
- * @note The battery model referenced in @p parameters must be kept valid as long as the library
+ * @details The library can be initialized based on a previously stored state.
+ *          This is useful when there are periods without RAM retention.
+ *          To resume from a previously stored state, the battery model must be the same
+ *          and be in the same memory location as when the library was first initialized.
+ *
+ * @note The battery model referenced in @ref parameters must be kept valid as long as the library
  *       is in use.
  *
- * @param[in] parameters Pointer to the parameter structure.
- * @param[out] v0 Adjusted battery voltage (optional, for logging purposes).
+ * @param parameters Pointer to the parameter structure.
+ * @param v0 Adjusted battery voltage (optional, for logging purposes).
  *
  * @retval 0 Initialization successful.
  * @retval -22 Initialization failed due to invalid parameters.
@@ -155,23 +288,27 @@ int nrf_fuel_gauge_init(const struct nrf_fuel_gauge_init_parameters *parameters,
 /**
  * @brief Process battery measurement values.
  *
+ * @details State-of-charge for primary cell battery models may be rounded off.
+ *          The raw value can always be obtained from the optional state info struct.
+ *
  * @param v Measured battery voltage [V].
  * @param i Measured battery current [A].
  * @param T Measured battery temperature [C].
  * @param t_delta Time delta since previous processed measurement [s].
- * @param vbus_present True if vbus voltage is present, for devices that supports this.
  * @param state Pointer to state info struct (optional, set to null to ignore).
  *
  * @retval Predicted state-of-charge [%].
  */
-float nrf_fuel_gauge_process(float v, float i, float T, float t_delta, bool vbus_present,
+float nrf_fuel_gauge_process(float v, float i, float T, float t_delta,
 			     struct nrf_fuel_gauge_state_info *state);
 
 /**
  * @brief Get predicted "time-to-empty" discharge duration.
  *
  * @details Time-to-empty is calculated based on the discharge rate. It may be NAN.
  *
+ * @note Primary cell variant will always return NAN.
+ *
  * @retval Predicted time-to-empty [s].
  */
 float nrf_fuel_gauge_tte_get(void);
@@ -181,12 +318,11 @@ float nrf_fuel_gauge_tte_get(void);
  *
  * @details Time-to-full is calculated based on the charge rate. It may be NAN.
  *
- * @param cc_charging True if ongoing charging is in constant current (CC) state. Otherwise false.
- * @param i_term Termination current [A].
+ * @note Primary cell variant will always return NAN.
  *
  * @retval Predicted time-to-full [s].
  */
-float nrf_fuel_gauge_ttf_get(bool cc_charging, float i_term);
+float nrf_fuel_gauge_ttf_get(void);
 
 /**
  * @brief Put library into the idle state.
@@ -211,6 +347,35 @@ float nrf_fuel_gauge_ttf_get(bool cc_charging, float i_term);
  */
 void nrf_fuel_gauge_idle_set(float v, float T, float i_avg);
 
+/**
+ * @brief Retrieve library state data.
+ *
+ * @details The state data can be stored in persistent storage during a period of no RAM
+ *          retention, and later used to resume the library from the same state.
+ *
+ * @param state Memory to copy state into.
+ * @param size Size of buffer. Must be at least @ref nrf_fuel_gauge_state_size.
+ *
+ * @retval 0 when successful, otherwise negative error code.
+ */
+int nrf_fuel_gauge_state_get(void *state, size_t size);
+
+/**
+ * @brief Optional function to inform library of external events and factors.
+ *
+ * @details Informing the library of certain external events and factors can help improve
+ *          battery state predictions.
+ *
+ * @note @ref nrf_fuel_gauge_ttf_get relies on external charger state information.
+ *
+ * @param type Type of external event.
+ * @param data Additional data for certain info types. Set to NULL when not relevant.
+ *
+ * @retval 0 when successful, otherwise negative error code.
+ */
+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);
+
 /**
  * @brief Update runtime parameters.
  *