LTE link controller

The LTE link controller library provides functionality to control the LTE link on an nRF9160 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 health parameters such as Radio Resource Control (RRC) mode, cell information, and the provided PSM or eDRX timer values.

Configuration

To enable the link controller library, set the option CONFIG_LTE_LINK_CONTROL option to y in the project configuration file prj.conf.

Establishing an LTE connection

The following block of code shows how the link controller API can be used to establish an LTE connection and get callbacks from the library:

#include <zephyr.h>
#include <modem/lte_lc.h>

/* Semaphore used to block the main thread until the link controller has
 * established an LTE connection.
 */
K_SEM_DEFINE(lte_connected, 0, 1);

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;
             }

             printk("Connected to: %s network\n",
             evt->nw_reg_status == LTE_LC_NW_REG_REGISTERED_HOME ? "home" : "roaming");

             k_sem_give(&lte_connected);
             break;
     case LTE_LC_EVT_PSM_UPDATE:
     case LTE_LC_EVT_EDRX_UPDATE:
     case LTE_LC_EVT_RRC_UPDATE:
     case LTE_LC_EVT_CELL_UPDATE:
     case LTE_LC_EVT_LTE_MODE_UPDATE:
     case LTE_LC_EVT_TAU_PRE_WARNING:
     case LTE_LC_EVT_NEIGHBOR_CELL_MEAS:
     case LTE_LC_EVT_MODEM_SLEEP_EXIT_PRE_WARNING:
     case LTE_LC_EVT_MODEM_SLEEP_EXIT:
     case LTE_LC_EVT_MODEM_SLEEP_ENTER:
             /* Callback events carrying LTE link data */
             break;
     default:
             break;
     }
}

void main(void)
{
     int err;

     printk("Connecting to LTE network. This may take a few minutes...\n");

     err = lte_lc_init_and_connect_async(lte_handler);
     if (err) {
             printk("lte_lc_init_and_connect_async, error: %d\n", err);
             return;
     }

     k_sem_take(&lte_connected, K_FOREVER);

     /* Continue execution... */
}

The code block demonstrates how the link controller can be utilized to asynchronously setup an LTE connection. For more information on the callback events received in lte_lc_evt_handler_t and data associated with each event, see the documentation on lte_lc_evt.

The following list mentions some of the information that can be extracted from the received callback events:

• Network registration status

• PSM parameters

• eDRX parameters

• RRC mode

• Cell information

• TAU prewarning notifications

• Modem sleep notifications

Note

Some of the functionalities might not be compatible with certain modem firmware versions. To check if a desired feature is compatible with a certain modem firmware version, see nRF9160 AT Commands Reference Guide.

The library supports an auto initialization and connection feature that enables the library to initialize and connect to LTE prior to the start of the application. To enable this feature, set the configuration option CONFIG_LTE_AUTO_INIT_AND_CONNECT to y. If you enable this option, you need not run additional library APIs.

Enabling power-saving features

PSM and eDRX power saving features can be requested at run time using the lte_lc_psm_req() and lte_lc_edrx_req() function calls. For an example implementation, see the following code:

/* ... */

void main(void)
{
     int err;

     err = lte_lc_init();
     if (err) {
             printk("lte_lc_init, error: %d\n", err);
             return;
     }

     err = lte_lc_psm_req(true);
     if (err) {
             printk("lte_lc_psm_req, error: %d\n", err);
             return;
     }

     err = lte_lc_edrx_req(true);
     if (err) {
             printk("lte_lc_edrx_req, error: %d\n", err);
             return;
     }

     err = lte_lc_connect_async(lte_handler);
     if (err) {
             printk("Connecting to LTE network failed, error: %d\n", err);
             return;
     }

     /* ... */
}

The recommended way of enabling power saving features is to request the respective feature before establishing an LTE connection. In this approach, the modem includes the requested power saving timers in the initial LTE network ATTACH instead of requesting the timer values after establishing an LTE connection. This saves the overhead related to the additional packet exchange.

The timer values requested by the modem can be configured with the following options and API calls:

• CONFIG_LTE_PSM_REQ_RPTAU

• CONFIG_LTE_PSM_REQ_RAT

• CONFIG_LTE_EDRX_REQ_VALUE_LTE_M

• CONFIG_LTE_EDRX_REQ_VALUE_NBIOT

• lte_lc_psm_param_set()

• lte_lc_edrx_param_set()

To request PSM and eDRX the following APIs must be used:

• lte_lc_psm_req() - Request PSM

• lte_lc_edrx_req() - Request eDRX

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.

Connection pre-evaluation

Modem firmware version 1.3.0 and higher supports connection a pre-evaluation feature that allows the application to get information about a cell that is likely to be used for an RRC connection. Based on the parameters received in the function call, the application can decide if it needs to send application data or not. The function lte_lc_conn_eval_params_get() populates a structure of type lte_lc_conn_eval_params that includes information on the current consumption cost by the data transmission when utilizing the given cell. The following code block shows a basic implementation of lte_lc_conn_eval_params_get():

...

void main(void)
{
     int err;

     printk("Connecting to LTE network. This may take a few minutes...\n");

     err = lte_lc_init_and_connect_async(lte_handler);
     if (err) {
             printk("lte_lc_init_and_connect_async, error: %d\n", err);
             return;
     }

     k_sem_take(&lte_connected, K_FOREVER);

     struct lte_lc_conn_eval_params params = {0};

     err = lte_lc_conn_eval_params_get(&params);
     if (err) {
             printk("lte_lc_conn_eval_params_get, error: %d\n", err);
             return;
     }

     /* Handle connection evaluation parameters... */
     /* Continue execution... */
}

