LTE link control

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.

Configuration 

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

Establishing an LTE connection 

The following block of code shows how you can use the API to establish an LTE connection and get callbacks from the library:

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

/* Semaphore used to block the main thread until modem 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:
        case LTE_LC_EVT_MODEM_EVENT:
                /* Handle LTE events */
                break;

        default:
                break;
        }
}

int main(void)
{
        int err;

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

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

        k_sem_take(&lte_connected, K_FOREVER);

        /* Continue execution... */
}

The code block demonstrates how you can use the library to asynchronously set up 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 connection state
Cell information
TAU pre-warning 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 the AT commands that are documented in the nRF91x1 AT Commands Reference Guide or nRF9160 AT Commands Reference Guide depending on the SiP you are using.

Enabling power-saving features 

The recommended way of enabling power saving features is to use the Kconfig options CONFIG_LTE_PSM_REQ and CONFIG_LTE_EDRX_REQ.

PSM and eDRX can also be requested at run time using the lte_lc_psm_req() and lte_lc_edrx_req() function calls. However, calling the functions during modem initialization can lead to conflicts with the value set by the Kconfig options.

You can set the timer values requested by the modem using the following options:

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 whether 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 snippet shows a basic implementation of lte_lc_conn_eval_params_get():

...

int main(void)
{
        int err;

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

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

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

        /* Handle connection evaluation parameters... */

        /* Continue execution... */
}

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

Modem sleep and TAU pre-warning notifications 

Modem firmware v1.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 before 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 nRF91 Series SiP.

To enable modem sleep and TAU pre-warning notifications, enable the following options:

For additional configurations related to these features, see the API documentation.

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:

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 the LTE_LC_ON_CFUN macro.

Important

When the LTE_LC_ON_CFUN macro is used, the application must not call nrf_modem_at_cfun_handler_set() as that will override the handler set by the modem library integration layer.

Note

The CFUN callback is not supported with nrf_modem_at_cmd_async().

The following code snippet shows how to use the LTE_LC_ON_CFUN macro:

/* Define a 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);
}

int main(void)
{
        /* Change functional mode using the LTE link control API */
        lte_lc_func_mode_set(LTE_LC_FUNC_MODE_NORMAL);
        return 0;
}

Dependencies 

This library uses the following nRF Connect SDK library:

Modem library

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 control library.

Defines

LTE_LC_CELL_TIMING_ADVANCE_MAX: Maximum timing advance value.

LTE_LC_CELL_TIMING_ADVANCE_INVALID: Invalid timing advance value.

LTE_LC_CELL_EARFCN_MAX: Maximum EARFCN value.

LTE_LC_CELL_RSRP_INVALID: Unknown or undetectable RSRP value.

LTE_LC_CELL_RSRQ_INVALID: Unknown or undetectable RSRQ value.

LTE_LC_CELL_EUTRAN_ID_INVALID: Cell ID value not valid.

LTE_LC_CELL_EUTRAN_ID_MAX: Maximum cell ID value.

LTE_LC_CELL_TAC_INVALID: Tracking Area Code value not valid.

LTE_LC_CELL_TIME_DIFF_INVALID: Time difference not valid.

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)

Handler for LTE events.

Param evt:: [in] Event.

Enums

enum lte_lc_nw_reg_status

Network registration status.

Note

Maps directly to the registration status as returned by the AT command AT+CEREG?.

Values:

enumerator LTE_LC_NW_REG_NOT_REGISTERED: Not registered. UE is not currently searching for an operator to register to.

enumerator LTE_LC_NW_REG_REGISTERED_HOME: Registered, home network.

enumerator LTE_LC_NW_REG_SEARCHING: Not registered, but UE is currently trying to attach or searching for an operator to register to.

enumerator LTE_LC_NW_REG_REGISTRATION_DENIED: Registration denied.

enumerator LTE_LC_NW_REG_UNKNOWN: Unknown, for example out of LTE coverage.

enumerator LTE_LC_NW_REG_REGISTERED_ROAMING: Registered, roaming.

enumerator LTE_LC_NW_REG_UICC_FAIL: Not registered due to UICC failure.

enum lte_lc_system_mode

System mode.

Values:

enumerator LTE_LC_SYSTEM_MODE_LTEM: LTE-M only.

enumerator LTE_LC_SYSTEM_MODE_NBIOT: NB-IoT only.

enumerator LTE_LC_SYSTEM_MODE_GPS: GNSS only.

