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 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_READYDynamic 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_READYMODEM_EVT_MODEM_DYNAMIC_DATA_NOT_READYMODEM_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.
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
asset_tracker_v2/src/events/modem_module_event.hasset_tracker_v2/src/events/modem_module_event.c, asset_tracker_v2/src/modules/modem_module.c