lte_lc_conn_eval_params lists all information that is available when performing connection pre-evaluation.

Modem sleep and TAU prewarning notifications

Modem firmware version 1.3.0 and higher supports receiving callbacks from the modem related to Tracking Area Updates (TAU) and modem sleep. Based on these notifications, the application can alter its behavior to optimize for a given metric. For instance, TAU pre-warning notifications can be used to schedule data transfers prior to a TAU so that data transfer and TAU occurs within the same RRC connection window, thereby saving the potential overhead associated with the additional data exchange. Modem sleep notifications can be used to schedule processing in the same operational window as the modem to limit the overall computation time of the nRF9160 SiP. To enable modem sleep and TAU pre-warning notifications, enable the following options:

• CONFIG_LTE_LC_MODEM_SLEEP_NOTIFICATIONS

• CONFIG_LTE_LC_TAU_PRE_WARNING_NOTIFICATIONS

Additional configurations related to these features can be found in the API documentation for the link controller.

Connection fallback mode

It is possible to try to switch between LTE-M and NB-IoT after a certain time period if a connection has not been established. This is useful when the connection to either of these networks becomes unavailable. You can also configure the switching period between the network modes. If a connection cannot be established by using the fallback mode, the library reports an error. You can use the following configuration options to configure the connection fallback mode:

• CONFIG_LTE_NETWORK_USE_FALLBACK

• CONFIG_LTE_NETWORK_TIMEOUT

Functional mode changes callback

