nPM10xx: Fuel gauge
The Fuel gauge sample demonstrates how to estimate the battery state of charge using an nPM1012 PMIC and the nRF Fuel Gauge library.
Requirements
The sample includes board overlays for the following development kits:
nRF54L15 DK (
nrf54l15dk/nrf54l15/cpuapp)nRF54LC10 DK (
nrf54lc10dk/nrf54lc10a/cpuapp)nRF54LM20 DK (
nrf54lm20dk/nrf54lm20a/cpuappornrf54lm20dk/nrf54lm20b/cpuapp)
You also need an nPM1012 evaluation kit (EK) and a rechargeable battery with an NTC thermistor. Connect the EK to the DK as described in Wiring.
Overview
The sample reads battery voltage, current, and NTC temperature through the nPM10xx ADC driver. It uses the nPM10xx charger driver to read charging status, charge type, and configured charging limits. These measurements and charger information are supplied to the nRF Fuel Gauge library to estimate state of charge, time to empty, time to full, and state of health.
The sample uses the 20 mAh battery model described in the src/battery_model_20mAh.inc file.
The npm1012.overlay file configures charging with the following values:
Termination voltage: 4.2 V.
Constant charging current: 10 mA.
Termination current: 6.25% of the constant charging current.
Thermistor beta: 3434 K.
The sample processes measurements approximately every 500 ms and logs the results.
State of health is calculated based on battery charge cycles. This is a slow process. For testing purposes, you can accelerate the process as follows:
Use a battery model with a very low capacity that can be charged quickly, such as the 20 mAh model included in this sample.
Configure the charging current to be as high as possible within the limits of your battery or as high as the PMIC allows when using a power supply or battery emulator instead of an actual battery.
Begin charging at state of charge less than 70%, and ensure that the charging cycle completes by reaching the configured termination voltage and termination current.
Ensure that charging completes before the battery state of charge reaches 100%, either by using a battery emulator, or configure the charger termination voltage to be lower than the modeled battery termination voltage.
Repeat the charging cycles at least two times to see any change in state of health.
The state of health will only decrease when the state of charge is less than 100% when charging completes.
The state of health will also be calculated during partial charge cycles, but this is a slower process compared to full charge cycles.
When the Zephyr Settings subsystem is enabled, the sample also demonstrates how to store the fuel gauge state in non-volatile memory and restore it on boot. You can store the fuel gauge state using a shell command described in Testing.
Wiring
To connect your DK to the nPM1012 EK, complete the following steps:
Make the following connections on the EK:
Remove all existing connections, including jumpers and USB-C cables.
On the P1 pin header, connect VBATIN and VBAT pins with a jumper.
On the P17 pin header, connect CHG LED with a jumper.
On the P14 pin header, connect RSET2 and VSET2 pins with a jumper.
If your battery does not include an NTC thermistor, connect the NTC and 10kOhm pins on the P3 pin header with a jumper.
Connect a suitable battery to either the J2 or J1 connector.
Connect a USB power supply to the J4 connector.
With these connections, the USB power supply is powering the EK, the BUCK regulators are enabled, and the I/O reference voltage is supplied by the DK as described in the next step.
Note
Battery charging will not begin if the NTC signal is disconnected.
Connect the chosen DK to the EK as in the following table:
nPM1012 EK connections. EK pins
nRF54L Series DK pins
SDA
P1.11
SCL
P1.12
GPIO2
P0.04
VDDIO
VDDIO
GND
GND
Note
When using the nRF54L15 DK, the PMIC GPIO2 interrupt pin assignment uses the DK’s BUTTON 3 pin.
Building and running
This sample can be found under samples/pmic/native/npm10xx_fuel_gauge in the nRF Connect SDK folder structure.
To build the sample, follow the instructions in Building an application for your preferred building environment. See also Programming an application for programming steps and Testing and optimization for general information about testing and debugging in the nRF Connect SDK.
Note
When building repository applications in the SDK repositories, building with sysbuild is enabled by default.
If you work with out-of-tree freestanding applications, you need to manually pass the --sysbuild parameter to every build command or configure west to always use it.
Apply the npm1012.overlay file as an extra devicetree overlay.
In the nRF Connect for VS Code extension, select it under Extra Devicetree overlays.
On the command line, use the -DEXTRA_DTC_OVERLAY_FILE CMake argument.
For example, to build for an nRF54L15 DK, run the following command:
west build -b nrf54l15dk/nrf54l15/cpuapp samples/pmic/native/npm10xx_fuel_gauge -- -DEXTRA_DTC_OVERLAY_FILE=npm1012.overlay
Testing
After programming the sample to your development kit, complete the following steps to test it:
Connect the kit to the computer using a USB cable. The kit is assigned a serial port. Serial ports are referred to as COM ports on Windows, /dev/ttyACM devices on Linux, and /dev/tty devices on macOS. To list Nordic Semiconductor devices connected to your computer together with their serial ports, open a terminal and run the
nrfutil device listcommand. Alternatively, check your operating system’s device manager or its equivalent.Connect to the kit with a terminal emulator (for example, the Serial Terminal app). See Testing and optimization for the required settings and steps.
After successful initialization, the sample logs the fuel gauge library version, the initial charger state, and PMIC device ok.
Measurement output has the following format (with illustrative values):
PMIC device ok
V: 4.101, I: 0.000, T: 23.06, SoC: 93.09, TTE: nan, TTF: nan, SoH: 100.00, Cycles: 0, Chg: 0.00
Symbol |
Description |
Units |
|---|---|---|
V |
Battery voltage |
Volts |
I |
Battery current |
Amps (positive for charging, negative for discharging) |
T |
Battery temperature |
Degrees Celsius |
SoC |
State of charge |
Percent |
TTE |
Estimated time to empty |
Seconds (may be NaN) |
TTF |
Estimated time to full |
Seconds (may be NaN) |
SoH |
State of health (available battery capacity) |
Percent of modeled capacity |
Cycles |
Charge-cycle count |
Integer |
Chg |
Cumulative charge since the last full cycle |
Milliamp-hours |
The displayed current follows the Zephyr sensor API convention. The sample reverses its sign before passing it to the nRF Fuel Gauge library. Time estimates can be NaN when the library does not yet have enough information to provide an estimate.
Connect or remove VBUS power and observe the Vbus connected or Vbus removed messages.
As charging progresses, the sample also logs charger-state changes, such as:
Trickle chargingConstant current chargingConstant voltage chargingCharge complete
To save the state, including learned state of health and cycle information, run the following command:
uart:~$ fuel_gauge_state_store
Storing state after next update
The fuel gauge state will be stored in non-volatile memory after the next measurement has been performed, and restored on the next boot. Use the following shell commands to view the stored state and clear it:
uart:~$ settings list
fuel_gauge_state
uart:~$ settings delete fuel_gauge_state
Dependencies
The sample uses the following sdk-nrfxlib library:
It also uses the Zephyr nPM10xx MFD, ADC, charger, and LED drivers, and the following libraries: