lib: lte_lc: deprecate several APIs

After recent commits, lte_lc_init() has become a no-op.
This triggered a series of function to be deprecated as well.

The following are deprecated:
- lte_lc_init()
- lte_lc_init_and_connect()
- lte_lc_init_and_connect_async()
- lte_lc_deinit()

Signed-off-by: Emanuele Di Santo <[email protected]>

applications/asset_tracker_v2/src/modules/modem_module.c

@@ -84,16 +84,6 @@ NRF_MODEM_LIB_ON_INIT(asset_tracker_init_hook, on_modem_lib_init, NULL);
 
 static void on_modem_lib_init(int ret, void *ctx)
 {
-	int err;
-
-	if (ret == 0) {
-		/* LTE LC is uninitialized on every modem shutdown. */
-		err = lte_lc_init();
-		if (err) {
-			LOG_ERR("lte_lc_init, error: %d", err);
-		}
-	}
-
 	k_sem_give(&nrf_modem_initialized);
 }
 

applications/asset_tracker_v2/tests/location_module/CMakeLists.txt

@@ -18,7 +18,9 @@ cmock_handle(${ZEPHYR_NRF_MODULE_DIR}/include/app_event_manager.h)
 cmock_handle(${ZEPHYR_NRF_MODULE_DIR}/subsys/app_event_manager/app_event_manager_priv.h)
 cmock_handle(${ZEPHYR_NRF_MODULE_DIR}/include/date_time.h)
 cmock_handle(${ZEPHYR_NRF_MODULE_DIR}/include/modem/location.h)
-cmock_handle(${ZEPHYR_NRF_MODULE_DIR}/include/modem/lte_lc.h FUNC_EXCLUDE ".*(lte_lc_rai_req|lte_lc_rai_param_set)")
+cmock_handle(${ZEPHYR_NRF_MODULE_DIR}/include/modem/lte_lc.h
+	FUNC_EXCLUDE ".*(lte_lc_rai_req|lte_lc_rai_param_set)"
+	WORD_EXCLUDE "__deprecated")
 cmock_handle(${ZEPHYR_NRFXLIB_MODULE_DIR}/nrf_modem/include/nrf_modem_gnss.h)
 
 # add location_module (the unit under test)

applications/asset_tracker_v2/tests/lwm2m_codec_helpers/CMakeLists.txt

@@ -26,7 +26,9 @@ cmock_handle(${ZEPHYR_BASE}/subsys/net/lib/lwm2m/lwm2m_engine.h lwm2m)
 cmock_handle(${ZEPHYR_BASE}/include/zephyr/net/lwm2m.h lwm2m)
 cmock_handle(${ZEPHYR_NRF_MODULE_DIR}/include/net/lwm2m_client_utils.h lwm2m_client_utils)
 cmock_handle(${ZEPHYR_NRF_MODULE_DIR}/include/net/lwm2m_client_utils_location.h lwm2m_client_utils)
-cmock_handle(${ZEPHYR_NRF_MODULE_DIR}/include/modem/lte_lc.h lte_lc FUNC_EXCLUDE ".*(lte_lc_rai_req|lte_lc_rai_param_set)")
+cmock_handle(${ZEPHYR_NRF_MODULE_DIR}/include/modem/lte_lc.h lte_lc
+	FUNC_EXCLUDE ".*(lte_lc_rai_req|lte_lc_rai_param_set)"
+	WORD_EXCLUDE "__deprecated")
 cmock_handle(${ZEPHYR_NRF_MODULE_DIR}/include/date_time.h date_time)
 
 # Add Unit Under Test source files

applications/asset_tracker_v2/tests/lwm2m_integration/CMakeLists.txt

@@ -23,7 +23,9 @@ cmock_handle(${ZEPHYR_BASE}/subsys/net/lib/lwm2m/lwm2m_engine.h lwm2m)
 cmock_handle(${ZEPHYR_BASE}/include/zephyr/net/lwm2m.h lwm2m)
 cmock_handle(${ZEPHYR_NRF_MODULE_DIR}/include/net/lwm2m_client_utils.h lwm2m_client_utils)
 cmock_handle(${ZEPHYR_NRF_MODULE_DIR}/include/net/lwm2m_client_utils_location.h lwm2m_client_utils)