enumerator LTE_LC_SYSTEM_MODE_LTEM_GPS: LTE-M + GNSS.

enumerator LTE_LC_SYSTEM_MODE_NBIOT_GPS: NB-IoT + GNSS.

enumerator LTE_LC_SYSTEM_MODE_LTEM_NBIOT: LTE-M + NB-IoT.

enumerator LTE_LC_SYSTEM_MODE_LTEM_NBIOT_GPS: LTE-M + NB-IoT + GNSS.

enum lte_lc_lte_mode

LTE mode.

The values for LTE-M and NB-IoT correspond to the values for the access technology field in AT responses.

Values:

enumerator LTE_LC_LTE_MODE_NONE: None.

enumerator LTE_LC_LTE_MODE_LTEM: LTE-M.

enumerator LTE_LC_LTE_MODE_NBIOT: NB-IoT.

enum lte_lc_system_mode_preference

LTE mode preference.

If multiple LTE system modes are 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 GNSS 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 mode, used to control RF functionality in the modem.

Note

The values are mapped to modem functional modes as described in “nRF91 AT Commands - Command Reference Guide”. Refer to the AT command guide to verify whether a functional mode is supported by a given modem firmware version.

Values:

enumerator LTE_LC_FUNC_MODE_POWER_OFF

Sets the device to minimum functionality.

Disables both transmit and receive RF circuits and deactivates LTE and GNSS.

enumerator LTE_LC_FUNC_MODE_NORMAL

Sets the device to full functionality.

Both LTE and GNSS will become active if the respective system modes are enabled.

enumerator LTE_LC_FUNC_MODE_RX_ONLY

Sets the device to receive only functionality.

Can be used, for example, to evaluate connections with lte_lc_conn_eval_params_get().

Note

This mode is only supported by modem firmware versions >= 1.3.0.

enumerator LTE_LC_FUNC_MODE_OFFLINE

Sets the device to flight mode.

Disables both transmit and receive RF circuits and deactivates LTE and GNSS services.

enumerator LTE_LC_FUNC_MODE_DEACTIVATE_LTE: Deactivates LTE without shutting down GNSS services.

enumerator LTE_LC_FUNC_MODE_ACTIVATE_LTE: Activates LTE without changing GNSS.

enumerator LTE_LC_FUNC_MODE_DEACTIVATE_GNSS: Deactivates GNSS without shutting down LTE services.

enumerator LTE_LC_FUNC_MODE_ACTIVATE_GNSS: Activates GNSS without changing LTE.

enumerator LTE_LC_FUNC_MODE_DEACTIVATE_UICC: Deactivates UICC.

enumerator LTE_LC_FUNC_MODE_ACTIVATE_UICC: Activates UICC.

enumerator LTE_LC_FUNC_MODE_OFFLINE_UICC_ON: Sets the device to flight mode without shutting down UICC.

enum lte_lc_evt_type

Event type.

Values:

enumerator LTE_LC_EVT_NW_REG_STATUS

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

PSM parameters provided 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

eDRX parameters provided 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

RRC connection state.

The associated payload is the rrc_mode member of type lte_lc_rrc_mode in the event.

enumerator LTE_LC_EVT_CELL_UPDATE

Current cell.

The associated payload is the cell member of type lte_lc_cell in the event. 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

Current LTE mode.

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 some time before TAU is scheduled to occur. The time is configurable. 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

Neighbor cell measurement results.

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 some time before the modem exits sleep. The time is configurable.

The associated payload is the modem_sleep member of type lte_lc_modem_sleep in the event. The time parameter indicates the time until modem exits sleep.

enumerator LTE_LC_EVT_MODEM_SLEEP_EXIT

Modem exited from 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

Modem entered sleep.

The associated payload is the modem_sleep member of type lte_lc_modem_sleep in the event. The time parameter indicates the duration of the sleep.

enumerator LTE_LC_EVT_MODEM_EVENT

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

RRC connection state.

Values:

enumerator LTE_LC_RRC_MODE_IDLE: Idle.

enumerator LTE_LC_RRC_MODE_CONNECTED: Connected.

enum lte_lc_modem_sleep_type

Modem sleep type.

Values:

enumerator LTE_LC_MODEM_SLEEP_PSM: Power Saving Mode (PSM).

enumerator LTE_LC_MODEM_SLEEP_RF_INACTIVITY: RF inactivity, for example eDRX.

