Modem module

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.

LTE connection handling

The module uses the LTE link controller library to control and monitor the LTE connection. The module registers an event handler with LTE link controller 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 controller 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:

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

Neighbor cell measurements

Neighbor cell measurements can be requested by the application by sending an APP_EVT_DATA_GET event where APP_DATA_NEIGHBOR_CELLS is part of the requested data list. Upon reception of that event, the modem module uses the LTE link controller to start a neighbor cell search of type LTE_LC_NEIGHBOR_SEARCH_TYPE_DEFAULT. See LTE link controller for more details on the available search types. When the search completes, the module sends a MODEM_EVT_NEIGHBOR_CELLS_DATA_READY event containing the cell information received from the modem. If the search fails, a MODEM_EVT_NEIGHBOR_CELLS_DATA_NOT_READY event is sent.

Module internals

The modem module has an internal thread with a message queue for processing. When an event is received in the 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_INIT - The initial state of the module in which it awaits the modem to be initialized. The module enters this state only if the LwM2M carrier library is enabled because the modem is automatically initialized otherwise.

  • STATE_DISCONNECTED - The module has performed all required initializations and is ready to establish an LTE connection. This is the initial state for applications that do not use the LwM2M carrier library.

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

CONFIG_MODEM_AUTO_REQUEST_POWER_SAVING_FEATURES - Configuration for automatic requests of PSM

The module automatically requests PSM from the LTE network. If PSM is granted by the network, it results in reduction of the modem’s power consumption. Note that the device is not reachable from the cloud when it is in PSM. The device exits PSM whenever the application sends data, or the configured PSM TAU (Tracking Area Update) interval has passed. To not request PSM from the network, disable this option.

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

Module events

The asset_tracker_v2/src/events/modem_module_event.h header file contains a list of the events sent by the modem module.

Dependencies

The module uses the following nRF Connect SDK libraries:

API documentation

Header file: asset_tracker_v2/src/events/modem_module_event.h
Source files: asset_tracker_v2/src/events/modem_module_event.c, asset_tracker_v2/src/modules/modem_module.c
group modem_module_event

Modem module event.

Enums

enum modem_module_event_type

Modem event types submitted by Modem module.

Values:

enumerator MODEM_EVT_INITIALIZED

Event signalling that the modem library and AT command library have been initialized and are ready for use by other modules. The event has no associated payload.

enumerator MODEM_EVT_LTE_CONNECTED

The device has been registered with an LTE network. The event has no associated payload.

enumerator MODEM_EVT_LTE_DISCONNECTED

The device has been de-registered with an LTE network. The event has no associated payload.

enumerator MODEM_EVT_LTE_CONNECTING

The device is searching for an LTE network. The event has no associated payload.

enumerator MODEM_EVT_LTE_CELL_UPDATE

The device is connected to a new LTE cell. The event has associated payload of type modem_module_cell in the data.cell member.

enumerator MODEM_EVT_LTE_PSM_UPDATE

PSM configuration has been received. The event has associated payload of type modem_module_psm in the data.psm member.

enumerator MODEM_EVT_LTE_EDRX_UPDATE

eDRX configuration has been received. The event has associated payload of type modem_module_edrx in the data.edrx member.

enumerator MODEM_EVT_MODEM_STATIC_DATA_READY

Static modem data has been sampled and is ready. The event has associated payload of type modem_module_static_modem_data in the data.modem_static member.

enumerator MODEM_EVT_MODEM_DYNAMIC_DATA_READY

Dynamic modem data has been sampled and is ready. The event has associated payload of type modem_module_dynamic_modem_data in the data.modem_dynamic member.

enumerator MODEM_EVT_MODEM_STATIC_DATA_NOT_READY

Static modem data could not be sampled will not be ready for this sampling interval. The event has no associated payload.

enumerator MODEM_EVT_MODEM_DYNAMIC_DATA_NOT_READY

Dynamic modem data could not be sampled will not be ready for this sampling interval. The event has no associated payload.

enumerator MODEM_EVT_NEIGHBOR_CELLS_DATA_READY

Neighbor cell measurements have been gathered and the data is ready. The event has associated payload of type modem_module_neighbor_cells in the data.neighbor_cells member.

enumerator MODEM_EVT_NEIGHBOR_CELLS_DATA_NOT_READY

Neighbor cell data measurements could not be gathered will not be ready for this sampling interval. The event has no associated payload.

enumerator MODEM_EVT_BATTERY_DATA_READY

Battery voltage has been sampled and is ready. The event has associated payload of type modem_module_battery_data in the data.bat member.

enumerator MODEM_EVT_BATTERY_DATA_NOT_READY

Battery data could not be sampled will not be ready for this sampling interval. The event has no associated payload.

enumerator MODEM_EVT_SHUTDOWN_READY

The modem module has successfully shut down. The event has associated payload of type uint32_t in the data.id member.

enumerator MODEM_EVT_ERROR

A crtical error has occurred, and the application should reboot to recover as the module may enter an undefined state. The event has associated payload of the type int in the data.err member.

enumerator MODEM_EVT_CARRIER_INITIALIZED

The carrier library has initialized the modem library and it is now ready to be used. When the carrier library is enabled, this event must be received before the modem module can proceed to initialize other dependencies and subsequently send MODEM_EVT_INITIALIZED. The event has no associated payload.

enumerator MODEM_EVT_CARRIER_FOTA_PENDING

Due to modem limitations for active TLS connections, the carrier library requires all other TLS connections in the system to be terminated while FOTA update is ongoing. The event has no associated payload.

enumerator MODEM_EVT_CARRIER_FOTA_STOPPED

FOTA update has been stopped and the application can set up TLS connections again. The event has no associated payload.

enumerator MODEM_EVT_CARRIER_REBOOT_REQUEST

The carrier library requests that the device reboots to apply downloaded firmware image(s) or for other reasons. The event has no associated payload.

struct modem_module_cell
#include <modem_module_event.h>

LTE cell information.

Public Members

uint32_t cell_id

E-UTRAN cell ID.

uint32_t tac

Tracking area code.

struct modem_module_psm
#include <modem_module_event.h>

PSM information.

Public Members

int tau

Tracking Area Update interval [s]. -1 if the timer is disabled.

int active_time

Active time [s]. -1 if the timer is disabled.

struct modem_module_edrx
#include <modem_module_event.h>

eDRX information.

Public Members

float edrx

eDRX interval value [s]

float ptw

Paging time window [s]

struct modem_module_static_modem_data
#include <modem_module_event.h>
struct modem_module_dynamic_modem_data
#include <modem_module_event.h>
struct modem_module_battery_data
#include <modem_module_event.h>
struct modem_module_neighbor_cells
#include <modem_module_event.h>
struct modem_module_event
#include <modem_module_event.h>

Modem event.