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.

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_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_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.

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.