enumerator LTE_LC_MODEM_SLEEP_LIMITED_SERVICE: Limited service or out of coverage.

enumerator LTE_LC_MODEM_SLEEP_FLIGHT_MODE: Flight mode.

enumerator LTE_LC_MODEM_SLEEP_PROPRIETARY_PSM: Proprietary PSM.

Note

This type is only supported by modem firmware versions >= 2.0.0.

enum lte_lc_energy_estimate

Energy consumption estimate.

Values:

enumerator LTE_LC_ENERGY_CONSUMPTION_EXCESSIVE

Bad conditions.

Difficulties in setting up connections. Maximum number of repetitions might be needed for data.

enumerator LTE_LC_ENERGY_CONSUMPTION_INCREASED

Poor conditions.

Setting up a connection might require retries and a higher number of repetitions for data.

enumerator LTE_LC_ENERGY_CONSUMPTION_NORMAL

Normal conditions.

No repetitions for data or only a few repetitions in the worst case.

enumerator LTE_LC_ENERGY_CONSUMPTION_REDUCED

Good conditions.

Possibly very good conditions for small amounts of data.

enumerator LTE_LC_ENERGY_CONSUMPTION_EFFICIENT

Excellent conditions.

Efficient data transfer estimated also for larger amounts of data.

enum lte_lc_tau_triggered

Cell in Tracking Area Identifier list.

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: Not known.

enum lte_lc_ce_level

CE level.

Values:

enumerator LTE_LC_CE_LEVEL_0: No repetitions or a small number of repetitions.

enumerator LTE_LC_CE_LEVEL_1: Medium number of repetitions.

enumerator LTE_LC_CE_LEVEL_2: Large number of repetitions.

enumerator LTE_LC_CE_LEVEL_3: Very large number of repetitions.

enumerator LTE_LC_CE_LEVEL_UNKNOWN: Not known.

enum lte_lc_reduced_mobility_mode

Reduced mobility mode.

Values:

enumerator LTE_LC_REDUCED_MOBILITY_DEFAULT: Functionality according to the 3GPP relaxed monitoring feature.

enumerator LTE_LC_REDUCED_MOBILITY_NORDIC: Enable Nordic-proprietary reduced mobility feature.

enumerator LTE_LC_REDUCED_MOBILITY_DISABLED

Full measurements for best possible mobility.

Disable the 3GPP relaxed monitoring and Nordic-proprietary reduced mobility features.

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 AT+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.

enumerator LTE_LC_MODEM_EVT_NO_IMEI: The modem does not have an IMEI.

enumerator LTE_LC_MODEM_EVT_CE_LEVEL_0: Selected CE level in RACH procedure is 0, see 3GPP TS 36.331 for details.

Note

This event is only supported by modem firmware versions >= 2.0.0.

enumerator LTE_LC_MODEM_EVT_CE_LEVEL_1: Selected CE level in RACH procedure is 1, see 3GPP TS 36.331 for details.

Note

This event is only supported by modem firmware versions >= 2.0.0.

enumerator LTE_LC_MODEM_EVT_CE_LEVEL_2: Selected CE level in RACH procedure is 2, see 3GPP TS 36.331 for details.

Note

This event is only supported by modem firmware versions >= 2.0.0.

enumerator LTE_LC_MODEM_EVT_CE_LEVEL_3: Selected CE level in RACH procedure is 3, see 3GPP TS 36.331 for details.

Note

This event is only supported by modem firmware versions >= 2.0.0.

enum lte_lc_factory_reset_type

Type of factory reset to perform.

Values:

enumerator LTE_LC_FACTORY_RESET_ALL: Reset all modem data to factory settings.

enumerator LTE_LC_FACTORY_RESET_USER: Reset user-configurable data to factory settings.

enum lte_lc_neighbor_search_type

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

When using search types up to LTE_LC_NEIGHBOR_SEARCH_TYPE_EXTENDED_COMPLETE, the result contains parameters from current/serving cell and optionally up to CONFIG_LTE_NEIGHBOR_CELLS_MAX neighbor cells.

Result notification for Global Cell ID (GCI) search types include Cell ID, PLMN and TAC for up to gci_count (lte_lc_ncellmeas_params) surrounding cells.

Values:

enumerator LTE_LC_NEIGHBOR_SEARCH_TYPE_DEFAULT: The modem searches the network it is registered to (RPLMN) based on previous cell history.

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, in other words, 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.

Note

