Connecting to LTE Network with nRF9151 LTE Modem
1. Overview
This application note describes how to use nRF9151 LTE modem to connect to LTE network.
2. Device Preparations
Set up the hardware platform with an LTE antenna as described in Setting Up Emcraft SOM-NRF9151 Hardware Platform.
Insert an activated nano SIM card to the SIM slot. Verify that the SIM has enough data on it.
Install the modem and application firmware onto the hardware platform as described in Installing SOM-NRF9151 Images.
3. nRF9151 LTE Modem Library
The Modem library is a binary library that provides a set of APIs that enable the use of the nRF91 Series modem by the application processor of the nRF91 Series SiP.
The following figure shows a simplified Modem library architecture:
For details about full LTE modem library API refer to https://docs.nordicsemi.com/bundle/ncs-latest/page/nrfxlib/nrf_modem/README.html.
3.1. LTE Modem Library Wrapper
The library wrapper is implemented in nrf/lib/nrf_modem_lib/nrf_modem_lib.c
and provides an encapsulation over the core Modem library functions such as initialization and shutdown:
Function | Description | Comments |
---|---|---|
| Initialize the Modem library and turn on the modem. | Returns 0 on success, or a negative error code on failure. The operation can take a few minutes when a firmware update is scheduled. To switch between the bootloader mode and normal operating mode, shutdown the modem |
| Shutdown the Modem library and turn off the modem. | Returns 0 on success, or a negative error code on failure. The modem must be put in minimal function mode before being shut down. |
| Modem fault handler. |
|
Partition Manager is the component that reserves the RAM memory for the shared memory regions used by the Modem library. For more information, see Partition manager integration.
When using the Modem library in nRF Connect SDK, the library must be initialized and shutdown using the nrf_modem_lib_init()
and nrf_modem_lib_shutdown()
function calls, respectively.
3.2. AT Host and AT Shell
The AT Host and AT Shell libraries exposes the AT command interface of the cellular modem for supported devices on an external serial interface and Zephyr Shell.
AT shell is compatible with Zephyr shell and can be enabled using the
CONFIG_AT_SHELL
andCONFIG_AT_SHELL_CMD_RESPONSE_MAX_LEN
options.AT host provide a “direct“ access to the AT command interface of the cellular modem over the serial interface. It can be enabled with
CONFIG_AT_HOST_LIBRARY
option. The library will useuart0
by default. However,ncs,at-host-uart
choice in devicetree can be used to change the UART device in the following way:/ { chosen { ncs,at-host-uart = &uart1; }; };
3.3. LTE Link Control Library
The LTE link control library provides functionality to control the LTE link on an nRF91 Series SiP.
The LTE link can be controlled through library configurations and API calls to enable a range of features such as specifying the Access Point Name (APN), switching between LTE network modes (NB-IoT or LTE-M), enabling GNSS support and power saving features such as Power Saving Mode (PSM) and enhanced Discontinuous Reception (eDRX).
The library also provides functionality that enables the application to receive notifications regarding LTE link parameters such as Radio Resource Control (RRC) connection state, cell information, and the provided PSM or eDRX timer values.
To use the LTE link control library, the Modem library is required.
4. Connecting to LTE Network with nRF9151 LTE Modem
4.1. Connecting to the Network using AT Commands
The AT shell is enabled in the customized Asset Tracker v2 application by default.
Complete the following steps to connect to the LTE network using AT commands:
Reset the board and wait for the application to start:
*** Booting nRF Connect SDK v2.8.0-e3db2104b81d *** *** Using Zephyr OS v3.7.99-78e3b9740208 *** [00:00:00.376,617] <inf> main: Start asset_tracker_v2 v0.0-0-debug on nrf9151som (debug build)
Verify that the modem responds to AT commands:
uart:~$ at AT OK
Verify that the device is able to identify that SIM card is inserted:
uart:~$ at AT%XSIM? %XSIM: 1 OK
Read ICCID from the SIM and verify that the returned string matches the value printed on the physical card:
uart:~$ at AT%XICCID %XICCID: 89852000261099626083 OK
From the serial console, set the modem to the minimum functionality mode:
uart:~$ at AT+CFUN=0 OK
Configure the APN table:
uart:~$ at AT+CGDCONT=<cid> [,<PDP_type> [,<APN>]] OK
Where:
<cid>
- Integer, 0–10 (mandatory). Specifies a particular Packet Data Protocol (PDP) Context definition. The parameter is local to the device and is used in other PDP contextrelated commands.<PDP_type>
- String. Specifies a Packet Data Protocol type (IP
,IPV6
,IPV4V6
orNon-IP
).<APN>
- String. Access Point Name (APN).
Return the modem to the full functionality mode:
uart:~$ at AT+CFUN=1 OK
Check the network registration status and verify that the modem is connected to the cell:
uart:~$ at AT+CEREG? +CEREG: 0,5,"2F43","02FFB415",7 OK
AT+CEREG?
response syntax:+CEREG: <n>,<stat>[...]
.<stat>
value can be interpreted as follows:1 or 5 - modem is connected to the network.
2 - modem is searching for network. If
AT+CEREG?
returns this status over a prolonged period of time, it may indicate issues with the device antenna.4 - out of coverage. If
AT+CEREG?
returns this status over a prolonged period of time, it may indicate issues with the device antenna.0 or 3 may indicate SIM card issues.
Issue the
AT+CESQ
command to read the signal parameters:uart:~$ at AT+CESQ +CESQ: 99,99,255,255,26,49 OK
AT+CESQ
response syntax:+CESQ: 99,99,255,255,<rsrq>,<rsrp>
.Use the following formula to convert
<rsrq>
index to dB value:(<rsrq> / 2) – 19,5 = dB
.
Resultant value can be interpreted as follows:RSRQ > -10 dB - Good signal, no antenna issues.
-10 dB ≥ RSRQ ≥ -15 dB - Usable signal, but may indicate issues with coverage or antenna.
-15 dB ≥ RSRQ ≥ -19,5 dB - Unusable, may indicate issues with the device antenna.
Use the following formula to convert the
<rsrp>
index to the dBm value:<rsrp> - 140 = dBm
.
Resultant value can be interpreted as follows:RSRP ≥ -90 dBm - Good signal, no antenna issues.
RSRP ≥ -100 dB - Usable signal, but may indicate issues with coverage or antenna.
RSRP ≤ -110 dB - Unusable, may indicate issues with the device antenna.
For full set of AT commands for nRF9151 LTE modem refer to .
4.2. Connecting to the Network using LTE Link Control Library
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.
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.
5. Sending Modem Data to nRF Cloud
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
5.1. Validating Modem Data Integration with nRF Cloud
Check the board
uuid
from the nRF9151 console (it is assumed that the nRF Device provisioning procedure has been performed earlier):uart:~$ nrf_provisioning uuid 50343959-3733-4c71-806b-202470cee0bf
Check that the board has successfully connected to the cloud over LTE:
[00:00:02.824,615] <inf> app_event_manager: MODEM_EVT_LTE_CONNECTING [00:00:04.110,168] <inf> app_event_manager: MODEM_EVT_LTE_CELL_UPDATE [00:00:15.095,916] <inf> app_event_manager: MODEM_EVT_LTE_CONNECTED [00:00:15.234,283] <inf> cloud_module: DEVICE CERTIFICATE IS PRESENT [00:00:15.236,907] <inf> app_event_manager: CLOUD_EVT_CONNECTING [00:00:15.237,426] <inf> app_event_manager: MODEM_EVT_LTE_PSM_UPDATE [00:00:15.237,915] <inf> app_event_manager: DATA_EVT_DATE_TIME_OBTAINED [00:00:22.080,871] <inf> net_mqtt: Connect completed
Login to the nRF Cloud and go to the DEVICE MANAGEMENT / Devices page. Find the board by the
uuid
ID and open the board page.Click the Manage Cards button and check the Device Data checkbox so that the Device Data card is displayed on the board page.
In the Device Data card, check the Last connected attribute to make sure that the board has recently connected to the cloud.
From the nRF9151 console, confirm that the modem data have been read successfully:
[00:00:27.074,676] <inf> app_event_manager: MODEM_EVT_MODEM_STATIC_DATA_READY [00:00:27.110,748] <inf> app_event_manager: MODEM_EVT_MODEM_DYNAMIC_DATA_READY
Wait 110 seconds for the device data to be updated on the cloud. The default timeout of 110 seconds can be reduced for convenience: click the View Config button, then Edit Configuration. If activeMode is false then the timeout is no greater than movementResolution, otherwise, it is no greater than activeWaitTime.
From the nRF9151 console, confirm that the device data have been sent to the cloud:
[00:02:16.997,283] <inf> app_event_manager: DATA_EVT_DATA_READY [00:02:17.002,197] <inf> app_event_manager: DATA_EVT_DATA_SEND_BATCH [00:02:17.002,868] <inf> app_event_manager: CLOUD_EVT_DATA_SEND_QOS
In the Device Data card on the nRF Cloud, verify that the Reference Signal Received Power attribute has just been updated and has a proper value:
Click the Show Reference Signal Received Power card icon to see the graphical representation of the Reference Signal Received Power values on the time scale:
Click the View historical data icon and select appropriate time interval to see the signal power history.
In the Device Information card, check the other modem static and dynamic data in the Device Info and Network Info tabs.