The LTE link controller library is a layer above the nRF Modem library and provides functionality to control the LTE link on the nRF91 Series.
Enabling the library
To enable the LTE link controller library in your application, enable the following Kconfig:
CONFIG_LTE_LINK_CONTROL=yInclude the header file of the LTE link controller library in your source code.
#include <modem/lte_lc.h>Defining a callback function
One advantage of using the LTE link controller library is that it provides a callback function, allowing the library to handle connection events and notify the application automatically, so the application doesn’t need to manage this process itself.
Define the callback function lte_handler().
For this lesson and subsequent exercise, we will use the events LTE_LC_EVT_NW_REG_STATUS and LTE_LC_EVT_RRC_UPDATE.
LTE_LC_EVT_NW_REG_STATUS: This event carries information about the modem’s network registration status, which can tell us if an LTE link has been established.LTE_LC_EVT_RRC_UPDATE: This event carries information about the RRC mode, and triggers whenever the mode changes.
In the function below, we check the registration status of evt->nw_reg_status of type lte_lc_nw_reg_status and if the registration status is of type registered home or registered roaming, we log that information. We also log any change to the RRC mode, as either Connected or Idle.
static void lte_handler(const struct lte_lc_evt *const evt)
{
switch (evt->type) {
case LTE_LC_EVT_NW_REG_STATUS:
if ((evt->nw_reg_status != LTE_LC_NW_REG_REGISTERED_HOME) &&
(evt->nw_reg_status != LTE_LC_NW_REG_REGISTERED_ROAMING)) {
break;
}
LOG_INF("Network registration status: %s",
evt->nw_reg_status == LTE_LC_NW_REG_REGISTERED_HOME ?
"Connected - home network" : "Connected - roaming");
break;
case LTE_LC_EVT_RRC_UPDATE:
LOG_INF("RRC mode: %s", evt->rrc_mode == LTE_LC_RRC_MODE_CONNECTED ?
"Connected" : "Idle");
break;
default:
break;
}
}The documentation for enum lte_lc_evt_type explains all the event types in the LTE link controller library.
Initialize and connect
Connect to the LTE network using the function lte_lc_connect_async(), which has the following signature.
This function takes the callback function lte_handler() that we defined in the previous step as a parameter.
lte_lc_connect_async(lte_handler);Using a semaphore
To ensure the application doesn’t proceed with other operations until an LTE connection is established, we will add a semaphore.
Define the semaphore lte_connected using K_SEM_DEFINE().
Since this semaphore will only be taken once, after the LTE connection function is called and given once, when the LTE connection is established, we pass initial_count 0 and count_limit 1.
K_SEM_DEFINE(lte_connected, 0, 1);After initiating the LTE connection, take the semaphore using k_sem_take().
k_sem_take(lte_connected, K_FOREVER);To make sure the application doesn’t proceed until an LTE connection is established, we want to give the semaphore, using k_sem_give(), in the event handler, after the registration status is confirmed as connected, see line 9 below.
case LTE_LC_EVT_NW_REG_STATUS:
if ((evt->nw_reg_status != LTE_LC_NW_REG_REGISTERED_HOME) &&
(evt->nw_reg_status != LTE_LC_NW_REG_REGISTERED_ROAMING)) {
break;
}
LOG_INF("Network registration status: %s",
evt->nw_reg_status == LTE_LC_NW_REG_REGISTERED_HOME ?
"Connected - home network" : "Connected - roaming");
k_sem_give(lte_connected);
break;Even though we are using a semaphore to make sure the application doesn’t proceed until an LTE connection is established, this is a non-blocking method because the application can still call functions and create threads after lte_lc_connect_async() (or lte_lc_init_and_connect_async()) has been called.
Enabling power save modes
The LTE link control library supports power save modes eDRX and PSM.
To enable the functionalities and Kconfigs related to eDRX and PSM, the individual modules need to be enabled through the following two Kconfigs:
CONFIG_LTE_LC_EDRX_MODULE=y
CONFIG_LTE_LC_PSM_MODULE=yThe eDRX and PSM related functions and Kconfigs are automatically included with the library.
The recommended way of enabling power saving features is to use the following Kconfig options
CONFIG_LTE_PSM_REQ=y
CONFIG_LTE_EDRX_REQ=yLTE_LC_EVT_PSM_UPDATE: This event carries information about the PSM parameters provided by the network.LTE_LC_EVT_EDRX_UPDATE: This event carries information about the eDRX parameters provided by the network
Note
A timer value that is requested by the modem is not necessarily given by the network. The event callbacks LTE_LC_EVT_PSM_UPDATE and LTE_LC_EVT_EDRX_UPDATE contain the values that are actually decided by the network.
The following code snippet shows how you can add these events to the callback function to log the values received by the network
case LTE_LC_EVT_PSM_UPDATE:
LOG_INF("PSM parameter update: Periodic TAU: %d s, Active time: %d s",
evt->psm_cfg.tau, evt->psm_cfg.active_time);
if (evt->psm_cfg.active_time == -1){
LOG_ERR("Network rejected PSM parameters. Failed to enable PSM");
}
break;
/* STEP 9.2 - On event eDRX update, print eDRX paramters */
case LTE_LC_EVT_EDRX_UPDATE:
LOG_INF("eDRX parameter update: eDRX: %f, PTW: %f",
(double)evt->edrx_cfg.edrx, (double)evt->edrx_cfg.ptw);
break;