This search type is only supported by modem firmware versions >= 1.3.1.

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.

Note

This search type is only supported by modem firmware versions >= 1.3.1.

enumerator LTE_LC_NEIGHBOR_SEARCH_TYPE_GCI_DEFAULT: GCI search, option 1. Modem searches EARFCNs based on previous cell history.

Note

This search type is only supported by modem firmware versions >= 1.3.4.

enumerator LTE_LC_NEIGHBOR_SEARCH_TYPE_GCI_EXTENDED_LIGHT: GCI search, option 2. Modem starts with the same search method as in LTE_LC_NEIGHBOR_SEARCH_TYPE_GCI_DEFAULT. If less than gci_count cells were found, the modem performs a light search on bands that are valid for the area of the current ITU-T region.

Note

This search type is only supported by modem firmware versions >= 1.3.4.

enumerator LTE_LC_NEIGHBOR_SEARCH_TYPE_GCI_EXTENDED_COMPLETE: GCI search, option 3. Modem starts with the same search method as in LTE_LC_NEIGHBOR_SEARCH_TYPE_GCI_DEFAULT. If less than gci_count cells were found, the modem performs a complete search on all supported bands.

Note

This search type is only supported by modem firmware versions >= 1.3.4.

enum lte_lc_periodic_search_pattern_type

Search pattern type.

Values:

enumerator LTE_LC_PERIODIC_SEARCH_PATTERN_RANGE: Range search pattern.

enumerator LTE_LC_PERIODIC_SEARCH_PATTERN_TABLE: Table search pattern.

Functions

void lte_lc_register_handler(lte_lc_evt_handler_t handler)

Register handler for LTE events.

Parameters:

handler – [in] Event handler.

int lte_lc_deregister_handler(lte_lc_evt_handler_t handler)

De-register handler for LTE events.

Parameters:

handler – [in] Event handler.

Return values:

0 – if successful.
-ENXIO – if the handler was not found.
-EINVAL – if the handler was a NULL pointer.

int lte_lc_init(void)

Initialize the library and configure the modem.

Deprecated:: There is no need to call this function anymore.

Note

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

Return values:: 0 – if successful.

int lte_lc_connect(void)

Connect to LTE network.

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.
-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)

Initialize the library, configure the modem and connect to LTE network.

Deprecated:: Use lte_lc_connect instead.

The function blocks until connection is established, or the connection attempt times out.

Note

The library 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.

The function returns immediately.

Note

The library must be initialized before this function is called.

Parameters:

handler – [in] 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)

Initialize the library, configure the modem and connect to LTE network.

Deprecated:: Use lte_lc_connect_async instead.

The function returns immediately.

Note

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

Parameters:

handler – [in] 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 library and power off the modem.

Deprecated:: Use lte_lc_power_off instead.

Return values:

0 – if successful.
-EFAULT – if an AT command failed.

int lte_lc_offline(void)

Set 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)

Set 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)

Set 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)

Set modem PSM parameters.

Requested periodic TAU (RPTAU) and requested active time (RAT) are used when PSM mode is subsequently enabled using lte_lc_psm_req(). These are the requested values and network determines the final values.

For encoding of the variables, see nRF AT Commands Reference Guide, 3GPP 27.007 Ch. 7.38., and 3GPP 24.008 Ch. 10.5.7.4a and Ch. 10.5.7.3.

Parameters:

rptau – [in]
Requested periodic TAU as a null-terminated 8 character long bit field string. Set to NULL to use modem’s default value. See 3GPP 24.008 Ch. 10.5.7.4a for data format.

For example, value of 32400 s is represented as ‘00101001’.

Bits 5 to 1 represent the binary coded timer value that is multiplied by timer unit.

Bits 8 to 6 define the timer unit as follows:
- 000: 10 minutes
- 001: 1 hour
- 010: 10 hours
- 011: 2 seconds
- 100: 30 seconds
- 101: 1 minute
- 110: 320 hours
rat – [in]
Requested active time as a null-terminated string. Set to NULL to use modem’s default value. See 3GPP 24.008 Ch. 10.5.7.3 for data format.

For example, value of 120 s is represented as ‘00100010’.

Bits 5 to 1 represent the binary coded timer value that is multiplied by timer unit.

Bits 8 to 6 define the timer unit as follows:
- 000: 2 seconds
- 001: 1 minute
- 010: 6 minutes
- 111: Timer is deactivated

Return values:

0 – if successful.
-EINVAL – if an input parameter was invalid.

