LTE link controller

The LTE link controller library is intended to be used for simpler control of LTE connections on an nRF9160 SiP.

This library provides the API and configurations for setting up an LTE connection with definite properties. Some of the properties that can be configured are Access Point Name (APN), support for LTE modes (NB-IoT or LTE-M), support for GPS, Power Saving Mode (PSM), and extended Discontinuous Reception (eDRX) parameters. Also, the modem can be locked to use specific LTE bands by modifying the properties.

The link controller is enabled with the CONFIG_LTE_LINK_CONTROL option.

Connection to an LTE network can take some time. The connection time is mostly in the range of few seconds and can go up to a few minutes. The LTE link controller library provides both blocking and non-blocking methods of connection. This provides the user an ability to decide the best way to handle the waiting time.

An event handler can be registered with the LTE link controller library using one of the following structures:

• lte_lc_register_handler

• lte_lc_connect_async

• lte_lc_init_and_connect_async

You can thus set the event handler separately or as part of a call to a non-blocking function to establish an LTE connection.

The handler is called with events as parameters when connection parameters change. Examples of connection parameters are listed below.

• Network registration status

• PSM parameters

• eDRX parameters

• RRC mode

• Charge of currently connected LTE cell

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.

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

enum lte_lc_func_mode

Values:

enumerator LTE_LC_FUNC_MODE_POWER_OFF

enumerator LTE_LC_FUNC_MODE_NORMAL

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_OFFLINE_UICC_ON

enum lte_lc_evt_type

Values:

enumerator LTE_LC_EVT_NW_REG_STATUS

enumerator LTE_LC_EVT_PSM_UPDATE

enumerator LTE_LC_EVT_EDRX_UPDATE

enumerator LTE_LC_EVT_RRC_UPDATE

enumerator LTE_LC_EVT_CELL_UPDATE

enum lte_lc_rrc_mode

Values:

enumerator LTE_LC_RRC_MODE_IDLE

enumerator LTE_LC_RRC_MODE_CONNECTED

enum lte_lc_pdp_type

Values:

enumerator LTE_LC_PDP_TYPE_IP

enumerator LTE_LC_PDP_TYPE_IPV6

enumerator LTE_LC_PDP_TYPE_IPV4V6

enum lte_lc_pdn_auth_type

Values:

enumerator LTE_LC_PDN_AUTH_TYPE_NONE

enumerator LTE_LC_PDN_AUTH_TYPE_PAP

enumerator LTE_LC_PDN_AUTH_TYPE_CHAP

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.

Return

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.

Return

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.

Return

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.

Return

Zero on success, -EINVAL if no handler is provided and not already registered, otherwise a (negative) error code.

Parameters

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

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.

Return

Zero on success, -EINVAL if no handler is provided and not already registered, otherwise a (negative) error code.

Parameters

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

int lte_lc_deinit(void)

Deinitialize the LTE module, powers of the modem.

Return

Zero on success, -EIO if it fails.

int lte_lc_offline(void)

Function for sending the modem to offline mode.

Return

Zero on success or (negative) error code otherwise.

int lte_lc_power_off(void)

Function for sending the modem to power off mode.

Return

Zero on success or (negative) error code otherwise.

int lte_lc_normal(void)

Function for sending the modem to normal mode.

Return

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.

Return

Zero on success or (negative) error code otherwise.

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.

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

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.

Return

Zero on success or (negative) error code otherwise.

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.

int lte_lc_ptw_set(const char *ptw)

Function for setting Paging Time Window (PTW) value to be used when eDRX is requested using lte_lc_edrx_req. For reference see subclause 10.5.5.32 of 3GPP TS 24.008.

Return

Zero on success or (negative) error code otherwise.

Parameters

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

int lte_lc_edrx_param_set(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.

Return

Zero on success or (negative) error code otherwise.

Parameters

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

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.

Return

Zero on success or (negative) error code otherwise.

Parameters

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

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.

Return

Zero on success or (negative) error code otherwise.

Parameters

• value: RAI value.

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.

Return

Zero on success or (negative) error code otherwise.

Parameters

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

int lte_lc_pdp_context_set(enum lte_lc_pdp_type type, const char *apn, bool ip4_addr_alloc, bool nslpi, bool secure_pco)

Set the parameters for the default PDP context. Must be called prior to lte_lc_init or lte_lc_init_and_connect.

Return

Zero on success or (negative) error code otherwise.

Parameters

• [in] type: One of enum lte_pdp_type

• [in] apn: null terminated APN string

• [in] ip4_addr_alloc: 0 - Allocate IPV4 address via NAS signaling (default), 1 - Allocate IPV4 address via DHCP.

• [in] nslpi: 0 - NSLPI value from configuration is used (default), 1 - Value “Not configured”.

• [in] secure_pco: 0 - Protected PCO transmission is not requested (default), 1 - Protected PCO transmission is requested

int lte_lc_pdn_auth_set(enum lte_lc_pdn_auth_type auth_prot, const char *username, const char *password)

Set PDN authentication parameters for the default context. Must be called prior to lte_lc_init or lte_lc_init_and_connect.

Return

Zero on success or (negative) error code otherwise.

Parameters

• [in] auth_prot: One of enum lte_lc_pdn_auth_type

• [in] username: Null terminated username string

• [in] password: Null terminated password string

int lte_lc_nw_reg_status_get(enum lte_lc_nw_reg_status *status)

Get the current network registration status.

Return

Zero on success or (negative) error code otherwise.

Parameters

• status: Pointer for network registation status.

int lte_lc_system_mode_set(enum lte_lc_system_mode mode)

Set the modem’s system mode.

Return

Zero on success or (negative) error code otherwise.

Parameters

• mode: System mode to set.

int lte_lc_system_mode_get(enum lte_lc_system_mode *mode)

Get the modem’s system mode.

Return

Zero on success or (negative) error code otherwise.

Parameters

• mode: Pointer to system mode variable.

int lte_lc_func_mode_get(enum lte_lc_func_mode *mode)

Get the modem’s functional mode.

Return

Zero on success or (negative) error code otherwise.

Parameters

• mode: Pointer to functional mode variable.

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>

struct lte_lc_evt

#include <lte_lc.h>