lib: lte_link_control: refactor into modules

Divides the LTE Link Controller into modules.

Signed-off-by: Mirko Covizzi <[email protected]>
Co-authored-by: divya pillai <[email protected]>

Author: 2 people

applications/asset_tracker_v2/overlay-lwm2m.conf

@@ -45,6 +45,7 @@ CONFIG_LWM2M_RD_CLIENT_STOP_POLLING_AT_IDLE=y
 CONFIG_LWM2M_QUEUE_MODE_UPTIME=30
 
 # Configure PSM mode
+CONFIG_LTE_LC_PSM_MODULE=y
 CONFIG_LTE_PSM_REQ=y
 # Request periodic TAU of 3600 seconds (60 minutes)
 CONFIG_LTE_PSM_REQ_RPTAU="00000110"
@@ -56,6 +57,7 @@ CONFIG_LTE_PSM_REQ_RPTAU="00000110"
 CONFIG_LTE_PSM_REQ_RAT="00001111"
 
 # Request eDRX mode
+CONFIG_LTE_LC_EDRX_MODULE=y
 CONFIG_LTE_EDRX_REQ=y
 
 # Requested eDRX cycle length for LTE-M and NB-IoT
@@ -76,6 +78,7 @@ CONFIG_LTE_PTW_VALUE_NBIOT="0000"
 
 # Get notification before Tracking Area Update (TAU). Notification triggers registration
 # update and TAU will be sent with the update which decreases power consumption.
+CONFIG_LTE_LC_TAU_PRE_WARNING_MODULE=y
 CONFIG_LTE_LC_TAU_PRE_WARNING_NOTIFICATIONS=y
 
 # Optimize powersaving by using tickless mode in LwM2M engine

applications/asset_tracker_v2/prj.conf

@@ -46,6 +46,11 @@ CONFIG_LTE_PSM_REQ=y
 CONFIG_LTE_PSM_REQ_RPTAU="11000001"
 ### 20 seconds active time.
 CONFIG_LTE_PSM_REQ_RAT="00001010"
+### Enable required modules
+CONFIG_LTE_LC_EDRX_MODULE=y
+CONFIG_LTE_LC_NEIGHBOR_CELL_MEAS_MODULE=y
+CONFIG_LTE_LC_PSM_MODULE=y
+CONFIG_LTE_LC_MODEM_SLEEP_MODULE=y
 
 # Settings - Used to store real-time device configuration to flash.
 CONFIG_SETTINGS=y

doc/nrf/libraries/modem/lte_lc.rst

@@ -20,6 +20,9 @@ Configuration
 
 To enable the library, set the Kconfig option :kconfig:option:`CONFIG_LTE_LINK_CONTROL` to ``y`` in the project configuration file :file:`prj.conf`.
 
+.. note::
+   By default, the library enables only the core features related to the network connectivity.
+
 Establishing an LTE connection
 ==============================
 
@@ -50,18 +53,11 @@ The following block of code shows how you can use the API to establish an LTE co
                    k_sem_give(&lte_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:
            case LTE_LC_EVT_MODEM_EVENT:
-                   /* Handle LTE events */
+                   /* Handle LTE events that are enabled by default. */
                    break;
 
            default:
@@ -87,17 +83,72 @@ The following block of code shows how you can use the API to establish an LTE co
    }
 
 The code block demonstrates how you can use the library to asynchronously set up an LTE connection.
-For more information on the callback events received in :c:type:`lte_lc_evt_handler_t` and data associated with each event, see the documentation on :c:struct:`lte_lc_evt`.
 
