Nordic nPM1300 PMIC
The npm1300 component configures and monitors the Nordic Semiconductor nPM1300 power management IC (PMIC) over
the I²C bus (product specification).
The nPM1300 has a 1-cell lithium-ion battery charger, two buck regulators (BUCK1, BUCK2), two LDOs or load switches
(LDO1, LDO2) and a 10-bit ADC that measures the battery, the system supply and the USB supply (VBUS).
The hub writes the VBUS current limit, the charger and the regulator settings at boot and reads the chip at
update_interval. The sensor, binary_sensor and text_sensor platforms report measurements and the charger
state, and the switch platform turns the charger and the regulators on and off.
Configuration
Section titled “Configuration”# Example configuration entrynpm1300: id: pmic vbus_current_limit: 500mA thermistor_resistance: 10kOhm charger: charge_current: 150mA termination_voltage: 4.2V warm_termination_voltage: 4.0V enabled: true
sensor: - platform: npm1300 battery_voltage: name: "Battery Voltage" battery_current: name: "Battery Current"
binary_sensor: - platform: npm1300 charging: name: "Charging"
text_sensor: - platform: npm1300 charger_status: name: "Charger Status"Configuration Variables
Section titled “Configuration Variables”- id (Optional, ID): Manually specify the ID used to reference this hub from the platforms and actions.
- address (Optional, int): The I²C address of the chip. Defaults to
0x6B. - i2c_id (Optional, ID): Manually specify the ID of the I²C bus.
- update_interval (Optional, Time): How often to read the chip.
Defaults to
60s. - vbus_current_limit (Optional, current): The current the chip may draw from VBUS (USB), from
100mAto1500mAin 100 mA steps. The chip uses100mAafter a reset and every time USB is plugged in again, so the limit is written again on every update while VBUS is present. If not set, the chip default (100mA) is kept. - thermistor_resistance (Optional, resistance): The nominal resistance of the battery thermistor (NTC), one of
10kOhm,47kOhm,100kOhm, ornonefor a battery without a thermistor. Withnone, the charger does not check the battery temperature. Required with achargerblock, thechargerswitch or thebattery_temperaturesensor. A configuration without any of these, for example one that only reads voltages, can leave it out. - thermistor_beta (Optional, int): The B constant of the battery thermistor. Only with a resistance in
thermistor_resistance. Defaults to the value the product specification lists for the resistance:3380for10kOhm,4050for47kOhmand4250for100kOhm. - charger (Optional): Configure the battery charger. See Charger.
- buck1, buck2 (Optional): Configure a buck regulator. See Regulators.
- ldo1, ldo2 (Optional): Configure an LDO or load switch. See Regulators.
The settings are written in this order: VBUS current limit, thermistor, charger, then the regulators. Raising the VBUS current limit first keeps the inrush current of a regulator from tripping the over-current protection of the chip when the board runs from USB.
Charger
Section titled “Charger”The defaults are the reset values of the chip from the product specification.
- charge_current (Optional, current): The charge current, from
32mAto800mAin 2 mA steps. Defaults to32mA. - termination_voltage (Optional, voltage): The voltage at which charging ends.
3.5Vto3.65Vor4.0Vto4.45V, in 50 mV steps. Defaults to3.6V. - warm_termination_voltage (Optional, voltage): The termination voltage when the battery is warm (45 °C to
60 °C), with the same values as
termination_voltage. Defaults to3.6V, or totermination_voltagewhen that is lower. A warning is shown when onlytermination_voltageis set, to a value above3.6V. - termination_current (Optional, string): The charge current, as a share of
charge_current, below which charging is complete. One of10%or20%. Defaults to10%. - trickle_voltage (Optional, voltage): Below this battery voltage the battery is charged with a small trickle
current. One of
2.5Vor2.9V. Defaults to2.9V. - discharge_current_limit (Optional, current): The battery discharge current limit. One of
200mAor1000mA. Defaults to1000mA. - recharge (Optional, boolean): Start charging again when the battery voltage drops after a complete charge.
Defaults to
true. - enabled (Optional, boolean): Turn on the charger at boot. Defaults to
false.
WARNING
thermistor_resistance must match the thermistor of your battery. The charger compares the thermistor with a
reference of the selected resistance, so a wrong value shifts the battery temperature it sees: a larger thermistor
than selected can let a hot battery charge, and a smaller one a freezing battery.
WARNING
Check charge_current and the termination voltages against the data sheet of your battery. Wrong values can damage
the battery.
NOTE
The nPM1300 cannot detect whether a battery is connected. With the charger on, USB connected and no battery, the
charger keeps starting and finishing a charge, so the charging and charge_complete binary sensors and the
charger_status text sensor change between states and do not mean anything. Turn the charger off on boards
that run without a battery.
Regulators
Section titled “Regulators”- voltage (Optional, voltage): The output voltage, from
1.0Vto3.3Vin 100 mV steps. For a buck regulator this replaces the voltage set by theVSETpin of the chip. For an LDO, it applies inldomode. - mode (Optional, string): LDO1 and LDO2 only:
ldoto regulate the output voltage, orload_switchto pass the input voltage through. - enabled (Optional, boolean): Turn the output on (
true) or off (false) at boot. If not set, the output stays as it is.
CAUTION
One of the buck regulators usually powers the microcontroller itself. A voltage above what the microcontroller supports can damage it. Turning the regulator off or setting a voltage that is too low stops the board. Because the setting is written at every boot, the board can then stop again each time it starts.
Sensor
Section titled “Sensor”sensor: - platform: npm1300 battery_voltage: name: "Battery Voltage" battery_current: name: "Battery Current" battery_temperature: name: "Battery Temperature" die_temperature: name: "PMIC Temperature" system_voltage: name: "System Voltage" vbus_voltage: name: "VBUS Voltage"- npm1300_id (Optional, ID): The ID of the
npm1300hub. - battery_voltage (Optional): The battery voltage, in volts.
- battery_current (Optional): The battery current, in amperes: positive while charging, negative while discharging. The chip measures it relative to the charge current or the discharge current limit, so it is most accurate near those values.
- battery_temperature (Optional): The battery temperature from the thermistor, in °C. Not available with
thermistor_resistance: none. - die_temperature (Optional): The temperature of the nPM1300 itself, in °C.
- system_voltage (Optional): The system supply voltage (VSYS), in volts.
- vbus_voltage (Optional): The USB supply voltage (VBUS), in volts.
- vbus_current_limit (Optional): The VBUS current limit selected in the chip (register
VBUSINILIM0), in amperes. The chip cannot measure the VBUS current itself. The reset value is 0.1 A. After USB is plugged in again the chip uses 100 mA until a new limit is applied, which the hub does on every update whenvbus_current_limitis set.
All options from Sensor.
Binary Sensor
Section titled “Binary Sensor”binary_sensor: - platform: npm1300 vbus_present: name: "USB Power" charging: name: "Charging"- npm1300_id (Optional, ID): The ID of the
npm1300hub. - vbus_present (Optional): On when a supply is connected to VBUS.
- vbus_current_limit_active (Optional): On while the VBUS current is held at its limit. The battery then
supplies the rest of the load, or charging slows down. If this is on often, raise
vbus_current_limit. - charging (Optional): On while the battery is charging (trickle, constant current or constant voltage).
- charge_complete (Optional): On when charging is complete.
- charger_error (Optional): On when the charger stopped because of an error, for example a battery or thermistor fault or a charge timeout. Turn the charger switch off and on to clear the error.
All options from Binary Sensor.
Text Sensor
Section titled “Text Sensor”text_sensor: - platform: npm1300 charger_status: name: "Charger Status"- npm1300_id (Optional, ID): The ID of the
npm1300hub. - charger_status (Optional): The state of the charger. The first one that applies is shown:
Discharging: no supply on VBUS, so the battery powers the board.Error: the charger stopped because of an error. See thecharger_errorbinary sensor.Disabled: the charger is turned off.Paused, PMIC Too Hot: the nPM1300 is too hot. Charging starts again when it cools down.Charge Complete,Trickle Charge,Constant CurrentorConstant Voltage: the charging phase.Paused, Battery Too ColdorPaused, Battery Too Hot: the battery temperature is below 0 °C or above 60 °C, the default limits of the chip. Not shown withthermistor_resistance: none.Not Charging: the charger is on but does not charge, for example because the VBUS voltage is too low or too high.
All options from Text Sensor.
Switch
Section titled “Switch”switch: - platform: npm1300 charger: name: "Charger" ldo1: name: "LDO1"- npm1300_id (Optional, ID): The ID of the
npm1300hub. - charger (Optional): Turn the battery charger on or off. Turning it on also clears a charger error. Needs
thermistor_resistanceon the hub. Withthermistor_resistance: none, it also needs achargerblock on the hub, which turns off the battery temperature check. - buck1, buck2, ldo1, ldo2 (Optional): Turn a regulator on or off.
The switches show the state read from the chip at every update, so their state is not restored at boot.
All options from Switch.
npm1300.enter_ship_mode Action
Section titled “npm1300.enter_ship_mode Action”Puts the chip in ship mode, its lowest power state: all outputs are turned off and the device stays off until the
SHPHLD button of the nPM1300 is pressed or VBUS is connected.
on_...: then: - npm1300.enter_ship_mode: pmicnpm1300.hibernate Action
Section titled “npm1300.hibernate Action”Puts the chip in hibernate mode: all outputs are turned off until the wake-up timer of the chip runs out, the
SHPHLD button is pressed or VBUS is connected. The device then starts again from the beginning.
on_...: then: - npm1300.hibernate: id: pmic duration: 1h- id (Required, ID): The ID of the
npm1300hub. - duration (Required, templatable, Time): How
long to stay in hibernate mode, from
16msto about74h, in 16 ms steps.
NOTE
A supply on VBUS wakes the chip, so with VBUS connected it leaves ship or hibernate mode right away.
Seeed Studio XIAO nRF54LM20A
Section titled “Seeed Studio XIAO nRF54LM20A”The XIAO nRF54LM20A boards have an nPM1300 at address 0x6B on its own I²C bus on P1.18 (SDA) and P1.17 (SCL),
with a 10 kΩ battery thermistor. BUCK2 powers the nRF54LM20A and must stay on, and LDO1 supplies 3.3 V to the IMU
and the microphone of the Sense version. This configuration matches the settings of the board in Zephyr:
i2c: - id: pmic_bus sda: P1.18 scl: P1.17
npm1300: id: pmic i2c_id: pmic_bus vbus_current_limit: 500mA thermistor_resistance: 10kOhm charger: charge_current: 150mA termination_voltage: 4.2V warm_termination_voltage: 4.0V enabled: true ldo1: voltage: 3.3V mode: ldo enabled: true
sensor: - platform: npm1300 battery_voltage: name: "Battery Voltage" battery_current: name: "Battery Current" battery_temperature: name: "Battery Temperature"
text_sensor: - platform: npm1300 charger_status: name: "Charger Status"