Modem battery

The modem battery library is used to get battery voltage information or notifications from the modem.

The library issues AT commands to perform the following actions:

  • Retrieve the battery voltage measured by the modem.

  • Set the battery voltage low level for the modem using the %XVBATLOWLVL command. See the Battery voltage low level %XVBATLOWLVL section in the nRF9160 AT Commands Reference Guide or the same section in the nRF91x1 AT Commands Reference Guide, depending on the SiP you are using.

  • Subscribe to or unsubscribe from unsolicited notifications on modem battery voltage low level.

  • Configure the power-off warnings from the modem (possible with modem firmware v1.3.1 and higher).

Configuration

You can enable this library using the Kconfig option CONFIG_MODEM_BATTERY. When enabled, the modem battery library automatically subscribes to unsolicited notifications on modem battery voltage low level and configures the power-off warnings from the modem.

Usage

The library can be used for the following purposes:

  • Retrieving the modem battery voltage

  • Setting the modem battery low level

  • Configuring power-off warnings

Retrieving the modem battery voltage

To retrieve the battery voltage measured (in mV) by the modem, call the modem_battery_voltage_get() function by passing a pointer to an integer variable for the battery voltage. The modem_battery_voltage_get() function sends the Nordic-proprietary %XVBAT command that reads battery voltage. When the modem is active (either involved in LTE communication or acts as a GNSS receiver), the %XVBAT command returns the latest voltage measured automatically during modem wakeup or reception. The voltage measured during transmission is not reported. During modem inactivity, the modem measures battery voltage when the %XVBAT command is received.

Setting the modem battery low level

The modem battery low level is a voltage threshold that can be set in the modem to get notified when the battery voltage drops below the set value. Battery low level notifications are received within a time interval of 60 seconds when the battery voltage has dropped below the threshold while maintaining an LTE connection.

Unsolicited notifications of battery voltage low level are automatically enabled when the modem battery library is enabled using the CONFIG_MODEM_BATTERY Kconfig option.

An application can follow +CSCON notifications and expect low battery level notification only after +CSCON: 1 is received. The factory default battery voltage low level is 3300 mV and the default range is 3100 to 3500 mV. To update this value, call the modem_battery_low_level_set() function by passing an integer for the battery voltage low level (measured in mV).

To start receiving notifications of battery voltage low level from the modem, first set a handler by calling the modem_battery_low_level_handler_set() function before subscribing. An integer value for the battery voltage (measured in mV) reported by the notification is passed to the handler. To manually subscribe to and unsubscribe from battery voltage low level notifications, call the modem_battery_low_level_enable() and the modem_battery_low_level_disable() functions, respectively.

Configuring power-off warnings

The power-off warning is received as an unsolicited AT notification when the modem battery voltage drops below a certain threshold. This threshold is not the same as the battery voltage low level threshold. When the power-off warning is sent, the modem sets itself to offline mode and sends an unsolicited notification. Active power-off warning blocks the storing to NVM.

The power-off warnings are automatically configured when the modem battery library is enabled using CONFIG_MODEM_BATTERY.

To start receiving power-off warnings from the modem, first set a handler by calling the modem_battery_pofwarn_handler_set() function before configuring.

Configuring and enabling the modem battery power-off warning is only supported by modem firmware v1.3.1 and higher. The application is responsible for detecting a possible increase in the battery voltage level and for restarting the LTE protocol activities. This can be detected by calling the modem_battery_voltage_get() function. If the level is acceptable again (value greater than 3000 mV), the application can proceed with initialization of the modem. The factory default is 3000 mV. To configure this value, call the modem_battery_pofwarn_enable() function by passing an enum corresponding to a voltage value. The expected values are 30 (for 3000 mV), 31 (for 3100 mV), 32 (for 3200 mV), 33 (for 3300 mV) and can be found in the pofwarn_level type as POFWARN_3000, POFWARN_3100, POFWARN_3200 and POFWARN_3300, respectively.

To manually configure and disable the power-off warnings, call the modem_battery_pofwarn_enable() and the modem_battery_pofwarn_disable() functions, respectively.

Dependencies

The modem battery library uses the AT monitor library.

API documentation

Header file: include/modem/modem_battery.h
Source files: lib/modem_battery/
group modem_battery