int lte_lc_psm_param_set_seconds(int rptau, int rat)

Set modem PSM parameters.

Requested periodic TAU (RPTAU) and requested active time (RAT) are used when PSM mode is subsequently enabled using lte_lc_psm_req(). These are the requested values and network determines the final values.

This is a convenience function to set PSM parameters in seconds while lte_lc_psm_param_set() requires the caller to encode the values. However, note that 3GPP specifications do not support all possible integer values but the encoding limits the potential values. The values are rounded up to the next possible value. There may be significant rounding up, especially when rptau is tens and hundreds of hours.

For more information about the encodings, see the description of the lte_lc_psm_param_set() function.

Parameters:

rptau – [in]
Requested periodic TAU in seconds as a non-negative integer. Range 0 - 35712000 s. Set to -1 to use modem’s default value. The given value will be rounded up to the closest possible value that is calculated by multiplying the timer unit with the timer value:
- Timer unit is one of: 2 s, 30 s, 60 s, 600 s (10 min), 3600 s (1 h), 36000 s (10 h), 1152000 s (320 h)
- Timer value range is 0-31
rat – [in]
Requested active time in seconds as a non-negative integer. Range 0 - 11160s. Set to -1 to use modem’s default value. The given value will be rounded up to the closest possible value that is calculated by multiplying the timer unit with the timer value:
- Timer unit is one of: 2 s, 30 s, 360 s (6 min)
- Timer value range is 0-31

Return values:

0 – if successful.
-EINVAL – if an input parameter was invalid.

int lte_lc_psm_req(bool enable)

Request modem to enable or disable Power Saving Mode (PSM).

PSM parameters can be set using CONFIG_LTE_PSM_REQ_FORMAT , CONFIG_LTE_PSM_REQ_RPTAU , CONFIG_LTE_PSM_REQ_RAT , CONFIG_LTE_PSM_REQ_RPTAU_SECONDS and CONFIG_LTE_PSM_REQ_RAT_SECONDS , or by calling lte_lc_psm_param_set() or lte_lc_psm_param_set_seconds().

Note

CONFIG_LTE_PSM_REQ can be set to enable PSM, which is generally sufficient. This option allows explicit disabling/enabling of PSM requesting after modem initialization. Calling this function for run-time control is possible, but it should be noted that conflicts may arise with the value set by CONFIG_LTE_PSM_REQ if it is called during modem initialization.

Parameters:

enable – [in] true to enable PSM, false to disable PSM.

Return values:

0 – if successful.
-EFAULT – if AT command failed.

int lte_lc_psm_get(int *tau, int *active_time)

Get the current PSM (Power Saving Mode) configuration.

Parameters:

tau – [out] Periodic TAU interval in seconds. A non-negative integer.
active_time – [out] Active time in seconds. A non-negative integer, or -1 if PSM 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, including the case when modem is not registered to network.

int lte_lc_proprietary_psm_req(bool enable)

Request modem to enable or disable proprietary Power Saving Mode (PSM).

The purpose of the proprietary PSM feature is to perform a PSM-like sleep when network does not allow normal PSM usage. During proprietary PSM, modem will fall to sleep in the same way than it would do if network allowed to use PSM. Sending of MO data or MO SMS will automatically wake up the modem just like if modem was in normal PSM sleep.

To use the feature, also PSM request must be enabled using CONFIG_LTE_PSM_REQ or lte_lc_psm_req().

Refer to the AT command guide for guidance and limitations of this feature.

Note

CONFIG_LTE_PROPRIETARY_PSM_REQ can be set to enable proprietary PSM, which is generally sufficient. This option allows to enable or disable proprietary PSM after modem initialization. Calling this function for run-time control is possible, but it should be noted that conflicts may arise with the value set by CONFIG_LTE_PROPRIETARY_PSM_REQ if it is called during modem initialization.

Note

This feature is only supported by modem firmware versions >= v2.0.0.

Return values:

0 – if successful.
-EFAULT – if AT command failed.

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

Set the Paging Time Window (PTW) value to be used with eDRX.

eDRX can be 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 is 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 – [in] LTE mode to which the PTW value applies.
ptw – [in] Paging Time Window value as a null-terminated string. Set to NULL to use modem’s 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)

Set the requested eDRX value.

eDRX can be requested using lte_lc_edrx_req(). eDRX value is set individually for LTE-M and NB-IoT.

For reference see 3GPP 27.007 Ch. 7.40.

