Modem information

The modem information library can be used by an LTE application to obtain specific data from a modem. It issues AT commands to retrieve the following data:

  • Signal strength indication (RSRP)

  • Current and supported LTE bands

  • Tracking area code, mobile country code, and mobile network code

  • Current mode and operator

  • The cell ID and IP address of the device

  • UICC state, SIM ICCID and SIM IMSI

  • The battery voltage and temperature level, measured by the modem

  • The modem firmware version

  • The modem serial number

  • The LTE-M, NB-IoT, and GNSS support mode

  • Mobile network time and date

The modem information library uses the AT command parser.

Call modem_info_init() to initialize the library. To obtain a data value, call modem_info_string_get() (to retrieve the value as a string) or modem_info_short_get() (to retrieve the value as a short).

You can also retrieve all available data. To do so, call modem_info_params_init() to initialize a structure that stores all retrieved information, then populate it by calling modem_info_params_get().

Note, however, that signal strength data (RSRP) is only available by registering a subscription. To do so, call modem_info_rsrp_register().

API documentation

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

Defines

MODEM_INFO_MAX_RESPONSE_SIZE

Largest expected parameter response size.

MODEM_INFO_JSON_STRING_SIZE

Size of the JSON string.

RSRP_OFFSET_VAL

RSRP offset value.

RSRQ_OFFSET_VAL

RSRQ offset value.

RSRQ_SCALE_VAL

RSRQ scale value.

MODEM_INFO_FWVER_SIZE

Modem firmware version string can be up to 40 characters long.

BAND_UNAVAILABLE

Band unavailable value.

MODEM_INFO_SHORT_OP_NAME_SIZE

Short operator size can be up to 64 characters long. Matches value in nrf/samples/cellular/modem_shell/src/link/link_api.h.

SNR_UNAVAILABLE

SNR unavailable value.

SNR_OFFSET_VAL

SNR offset value.

RSRP_IDX_TO_DBM(rsrp)

Modem returns RSRP and RSRQ as index values which require a conversion to dBm and dB respectively. See modem AT command reference guide for more information.

RSRQ_IDX_TO_DB(rsrq)

Typedefs

typedef void (*rsrp_cb_t)(char rsrp_value)

RSRP event handler function prototype.

Enums

enum modem_info

LTE link information data.

Values:

enumerator MODEM_INFO_RSRP

Signal strength.

enumerator MODEM_INFO_CUR_BAND

Current LTE band.

enumerator MODEM_INFO_SUP_BAND

Supported LTE bands.

enumerator MODEM_INFO_AREA_CODE

Tracking area code.

enumerator MODEM_INFO_UE_MODE

Current mode.

enumerator MODEM_INFO_OPERATOR

Current operator name.

enumerator MODEM_INFO_MCC

Mobile country code.

enumerator MODEM_INFO_MNC

Mobile network code.

enumerator MODEM_INFO_CELLID

Cell ID of the device.

enumerator MODEM_INFO_IP_ADDRESS

IP address of the device.

enumerator MODEM_INFO_UICC

UICC state.

enumerator MODEM_INFO_BATTERY

Battery voltage.

enumerator MODEM_INFO_TEMP

Temperature level.

enumerator MODEM_INFO_FW_VERSION

Modem firmware version.

enumerator MODEM_INFO_ICCID

SIM ICCID.

enumerator MODEM_INFO_LTE_MODE

LTE-M support mode.

enumerator MODEM_INFO_NBIOT_MODE

NB-IoT support mode.

enumerator MODEM_INFO_GPS_MODE

GPS support mode.

enumerator MODEM_INFO_IMSI

Mobile subscriber identity.

enumerator MODEM_INFO_IMEI

Modem serial number.

enumerator MODEM_INFO_DATE_TIME

Mobile network time and date

enumerator MODEM_INFO_APN

Access point name.

enumerator MODEM_INFO_COUNT

Number of legal elements in the enum.

Functions

int modem_info_init(void)

Initialize the modem information module.

Return values:

0 – If the operation was successful. Otherwise, a (negative) error code is returned.

int modem_info_params_init(struct modem_param_info *modem_param)

Initialize the structure that stores modem information.