-The following list mentions some of the information that can be extracted from the received callback events:
+Additionally, to enable specific functionalities and receive specific events from the library, you must enable the corresponding modules through their respective Kconfig options:
+
+Connection Parameters Evaluation:
+  Use the :kconfig:option:`CONFIG_LTE_LC_CONN_EVAL_MODULE` Kconfig option to enable the following functionality related to Connection Parameters Evaluation:
+
+  * :c:func:`lte_lc_conn_eval_params_get`
+
+eDRX (Extended Discontinuous Reception):
+  Use the :kconfig:option:`CONFIG_LTE_LC_EDRX_MODULE` Kconfig option to enable all the following functionalities related to eDRX:
+
+  * :c:enumerator:`LTE_LC_EVT_EDRX_UPDATE` events
+  * :c:func:`lte_lc_ptw_set`
+  * :c:func:`lte_lc_edrx_param_set`
+  * :c:func:`lte_lc_edrx_req`
+  * :c:func:`lte_lc_edrx_get`
+  * :kconfig:option:`CONFIG_LTE_EDRX_REQ`
+
+Neighboring Cell Measurements:
+  Use the :kconfig:option:`CONFIG_LTE_LC_NEIGHBOR_CELL_MEAS_MODULE` Kconfig option to enable all the following functionalities related to Neighboring Cell Measurements:
+
+  * :c:enumerator:`LTE_LC_EVT_NEIGHBOR_CELL_MEAS` events
+  * :c:func:`lte_lc_neighbor_cell_measurement_cancel`
+  * :c:func:`lte_lc_neighbor_cell_measurement`
+
+Periodic Search Configuration:
+  Use the :kconfig:option:`CONFIG_LTE_LC_PERIODIC_SEARCH_MODULE` Kconfig option to enable all the following functionalities related to Periodic Search Configuration:
+
+  * :c:func:`lte_lc_periodic_search_request`
+  * :c:func:`lte_lc_periodic_search_clear`
+  * :c:func:`lte_lc_periodic_search_get`
+  * :c:func:`lte_lc_periodic_search_set`
 
-* Network registration status
-* PSM parameters
-* eDRX parameters
-* RRC connection state
-* Cell information
-* TAU pre-warning notifications
-* Modem sleep notifications
+PSM (Power Saving Mode):
+  Use the :kconfig:option:`CONFIG_LTE_LC_PSM_MODULE` Kconfig option to enable all the following functionalities related to PSM:
+
+  * :c:enumerator:`LTE_LC_EVT_PSM_UPDATE` events
+  * :c:func:`lte_lc_psm_param_set`
+  * :c:func:`lte_lc_psm_param_set_seconds`
+  * :c:func:`lte_lc_psm_req`
+  * :c:func:`lte_lc_psm_get`
+  * :c:func:`lte_lc_proprietary_psm_req`
+  * :kconfig:option:`CONFIG_LTE_PSM_REQ`
+
+Release Assistance Indication (RAI):
+  Use the :kconfig:option:`CONFIG_LTE_LC_RAI_MODULE` Kconfig option to enable the following functionalities related to RAI:
+
+  * :c:enumerator:`LTE_LC_EVT_RAI_UPDATE` events
+  * :kconfig:option:`CONFIG_LTE_RAI_REQ`
+
+Modem Sleep Notifications:
+  Use the :kconfig:option:`CONFIG_LTE_LC_MODEM_SLEEP_MODULE` Kconfig option to enable all the following functionalities related to Modem Sleep Notifications:
+
+  * :c:enumerator:`LTE_LC_EVT_MODEM_SLEEP_EXIT_PRE_WARNING` events
+  * :c:enumerator:`LTE_LC_EVT_MODEM_SLEEP_ENTER` events
+  * :c:enumerator:`LTE_LC_EVT_MODEM_SLEEP_EXIT` events
+  * :kconfig:option:`CONFIG_LTE_LC_MODEM_SLEEP_NOTIFICATIONS`
+
+Tracking Area Update (TAU) Pre-warning:
+  Use the :kconfig:option:`CONFIG_LTE_LC_TAU_PRE_WARNING_MODULE` Kconfig option to enable the following functionalities related to TAU Pre-warning:
+
+  * :c:enumerator:`LTE_LC_EVT_TAU_PRE_WARNING` events
+  * :kconfig:option:`CONFIG_LTE_LC_TAU_PRE_WARNING_NOTIFICATIONS`
+
+For more information on the callback events received in :c:type:`lte_lc_evt_handler_t` and data associated with each event, see the documentation on :c:struct:`lte_lc_evt`.
+For more information on the functions and data associated with each, refer to the API documentation.
 
 .. note::
    Some of the functionalities might not be compatible with certain modem firmware versions.
