lte_lc.h

Go to the documentation of this file.

/*
 * Copyright (c) 2018 Nordic Semiconductor ASA
 *
 * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
 */
 
#ifndef LTE_LC_H__
#define LTE_LC_H__
 
#include <stdbool.h>
#include <stdint.h>
#include <zephyr/kernel.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
enum lte_lc_nw_reg_status {
        LTE_LC_NW_REG_NOT_REGISTERED            = 0,
 
        LTE_LC_NW_REG_REGISTERED_HOME           = 1,
 
        LTE_LC_NW_REG_SEARCHING                 = 2,
 
        LTE_LC_NW_REG_REGISTRATION_DENIED       = 3,
 
        LTE_LC_NW_REG_UNKNOWN                   = 4,
 
        LTE_LC_NW_REG_REGISTERED_ROAMING        = 5,
 
        LTE_LC_NW_REG_UICC_FAIL                 = 90
};
 
enum lte_lc_system_mode {
        LTE_LC_SYSTEM_MODE_LTEM = 1,
 
        LTE_LC_SYSTEM_MODE_NBIOT,
 
        LTE_LC_SYSTEM_MODE_GPS,
 
        LTE_LC_SYSTEM_MODE_LTEM_GPS,
 
        LTE_LC_SYSTEM_MODE_NBIOT_GPS,
 
        LTE_LC_SYSTEM_MODE_LTEM_NBIOT,
 
        LTE_LC_SYSTEM_MODE_LTEM_NBIOT_GPS,
};
 
enum lte_lc_lte_mode {
        LTE_LC_LTE_MODE_NONE    = 0,
 
        LTE_LC_LTE_MODE_LTEM    = 7,
 
        LTE_LC_LTE_MODE_NBIOT   = 9,
};
 
enum lte_lc_system_mode_preference {
        LTE_LC_SYSTEM_MODE_PREFER_AUTO = 0,
 
        LTE_LC_SYSTEM_MODE_PREFER_LTEM,
 
        LTE_LC_SYSTEM_MODE_PREFER_NBIOT,
 
        LTE_LC_SYSTEM_MODE_PREFER_LTEM_PLMN_PRIO,
 
        LTE_LC_SYSTEM_MODE_PREFER_NBIOT_PLMN_PRIO
};
 
enum lte_lc_func_mode {
        LTE_LC_FUNC_MODE_POWER_OFF              = 0,
 
        LTE_LC_FUNC_MODE_NORMAL                 = 1,
 
        LTE_LC_FUNC_MODE_RX_ONLY                = 2,
 
        LTE_LC_FUNC_MODE_OFFLINE                = 4,
 
        LTE_LC_FUNC_MODE_DEACTIVATE_LTE         = 20,
 
        LTE_LC_FUNC_MODE_ACTIVATE_LTE           = 21,
 
        LTE_LC_FUNC_MODE_DEACTIVATE_GNSS        = 30,
 
        LTE_LC_FUNC_MODE_ACTIVATE_GNSS          = 31,
 
        LTE_LC_FUNC_MODE_DEACTIVATE_UICC        = 40,
 
        LTE_LC_FUNC_MODE_ACTIVATE_UICC          = 41,
 
        LTE_LC_FUNC_MODE_OFFLINE_UICC_ON        = 44,
};
 
enum lte_lc_evt_type {
        LTE_LC_EVT_NW_REG_STATUS,
 
        LTE_LC_EVT_PSM_UPDATE,
 
        LTE_LC_EVT_EDRX_UPDATE,
 
        LTE_LC_EVT_RRC_UPDATE,
 
        LTE_LC_EVT_CELL_UPDATE,
 
        LTE_LC_EVT_LTE_MODE_UPDATE,
 
        LTE_LC_EVT_TAU_PRE_WARNING,
 
        LTE_LC_EVT_NEIGHBOR_CELL_MEAS,
 
        LTE_LC_EVT_MODEM_SLEEP_EXIT_PRE_WARNING,
 
        LTE_LC_EVT_MODEM_SLEEP_EXIT,
 
        LTE_LC_EVT_MODEM_SLEEP_ENTER,
 