Parameters:

mode – [in] LTE mode to which the eDRX value applies.
edrx – [in] eDRX value as a null-terminated string. Set to NULL to use modem’s default value.

Return values:

0 – if successful.
-EINVAL – if an input parameter was invalid.

int lte_lc_edrx_req(bool enable)

Request modem to enable or disable use of eDRX.

eDRX parameters can be set using CONFIG_LTE_EDRX_REQ_VALUE_LTE_M , CONFIG_LTE_EDRX_REQ_VALUE_NBIOT , CONFIG_LTE_PTW_VALUE_LTE_M and CONFIG_LTE_PTW_VALUE_NBIOT , or by calling lte_lc_edrx_param_set() and lte_lc_ptw_set().

For reference see 3GPP 27.007 Ch. 7.40.

Note

CONFIG_LTE_EDRX_REQ can be set to enable eDRX, which is generally sufficient. This option allows explicit disabling/enabling of eDRX requesting after modem initialization. Calling this function for run-time control is possible, but it should be noted that conflicts may arise with the value set by CONFIG_LTE_EDRX_REQ if it is called during modem initialization.

Parameters:

enable – [in] true to enable eDRX, false to disable eDRX.

Return values:

0 – if successful.
-EFAULT – if AT command failed.

int lte_lc_edrx_get(struct lte_lc_edrx_cfg *edrx_cfg)

Get the eDRX parameters currently provided by the network.

Parameters:

edrx_cfg – [out] eDRX configuration.

Return values:

0 – if successful.
-EINVAL – if input argument was invalid.
-EFAULT – if AT command failed.
-EBADMSG – if parsing of the AT command response failed.

int lte_lc_nw_reg_status_get(enum lte_lc_nw_reg_status *status)

Get the current network registration status.

Parameters:

status – [out] 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 – [in] System mode.
preference – [in] 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 – [out] System mode.
preference – [out] System mode preference. 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 – [in] Functional mode.

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 – [out] Functional mode.

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 – [out] LTE mode.

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(struct lte_lc_ncellmeas_params *params)

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, LTE connection state and requested search type, 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

This feature is only supported by modem firmware versions >= 1.3.0.

Parameters:

params – [in] Search type parameters or NULL to initiate a measurement with the default parameters. See lte_lc_ncellmeas_params for more information.

Return values:

0 – if neighbor cell measurement was successfully initiated.
-EFAULT – if AT command failed.
-EINPROGRESS – if a neighbor cell measurement is already in progress.

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 before the actual data transmission.

Parameters:

params – [out] Connection evaluation parameters.

Return values:

0 – if evaluation succeeded.
1 – if evaluation failed, no cell available.
2 – if evaluation failed, UICC not available.
3 – if evaluation failed, only barred cells available.
4 – if evaluation failed, radio busy (e.g GNSS activity).
5 – if evaluation failed, aborted due to higher priority operation.
6 – if evaluation failed, UE not registered to network.
7 – if 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 which events may be received. An event handler must be registered to receive events.

Note

This feature is only supported by modem firmware versions >= 1.3.0.

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 lte_lc_periodic_search_cfg and “nRF91 AT Commands - Command Reference Guide” for more information and in-depth explanations of periodic search configuration.

Parameters:

cfg – [in] 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.

Parameters:

cfg – [out] Periodic search configuration.

Return values:

0 – if a configuration was found and populated to the provided pointer.
-EINVAL – if input parameter was NULL.
-ENOENT – if periodic search configuration was not set.
-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.

int lte_lc_reduced_mobility_get(enum lte_lc_reduced_mobility_mode *mode)

Read the current reduced mobility mode.

Note

This feature is only supported by modem firmware versions >= 1.3.2.

Parameters:

mode – [out] Reduced mobility mode.

Return values:

0 – if a mode was found and written to the provided pointer.
-EINVAL – if input parameter was NULL.
-EFAULT – if an AT command failed.

int lte_lc_reduced_mobility_set(enum lte_lc_reduced_mobility_mode mode)

Set reduced mobility mode.

Note

This feature is only supported by modem firmware versions >= 1.3.2.

Parameters:

mode – [in] Reduced mobility mode.

Return values:

0 – if the new reduced mobility mode was accepted by the modem.
-EFAULT – if an AT command failed.

int lte_lc_factory_reset(enum lte_lc_factory_reset_type type)

Reset modem to factory settings.

This operation is allowed only when the modem is not activated.

Note

This feature is only supported by modem firmware versions >= 1.3.0.

Parameters:

type – [in] Factory reset type.

Return values:

0 – if factory reset was performed successfully.
-EFAULT – if an AT command failed.

struct lte_lc_psm_cfg

#include <lte_lc.h>

Power Saving Mode (PSM) configuration.

Public Members

int tau: Periodic Tracking Area Update interval in seconds.

int active_time: Active-time (time from RRC idle to PSM) in seconds or -1 if PSM is deactivated.

struct lte_lc_edrx_cfg

#include <lte_lc.h>

eDRX configuration.

Public Members

enum lte_lc_lte_mode mode

LTE mode for which the configuration is valid.

If the mode is LTE_LC_LTE_MODE_NONE, access technology is not using eDRX.

float edrx: eDRX interval in seconds.

float ptw: Paging time window in seconds.

struct lte_lc_ncell

#include <lte_lc.h>

Neighbor cell information.

Public Members

uint32_t earfcn: EARFCN per 3GPP TS 36.101.

int time_diff: Difference of current cell and neighbor cell measurement, in the range -99999 ms < time_diff < 99999 ms. LTE_LC_CELL_TIME_DIFF_INVALID if the value is not valid.

uint16_t phys_cell_id: Physical cell ID.

int16_t rsrp

RSRP.

Format is the same as for rsrp member of struct lte_lc_cell.

int16_t rsrq

RSRQ.

Format is the same as for rsrq member of struct lte_lc_cell.

struct lte_lc_cell

#include <lte_lc.h>

Cell information.

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 per 3GPP TS 36.101.

uint16_t timing_advance

Timing advance decimal value.

Range 0 - LTE_LC_CELL_TIMING_ADVANCE_MAX. LTE_LC_CELL_TIMING_ADVANCE_INVALID if timing advance is not valid.

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, calculated from modem boot time.

Range 0 - 18 446 744 073 709 551 614 ms.

Note

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.

Range 0 - 18 446 744 073 709 551 614 ms.

uint16_t phys_cell_id: Physical cell ID.

int16_t rsrp

RSRP.

-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
LTE_LC_CELL_RSRP_INVALID : not known or not detectable

int16_t rsrq

RSRQ.

-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
LTE_LC_CELL_RSRQ_INVALID : not known or not detectable.

struct lte_lc_cells_info

#include <lte_lc.h>

Results of neighbor cell measurements.

Public Members

struct lte_lc_cell current_cell: The current cell information is valid if the current cell ID is not set to LTE_LC_CELL_EUTRAN_ID_INVALID.

uint8_t ncells_count: Indicates whether or not the neighbor_cells contains valid neighbor cell information. If it is zero, no neighbor cells were found for the current cell.

struct lte_lc_ncell *neighbor_cells: Neighbor cells for the current cell.

uint8_t gci_cells_count: Indicates whether or not the gci_cells contains valid surrounding cell information from GCI search types (lte_lc_neighbor_search_type). If it is zero, no cells were found.

struct lte_lc_cell *gci_cells: Surrounding cells found by the GCI search types.

struct lte_lc_modem_sleep

#include <lte_lc.h>

Modem sleep information.

Public Members

enum lte_lc_modem_sleep_type type: Sleep type.

int64_t time: Sleep time in milliseconds. If this value is set to -1, the sleep is considered infinite.

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 indicates 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.

If rrc_state is LTE_LC_RRC_MODE_IDLE, the CE level is estimated based on RSRP and network configuration.

If rrc_state is LTE_LC_RRC_MODE_CONNECTED, the currently used CE level is reported.

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
LTE_LC_CELL_RSRP_INVALID : 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
LTE_LC_CELL_RSRQ_INVALID : not known or not detectable.

int16_t tx_rep

Estimated TX repetitions.

If rrc_state is LTE_LC_RRC_MODE_IDLE, this value is the initial preamble repetition level in (N)PRACH based on CE level and network configuration.

If rrc_state is LTE_LC_RRC_MODE_CONNECTED, this value is the latest physical data channel (N)PUSCH transmission repetition level.

See 3GPP TS 36.331 and 36.213 for details.

int16_t rx_rep

Estimated RX repetitions.

If rrc_state is LTE_LC_RRC_MODE_IDLE, this value is the initial random access control channel (M/NPDCCH) repetition level based on CE level and network configuration.

