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 GPS 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(<e_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(<e_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:
To request PSM and eDRX the following APIs must be used:
lte_lc_psm_req()
- Request PSMlte_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(<e_connected, K_FOREVER);
struct lte_lc_conn_eval_params params = {0};
err = lte_lc_conn_eval_params_get(¶ms);
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:
Additional configurations related to these features can be found in the API documentation for the link controller.
API documentation¶
include/modem/lte_lc.h
lib/lte_link_control/lte_lc.c
-
group
lte_lc
Public APIs for the LTE Link Controller.
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
¶
-
enumerator
-
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
¶
-
enumerator
-
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
¶
-
enumerator
-
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.
-
enumerator
-
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
¶
-
enumerator
-
enum
lte_lc_evt_type
¶ Values:
-
enumerator
LTE_LC_EVT_NW_REG_STATUS
¶ Event received carrying information about the modems network registration status. Payload is of type lte_lc_nw_reg_status.
-
enumerator
LTE_LC_EVT_PSM_UPDATE
¶ Event received carrying information about PSM updates. Contains PSM parameters given by the network. Payload is of type lte_lc_psm_cfg.
-
enumerator
LTE_LC_EVT_EDRX_UPDATE
¶ Event received carrying information about eDRX updates. Contains eDRX parameters given by the network. Payload is of type lte_lc_edrx_cfg.
-
enumerator
LTE_LC_EVT_RRC_UPDATE
¶ Event received carrying information about the modems RRC state. Payload is of type lte_lc_rrc_mode.
-
enumerator
LTE_LC_EVT_CELL_UPDATE
¶ Event received carrying information about the currently connected cell. Payload is of type lte_lc_cell.
-
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. Payload is of type lte_lc_lte_mode.
-
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. Payload of this event is contained in the time entry in lte_lc_evt.
-
enumerator
LTE_LC_EVT_NEIGHBOR_CELL_MEAS
¶ Event containing results from neighbor cell measurements. Payload is of type lte_lc_cells_info.
-
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. Payload is of type lte_lc_modem_sleep.
-
enumerator
LTE_LC_EVT_MODEM_SLEEP_EXIT
¶ This event will be received when the modem exits sleep. Payload is of type lte_lc_modem_sleep.
-
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. Payload is of type lte_lc_modem_sleep.
-
enumerator
-
enum
lte_lc_rrc_mode
¶ Values:
-
enumerator
LTE_LC_RRC_MODE_IDLE
¶
-
enumerator
LTE_LC_RRC_MODE_CONNECTED
¶
-
enumerator
-
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
¶
-
enumerator
-
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
¶
-
enumerator
-
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
¶
-
enumerator
Functions
-
void
lte_lc_register_handler
(lte_lc_evt_handler_t handler)¶ Register event handler for LTE events.
- Parameters
handler – Event handler. Handler is de-registered if parameter is NULL.
-
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 -EALREADY.
- Returns
Zero on success or (negative) error code otherwise.
-
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.
- Returns
Zero on success, -EPERM if the module has not been initialized, otherwise a (negative) error code.
-
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 -EALREADY. lte_lc_connect_async() should be used on subsequent calls.
- Returns
Zero on success or (negative) error code otherwise.
-
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.
- Returns
Zero on success, -EINVAL if no handler is provided and not already registered, otherwise a (negative) error code.
-
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 -EALREADY. 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.
- Returns
Zero on success, -EINVAL if no handler is provided and not already registered, otherwise a (negative) error code.
-
int
lte_lc_deinit
(void)¶ Deinitialize the LTE module, powers of the modem.
- Returns
Zero on success, -EIO if it fails.
-
int
lte_lc_offline
(void)¶ Function for sending the modem to offline mode.
- Returns
Zero on success or (negative) error code otherwise.
-
int
lte_lc_power_off
(void)¶ Function for sending the modem to power off mode.
- Returns
Zero on success or (negative) error code otherwise.
-
int
lte_lc_normal
(void)¶ Function for sending the modem to normal mode.
- Returns
Zero on success or (negative) error code otherwise.
-
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.
- Returns
Zero on success or (negative) error code otherwise.
-
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
.- Returns
Zero on success or (negative) error code otherwise.
-
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.
- Returns
Zero on success or (negative) error code otherwise.
-
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.
- Returns
Zero on success or (negative) error code otherwise.
-
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.
- Returns
Zero on success or (negative) error code otherwise.
-
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.
- Returns
Zero on success or (negative) error code otherwise.
-
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.
- Returns
Zero on success or (negative) error code otherwise.
-
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.
- Returns
Zero on success or (negative) error code otherwise.
-
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.
- Returns
Zero on success or (negative) error code otherwise.
-
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.
- Returns
Zero on success or (negative) error code otherwise.
-
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.
- Returns
Zero on success or (negative) error code otherwise.
-
int
lte_lc_func_mode_set
(enum lte_lc_func_mode mode)¶ Set the modem’s functional mode.
- Parameters
mode – Functional mode to set.
- Returns
Zero on success or (negative) error code otherwise.
-
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.
- Returns
Zero on success or (negative) error code otherwise.
-
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.
- Returns
Zero on success or (negative) error code otherwise.
-
int
lte_lc_neighbor_cell_measurement
(void)¶ 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.
- Returns
Zero on success or (negative) error code otherwise.
-
int
lte_lc_neighbor_cell_measurement_cancel
(void)¶ Cancel an ongoing neighbor cell measurement.
- Returns
Zero on success or (negative) error code otherwise.
-
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.
- Returns 0
Evaluation succeeded.
- Returns 1
Evaluation failed, no cell available.
- Returns 2
Evaluation failed, UICC not available.
- Returns 3
Evaluation failed, only barred cells available.
- Returns 4
Evaluation failed, radio busy (e.g GNSS activity)
- Returns 5
Evaluation failed, aborted due to higher priority operation.
- Returns 6
Evaluation failed, UE not registered to network.
- Returns 7
Evaluation failed, Unspecified.
- 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.
-
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.
-
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].
-
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.
-
int
-
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.
-
uint32_t
-
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 non-zero. 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.
-
enum lte_lc_rrc_mode
-
struct
lte_lc_evt
¶ - #include <lte_lc.h>
-
typedef void (*