        LTE_LC_EVT_MODEM_EVENT,
 
        LTE_LC_EVT_RAI_UPDATE,
};
 
enum lte_lc_rrc_mode {
        LTE_LC_RRC_MODE_IDLE            = 0,
 
        LTE_LC_RRC_MODE_CONNECTED       = 1,
};
 
struct lte_lc_psm_cfg {
        int tau;
 
        int active_time;
};
 
struct lte_lc_edrx_cfg {
        enum lte_lc_lte_mode mode;
 
        float edrx;
 
        float ptw;
};
 
#define LTE_LC_CELL_TIMING_ADVANCE_MAX          20512
#define LTE_LC_CELL_TIMING_ADVANCE_INVALID      65535
#define LTE_LC_CELL_EARFCN_MAX                  262143
#define LTE_LC_CELL_RSRP_INVALID                255
#define LTE_LC_CELL_RSRQ_INVALID                255
#define LTE_LC_CELL_EUTRAN_ID_INVALID           UINT32_MAX
#define LTE_LC_CELL_EUTRAN_ID_MAX               268435455
#define LTE_LC_CELL_TAC_INVALID                 UINT32_MAX
#define LTE_LC_CELL_TIME_DIFF_INVALID           0
 
struct lte_lc_ncell {
        uint32_t earfcn;
 
        int time_diff;
 
        uint16_t phys_cell_id;
 
        int16_t rsrp;
 
        int16_t rsrq;
};
 
struct lte_lc_cell {
        int mcc;
 
        int mnc;
 
        uint32_t id;
 
        uint32_t tac;
 
        uint32_t earfcn;
 
        uint16_t timing_advance;
 
        uint64_t timing_advance_meas_time;
 
        uint64_t measurement_time;
 
        uint16_t phys_cell_id;
 
        int16_t rsrp;
 
        int16_t rsrq;
};
 
 
struct lte_lc_cells_info {
        struct lte_lc_cell current_cell;
 
        uint8_t ncells_count;
 
        struct lte_lc_ncell *neighbor_cells;
 
        uint8_t gci_cells_count;
 
        struct lte_lc_cell *gci_cells;
};
 
enum lte_lc_modem_sleep_type {
        LTE_LC_MODEM_SLEEP_PSM                  = 1,
 
        LTE_LC_MODEM_SLEEP_RF_INACTIVITY        = 2,
 
        LTE_LC_MODEM_SLEEP_LIMITED_SERVICE      = 3,
 
        LTE_LC_MODEM_SLEEP_FLIGHT_MODE          = 4,
 
        LTE_LC_MODEM_SLEEP_PROPRIETARY_PSM      = 7,
};
 
struct lte_lc_modem_sleep {
        enum lte_lc_modem_sleep_type type;
 
        int64_t time;
};
 
enum lte_lc_energy_estimate {
        LTE_LC_ENERGY_CONSUMPTION_EXCESSIVE     = 5,
 
        LTE_LC_ENERGY_CONSUMPTION_INCREASED     = 6,
 
        LTE_LC_ENERGY_CONSUMPTION_NORMAL        = 7,
 
        LTE_LC_ENERGY_CONSUMPTION_REDUCED       = 8,
 
        LTE_LC_ENERGY_CONSUMPTION_EFFICIENT     = 9,
};
 
enum lte_lc_tau_triggered {
        LTE_LC_CELL_IN_TAI_LIST         = 0,
 
        LTE_LC_CELL_NOT_IN_TAI_LIST     = 1,
 
        LTE_LC_CELL_UNKNOWN             = UINT8_MAX
};
 
enum lte_lc_ce_level {
        LTE_LC_CE_LEVEL_0       = 0,
 
        LTE_LC_CE_LEVEL_1       = 1,
 
        LTE_LC_CE_LEVEL_2       = 2,
 
        LTE_LC_CE_LEVEL_3       = 3,
 
        LTE_LC_CE_LEVEL_UNKNOWN = UINT8_MAX,
};
 
enum lte_lc_reduced_mobility_mode {
        LTE_LC_REDUCED_MOBILITY_DEFAULT = 0,
 