If rrc_state is LTE_LC_RRC_MODE_CONNECTED, this value is the latest physical data channel (N)PDSCH reception repetition level.

See 3GPP TS 36.331 and 36.213 for details.

int16_t phy_cid: Physical cell ID of evaluated cell.

int16_t band

Current band information.

0 when band information is not available.

See 3GPP TS 36.101 for details.

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

Estimated TX power in dBm.

If rrc_state is LTE_LC_RRC_MODE_IDLE, the value is for first preamble transmission in (N)PRACH.

If rrc_state is LTE_LC_RRC_MODE_CONNECTED, the value is the latest physical data channel (N)PUSCH transmission power level.

See 3GPP TS 36.101 and 36.213 for details.

int mcc: Mobile Country Code.

int mnc: Mobile Network Code.

uint32_t cell_id: E-UTRAN cell ID.

struct lte_lc_ncellmeas_params

#include <lte_lc.h>

Neighbor cell measurement initiation parameters.

Public Members

enum lte_lc_neighbor_search_type search_type: Search type, lte_lc_neighbor_search_type.

uint8_t gci_count

Maximum number of GCI cells to be searched. Integer, range: 2-15.

Current cell is counted as one cell. Mandatory with the GCI search types, ignored with other search types.

Note

GCI search types are only supported by modem firmware versions >= 1.3.4.

struct lte_lc_periodic_search_range_cfg

#include <lte_lc.h>

Configuration for periodic search of type LTE_LC_PERIODIC_SEARCH_PATTERN_RANGE.

Public Members

uint16_t initial_sleep

Sleep time between searches in the beginning of the range.

Allowed values: 0 - 65535 seconds.

uint16_t final_sleep

Sleep time 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 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.

struct lte_lc_periodic_search_table_cfg

#include <lte_lc.h>

Configuration for periodic search of type LTE_LC_PERIODIC_SEARCH_PATTERN_TABLE.

1 to 5 sleep time values for sleep between searches can be configured. It is mandatory to provide val_1, while the rest are optional. Unused values must be set to -1. After going through all values, the last value of the last search pattern is repeated, if not configured differently by the loop or return_to_pattern parameters.

Allowed values:

-1: Value unused.
0 - 65535 seconds.

Public Members

int val_1: Mandatory sleep time.

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 take effect.

Must be set to -1 if not used.

int val_4

Optional sleep time.

val_3 must be configured for this parameter to take effect.

Must be set to -1 if not used.

int val_5

Optional sleep time.

val_4 must be configured for this parameter to take effect.

Must be set to -1 if not used.

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

enum lte_lc_periodic_search_pattern_type type: Search pattern type.

struct lte_lc_periodic_search_range_cfg range: Configuration for periodic search of type ‘range’.

struct lte_lc_periodic_search_table_cfg table: Configuration for periodic search of type ‘table’.

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

Indicates if band optimization shall be used.

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>

Callback for modem functional mode changes.

struct lte_lc_evt

#include <lte_lc.h>

LTE event.

Public Members

enum lte_lc_evt_type type: Event type.

enum lte_lc_nw_reg_status nw_reg_status: Payload for event LTE_LC_EVT_NW_REG_STATUS.

enum lte_lc_rrc_mode rrc_mode: Payload for event LTE_LC_EVT_RRC_UPDATE.

struct lte_lc_psm_cfg psm_cfg: Payload for event LTE_LC_EVT_PSM_UPDATE.

struct lte_lc_edrx_cfg edrx_cfg: Payload for event LTE_LC_EVT_EDRX_UPDATE.

struct lte_lc_cell cell: Payload for event LTE_LC_EVT_CELL_UPDATE.

enum lte_lc_lte_mode lte_mode: Payload for event LTE_LC_EVT_LTE_MODE_UPDATE.

struct lte_lc_modem_sleep modem_sleep: Payload for events LTE_LC_EVT_MODEM_SLEEP_EXIT_PRE_WARNING, LTE_LC_EVT_MODEM_SLEEP_EXIT and LTE_LC_EVT_MODEM_SLEEP_ENTER.

enum lte_lc_modem_evt modem_evt: Payload for event LTE_LC_EVT_MODEM_EVENT.

uint64_t time

Payload for event LTE_LC_EVT_TAU_PRE_WARNING.

Time until next Tracking Area Update in milliseconds.

struct lte_lc_cells_info cells_info: Payload for event LTE_LC_EVT_NEIGHBOR_CELL_MEAS.