Public APIs for modem battery.

Typedefs

typedef void (*modem_battery_low_level_handler_t)(int battery_voltage)

Type definition of event handler for battery voltage low level notifications.

Param battery_voltage:

Battery voltage provided by the low level notification. Unit of measure mV.

typedef void (*modem_battery_pofwarn_handler_t)(void)

Type definition of Event handler for power-off warnings.

Enums

enum pofwarn_level

Battery voltage levels for power-off warnings.

Values:

enumerator POFWARN_3000
enumerator POFWARN_3100
enumerator POFWARN_3200
enumerator POFWARN_3300

Functions

int modem_battery_low_level_handler_set(modem_battery_low_level_handler_t handler)

Function to set an event handler for battery voltage low level notifications.

Parameters:

  • handler – Event handler.

Return values:

  • 0 – If execution was successful.

  • -EINVAL – If handler is a NULL pointer.

int modem_battery_pofwarn_handler_set(modem_battery_pofwarn_handler_t handler)

Function to set an event handler for power-off warnings.

Note

Only supported with modem firmware v1.3.1 and higher.

Parameters:

  • handler – Event handler.

Return values:

  • 0 – If execution was successful.

  • -EINVAL – If handler is a NULL pointer.

int modem_battery_pofwarn_enable(enum pofwarn_level level)

Configure power-off warnings from the modem.

Note

The warning is received as an unsolicited AT notification.

Note

When the power-off warning is sent, the modem sets itself to Offline mode and sends unsolicited notifications.

Note

The application is responsible for detecting possible increase in the battery voltage level and for restarting the LTE protocol activities. This can be detected by calling modem_battery_voltage_get. If the level is acceptable again (>3000 mV), the application can proceed with initialization of the modem.

Note

Only supported with modem firmware v1.3.1 and higher.

Parameters:

  • level – Battery voltage level for the power-off warnings.

Return values:

  • 0 – if successful.

  • -EFAULT – if AT command failed.

int modem_battery_pofwarn_disable(void)

Disable power-off warnings from the modem.

Note

Only supported with modem firmware v1.3.1 and higher.

Return values:

  • 0 – if successful.

  • -EFAULT – if AT command failed.

int modem_battery_low_level_enable(void)

Subscribe unsolicited notifications of battery voltage low level.

Note

The command configuration is stored to NVM approximately every 48 hours and when the modem is powered off with the +CFUN=0 command.

Return values:

  • 0 – if successful.

  • -EFAULT – if AT command failed.

int modem_battery_low_level_disable(void)

Unsubscribe unsolicited notifications of battery voltage low level.

Note

The command configuration is stored to NVM approximately every 48 hours and when the modem is powered off with the +CFUN=0 command.

Return values:

  • 0 – if successful.

  • -EFAULT – if AT command failed.

int modem_battery_low_level_set(int battery_level)

Set the battery voltage low level for the modem.

Note

This function sends an AT command for setting the battery voltage low level for the modem. If notifications of battery voltage low level have been subscribed (see modem_battery_low_level_enable), the modem sends clients a notification when the measured battery voltage is below the defined level. The modem reads sensors periodically in connected mode. The default period is 60 seconds. If the temperature or voltage gets close to the set threshold, a shorter period is used. Battery voltage low level has range 3100-5000 mV. Factory default is 3300 mV.

Parameters:

  • battery_level – Battery voltage low level. Unit of measure mV.

Return values:

  • 0 – if successful.

  • -EFAULT – if AT command failed.

int modem_battery_voltage_get(int *battery_voltage)

Function for retrieving the latest voltage measured automatically during modem wakeup or reception. During modem inactivity, the modem measures battery voltage when this function is called.

Note

This function sends the Nordic-proprietary XVBAT command that reads battery voltage. When the modem is active (either LTE communication or GNSS receiver), the XVBAT command returns the latest voltage measured automatically during modem wakeup or reception. The voltage measured during transmission is not reported. During modem inactivity, the modem measures battery voltage when the XVBAT command is received.

Parameters:

  • battery_voltage – [out] Pointer to the variable for battery voltage. Battery voltage in mV, with a resolution of 4mV.

Return values:

  • 0 – if successful.

  • -EINVAL – if input argument was invalid.

  • -EFAULT – if AT command failed.