LTE link controller¶

API documentation

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.
rat: Requested active time

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.

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.

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>

LTE link controller¶

API documentation¶

API documentation ¶