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, LTE_LC_EVT_NW_REG_STATUS is the only event where the callback function executes something. This event carries information about the modem’s network registration status, which can tell us if an LTE link has been established.
In the function below, we check the registration status of evt->nw_reg_status of type lte_lc_nw_reg_status and proceed to unblock the main() function by giving the semaphore only if the registration status is of type registered home or registered roaming, indicating an LTE connection.
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");
k_sem_give(<e_connected);
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
Initialize the library with lte_lc_init(), which has the following signature.
Important
lte_lc_init() is deprecated in nRF Connect SDK v2.6.0 and higher.
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.
We will use NCS_VERSION_NUMBER to only call lte_lc_init() if the nRF Connect SDK version is less than v2.6.0.
/* lte_lc_init deprecated in >= v2.6.0 */
#if NCS_VERSION_NUMBER < 0x20600
lte_lc_init();
#endif
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(<e_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.
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("Connected to: %s network\n",
evt->nw_reg_status == LTE_LC_NW_REG_REGISTERED_HOME ? "home" : "roaming");
k_sem_give(<e_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.