        LTE_LC_REDUCED_MOBILITY_NORDIC = 1,
 
        LTE_LC_REDUCED_MOBILITY_DISABLED = 2,
};
 
enum lte_lc_modem_evt {
        LTE_LC_MODEM_EVT_LIGHT_SEARCH_DONE,
 
        LTE_LC_MODEM_EVT_SEARCH_DONE,
 
        LTE_LC_MODEM_EVT_RESET_LOOP,
 
        LTE_LC_MODEM_EVT_BATTERY_LOW,
 
        LTE_LC_MODEM_EVT_OVERHEATED,
 
        LTE_LC_MODEM_EVT_NO_IMEI,
 
        LTE_LC_MODEM_EVT_CE_LEVEL_0,
 
        LTE_LC_MODEM_EVT_CE_LEVEL_1,
 
        LTE_LC_MODEM_EVT_CE_LEVEL_2,
 
        LTE_LC_MODEM_EVT_CE_LEVEL_3,
};
 
enum lte_lc_factory_reset_type {
        LTE_LC_FACTORY_RESET_ALL = 0,
 
        LTE_LC_FACTORY_RESET_USER = 1,
};
 
struct lte_lc_rai_cfg {
        uint32_t cell_id;
        int mcc;
        int mnc;
        bool as_rai;
        bool cp_rai;
};
 
struct lte_lc_conn_eval_params {
        enum lte_lc_rrc_mode rrc_state;
 
        enum lte_lc_energy_estimate energy_estimate;
 
        enum lte_lc_tau_triggered tau_trig;
 
        enum lte_lc_ce_level ce_level;
 
        int earfcn;
 
        int16_t dl_pathloss;
 
        int16_t rsrp;
 
        int16_t rsrq;
 
        int16_t tx_rep;
 
        int16_t rx_rep;
 
        int16_t phy_cid;
 
        int16_t band;
 
        int16_t snr;
 
        int16_t tx_power;
 
        int mcc;
 
        int mnc;
 
        uint32_t cell_id;
};
 
enum lte_lc_neighbor_search_type {
        LTE_LC_NEIGHBOR_SEARCH_TYPE_DEFAULT = 1,
 
        LTE_LC_NEIGHBOR_SEARCH_TYPE_EXTENDED_LIGHT = 2,
 
        LTE_LC_NEIGHBOR_SEARCH_TYPE_EXTENDED_COMPLETE = 3,
 
        LTE_LC_NEIGHBOR_SEARCH_TYPE_GCI_DEFAULT = 4,
 
        LTE_LC_NEIGHBOR_SEARCH_TYPE_GCI_EXTENDED_LIGHT = 5,
 
        LTE_LC_NEIGHBOR_SEARCH_TYPE_GCI_EXTENDED_COMPLETE = 6,
};
 
struct lte_lc_ncellmeas_params {
        enum lte_lc_neighbor_search_type search_type;
 
        uint8_t gci_count;
};
 
 
enum lte_lc_periodic_search_pattern_type {
        LTE_LC_PERIODIC_SEARCH_PATTERN_RANGE = 0,
 
        LTE_LC_PERIODIC_SEARCH_PATTERN_TABLE = 1,
};
 
struct lte_lc_periodic_search_range_cfg {
        uint16_t initial_sleep;
 
        uint16_t final_sleep;
 
        int16_t time_to_final_sleep;
 
        int16_t pattern_end_point;
};
 
struct lte_lc_periodic_search_table_cfg {
        int val_1;
 
        int val_2;
 
        int val_3;
 
        int val_4;
 
        int val_5;
};
 
struct lte_lc_periodic_search_pattern {
        enum lte_lc_periodic_search_pattern_type type;
 
        union {
                struct lte_lc_periodic_search_range_cfg range;
 
                struct lte_lc_periodic_search_table_cfg table;
        };
};
 
struct lte_lc_periodic_search_cfg {
        bool loop;
 
        uint16_t return_to_pattern;
 
        uint16_t band_optimization;
 
        size_t pattern_count;
 
        struct lte_lc_periodic_search_pattern patterns[4];
};
 