Parameters:

  • modem_param – Pointer to the modem parameter structure.

Return values:

0 – If the operation was successful. Otherwise, a (negative) error code is returned.

int modem_info_rsrp_register(rsrp_cb_t cb)

Initialize the subscription of RSRP values.

Parameters:

  • cb – Callback function.

Return values:

0 – If the operation was successful. Otherwise, a (negative) error code is returned.

int modem_info_connectivity_stats_init(void)

Initialize collection of connectivity statistics.

Note

The function will reset statistics if connectivity statistics are already initialized/enabled.

Returns:

0 If the operation was successful. Otherwise, a (negative) error code is returned.

int modem_info_connectivity_stats_disable(void)

Disable collection of connectivity statistics.

Returns:

0 If the operation was successful. Otherwise, a (negative) error code is returned.

int modem_info_string_get(enum modem_info info, char *buf, const size_t buf_size)

Request the current modem status of any predefined information value as a string.

If the data parameter returned by the modem is originally a short, it is still returned as a string.

Parameters:

  • info – The requested information type.

  • buf – The buffer to store the null-terminated string.

  • buf_size – The size of the buffer.

Returns:

Length of received data if the operation was successful. Otherwise, a (negative) error code is returned.

int modem_info_short_get(enum modem_info info, uint16_t *buf)

Request the current modem status of any predefined information value as a short.

If the data parameter returned by the modem is originally a string, this function fails.

Parameters:

  • info – The requested information type.

  • buf – The short where to store the information.

Returns:

Length of received data if the operation was successful. Otherwise, a (negative) error code is returned.

int modem_info_name_get(enum modem_info info, char *name)

Request the name of a modem information data type.

Parameters:

  • info – The requested information type.

  • name – The string where to store the name.

Returns:

Length of received data if the operation was successful. Otherwise, a (negative) error code is returned.

enum at_param_type modem_info_type_get(enum modem_info info)

Request the data type of the current modem information type.

Parameters:

  • info – The requested information type.

Returns:

The data type of the requested modem information data. Otherwise, a (negative) error code is returned.

int modem_info_params_get(struct modem_param_info *modem_param)

Obtain the modem parameters.

The data is stored in the provided info structure.

Parameters:

  • modem_param – Pointer to the storage parameters.

Return values:

0 – If the operation was successful. Otherwise, a (negative) error code is returned.

int modem_info_get_fw_uuid(char *buf, size_t buf_size)

Obtain the UUID of the modem firmware build.

The UUID is represented as a string, for example: 25c95751-efa4-40d4-8b4a-1dcaab81fac9

See the documentation for the AT command XMODEMUUID.

Parameters:

  • buf – Pointer to the target buffer.

  • buf_size – Size of target buffer.

Return values:

  • 0 – if the operation was successful.

  • -EINVAL – if the provided buf_size was not enough. Otherwise, a (negative) error code is returned.

int modem_info_get_fw_version(char *buf, size_t buf_size)

Obtain the short software identification.

The short software identification is represented as a string, for example: nrf9160_1.1.2

See the documentation for the AT command SHORTSWVER.

Parameters:

  • buf – Pointer to the target buffer.

  • buf_size – Size of target buffer.

Return values:

  • 0 – if the operation was successful.

  • -EINVAL – if the provided buf_size was not enough. Otherwise, a (negative) error code is returned.

int modem_info_get_hw_version(char *buf, uint8_t buf_size)

Obtain the hardware version string.

The hardware version is represented as a string, for example: nRF9160 SICA B0A

See the documentation for the AT command HWVERSION.

Parameters:

  • buf – Pointer to the target buffer.

  • buf_size – Size of target buffer.

Return values:

  • 0 – if the operation was successful.

  • -EINVAL – if a parameter was invalid. Otherwise, a (negative) error code is returned.

int modem_info_get_svn(char *buf, size_t buf_size)

Obtain the modem Software Version Number (SVN).

The SVN is represented as a string, for example: 12

See the documentation for the AT command +CGSN.

Parameters:

  • buf – Pointer to the target buffer.

  • buf_size – Size of target buffer.

Return values:

  • 0 – if the operation was successful.

  • -EINVAL – if the provided buf_size was not enough. Otherwise, a (negative) error code is returned.

int modem_info_get_batt_voltage(int *val)

Obtain the battery voltage.

Get the battery voltage, in mV, with a 4 mV resolution.

Parameters:

  • val – Pointer to the target variable.

Return values:

  • 0 – if the operation was successful.

  • -EINVAL – if the provided buf_size was not enough. Otherwise, a (negative) error code is returned.

int modem_info_get_temperature(int *val)

Obtain the internal temperature.

Get the internal temperature, in degrees Celsius.

Parameters:

  • val – Pointer to the target variable.

Return values:

0 – if the operation was successful. Otherwise, a (negative) error code is returned.

int modem_info_get_rsrp(int *val)

Obtain the RSRP.

Get the reference signal received strength (RSRP), in dBm.

Parameters:

  • val – Pointer to the target variable.

Return values:

  • 0 – if the operation was successful.

  • -ENOENT – if there is no valid RSRP. Otherwise, a (negative) error code is returned.

int modem_info_get_connectivity_stats(int *tx_kbytes, int *rx_kbytes)

Obtain the connectivity statistics.

Get the total amount of data transmitted and receievd during the collection period.

Note

Will return bytes = 0 until connectivity statistics collection has been enabled using ATXCONNSTAT=1, or with modem_info_connectivity_stats_init().

Parameters:

  • tx_kbytes – Pointer to the target variable for the number of kilobytes transmitted.

  • rx_kbytes – Pointer to the target variable for the number of kilobytes received.

Returns:

0 if the operation was successful. Otherwise, a (negative) error code is returned.

int modem_info_get_current_band(uint8_t *val)

Obtain the current band.

Parameters:

  • val – Pointer to the target variable.

Returns:

0 if the operation was successful.

Returns:

-ENOENT if there is no valid band. Otherwise, a (negative) error code is returned.

int modem_info_get_operator(char *buf, size_t buf_size)

Obtain the operator name.

Parameters:

  • buf – Pointer to the target buffer.

  • buf_size – Size of target buffer.

Returns:

0 if the operation was successful. Otherwise, a (negative) error code is returned.

int modem_info_get_snr(int *val)

Obtain the signal-to-noise ratio.

Parameters:

  • val – Pointer to the target variable.

Returns:

0 if the operation was successful.

Returns:

-ENOENT if there is no valid SNR. Otherwise, a (negative) error code is returned.

struct lte_param
#include <modem_info.h>

LTE parameter data.

Public Members

uint16_t value

The retrieved value.

char value_string[100]

The retrieved value in string format.

char *data_name

The name of the information type.

enum modem_info type

The information type.

struct network_param
#include <modem_info.h>

Network parameters.

Public Members

struct lte_param current_band

Current LTE band.

struct lte_param sup_band

Supported LTE bands.

struct lte_param area_code

Tracking area code.

struct lte_param current_operator

Current operator.

struct lte_param mcc

Mobile country code.

struct lte_param mnc

Mobile network code.

struct lte_param cellid_hex

Cell ID of the device (in HEX format).

struct lte_param ip_address

IP address of the device.

struct lte_param ue_mode

Current mode.

struct lte_param lte_mode

LTE-M support mode.

struct lte_param nbiot_mode

NB-IoT support mode.

struct lte_param gps_mode

GPS support mode.

struct lte_param date_time

Mobile network time and date

struct lte_param apn

Access point name (string).

struct lte_param rsrp

Received signal strength.

double cellid_dec

Cell ID of the device (in decimal format).

struct sim_param
#include <modem_info.h>

SIM card parameters.

Public Members

struct lte_param uicc

UICC state.

struct lte_param iccid

SIM ICCID.

struct lte_param imsi

Mobile subscriber identity.

struct device_param
#include <modem_info.h>

Device parameters.

Public Members

struct lte_param modem_fw

Modem firmware version.

struct lte_param battery

Battery voltage.

struct lte_param imei

Modem serial number.

const char *board

Board version.

const char *app_version

Application version.

const char *app_name

Application name.

struct modem_param_info
#include <modem_info.h>

Modem parameters.

Public Members

struct network_param network

Network parameters.

struct sim_param sim

SIM card parameters.

struct device_param device

Device parameters.