The library allows the application to define compile-time callbacks to receive the modem’s functional mode changes. These callbacks allow any part of the application to perform certain operations when the modem enters or re-enters a certain functional mode using the library lte_lc_func_mode_set() API. For example, one kind of operation that the application or a library may need to perform and repeat, whenever the modem enters a certain functional mode is the subscription to AT notifications. The application can set up a callback for modem`s functional mode changes using LTE_LC_ON_CFUN macro.

The following code snippet shows how to use LTE_LC_ON_CFUN macro:

/* define callback */
LTE_LC_ON_CFUN(cfun_hook, on_cfun, NULL);

/* callback implementation */
static void on_cfun(enum lte_lc_func_mode mode, void *context)
{
    printk("Functional mode changed to %d\n", mode);
}

void main(void)
{
    /* change functional mode using the Link Controller API */
    lte_lc_func_mode_set(LTE_LC_FUNC_MODE_NORMAL);
}

API documentation

Header file: include/modem/lte_lc.h

Source file: lib/lte_link_control/lte_lc.c

group lte_lc

Public APIs for the LTE Link Controller.

Defines

LTE_LC_CELL_TIMING_ADVANCE_MAX

LTE_LC_CELL_TIMING_ADVANCE_INVALID

LTE_LC_CELL_EARFCN_MAX

LTE_LC_CELL_RSRP_INVALID

LTE_LC_CELL_RSRQ_INVALID

LTE_LC_CELL_EUTRAN_ID_INVALID

LTE_LC_CELL_EUTRAN_ID_MAX

LTE_LC_ON_CFUN(name, _callback, _context)

Define a callback for functional mode changes through lte_lc_func_mode_set.

Parameters

• name – Callback name

• _callback – Callback function

• _context – User-defined context

Typedefs

typedef void (*lte_lc_evt_handler_t)(const struct lte_lc_evt *const evt)

Enums

enum lte_lc_nw_reg_status

Values:

enumerator LTE_LC_NW_REG_NOT_REGISTERED

enumerator LTE_LC_NW_REG_REGISTERED_HOME

enumerator LTE_LC_NW_REG_SEARCHING

enumerator LTE_LC_NW_REG_REGISTRATION_DENIED

enumerator LTE_LC_NW_REG_UNKNOWN

enumerator LTE_LC_NW_REG_REGISTERED_ROAMING

enumerator LTE_LC_NW_REG_REGISTERED_EMERGENCY

enumerator LTE_LC_NW_REG_UICC_FAIL

enum lte_lc_system_mode

Values:

enumerator LTE_LC_SYSTEM_MODE_NONE

enumerator LTE_LC_SYSTEM_MODE_LTEM

enumerator LTE_LC_SYSTEM_MODE_NBIOT

enumerator LTE_LC_SYSTEM_MODE_GPS

enumerator LTE_LC_SYSTEM_MODE_LTEM_GPS

enumerator LTE_LC_SYSTEM_MODE_NBIOT_GPS

enumerator LTE_LC_SYSTEM_MODE_LTEM_NBIOT

enumerator LTE_LC_SYSTEM_MODE_LTEM_NBIOT_GPS

enum lte_lc_lte_mode

LTE mode. The values for LTE-M and NB-IoT correspond to the values for the AcT field in an AT+CEREG response.

Values:

enumerator LTE_LC_LTE_MODE_NONE

enumerator LTE_LC_LTE_MODE_LTEM

enumerator LTE_LC_LTE_MODE_NBIOT

enum lte_lc_system_mode_preference

LTE mode preference. If more than one LTE system mode is enabled, the modem can select the mode that best meets the criteria set by this configuration. The LTE mode preference does not affect the way GPS operates.

Note that there’s a distinction between preferred and prioritized mode.

Values:

enumerator LTE_LC_SYSTEM_MODE_PREFER_AUTO

No LTE preference, automatically selected by the modem.

enumerator LTE_LC_SYSTEM_MODE_PREFER_LTEM

LTE-M is preferred over PLMN selection. The modem will prioritize to use LTE-M and switch over to a PLMN where LTE-M is available whenever possible.

enumerator LTE_LC_SYSTEM_MODE_PREFER_NBIOT

NB-IoT is preferred over PLMN selection. The modem will prioritize to use NB-IoT and switch over to a PLMN where NB-IoT is available whenever possible.

enumerator LTE_LC_SYSTEM_MODE_PREFER_LTEM_PLMN_PRIO

LTE-M is preferred, but PLMN selection is more important. The modem will prioritize to stay on home network and switch over to NB-IoT if LTE-M is not available.

enumerator LTE_LC_SYSTEM_MODE_PREFER_NBIOT_PLMN_PRIO

NB-IoT is preferred, but PLMN selection is more important. The modem will prioritize to stay on home network and switch over to LTE-M if NB-IoT is not available.

enum lte_lc_func_mode

Functional modes, used to control RF functionality in the modem.

Note

The functional modes map directly to the functional modes as described in “nRF91 AT Commands - Command Reference Guide”. Please refer to the AT command guide to verify if a functional mode is supported by a given modem firmware version.

Values:

enumerator LTE_LC_FUNC_MODE_POWER_OFF

enumerator LTE_LC_FUNC_MODE_NORMAL

enumerator LTE_LC_FUNC_MODE_RX_ONLY

enumerator LTE_LC_FUNC_MODE_OFFLINE

enumerator LTE_LC_FUNC_MODE_DEACTIVATE_LTE

enumerator LTE_LC_FUNC_MODE_ACTIVATE_LTE

enumerator LTE_LC_FUNC_MODE_DEACTIVATE_GNSS

enumerator LTE_LC_FUNC_MODE_ACTIVATE_GNSS

enumerator LTE_LC_FUNC_MODE_DEACTIVATE_UICC

enumerator LTE_LC_FUNC_MODE_ACTIVATE_UICC

enumerator LTE_LC_FUNC_MODE_OFFLINE_UICC_ON

enum lte_lc_evt_type

Values:

enumerator LTE_LC_EVT_NW_REG_STATUS

Event received carrying information about the modems network registration status. The associated payload is the nw_reg_status member of type lte_lc_nw_reg_status in the event.

enumerator LTE_LC_EVT_PSM_UPDATE

Event received carrying information about PSM updates. Contains PSM parameters given by the network. The associated payload is the psm_cfg member of type lte_lc_psm_cfg in the event.

enumerator LTE_LC_EVT_EDRX_UPDATE

Event received carrying information about eDRX updates. Contains eDRX parameters given by the network. The associated payload is the edrx_cfg member of type lte_lc_edrx_cfg in the event.

enumerator LTE_LC_EVT_RRC_UPDATE

Event received carrying information about the modems RRC state. The associated payload is the rrc_mode member of type lte_lc_rrc_mode in the event.

enumerator LTE_LC_EVT_CELL_UPDATE

Event received carrying information about the currently connected cell. The associated payload is the cell member of type lte_lc_cell in the event. Note that only the cell.tac and cell.id members are populated in the event payload. The rest are expected to be zero.

enumerator LTE_LC_EVT_LTE_MODE_UPDATE

The currently active LTE mode is updated. If a system mode that enables both LTE-M and NB-IoT is configured, the modem may change the currently active LTE mode based on the system mode preference and network availability. This event will then indicate which LTE mode is currently used by the modem. The associated payload is the lte_mode member of type lte_lc_lte_mode in the event.

enumerator LTE_LC_EVT_TAU_PRE_WARNING

Tracking Area Update pre-warning. This event will be received a configurable amount of time before TAU is scheduled to occur. This gives the application the opportunity to send data over the network before the TAU happens, thus saving power by avoiding sending data and the TAU separately. The associated payload is the time member of type uint64_t in the event.

enumerator LTE_LC_EVT_NEIGHBOR_CELL_MEAS

Event containing results from neighbor cell measurements. The associated payload is the cells_info member of type lte_lc_cells_info in the event.

enumerator LTE_LC_EVT_MODEM_SLEEP_EXIT_PRE_WARNING

Modem sleep pre-warning This event will be received a configurable amount of time before the modem exits sleep. The time parameter associated with this event signifies the time until modem exits sleep. The associated payload is the modem_sleep member of type lte_lc_modem_sleep in the event.

enumerator LTE_LC_EVT_MODEM_SLEEP_EXIT

This event will be received when the modem exits sleep. The associated payload is the modem_sleep member of type lte_lc_modem_sleep in the event.

enumerator LTE_LC_EVT_MODEM_SLEEP_ENTER

This event will be received when the modem enters sleep. The time parameter associated with this event signifies the duration of the sleep. The associated payload is the modem_sleep member of type lte_lc_modem_sleep in the event.

enumerator LTE_LC_EVT_MODEM_EVENT

Modem domain event carrying information about modem operation. The associated payload is the modem_evt member of type lte_lc_modem_evt in the event.

enum lte_lc_rrc_mode

Values:

enumerator LTE_LC_RRC_MODE_IDLE

enumerator LTE_LC_RRC_MODE_CONNECTED

enum lte_lc_modem_sleep_type

Values:

enumerator LTE_LC_MODEM_SLEEP_PSM

enumerator LTE_LC_MODEM_SLEEP_RF_INACTIVITY

enumerator LTE_LC_MODEM_SLEEP_FLIGHT_MODE

enum lte_lc_energy_estimate

Values:

enumerator LTE_LC_ENERGY_CONSUMPTION_EXCESSIVE

enumerator LTE_LC_ENERGY_CONSUMPTION_INCREASED

enumerator LTE_LC_ENERGY_CONSUMPTION_NORMAL

enumerator LTE_LC_ENERGY_CONSUMPTION_REDUCED

enumerator LTE_LC_ENERGY_CONSUMPTION_EFFICIENT

enum lte_lc_tau_triggered

Values:

enumerator LTE_LC_CELL_IN_TAI_LIST

The evaluated cell is in the Tracking Area Identifier list. When switching to this cell, a TAU will not be triggered.

enumerator LTE_LC_CELL_NOT_IN_TAI_LIST

The evaluated cell is not in the Tracking Area Identifier list. When switching to this cell, a TAU will be triggered.

enumerator LTE_LC_CELL_UNKNOWN

enum lte_lc_ce_level

Values:

enumerator LTE_LC_CE_LEVEL_0_NO_REPETITION

enumerator LTE_LC_CE_LEVEL_1_LOW_REPETITION

enumerator LTE_LC_CE_LEVEL_2_MEDIUM_REPETITION

enumerator LTE_LC_CE_LEVEL_3_LARGE_REPETITION

enumerator LTE_LC_CE_LEVEL_UNKNOWN

enum lte_lc_modem_evt

Modem domain events.

Values:

enumerator LTE_LC_MODEM_EVT_LIGHT_SEARCH_DONE

Indicates that a light search has been performed. This event gives the application the chance to stop using more power when searching networks in possibly weaker radio conditions. Before sending this event, the modem searches for cells based on previous cell history, measures the radio conditions, and makes assumptions on where networks might be deployed. This event means that the modem has not found a network that it could select based on the 3GPP network selection rules from those locations. It does not mean that there are no networks to be found in the area. The modem continues more thorough searches automatically after sending this status.

enumerator LTE_LC_MODEM_EVT_SEARCH_DONE

Indicates that a network search has been performed. The modem has found a network that it can select according to the 3GPP network selection rules or all frequencies have been scanned and a suitable cell was not found. In the latter case, the modem enters normal limited service state functionality and performs scan for service periodically.

enumerator LTE_LC_MODEM_EVT_RESET_LOOP

The modem has detected a reset loop. A reset loop indicates that the modem restricts network attach attempts for the next 30 minutes. The timer does not run when the modem has no power or while it stays in the reset loop. The modem counts all the resets where the modem is not gracefully deinitialized with +CFUN=0 or using an API performing the equivalent operation, such as setting the functional mode to LTE_LC_FUNC_MODE_POWER_OFF.

enumerator LTE_LC_MODEM_EVT_BATTERY_LOW

Battery voltage is low and the modem is therefore deactivated.

enumerator LTE_LC_MODEM_EVT_OVERHEATED

The device is overheated and the modem is therefore deactivated.

enum lte_lc_neighbor_search_type

Specifies which type of search the modem should perform when a neighbor cell measurement is started.

Values:

enumerator LTE_LC_NEIGHBOR_SEARCH_TYPE_DEFAULT

The modem searches the network it is registered to (RPLMN) based on previous cell history. For modem firmware versions < 1.3.1, this is the only valid option.

enumerator LTE_LC_NEIGHBOR_SEARCH_TYPE_EXTENDED_LIGHT

The modem starts with the same search method as the default type. If needed, it continues to search by measuring the radio conditions and makes assumptions on where networks might be deployed, i.e. a light search. The search is limited to bands that are valid for the area of the current ITU-T region. If RPLMN is not found based on previous cell history, the modem accepts any found PLMN.

enumerator LTE_LC_NEIGHBOR_SEARCH_TYPE_EXTENDED_COMPLETE

The modem follows the same procedure as for LTE_LC_NEIGHBOR_SEARCH_TYPE_EXTENDED_LIGHT, but will continue to perform a complete search instead of a light search, and the search is performed for all supported bands.

Functions

void lte_lc_register_handler(lte_lc_evt_handler_t handler)

Register event handler for LTE events.

Parameters

• handler – Event handler.

int lte_lc_deregister_handler(lte_lc_evt_handler_t handler)

Function to de-register event handler for LTE events.

Parameters

• handler – Event handler.

Return values

• 0 – If command execution was successful.

• -ENXIO – If handler cannot be found.

• -EINVAL – If handler is a NULL pointer.

int lte_lc_init(void)

Initializes the module and configures the modem.

Note

a follow-up call to lte_lc_connect() or lte_lc_connect_async() must be made to establish an LTE connection. The module can be initialized only once, and subsequent calls will return 0.

Return values

• 0 – if successful.

• -EFAULT – if an AT command failed.

int lte_lc_connect(void)

Function to make a connection with the modem.

Note

Prior to calling this function a call to lte_lc_init must be made, otherwise -EPERM is returned.

Note

After initialization, the system mode will be set to the default mode selected with Kconfig and LTE preference set to automatic selection.

Return values

• 0 – if successful.

• -EPERM – if the link controller was not initialized.

• -EFAULT – if an AT command failed.

• -ETIMEDOUT – if a connection attempt timed out before the device was registered to a network.

• -EINPROGRESS – if a connection establishment attempt is already in progress.

int lte_lc_init_and_connect(void)

Initializes the LTE module, configures the modem and connects to LTE network. The function blocks until connection is established, or the connection attempt times out.

Note

The module can be initialized only once, and repeated calls will return 0. lte_lc_connect_async() should be used on subsequent calls.

Return values

• 0 – if successful.

• -EFAULT – if an AT command failed.

• -ETIMEDOUT – if a connection attempt timed out before the device was registered to a network.

• -EINPROGRESS – if a connection establishment attempt is already in progress.

int lte_lc_connect_async(lte_lc_evt_handler_t handler)

Connect to LTE network. Non-blocking.

Note

The module must be initialized before this function is called.

Parameters

• handler – Event handler for receiving LTE events. The parameter can be NULL if an event handler is already registered.

Return values

• 0 – if successful.

• -EINVAL – if no event handler was registered.

• -EFAULT – if an AT command failed.

int lte_lc_init_and_connect_async(lte_lc_evt_handler_t handler)

Initializes the LTE module, configures the modem and connects to LTE network. Non-blocking.

Note

The module can be initialized only once, and repeated calls will return 0. lte_lc_connect() should be used on subsequent calls.

Parameters

• handler – Event handler for receiving LTE events. The parameter can be NULL if an event handler is already registered.

Return values

• 0 – if successful.

• -EFAULT – if an AT command failed.

• -EINVAL – if no event handler was registered.

int lte_lc_deinit(void)

Deinitialize the LTE module, powers of the modem.

Return values

• 0 – if successful.

• -EFAULT – if an AT command failed.

int lte_lc_offline(void)

Function for sending the modem to offline mode.

Return values

• 0 – if successful.

• -EFAULT – if the functional mode could not be configured.

int lte_lc_power_off(void)

Function for sending the modem to power off mode.

Return values

• 0 – if successful.

• -EFAULT – if the functional mode could not be configured.

int lte_lc_normal(void)

Function for sending the modem to normal mode.

Return values

• 0 – if successful.

• -EFAULT – if the functional mode could not be configured.

int lte_lc_psm_param_set(const char *rptau, const char *rat)

Function for setting modem PSM parameters: requested periodic TAU (RPTAU) and requested active time (RAT) to be used when PSM mode is subsequently enabled using lte_lc_psm_req. For reference see 3GPP 27.007 Ch. 7.38.

Parameters

• rptau – Requested periodic TAU as null-terminated string. Set NULL to use manufacturer-specific default value.

• rat – Requested active time as null-terminated string. Set NULL to use manufacturer-specific default value.

Return values

• 0 – if successful.

• -EINVAL – if an input parameter was invalid.

int lte_lc_psm_req(bool enable)

Function for requesting modem to enable or disable power saving mode (PSM) using default Kconfig value or as set using lte_lc_psm_param_set.

Return values

• 0 – if successful.

• -EFAULT – if AT command failed.

int lte_lc_psm_get(int *tau, int *active_time)

Function for getting the current PSM (Power Saving Mode) configurations for periodic TAU (Tracking Area Update) and active time, both in units of seconds.

Parameters

• tau – Pointer to the variable for parsed periodic TAU interval in seconds. Positive integer, or -1 if timer is deactivated.

• active_time – Pointer to the variable for parsed active time in seconds. Positive integer, or -1 if timer is deactivated.

Return values

• 0 – if successful.

• -EINVAL – if input argument was invalid.

• -EFAULT – if AT command failed.

• -EBADMSG – if no active time and/or TAU value was received.

int lte_lc_ptw_set(enum lte_lc_lte_mode mode, const char *ptw)

Function for setting Paging Time Window (PTW) value to be used when eDRX is requested using lte_lc_edrx_req. PTW is set individually for LTE-M and NB-IoT. Requesting a specific PTW configuration should be done with caution. The requested value must be compliant with the eDRX value that is configured, and it’s usually best to let the modem use default PTW values. For reference to which values can be set, see subclause 10.5.5.32 of 3GPP TS 24.008.

Parameters

• mode – LTE mode to which the PTW value applies.

• ptw – Paging Time Window value as null-terminated string. Set NULL to use manufacturer-specific default value.

Return values

• 0 – if successful.

• -EINVAL – if an input parameter was invalid.

int lte_lc_edrx_param_set(enum lte_lc_lte_mode mode, const char *edrx)

Function for setting modem eDRX value to be used when eDRX is subsequently enabled using lte_lc_edrx_req. For reference see 3GPP 27.007 Ch. 7.40.

Parameters

• mode – LTE mode to which the eDRX value applies.

• edrx – eDRX value as null-terminated string. Set NULL to use manufacturer-specific default.

Return values

• 0 – if successful.

• -EINVAL – if an input parameter was invalid.

int lte_lc_edrx_req(bool enable)

Function for requesting modem to enable or disable use of eDRX using values set by lte_lc_edrx_param_set. The default values are defined in kconfig. For reference see 3GPP 27.007 Ch. 7.40.

Parameters

• enable – Boolean value enabling or disabling the use of eDRX.

Return values

• 0 – if successful.

• -EFAULT – if AT command failed.

int lte_lc_rai_param_set(const char *value)

Function for setting modem RAI value to be used when RAI is subsequently enabled using lte_lc_rai_req. For reference see 3GPP 24.301 Ch. 9.9.4.25.

Parameters

• value – RAI value.

Return values

• 0 – if successful.

• -EINVAL – if an input parameter was invalid.

int lte_lc_rai_req(bool enable)

Function for requesting modem to enable or disable use of RAI using values set by lte_lc_rai_param_set. The default values are defined in Kconfig.

Parameters

• enable – Boolean value enabling or disabling the use of RAI.

Return values

• 0 – if successful.

• -EFAULT – if AT command failed.

• -EOPNOTSUPP – if RAI is not supported in the current system mode.

int lte_lc_nw_reg_status_get(enum lte_lc_nw_reg_status *status)

Get the current network registration status.

Parameters

• status – Pointer for network registration status.

Return values

• 0 – if successful.

• -EINVAL – if input argument was invalid.

• -EFAULT – if the network registration could not be retrieved from the modem.

int lte_lc_system_mode_set(enum lte_lc_system_mode mode, enum lte_lc_system_mode_preference preference)

Set the modem’s system mode and LTE preference.

Parameters

• mode – System mode to set.

• preference – System mode preference.

Return values

• 0 – if successful.

• -EINVAL – if input argument was invalid.

• -EFAULT – if the network registration could not be retrieved from the modem.

int lte_lc_system_mode_get(enum lte_lc_system_mode *mode, enum lte_lc_system_mode_preference *preference)

Get the modem’s system mode and LTE preference.

Parameters

• mode – Pointer to system mode variable.

• preference – Pointer to system mode preference variable. Can be NULL.

Return values

• 0 – if successful.

• -EINVAL – if input argument was invalid.

• -EFAULT – if the system mode could not be retrieved from the modem.

int lte_lc_func_mode_set(enum lte_lc_func_mode mode)

Set the modem’s functional mode.

Parameters

• mode – Functional mode to set.

Return values

• 0 – if successful.

• -EINVAL – if input argument was invalid.

• -EFAULT – if the functional mode could not be retrieved from the modem.

int lte_lc_func_mode_get(enum lte_lc_func_mode *mode)

Get the modem’s functional mode.

Parameters

• mode – Pointer to functional mode variable.

Return values

• 0 – if successful.

• -EINVAL – if input argument was invalid.

• -EFAULT – if the functional mode could not be retrieved from the modem.

int lte_lc_lte_mode_get(enum lte_lc_lte_mode *mode)

Get the currently active LTE mode.

Parameters

• mode – Pointer to LTE mode variable.

Return values

• 0 – if successful.

• -EINVAL – if input argument was invalid.

• -EFAULT – if the current LTE mode could not be retrieved.

• -EBADMSG – if the LTE mode was not recognized.

int lte_lc_neighbor_cell_measurement(enum lte_lc_neighbor_search_type type)

Initiate a neighbor cell measurement. The result of the measurement is reported back as an event of the type LTE_LC_EVT_NEIGHBOR_CELL_MEAS, meaning that an event handler must be registered to receive the information. Depending on the network conditions and LTE connection state, it may take a while before the measurement result is ready and reported back. After the event is received, the neighbor cell measurements are automatically stopped.

Note

For modem firmware versions < v1.3.1, LTE_LC_NEIGHBOR_SEARCH_TYPE_DEFAULT is the only accepted type. Other types will result in an error being returned.

Parameters

• type – Search type, see enum lte_lc_neighbor_search_type for more information.

Return values

• 0 – if neighbor cell measurement was successfully initiated.

• -EFAULT – if AT command failed.

int lte_lc_neighbor_cell_measurement_cancel(void)

Cancel an ongoing neighbor cell measurement.

Return values

• 0 – if neighbor cell measurement was cancelled.

• -EFAULT – if AT command failed.

int lte_lc_conn_eval_params_get(struct lte_lc_conn_eval_params *params)

Get connection evaluation parameters. Connection evaluation parameters can be used to determine the energy efficiency of data transmission prior to the actual data transmission.

Parameters

• params – Pointer to structure to hold connection evaluation parameters.

Return values

• 0 – Evaluation succeeded.

• 1 – Evaluation failed, no cell available.

• 2 – Evaluation failed, UICC not available.

• 3 – Evaluation failed, only barred cells available.

• 4 – Evaluation failed, radio busy (e.g GNSS activity)

• 5 – Evaluation failed, aborted due to higher priority operation.

• 6 – Evaluation failed, UE not registered to network.

• 7 – Evaluation failed, Unspecified.

• -EINVAL – if input argument was invalid.

• -EFAULT – if AT command failed.

• -EOPNOTSUPP – if connection evaluation is not available in the current functional mode.

• -EBADMSG – if parsing of the AT command response failed.

Returns

Zero on success, negative errno code if the API call fails, and a positive error code if the API call succeeds but connection evaluation fails due to modem/network related reasons.

int lte_lc_modem_events_enable(void)

Enable modem domain events. See lte_lc_modem_evt for more information on what events may be received.

Note

This feature is supported for nRF9160 modem firmware v1.3.0 and later versions. Attempting to use this API with older modem versions will result in an error being returned.

Note

An event handler must be registered in order to receive events.

Return values

• 0 – if successful.

• -EFAULT – if AT command failed.

int lte_lc_modem_events_disable(void)

Disable modem domain events.

Return values

• 0 – if successful.

• -EFAULT – if AT command failed.

int lte_lc_periodic_search_set(const struct lte_lc_periodic_search_cfg *const cfg)

Configure periodic searches. This configuration affects the periodic searches that the modem performs in limited service state to obtain normal service. See struct lte_lc_periodic_search_cfg and “nRF91 AT Commands - Command Reference Guide” for more information and in-depth explanations of periodic search configuration.

Return values

• 0 – if the configuration was successfully sent to the modem.

• -EINVAL – if an input parameter was NULL or contained an invalid pattern count.

• -EFAULT – if an AT command could not be sent to the modem.

• -EBADMSG – if the modem responded with an error to an AT command.

int lte_lc_periodic_search_get(struct lte_lc_periodic_search_cfg *const cfg)

Get the configured periodic search parameters.

Return values

• 0 – if a configuration was found and populated to the provided pointer.

• -EINVAL – if input parameter was NULL.

• -ENOENT – if no periodic search was not configured.

• -EFAULT – if an AT command failed.

• -EBADMSG – if the modem responded with an error to an AT command or the response could not be parsed.

int lte_lc_periodic_search_clear(void)

Clear the configured periodic search parameters.

Return values

• 0 – if the configuration was cleared.

• -EFAULT – if an AT command could not be sent to the modem.

• -EBADMSG – if the modem responded with an error to an AT command.

int lte_lc_periodic_search_request(void)

Request an extra search. This can be used for example when modem is in sleep state between periodic searches. The search is performed only when the modem is in sleep state between periodic searches.

Return values

• 0 – if the search request was successfully delivered to the modem.

• -EFAULT – if an AT command could not be sent to the modem.

struct lte_lc_psm_cfg

#include <lte_lc.h>

struct lte_lc_edrx_cfg

#include <lte_lc.h>

struct lte_lc_cell

#include <lte_lc.h>

Public Members

int mcc

Mobile Country Code.

int mnc

Mobile Network Code.

uint32_t id

E-UTRAN cell ID, range 0 - LTE_LC_CELL_EUTRAN_ID_MAX

uint32_t tac

Tracking area code.

uint32_t earfcn

EARFCN of the neighbour cell, per 3GPP TS 36.101.

uint16_t timing_advance

Timing advance decimal value. Range [0..20512, TIMING_ADVANCE_NOT_VALID = 65535].

Note: Timing advance may be reported from past measurements. The parameters timing_advance_meas_time and measurement_time can be used to evaluate if the parameter is usable.

uint64_t timing_advance_meas_time

Timing advance measurement time in milliseconds, calculated from modem boot time. Range 0 - 18 446 744 073 709 551 614 ms.

For modem firmware versions >= 1.3.1, timing advance measurement time may be reported from the modem. This means that timing advance data may now also be available in neighbor cell measurements done in RRC idle, even though the timing advance data was captured in RRC connected. If the value is not reported by the modem, it is set to 0.

uint64_t measurement_time

Measurement time of serving cell in milliseconds. Range 0 - 18 446 744 073 709 551 614 ms.

uint16_t phys_cell_id

Physical cell ID.

int16_t rsrp

RSRP of the neighbor cell. -17: RSRP < -156 dBm -16: -156 ≤ RSRP < -155 dBm … -3: -143 ≤ RSRP < -142 dBm -2: -142 ≤ RSRP < -141 dBm -1: -141 ≤ RSRP < -140 dBm 0: RSRP < -140 dBm 1: -140 ≤ RSRP < -139 dBm 2: -139 ≤ RSRP < -138 dBm … 95: -46 ≤ RSRP < -45 dBm 96: -45 ≤ RSRP < -44 dBm 97: -44 ≤ RSRP dBm 255: not known or not detectable

int16_t rsrq

RSRQ of the neighbor cell. -30: RSRQ < -34 dB -29: -34 ≤ RSRQ < -33.5 dB … -2: -20.5 ≤ RSRQ < -20 dB -1: -20 ≤ RSRQ < -19.5 dB 0: RSRQ < -19.5 dB 1: -19.5 ≤ RSRQ < -19 dB 2: -19 ≤ RSRQ < -18.5 dB … 32: -4 ≤ RSRQ < -3.5 dB 33: -3.5 ≤ RSRQ < -3 dB 34: -3 ≤ RSRQ dB 35: -3 ≤ RSRQ < -2.5 dB 36: -2.5 ≤ RSRQ < -2 dB … 45: 2 ≤ RSRQ < 2.5 dB 46: 2.5 ≤ RSRQ dB 255: not known or not detectable.

struct lte_lc_ncell

#include <lte_lc.h>

Public Members

uint32_t earfcn

EARFCN of the neighbour cell, per 3GPP TS 36.101.

int time_diff

Difference in milliseconds of serving cell and neighbor cell measurement, in the range -99999 ms < time_diff < 99999 ms.

uint16_t phys_cell_id

Physical cell ID.

int16_t rsrp

RSRP of the neighbor cell. Format is the same as for RSRP member of struct lte_lc_cell.

int16_t rsrq

RSRQ of the neighbor cell. Format is the same as for RSRQ member of struct lte_lc_cell.

struct lte_lc_cells_info

#include <lte_lc.h>

Structure containing results of neighbor cell measurements. The current cell information is valid if the current cell ID is not set to LTE_LC_CELL_EUTRAN_ID_INVALID. The ncells_count member indicates whether or not the structure contains valid neighbor cell information. If it is zero, no cells were found, and the information in the rest of structure members do not contain valid data.

struct lte_lc_modem_sleep

#include <lte_lc.h>

struct lte_lc_conn_eval_params

#include <lte_lc.h>

Connection evaluation parameters.

Note

For more information on the various connection evaluation parameters, refer to the “nRF91 AT Commands - Command Reference Guide”.

Public Members

enum lte_lc_rrc_mode rrc_state

RRC connection state during measurements.

enum lte_lc_energy_estimate energy_estimate

Relative estimated energy consumption for data transmission compared to nominal consumption.

enum lte_lc_tau_triggered tau_trig

Value that signifies if the evaluated cell is a part of the Tracking Area Identifier list received from the network.

enum lte_lc_ce_level ce_level

Coverage Enhancement level for PRACH depending on RRC state measured in.

RRC IDLE: CE level is estimated based on RSRP and network configuration.

RRC CONNECTED: Currently configured CE level.

CE levels 0-2 are supported in NB-IoT. CE levels 0-1 are supported in LTE-M.

int earfcn

EARFCN for given cell where EARFCN is per 3GPP TS 36.101.

int16_t dl_pathloss

Reduction in power density in dB.

int16_t rsrp

Current RSRP level at time of report. -17: RSRP < -156 dBm -16: -156 ≤ RSRP < -155 dBm … -3: -143 ≤ RSRP < -142 dBm -2: -142 ≤ RSRP < -141 dBm -1: -141 ≤ RSRP < -140 dBm 0: RSRP < -140 dBm 1: -140 ≤ RSRP < -139 dBm 2: -139 ≤ RSRP < -138 dBm … 95: -46 ≤ RSRP < -45 dBm 96: -45 ≤ RSRP < -44 dBm 97: -44 ≤ RSRP dBm 255: not known or not detectable

int16_t rsrq

Current RSRQ level at time of report. -30: RSRQ < -34 dB -29: -34 ≤ RSRQ < -33.5 dB … -2: -20.5 ≤ RSRQ < -20 dB -1: -20 ≤ RSRQ < -19.5 dB 0: RSRQ < -19.5 dB 1: -19.5 ≤ RSRQ < -19 dB 2: -19 ≤ RSRQ < -18.5 dB … 32: -4 ≤ RSRQ < -3.5 dB 33: -3.5 ≤ RSRQ < -3 dB 34: -3 ≤ RSRQ dB 35: -3 ≤ RSRQ < -2.5 dB 36: -2.5 ≤ RSRQ < -2 dB … 45: 2 ≤ RSRQ < 2.5 dB 46: 2.5 ≤ RSRQ dB 255: not known or not detectable.

int16_t tx_rep

Estimate of TX repetitions depending on RRC state measured in. 3GPP TS 36.331 and 36.213

RRC IDLE: Initial preamble repetition level in (N)PRACH based on CE level and network configuration.

RRC CONNECTED: Latest physical data channel (N)PUSCH transmission repetition level.

int16_t rx_rep

Estimate of RX repetitions depending on RRC state measured in. 3GPP TS 36.331 and 36.213

RRC IDLE: Initial Random Access control channel (M/NPDCCH) repetition level based on CE level and network configuration.

RRC CONNECTED: Latest physical data channel (N)PDSCH reception repetition level.

int16_t phy_cid

Physical cell ID of evaluated cell.

int16_t band

Current band information. 0 when band information is not available. 3GPP TS 36.101.

int16_t snr

Current signal-to-noise ratio at time of report. 0: SNR < -24 dB 1: -24 dB <= SNR < -23 dB 2: -23 dB <= SNR < -22 dB … 47: 22 dB <= SNR < 23 dB 48: 23 dB <= SNR < 24 dB 49: 24 dB <= SNR 127: Not known or not detectable.

int16_t tx_power

Estimate of TX power in dBm depending on RRC state measured in. 3GPP TS 36.101 and 36.213.

RRC IDLE: Estimated TX power level is for first preamble transmission in (N)PRACH).

RRC CONNECTED: Latest physical data channel (N)PUSCH transmission power level.

int mcc

Mobile Country Code.

int mnc

Mobile Network Code.

uint32_t cell_id

E-UTRAN cell ID.

struct lte_lc_periodic_search_pattern

#include <lte_lc.h>

Periodic search pattern. A search pattern may be of either ‘range’ or ‘table’ type.

Public Members

uint16_t initial_sleep

Sleep time in seconds between searches in the beginning of the range. Allowed values: 0 - 65535 seconds.

uint16_t final_sleep

Sleep time in seconds between searches in the end of the range. Allowed values: 0 - 65535 seconds.

int16_t time_to_final_sleep

Optional target time in minutes for achieving the final_sleep value. This can be used to determine angle factor between the initial and final sleep times. The timeline for the time_to_final_sleep starts from the beginning of the search pattern. If given, the value cannot be greater than the value of the pattern_end_point value in the same search pattern. If not given, the angle factor is calculated by using the pattern_end_point value so that the final_sleep value is reached at the point of pattern_end_point.

Allowed values: -1: Not used 0 - 1080 minutes

int16_t pattern_end_point

Time in minutes that must elapse before entering the next search pattern. The timeline for pattern_end_point starts from the beginning of the limited service starting point, which is the moment when the first sleep period started.

Allowed values: 0 - 1080 minutes.

int val_1

Mandatory when LTE_LC_PERIODIC_SEARCH_PATTERN_TABLE is used.

int val_2

Optional sleep time. Must be set to -1 if not used.

int val_3

Optional sleep time. val_2 must be configured for this parameter to have effect. Must be set to -1 if not used.

int val_4

Optional sleep time. val_3 must be configured for this parameter to have effect. Must be set to -1 if not used.

int val_5

Optional sleep time. val_4 must be configured for this parameter to have effect. Must be set to -1 if not used.

struct lte_lc_periodic_search_cfg

#include <lte_lc.h>

Periodic search configuration.

Public Members

bool loop

Indicates if the last given pattern is looped from the beginning when the pattern has ended. If several patterns are configured, this impacts only the last pattern.

uint16_t return_to_pattern

Indicates if the modem can return to a given search pattern with shorter sleeps, for example, when radio conditions change and the given pattern index has already been exceeded.

Allowed values: 0: No return pattern. 1 - 4: Return to search pattern index 1..4.

uint16_t band_optimization

0: No optimization. Every periodic search shall be all band search. 1: Use default optimizations predefined by modem. Predefinition depends on the active data profile. See “nRF91 AT Commands - Command Reference Guide” for more information. 2 - 20: Every n periodic search must be an all band search.

size_t pattern_count

The number of valid patterns. Range 1 - 4.

struct lte_lc_periodic_search_pattern patterns[4]

Array of periodic search patterns.

struct lte_lc_cfun_cb

#include <lte_lc.h>

Link controller callback for modem functional mode changes.

struct lte_lc_evt

#include <lte_lc.h>