Modem module

Important

The Asset Tracker v2 application is in maintenance mode. For new projects, it is recommended to use the Cellular: nRF Cloud multi-service sample instead.

The modem module communicates with the modem to control the LTE connection and retrieve information from the modem about the device and LTE network.

Features 

This section documents the features implemented by the module.

The module uses the LTE link control library to control and monitor the LTE connection. The module registers an event handler with LTE link control to receive updates from the modem about the state of the LTE connection and network information. If you use the LwM2M carrier library, refer to Carrier library support for additional information on LTE connection handling.

In its default configuration, the modem module makes an attempt to establish an LTE connection immediately when it is initialized. There is no timeout on the connection attempt, so the modem searches for a suitable LTE network until it finds one.

When the device is registered to an LTE network, the LTE connection is considered to be established, and a MODEM_EVT_LTE_CONNECTED event is sent. If the network registration is lost at some point, a MODEM_EVT_LTE_DISCONNECTED event is sent.

If the device connects to a new LTE cell, an LTE_LC_EVT_CELL_UPDATE is sent. The event contains cell ID and tracking area code as payload, which can be used to determine the device’s coarse position.

If the modem module receives an APP_EVT_LTE_DISCONNECT event, it instructs the modem to detach from the network, and a subsequent MODEM_EVT_LTE_DISCONNECTED event can be expected after the disconnect.

To configure the LTE connection parameters, refer to the LTE link control Kconfig options. These options can be used to select the access technology to use (LTE-M or NB-IoT), default values for Power Saving Mode (PSM) timers and more.

Note that some network parameters, such as PSM timer values, are requests to the network and might not be granted as requested, and the network might grant a different value than the requested values or deny the request altogether. The actual values that are received from the network are distributed in MODEM_EVT_LTE_PSM_UPDATE events.

Carrier library support 

The modem module has support for the LwM2M carrier library. When the library is enabled, the modem module leaves the LTE connection handling to the library in order to adhere to the specific carrier’s requirements.

If the LwM2M carrier library starts a modem firmware update, the modem module sends a MODEM_EVT_CARRIER_FOTA_PENDING event. This event signals that a modem firmware FOTA download is about to start, and all the other TLS connections in the system must be closed, including any cloud connection. After a successful FOTA, MODEM_EVT_CARRIER_REBOOT_REQUEST is sent, indicating that the application must perform a graceful shutdown and reboot the device to apply the new modem firmware. If a FOTA download fails, a MODEM_EVT_CARRIER_FOTA_STOPPED event is sent, and the application might again establish TLS connections and continue normal operation.

For more details and configuration options, you can refer to LwM2M carrier.

Modem information 

When the application module sends out an APP_EVT_DATA_GET event, the modem module checks the requested data list for relevant requests:

APP_DATA_MODEM_STATIC - Static modem data, such as configured system mode (any combination of LTE-M, NB-IoT and GNSS), ICCID, modem firmware version, application version and board version.
APP_DATA_MODEM_DYNAMIC - Dynamic modem data, such as Cell ID, tracking area code, RSRP, IP address and PLMN (MCCMNC).
APP_DATA_BATTERY - Voltage of the modem’s power supply.

The module uses Modem information to acquire information about the modem, LTE network and the modem’s power supply. The response for the three different data types is sent as separate events:

Static data as MODEM_EVT_MODEM_STATIC_DATA_READY
Dynamic data as MODEM_EVT_MODEM_DYNAMIC_DATA_READY

If the sampling of data fails, a corresponding error message is sent through one of the following events:

MODEM_EVT_MODEM_STATIC_DATA_NOT_READY
MODEM_EVT_MODEM_DYNAMIC_DATA_NOT_READY
MODEM_EVT_BATTERY_DATA_NOT_READY

Module internals 

The modem module has an internal thread with a message queue for processing. When an event is received in the Application Event Manager handler, the event is converted to a message and put into the module’s queue for processing in thread context. This gives the module the flexibility to call functions that might take some time to complete.

Module states 

The modem module has an internal state machine with the following states:

STATE_DISCONNECTED - The module has performed all required initializations and is ready to establish an LTE connection.

STATE_CONNECTING - The modem is currently searching for a suitable LTE network and attempting to establish a connection.

STATE_CONNECTED - The device is connected to an LTE network.

STATE_SHUTDOWN - The module has been shut down after receiving a request from the utility module.

State transitions take place based on input from other modules through the Application Event Manager handler and the LTE link controller handler.

Configuration options 

You can set the following options to configure the modem module:

CONFIG_MODEM_MODULE - Configuration for modem module: This option enables the modem module.

CONFIG_MODEM_THREAD_STACK_SIZE - Configuration for thread stack size: This option configures the modem module thread stack size.

CONFIG_MODEM_SEND_ALL_SAMPLED_DATA - Configuration for sending all sampled data: By default, the modem module sends only events with sampled data that has changed since the last sampling. To send unchanged data also, enable this option.

For more information on LTE configuration options, see LTE link control.

Modem module event

Modem module

Features 

LTE connection handling 

Carrier library support 

Modem information 

Module internals 

Module states 

Configuration options 

Module events 

Dependencies 

API documentation 