struct lte_lc_cfun_cb {
        void (*callback)(enum lte_lc_func_mode, void *ctx);
        void *context;
};
 
#define LTE_LC_ON_CFUN(name, _callback, _context)                                                  \
        static void _callback(enum lte_lc_func_mode, void *ctx);                                   \
        STRUCT_SECTION_ITERABLE(lte_lc_cfun_cb, lte_lc_cfun_cb_##name) = {                         \
                .callback = _callback,                                                             \
                .context = _context,                                                               \
        };
 
struct lte_lc_evt {
        enum lte_lc_evt_type type;
 
        union {
                enum lte_lc_nw_reg_status nw_reg_status;
 
                enum lte_lc_rrc_mode rrc_mode;
 
                struct lte_lc_psm_cfg psm_cfg;
 
                struct lte_lc_edrx_cfg edrx_cfg;
 
                struct lte_lc_cell cell;
 
                enum lte_lc_lte_mode lte_mode;
 
                struct lte_lc_modem_sleep modem_sleep;
 
                enum lte_lc_modem_evt modem_evt;
 
                uint64_t time;
 
                struct lte_lc_cells_info cells_info;
 
                struct lte_lc_rai_cfg rai_cfg;
        };
};
 
typedef void(*lte_lc_evt_handler_t)(const struct lte_lc_evt *const evt);
 
void lte_lc_register_handler(lte_lc_evt_handler_t handler);
 
int lte_lc_deregister_handler(lte_lc_evt_handler_t handler);
 
int lte_lc_connect(void);
 
int lte_lc_connect_async(lte_lc_evt_handler_t handler);
 
int lte_lc_offline(void);
 
int lte_lc_power_off(void);
 
int lte_lc_normal(void);
 
int lte_lc_psm_param_set(const char *rptau, const char *rat);
 
int lte_lc_psm_param_set_seconds(int rptau, int rat);
 
int lte_lc_psm_req(bool enable);
 
int lte_lc_psm_get(int *tau, int *active_time);
 
int lte_lc_proprietary_psm_req(bool enable);
 
int lte_lc_ptw_set(enum lte_lc_lte_mode mode, const char *ptw);
 
int lte_lc_edrx_param_set(enum lte_lc_lte_mode mode, const char *edrx);
 
int lte_lc_edrx_req(bool enable);
 
int lte_lc_edrx_get(struct lte_lc_edrx_cfg *edrx_cfg);
 
int lte_lc_nw_reg_status_get(enum lte_lc_nw_reg_status *status);
 
int lte_lc_system_mode_set(enum lte_lc_system_mode mode,
                           enum lte_lc_system_mode_preference preference);
 
int lte_lc_system_mode_get(enum lte_lc_system_mode *mode,
                           enum lte_lc_system_mode_preference *preference);
 
int lte_lc_func_mode_set(enum lte_lc_func_mode mode);
 
int lte_lc_func_mode_get(enum lte_lc_func_mode *mode);
 
int lte_lc_lte_mode_get(enum lte_lc_lte_mode *mode);
 
int lte_lc_neighbor_cell_measurement(struct lte_lc_ncellmeas_params *params);
 
int lte_lc_neighbor_cell_measurement_cancel(void);
 
int lte_lc_conn_eval_params_get(struct lte_lc_conn_eval_params *params);
 
int lte_lc_modem_events_enable(void);
 
int lte_lc_modem_events_disable(void);
 
int lte_lc_periodic_search_set(const struct lte_lc_periodic_search_cfg *const cfg);
 
int lte_lc_periodic_search_get(struct lte_lc_periodic_search_cfg *const cfg);
 
int lte_lc_periodic_search_clear(void);
 
int lte_lc_periodic_search_request(void);
 
int lte_lc_reduced_mobility_get(enum lte_lc_reduced_mobility_mode *mode);
 
int lte_lc_reduced_mobility_set(enum lte_lc_reduced_mobility_mode mode);
 
int lte_lc_factory_reset(enum lte_lc_factory_reset_type type);
 
#ifdef __cplusplus
}
#endif
 
#endif /* LTE_LC_H__ */