-cmock_handle(${ZEPHYR_NRF_MODULE_DIR}/include/modem/lte_lc.h lte_lc FUNC_EXCLUDE ".*(lte_lc_rai_req|lte_lc_rai_param_set)")
+cmock_handle(${ZEPHYR_NRF_MODULE_DIR}/include/modem/lte_lc.h lte_lc
+	FUNC_EXCLUDE ".*(lte_lc_rai_req|lte_lc_rai_param_set)"
+	WORD_EXCLUDE "__deprecated")
 
 # Add Unit Under Test source files
 target_sources(app PRIVATE ${ASSET_TRACKER_V2_DIR}/src/cloud/lwm2m_integration/lwm2m_integration.c)

doc/nrf/libraries/modem/lte_lc.rst

@@ -73,9 +73,9 @@ The following block of code shows how you can use the API to establish an LTE co
 
            printk("Connecting to LTE network. This may take a few minutes...\n");
 
-           err = lte_lc_init_and_connect_async(lte_handler);
+           err = lte_lc_connect_async(lte_handler);
            if (err) {
-                   printk("lte_lc_init_and_connect_async, error: %d\n", err);
+                   printk("lte_lc_connect_async, error: %d\n", err);
                    return 0;
            }
 
@@ -140,9 +140,9 @@ The following code block shows a basic implementation of :c:func:`lte_lc_conn_ev
 
            printk("Connecting to LTE network. This may take a few minutes...\n");
 
-           err = lte_lc_init_and_connect_async(lte_handler);
+           err = lte_lc_connect_async(lte_handler);
            if (err) {
-                   printk("lte_lc_init_and_connect_async, error: %d\n", err);
+                   printk("lte_lc_connect_async, error: %d\n", err);
                    return 0;
            }
 

doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst

@@ -417,9 +417,21 @@ DFU libraries
 Modem libraries
 ---------------
 
-* :ref:`lte_lc_readme`:
+* :ref:`lte_lc_readme` library:
 
-  * Added the :c:func:`lte_lc_psm_param_set_seconds` function and Kconfig options :kconfig:option:`LTE_PSM_REQ_FORMAT`, :kconfig:option:`CONFIG_LTE_PSM_REQ_RPTAU_SECONDS`, and :kconfig:option:`CONFIG_LTE_PSM_REQ_RAT_SECONDS` to enable setting of PSM parameters in seconds instead of using bit field strings.
+  * Added:
+
+    * The :c:func:`lte_lc_psm_param_set_seconds` function and Kconfig options :kconfig:option:`CONFIG_LTE_PSM_REQ_FORMAT`, :kconfig:option:`CONFIG_LTE_PSM_REQ_RPTAU_SECONDS`, and :kconfig:option:`CONFIG_LTE_PSM_REQ_RAT_SECONDS` to enable setting of PSM parameters in seconds instead of using bit field strings.
+
+  * Updated:
+
+    * The :c:func:`lte_lc_init` function is deprecated.
+    * The :c:func:`lte_lc_deinit` function is deprecated.
+      Use the :c:func:`lte_lc_power_off` function instead.
+    * The :c:func:`lte_lc_init_and_connect` function is deprecated.
+      Use the :c:func:`lte_lc_connect` function instead.
+    * The :c:func:`lte_lc_init_and_connect_async` function is deprecated.
+      Use the :c:func:`lte_lc_connect_async` function instead.
 
   * Removed:
 

include/modem/lte_lc.h

@@ -1232,26 +1232,24 @@ int lte_lc_deregister_handler(lte_lc_evt_handler_t handler);
 /**
  * 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 @c 0.
  *
  * @retval 0 if successful.
- * @retval -EFAULT if an AT command failed.
  */
-int lte_lc_init(void);
+__deprecated int lte_lc_init(void);
 
 /**
  * Connect to LTE network.
  *
- * @note Before calling this function, a call to lte_lc_init() must be made, otherwise @c -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.
  *
  * @retval 0 if successful.
- * @retval -EPERM if the library was not initialized.
  * @retval -EFAULT if an AT command failed.
  * @retval -ETIMEDOUT if a connection attempt timed out before the device was
  *	   registered to a network.
@@ -1262,6 +1260,8 @@ int lte_lc_connect(void);
 /**
  * Initialize the library, configure the modem and connect to LTE network.
  *
+ * @deprecated Use @ref 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 @c 0.
@@ -1273,7 +1273,7 @@ int lte_lc_connect(void);
  *	   registered to a network.
  * @retval -EINPROGRESS if a connection establishment attempt is already in progress.
  */
-int lte_lc_init_and_connect(void);
+__deprecated int lte_lc_init_and_connect(void);
 
 /**
  * Connect to LTE network.
@@ -1294,6 +1294,8 @@ int lte_lc_connect_async(lte_lc_evt_handler_t handler);
 /**
  * Initialize the library, configure the modem and connect to LTE network.
  *
+ * @deprecated Use @ref lte_lc_connect_async instead.
+ *
  * The function returns immediately.
  *
  * @note The library can be initialized only once, and repeated calls will return @c 0.
@@ -1306,15 +1308,17 @@ int lte_lc_connect_async(lte_lc_evt_handler_t handler);
  * @retval -EFAULT if an AT command failed.
  * @retval -EINVAL if no event handler was registered.
  */
-int lte_lc_init_and_connect_async(lte_lc_evt_handler_t handler);
+__deprecated int lte_lc_init_and_connect_async(lte_lc_evt_handler_t handler);
 
 /**
  * Deinitialize the library and power off the modem.
  *
+ * @deprecated Use @ref lte_lc_power_off instead.
+ *
  * @retval 0 if successful.
  * @retval -EFAULT if an AT command failed.
  */
-int lte_lc_deinit(void);
+__deprecated int lte_lc_deinit(void);
 
 /**
  * Set the modem to offline mode.

lib/lte_link_control/lte_lc.c

@@ -57,8 +57,6 @@ enum feaconf_feat {
 
 /* Static variables */
 
-static bool is_initialized;
-
 /* Request eDRX to be disabled */
 static const char edrx_disable[] = "AT+CEDRXS=3";
 /* Default eDRX setting */
@@ -568,18 +566,6 @@ static int enable_notifications(void)
 	return 0;
 }
 
-static int init_and_config(void)
-{
-	if (is_initialized) {
-		LOG_DBG("The library is already initialized and configured");
-		return 0;
-	}
-
-	is_initialized = true;
-
-	return 0;
-}
-
 static int connect_lte(bool blocking)
 {
 	int err;
@@ -588,11 +574,6 @@ static int connect_lte(bool blocking)
 	enum lte_lc_nw_reg_status reg_status;
 	static atomic_t in_progress;
 
-	if (!is_initialized) {
-		LOG_ERR("The LTE link controller is not initialized");
-		return -EPERM;
-	}
-
 	/* Check if a connection attempt is already in progress */
 	if (atomic_set(&in_progress, 1)) {
 		return -EINPROGRESS;
@@ -680,18 +661,6 @@ static int connect_lte(bool blocking)
 	return err;
 }
 
-static int init_and_connect(void)
-{
-	int err;
-
-	err = lte_lc_init();
-	if (err) {
-		return err;
-	}
-
-	return connect_lte(true);
-}
-
 static int feaconf_write(enum feaconf_feat feat, bool state)
 {
 	return nrf_modem_at_printf("AT%%FEACONF=%d,%d,%u", FEACONF_OPER_WRITE, feat, state);
@@ -701,9 +670,7 @@ static int feaconf_write(enum feaconf_feat feat, bool state)
 
 int lte_lc_init(void)
 {
-	int err = init_and_config();
-
-	return err ? -EFAULT : 0;
+	return 0;
 }
 
 void lte_lc_register_handler(lte_lc_evt_handler_t handler)
@@ -719,10 +686,6 @@ void lte_lc_register_handler(lte_lc_evt_handler_t handler)
 
 int lte_lc_deregister_handler(lte_lc_evt_handler_t handler)
 {
-	if (!is_initialized) {
-		LOG_ERR("Module not initialized yet");
-		return -EINVAL;
-	}
 	if (handler == NULL) {
 		LOG_ERR("Invalid handler (handler=0x%08X)", (uint32_t)handler);
 		return -EINVAL;
@@ -738,7 +701,7 @@ int lte_lc_connect(void)
 
 int lte_lc_init_and_connect(void)
 {
-	return init_and_connect();
+	return connect_lte(true);
 }
 
 int lte_lc_connect_async(lte_lc_evt_handler_t handler)
@@ -755,25 +718,12 @@ int lte_lc_connect_async(lte_lc_evt_handler_t handler)
 
 int lte_lc_init_and_connect_async(lte_lc_evt_handler_t handler)
 {
-	int err;
-
-	err = init_and_config();
-	if (err) {
-		return -EFAULT;
-	}
-
 	return lte_lc_connect_async(handler);
 }
 
 int lte_lc_deinit(void)
 {
-	if (is_initialized) {
-		is_initialized = false;
-
-		return lte_lc_func_mode_set(LTE_LC_FUNC_MODE_POWER_OFF) ? -EFAULT : 0;
-	}
-
-	return 0;
+	return lte_lc_power_off();
 }
 
 int lte_lc_normal(void)

lib/lte_link_control/lte_lc_modem_hooks.c

@@ -126,5 +126,5 @@ static void on_modem_init(int err, void *ctx)
 
 static void on_modem_shutdown(void *ctx)
 {
-	(void)lte_lc_deinit();
+	(void)lte_lc_power_off();
 }

lib/nrf_modem_lib/lte_net_if/lte_net_if.c

@@ -209,13 +209,6 @@ static void connection_timeout_schedule(void)
 	}
 }
 
-static int modem_init(void)
-{
-	LOG_DBG("Initializing nRF Modem Library");
-
-	return nrf_modem_lib_init();
-}
-
 static void on_pdn_activated(void)
 {
 	int ret;
@@ -403,23 +396,8 @@ static void lte_net_if_init(struct conn_mgr_conn_binding *if_conn)
 
 int lte_net_if_enable(void)
 {
-	int ret;
-
 	if (!nrf_modem_is_initialized()) {
-		ret = modem_init();
-		if (ret) {
-			LOG_ERR("modem_init, error: %d", ret);
-			return ret;
-		}
-	}
-
-	/* Calling this function if the link controller has already been initialized is safe,
-	 * as it will return 0 in that case.
-	 */
-	ret = lte_lc_init();
-	if (ret) {
-		LOG_ERR("lte_lc_init, error: %d", ret);
-		return ret;
+		return nrf_modem_lib_init();
 	}
 
 	return 0;

samples/cellular/battery/src/main.c

@@ -89,9 +89,9 @@ static void low_level_state_update(struct k_work *item)
 	k_sem_take(&state_sem, K_FOREVER);
 
 	if (state == NORMAL_HIGH_BAT) {
-		err = lte_lc_deinit();
+		err = lte_lc_power_off();
 		if (err) {
-			printk("Modem deinitialization failed, err: %d\n", err);
+			printk("Failed to power off modem, err: %d\n", err);
 			return;
 		}
 
@@ -198,11 +198,9 @@ static int modem_init_and_connect(void)
 {
 	int err;
 
-	printk("Initializing modem and connecting...\n");
-
-	err = lte_lc_init_and_connect();
+	err = lte_lc_connect();
 	if (err) {
-		printk("Modem initialization and connect failed, err: %d\n", err);
+		printk("Failed to connect to network, err: %d\n", err);
 		return err;
 	}
 

samples/cellular/ciphersuites/src/main.c

@@ -162,7 +162,7 @@ int main(void)
 	}
 
 	printk("Waiting for network.. ");
-	err = lte_lc_init_and_connect();
+	err = lte_lc_connect();
 	if (err) {
 		printk("Failed to connect to the LTE network, err %d\n", err);
 		return 0;

samples/cellular/gnss/src/main.c

@@ -446,11 +446,6 @@ static int modem_init(void)
 		date_time_register_handler(date_time_evt_handler);
 	}
 
-	if (lte_lc_init() != 0) {
-		LOG_ERR("Failed to initialize LTE link controller");
-		return -1;
-	}
-
 #if defined(CONFIG_GNSS_SAMPLE_LTE_ON_DEMAND)
 	lte_lc_register_handler(lte_lc_event_handler);
 #elif !defined(CONFIG_GNSS_SAMPLE_ASSISTANCE_NONE)