@@ -108,7 +159,12 @@ The following list mentions some of the information that can be extracted from t
 Enabling power-saving features
 ==============================
 
-The recommended way of enabling power saving features is to use the Kconfig options :kconfig:option:`CONFIG_LTE_PSM_REQ` and :kconfig:option:`CONFIG_LTE_EDRX_REQ`.
+To enable power-saving features, use the following options:
+
+* :kconfig:option:`CONFIG_LTE_LC_PSM_MODULE`
+* :kconfig:option:`CONFIG_LTE_LC_EDRX_MODULE`
+* :kconfig:option:`CONFIG_LTE_LC_PSM_REQ`
+* :kconfig:option:`CONFIG_LTE_LC_EDRX_REQ`
 
 PSM and eDRX can also be requested at run time using the :c:func:`lte_lc_psm_req` and :c:func:`lte_lc_edrx_req` function calls.
 However, calling the functions during modem initialization can lead to conflicts with the value set by the Kconfig options.
@@ -131,6 +187,7 @@ 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 whether to send application data or not.
+To enable this module, use the :kconfig:option:`CONFIG_LTE_LC_CONN_EVAL_MODULE` Kconfig option.
 The function :c:func:`lte_lc_conn_eval_params_get` populates a structure of type :c:struct:`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 snippet shows a basic implementation of :c:func:`lte_lc_conn_eval_params_get`:
 
@@ -177,8 +234,10 @@ For instance, TAU pre-warning notifications can be used to schedule data transfe
 
 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 nRF91 Series SiP.
 
-To enable modem sleep and TAU pre-warning notifications, enable the following options:
+To enable modem sleep and TAU pre-warning notifications, use the following options:
 
+* :kconfig:option:`CONFIG_LTE_LC_MODEM_SLEEP_MODULE`
+* :kconfig:option:`CONFIG_LTE_LC_TAU_PRE_WARNING_MODULE`
 * :kconfig:option:`CONFIG_LTE_LC_MODEM_SLEEP_NOTIFICATIONS`
 * :kconfig:option:`CONFIG_LTE_LC_TAU_PRE_WARNING_NOTIFICATIONS`
 

doc/nrf/nrf.doxyfile.in

@@ -2464,7 +2464,15 @@ PREDEFINED             = __DOXYGEN__ \
                          "CONFIG_ZIGBEE_ROLE_END_DEVICE=y" \
                          "CONFIG_ZIGBEE_FACTORY_RESET=y" \
                          "CONFIG_NRF_CLOUD_GATEWAY=y" \
-                         "CONFIG_BT_CENTRAL"
+                         "CONFIG_BT_CENTRAL" \
+                         "CONFIG_LTE_LC_CONN_EVAL_MODULE=y" \
+                         "CONFIG_LTE_LC_EDRX_MODULE=y" \
+                         "CONFIG_LTE_LC_NEIGHBOR_CELL_MEAS_MODULE=y" \
+                         "CONFIG_LTE_LC_PERIODIC_SEARCH_MODULE=y" \
+                         "CONFIG_LTE_LC_PSM_MODULE=y" \
+                         "CONFIG_LTE_LC_RAI_MODULE=y" \
+                         "CONFIG_LTE_LC_MODEM_SLEEP_MODULE=y" \
+                         "CONFIG_LTE_LC_TAU_PRE_WARNING_MODULE=y"
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The

doc/nrf/releases_and_maturity/migration/migration_guide_2.8.rst

@@ -139,6 +139,71 @@ LTE link control library
        Use the :kconfig:option:`CONFIG_LTE_NETWORK_MODE_LTE_M_NBIOT` or :kconfig:option:`CONFIG_LTE_NETWORK_MODE_LTE_M_NBIOT_GPS` Kconfig option instead.
        In addition, you can control the priority between LTE-M and NB-IoT using the :kconfig:option:`CONFIG_LTE_MODE_PREFERENCE` Kconfig option.
 
+     * The library has been reorganized into modules that are enabled via their respective Kconfig options.
+       This change requires the following updates:
+
+      * If your application uses:
+
+         * :c:func:`lte_lc_conn_eval_params_get`
+
+         You must use the new :kconfig:option:`CONFIG_LTE_LC_CONN_EVAL_MODULE` Kconfig option.
+
+      * If your application uses:
+
+         * :c:enumerator:`LTE_LC_EVT_EDRX_UPDATE`
+         * :c:func:`lte_lc_ptw_set`
+         * :c:func:`lte_lc_edrx_param_set`
+         * :c:func:`lte_lc_edrx_req`
+         * :c:func:`lte_lc_edrx_get`
+         * :kconfig:option:`CONFIG_LTE_EDRX_REQ`
+
+         You must use the new :kconfig:option:`CONFIG_LTE_LC_EDRX_MODULE` Kconfig option.
+
+      * If your application uses:
+
+         * :c:enumerator:`LTE_LC_EVT_NEIGHBOR_CELL_MEAS`
+         * :c:func:`lte_lc_neighbor_cell_measurement_cancel`
+         * :c:func:`lte_lc_neighbor_cell_measurement`
+
+         You must use the new :kconfig:option:`CONFIG_LTE_LC_NEIGHBOR_CELL_MEAS_MODULE` Kconfig option.
+
+      * If your application uses:
+
+         * :c:func:`lte_lc_periodic_search_request`
+         * :c:func:`lte_lc_periodic_search_clear`
+         * :c:func:`lte_lc_periodic_search_get`
+         * :c:func:`lte_lc_periodic_search_set`
+
+         You must use the new :kconfig:option:`CONFIG_LTE_LC_PERIODIC_SEARCH_MODULE` Kconfig option.
+
+      * If your application uses:
+
+         * :c:enumerator:`LTE_LC_EVT_PSM_UPDATE`
+         * :c:func:`lte_lc_psm_param_set`
+         * :c:func:`lte_lc_psm_param_set_seconds`
+         * :c:func:`lte_lc_psm_req`
+         * :c:func:`lte_lc_psm_get`
+         * :c:func:`lte_lc_proprietary_psm_req`
+         * :kconfig:option:`CONFIG_LTE_PSM_REQ`
+
+         You must use the new :kconfig:option:`CONFIG_LTE_LC_PSM_MODULE` Kconfig option.
+
+      * If your application uses:
+
+         * :c:enumerator:`LTE_LC_EVT_MODEM_SLEEP_EXIT_PRE_WARNING`
+         * :c:enumerator:`LTE_LC_EVT_MODEM_SLEEP_ENTER`
+         * :c:enumerator:`LTE_LC_EVT_MODEM_SLEEP_EXIT`
+         * :kconfig:option:`CONFIG_LTE_LC_MODEM_SLEEP_NOTIFICATIONS`
+
+         You must use the new :kconfig:option:`CONFIG_LTE_LC_MODEM_SLEEP_MODULE` Kconfig option.
+
+      * If your application uses:
+
+         * :c:enumerator:`LTE_LC_EVT_TAU_PRE_WARNING`
+         * :kconfig:option:`CONFIG_LTE_LC_TAU_PRE_WARNING_NOTIFICATIONS`
+
+         You must use the new :kconfig:option:`CONFIG_LTE_LC_TAU_PRE_WARNING_MODULE` Kconfig option.
+
 AT command parser
 -----------------
 

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

@@ -853,24 +853,18 @@ Modem libraries
 
 * :ref:`lte_lc_readme` library:
 
-  * Removed:
-
-    * The :c:func:`lte_lc_init` function.
-      All instances of this function can be removed without any additional actions.
-    * The :c:func:`lte_lc_deinit` function.
-      Use the :c:func:`lte_lc_power_off` function instead.
-    * The :c:func:`lte_lc_init_and_connect` function.
-      Use the :c:func:`lte_lc_connect` function instead.
-    * The :c:func:`lte_lc_init_and_connect_async` function.
-      Use the :c:func:`lte_lc_connect_async` function instead.
-    * The ``CONFIG_LTE_NETWORK_USE_FALLBACK`` Kconfig option.
-      Use the :kconfig:option:`CONFIG_LTE_NETWORK_MODE_LTE_M_NBIOT` or :kconfig:option:`CONFIG_LTE_NETWORK_MODE_LTE_M_NBIOT_GPS` Kconfig option instead.
-      In addition, you can control the priority between LTE-M and NB-IoT using the :kconfig:option:`CONFIG_LTE_MODE_PREFERENCE` Kconfig option.
-
-  * Deprecated the :c:macro:`LTE_LC_ON_CFUN` macro.
-    Use the :c:macro:`NRF_MODEM_LIB_ON_CFUN` macro instead.
+  * Added:
 
-  * Added a new :c:enumerator:`LTE_LC_EVT_RAI_UPDATE` event that is enabled with the :kconfig:option:`CONFIG_LTE_RAI_REQ` Kconfig option.
+    * The :kconfig:option:`CONFIG_LTE_LC_CONN_EVAL_MODULE` Kconfig option to enable the Connection Parameters Evaluation module.
+    * The :kconfig:option:`CONFIG_LTE_LC_EDRX_MODULE` Kconfig option to enable the eDRX module.
+    * The :kconfig:option:`CONFIG_LTE_LC_NEIGHBOR_CELL_MEAS_MODULE` Kconfig option to enable the Neighboring Cell Measurements module.
+    * The :kconfig:option:`CONFIG_LTE_LC_PERIODIC_SEARCH_MODULE` Kconfig option to enable the Periodic Search Configuration module.
+    * The :kconfig:option:`CONFIG_LTE_LC_PSM_MODULE` Kconfig option to enable the PSM module.
+    * The :kconfig:option:`CONFIG_LTE_LC_RAI_MODULE` Kconfig option to enable the RAI module.
+    * The :kconfig:option:`CONFIG_LTE_LC_MODEM_SLEEP_MODULE` Kconfig option to enable the Modem Sleep Notifications module.
+    * The :kconfig:option:`CONFIG_LTE_LC_TAU_PRE_WARNING_MODULE` Kconfig option to enable the TAU Pre-warning module.
+    * The :c:enumerator:`LTE_LC_EVT_RAI_UPDATE` event that is enabled with the :kconfig:option:`CONFIG_LTE_RAI_REQ` Kconfig option.
+      This requires the :kconfig:option:`CONFIG_LTE_LC_RAI_MODULE` Kconfig option to be enabled.
 
   * Updated:
 
@@ -884,6 +878,35 @@ Modem libraries
       Refer to the :ref:`migration guide <migration_2.8>` for more details.
     * The :c:enum:`lte_lc_reduced_mobility_mode` type has been deprecated.
       Refer to the :ref:`migration guide <migration_2.8>` for more details.
+    * The library was reorganized into modules that are enabled through their respective Kconfig options.
+      By default, the library now enables only the core features related to the network connectivity.
+      This reorganization reduces flash memory consumption for applications that only use the core features of the library related to network connectivity.
+      For more information on how to update your project, see the :ref:`migration guide <migration_2.8_required>`.
+
+      * The :c:func:`lte_lc_conn_eval_params_get` function now requires the new :kconfig:option:`CONFIG_LTE_LC_CONN_EVAL_MODULE` Kconfig option to be enabled.
+      * The :c:enumerator:`LTE_LC_EVT_EDRX_UPDATE` event and the :c:func:`lte_lc_ptw_set`, :c:func:`lte_lc_edrx_param_set`, :c:func:`lte_lc_edrx_req`, and :c:func:`lte_lc_edrx_get` functions require the new :kconfig:option:`CONFIG_LTE_LC_EDRX_MODULE` Kconfig option to be enabled.
+      * The :c:enumerator:`LTE_LC_EVT_NEIGHBOR_CELL_MEAS` event and the :c:func:`lte_lc_neighbor_cell_measurement_cancel`, and :c:func:`lte_lc_neighbor_cell_measurement` functions require the new :kconfig:option:`CONFIG_LTE_LC_NEIGHBOR_CELL_MEAS_MODULE` Kconfig option to be enabled.
+      * The :c:func:`lte_lc_periodic_search_request`, :c:func:`lte_lc_periodic_search_clear`, :c:func:`lte_lc_periodic_search_get`, and :c:func:`lte_lc_periodic_search_set` functions require the new :kconfig:option:`CONFIG_LTE_LC_PERIODIC_SEARCH_MODULE` Kconfig option to be enabled.
+      * The :c:enumerator:`LTE_LC_EVT_PSM_UPDATE` event and the :c:func:`lte_lc_psm_param_set`, :c:func:`lte_lc_psm_param_set_seconds`, :c:func:`lte_lc_psm_req`, :c:func:`lte_lc_psm_get`, and :c:func:`lte_lc_proprietary_psm_req` functions require the new :kconfig:option:`CONFIG_LTE_LC_PSM_MODULE` Kconfig option to be enabled.
+      * The :c:enumerator:`LTE_LC_EVT_MODEM_SLEEP_EXIT_PRE_WARNING`, :c:enumerator:`LTE_LC_EVT_MODEM_SLEEP_ENTER`, and :c:enumerator:`LTE_LC_EVT_MODEM_SLEEP_EXIT` events require the new :kconfig:option:`CONFIG_LTE_LC_MODEM_SLEEP_MODULE` Kconfig option to be enabled.
+      * The :c:enumerator:`LTE_LC_EVT_TAU_PRE_WARNING` event requires the new :kconfig:option:`CONFIG_LTE_LC_TAU_PRE_WARNING_MODULE` Kconfig option to be enabled.
+
+  * Deprecated the :c:macro:`LTE_LC_ON_CFUN` macro.
+    Use the :c:macro:`NRF_MODEM_LIB_ON_CFUN` macro instead.
+
+  * Removed:
+
+    * The :c:func:`lte_lc_init` function.
+      All instances of this function can be removed without any additional actions.
+    * The :c:func:`lte_lc_deinit` function.
+      Use the :c:func:`lte_lc_power_off` function instead.
+    * The :c:func:`lte_lc_init_and_connect` function.
+      Use the :c:func:`lte_lc_connect` function instead.
+    * The :c:func:`lte_lc_init_and_connect_async` function.
+      Use the :c:func:`lte_lc_connect_async` function instead.
+    * The ``CONFIG_LTE_NETWORK_USE_FALLBACK`` Kconfig option.
+      Use the :kconfig:option:`CONFIG_LTE_NETWORK_MODE_LTE_M_NBIOT` or :kconfig:option:`CONFIG_LTE_NETWORK_MODE_LTE_M_NBIOT_GPS` Kconfig option instead.
+      In addition, you can control the priority between LTE-M and NB-IoT using the :kconfig:option:`CONFIG_LTE_MODE_PREFERENCE` Kconfig option.
 
 * :ref:`lib_location` library: