lib: lte_link_control: Add support for environment evaluation

Added support for environment evaluation using the %ENVEVAL AT
command introduced in nRF91x1 modem firmware v2.0.3.

Signed-off-by: Tommi Kangas <[email protected]>

Author: tokangas

doc/nrf/libraries/modem/lte_lc.rst

@@ -147,7 +147,7 @@ Tracking Area Update (TAU) Pre-warning:
   * :c:enumerator:`LTE_LC_EVT_TAU_PRE_WARNING` events
   * :kconfig:option:`CONFIG_LTE_LC_TAU_PRE_WARNING_NOTIFICATIONS`
 
-DNS fallback:
+DNS Fallback:
   The :kconfig:option:`CONFIG_LTE_LC_DNS_FALLBACK_MODULE` Kconfig option controls the use of a fallback DNS server address.
 
   The device might or might not receive a DNS server address by the network during a PDN connection.
@@ -158,6 +158,13 @@ DNS fallback:
   If the application has configured a DNS server address in Zephyr's native networking stack using the :kconfig:option:`CONFIG_DNS_SERVER1` Kconfig option, the same server is set as the fallback address for DNS queries offloaded to the nRF91 Series modem.
   Otherwise, the :kconfig:option:`CONFIG_LTE_LC_DNS_FALLBACK_ADDRESS` Kconfig option controls the fallback DNS server address that is set to Cloudflare's DNS server: 1.1.1.1 by default.
 
+Environment Evaluation:
+  Use the :kconfig:option:`CONFIG_LTE_LC_ENV_EVAL_MODULE` Kconfig option to enable the following functionalities related to Environment Evaluation:
+
+  * :c:enumerator:`LTE_LC_EVT_ENV_EVAL_RESULT` events
+  * :c:func:`lte_lc_env_eval`
+  * :c:func:`lte_lc_env_eval_cancel`
+
 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.
 
@@ -254,6 +261,20 @@ To enable modem sleep and TAU pre-warning notifications, use the following optio
 
 For additional configurations related to these features, see the API documentation.
 
+Environment evaluation
+======================
+
+Modem firmware mfw_nrf91x1 v2.0.3 and higher, and mfw_nrf9151-ntn support environment evaluation.
+Environment evaluation allows the application to evaluate available PLMNs and select the best PLMN to use before connecting to the network.
+This is useful especially in cases where the device has multiple SIMs or SIM profiles to select from.
+
+Environment evaluation can only be performed in *receive only* functional mode.
+During the environment evaluation, the device searches for the best cell for each PLMN.
+
+The :c:func:`lte_lc_env_eval` function starts the environment evaluation for the given PLMNs.
+When the environment evaluation is complete, an :c:enumerator:`LTE_LC_EVT_ENV_EVAL_RESULT` event with the evaluation results is received.
+For each found PLMN, the :c:struct:`lte_lc_conn_eval_params` structure is populated with the evaluation results.
+
 Limitations
 ***********
 

doc/nrf/nrf.doxyfile.in

@@ -2464,7 +2464,8 @@ PREDEFINED             = __DOXYGEN__ \
                          "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"
+                         "CONFIG_LTE_LC_TAU_PRE_WARNING_MODULE=y" \
+                         "CONFIG_LTE_LC_ENV_EVAL_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/releases/release-notes-changelog.rst

@@ -586,6 +586,7 @@ Modem libraries
 
   * Added:
 
+    * Support for environment evaluation.
     * Support for NTN NB-IoT system mode.
     * eDRX support for NTN NB-IoT.
 

include/modem/lte_lc.h

@@ -362,6 +362,20 @@ enum lte_lc_evt_type {
 	 */
 	LTE_LC_EVT_RAI_UPDATE			= 12,
 #endif /* CONFIG_LTE_LC_RAI_MODULE */
+
+#if defined(CONFIG_LTE_LC_ENV_EVAL_MODULE)
+	/**
+	 * Environment evaluation result.
+	 *
+	 * The associated payload is the @c lte_lc_evt.env_eval_result member of type
+	 * @ref lte_lc_env_eval_result in the event.
+	 *
+	 * @note This is only supported by the following modem firmware:
+	 *       - mfw_nrf91x1 >= v2.0.3
+	 *       - mfw_nrf9151-ntn
+	 */
+	LTE_LC_EVT_ENV_EVAL_RESULT		= 13,
+#endif /* CONFIG_LTE_LC_ENV_EVAL_MODULE */
 };
 
 /** RRC connection state. */
@@ -1052,6 +1066,49 @@ struct lte_lc_ncellmeas_params {
 	uint8_t gci_count;
 };
 
+/** Environment evaluation type. */
+enum lte_lc_env_eval_type {
+	/**
+	 * PLMN search is stopped after light search if any of the PLMNs to evaluate were found.
+	 * Search is continued over all frequency bands if light search did not find any results.
+	 */
+	LTE_LC_ENV_EVAL_TYPE_DYNAMIC = 0,
+
+	/** PLMN search is stopped after light search even if no PLMNs to evaluate were found. */
+	LTE_LC_ENV_EVAL_TYPE_LIGHT = 1,
+
+	/** PLMN search covers all channels in all supported frequency bands. */
+	LTE_LC_ENV_EVAL_TYPE_FULL = 2
+};
+
+/** PLMN to evaluate. */
+struct lte_lc_env_eval_plmn {
+	/** Mobile Country Code (MCC). */
+	int mcc;
+
+	/** Mobile Network Code (MNC). */
+	int mnc;
+};
+
+/** Environment evaluation parameters. */
+struct lte_lc_env_eval_params {
+	/**
+	 * Environment evaluation type.
+	 */
+	enum lte_lc_env_eval_type eval_type;
+
+	/**
+	 * Number of PLMNs to evaluate.
+	 *
+	 * Must be less than or equal to @c CONFIG_LTE_LC_ENV_EVAL_MAX_PLMN_COUNT.
+	 */
+	uint8_t plmn_count;
+
+	/**
+	 * Pointer to an array of PLMNs to evaluate.
+	 */
+	struct lte_lc_env_eval_plmn *plmn_list;
+};
 
 /** Search pattern type. */
 enum lte_lc_periodic_search_pattern_type {
@@ -1214,6 +1271,38 @@ struct lte_lc_periodic_search_cfg {
 	struct lte_lc_periodic_search_pattern patterns[4];
 };
 
+#if defined(CONFIG_LTE_LC_ENV_EVAL_MODULE)
+/**
+ * @brief Environment evaluation results.
+ *
+ * This structure is used as the payload for event @ref LTE_LC_EVT_ENV_EVAL_RESULT.
+ */
+struct lte_lc_env_eval_result {
+	/**
+	 * Status for the environment evaluation.
+	 *
+	 * 0 indicates successful completion of the evaluation.
+	 * 5 indicates that evaluation failed, aborted due to higher priority operation.
+	 * 7 indicates that evaluation failed, unspecified.
+	 */
+	uint8_t status;
+
+	/**
+	 * Number of PLMN results available in the results array.
+	 *
+	 * Range: 0 to CONFIG_LTE_LC_ENV_EVAL_MAX_PLMN_COUNT
+	 */
+	uint8_t result_count;
+
+	/**
+	 * Pointer to an array of environment evaluation results for different PLMNs.
+	 *
+	 * Each entry contains the evaluation result for a specific PLMN.
+	 */
+	struct lte_lc_conn_eval_params *results;
+};
+#endif /* CONFIG_LTE_LC_ENV_EVAL_MODULE */
+
 /** Callback for modem functional mode changes. */
 struct lte_lc_cfun_cb {
 	void (*callback)(enum lte_lc_func_mode, void *ctx);
@@ -1275,6 +1364,11 @@ struct lte_lc_evt {
 		/** Payload for event @ref LTE_LC_EVT_RAI_UPDATE. */
 		struct lte_lc_rai_cfg rai_cfg;
 #endif /* CONFIG_LTE_LC_RAI_MODULE */
+
+#if defined(CONFIG_LTE_LC_ENV_EVAL_MODULE)
+		/** Payload for event @ref LTE_LC_EVT_ENV_EVAL_RESULT. */
+		struct lte_lc_env_eval_result env_eval_result;
+#endif /* CONFIG_LTE_LC_ENV_EVAL_MODULE */
 	};
 };
 
@@ -1754,6 +1848,48 @@ int lte_lc_neighbor_cell_measurement_cancel(void);
  */
 int lte_lc_conn_eval_params_get(struct lte_lc_conn_eval_params *params);
 
+/**
+ * Start environment evaluation.
+ *
+ * Perform evaluation for PLMN selection. Evaluates available PLMNs and provides information
+ * of their estimated signalling conditions. Based on the evaluation results, the application
+ * can then select the best PLMN to use. This is useful especially in cases where the device
+ * has multiple SIMs or SIM profiles to select from.
+ *
+ * PLMNs (MCC/MNC pairs) to be evaluated are listed in the @ref lte_lc_env_eval_params
+ * structure. For each PLMN, evaluation results for the best found cell are returned. The results
+ * are returned with the @ref LTE_LC_EVT_ENV_EVAL_RESULT event.
+ *
+ * Environment evaluation can only be performed in receive only functional mode. The device does
+ * not transmit anything during the evaluation.
+ *
+ * @note This is only supported by the following modem firmware:
+ *       - mfw_nrf91x1 >= v2.0.3
+ *       - mfw_nrf9151-ntn
+ *
+ * @note Requires `CONFIG_LTE_LC_ENV_EVAL_MODULE` to be enabled.
+ *
+ * @param[in] params Environment evaluation parameters.
+ *
+ * @retval 0 if environment evaluation was successfully initiated.
+ * @retval -EFAULT if AT command failed or feature is not supported by the modem firmware.
+ * @retval -EINVAL if parameters are invalid.
+ * @retval -EOPNOTSUPP if environment evaluation is not available in the current functional mode.
+ */
+int lte_lc_env_eval(struct lte_lc_env_eval_params *params);
+
+/**
+ * Cancel an ongoing environment evaluation.
+ *
+ * If environment evaluation was in progress, an @ref LTE_LC_EVT_ENV_EVAL_RESULT event is received.
+ *
+ * @note Requires `CONFIG_LTE_LC_ENV_EVAL_MODULE` to be enabled.
+ *
+ * @retval 0 if environment evaluation was cancelled.
+ * @retval -EFAULT if AT command failed.
+ */
+int lte_lc_env_eval_cancel(void);
+
 /**
  * Enable modem domain events.
  *

lib/lte_link_control/Kconfig

@@ -20,7 +20,7 @@ config LTE_LC_CONN_EVAL_MODULE
 	bool "Connection Parameters Evaluation module"
 
 config LTE_LC_EDRX_MODULE
-	bool "Extended Discountinuous Reception (eDRX) module"
+	bool "Extended Discontinuous Reception (eDRX) module"
 
 config LTE_LC_NEIGHBOR_CELL_MEAS_MODULE
 	bool "Neighboring Cell Measurements module"
@@ -40,8 +40,11 @@ config LTE_LC_MODEM_SLEEP_MODULE
 config LTE_LC_TAU_PRE_WARNING_MODULE
 	bool "Tracking Area Update (TAU) module"
 
+config LTE_LC_ENV_EVAL_MODULE
+	bool "Environment Evaluation module"
+
 menuconfig LTE_LC_DNS_FALLBACK_MODULE
-	bool "Fallback DNS module"
+	bool "DNS Fallback module"
 	default y
 	help
 	  The device might or might not receive a DNS server address by the network during a PDN connection.
@@ -442,6 +445,12 @@ config LTE_LC_MODEM_SLEEP_NOTIFICATIONS_THRESHOLD_MS
 
 endif # LTE_LC_MODEM_SLEEP_MODULE
 
+config LTE_LC_ENV_EVAL_MAX_PLMN_COUNT
+	int "Maximum number of PLMNs to evaluate"
+	default 3
+	help
+	  Maximum number of PLMNs that can be evaluated with lte_lc_env_eval().
+
 config LTE_LC_TRACE
 	bool "LTE link control tracing"
 	help

lib/lte_link_control/include/modules/enveval.h

@@ -0,0 +1,26 @@
+/*
+ * Copyright (c) 2025 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+ */
+
+#ifndef ENVEVAL_H__
+#define ENVEVAL_H__
+
+#include <modem/lte_lc.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* Perform environment evaluation. */
+int env_eval(struct lte_lc_env_eval_params *params);
+
+/* Cancel an ongoing environment evaluation. */
+int env_eval_cancel(void);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* ENVEVAL_H__ */

lib/lte_link_control/lte_lc.c

@@ -29,6 +29,7 @@
 #include "modules/xmodemsleep.h"
 #include "modules/xsystemmode.h"
 #include "modules/xt3412.h"
+#include "modules/enveval.h"
 
 #include "common/work_q.h"
 #include "common/event_handler_list.h"
@@ -184,6 +185,16 @@ int lte_lc_conn_eval_params_get(struct lte_lc_conn_eval_params *params)
 	return coneval_params_get(params);
 }
 
+int lte_lc_env_eval(struct lte_lc_env_eval_params *params)
+{
+	return env_eval(params);
+}
+
+int lte_lc_env_eval_cancel(void)
+{
+	return env_eval_cancel();
+}
+
 int lte_lc_modem_events_enable(void)
 {
 	return mdmev_enable();

lib/lte_link_control/modules/CMakeLists.txt

@@ -18,3 +18,4 @@ zephyr_library_sources_ifdef(CONFIG_LTE_LC_PERIODIC_SEARCH_MODULE periodicsearch
 zephyr_library_sources_ifdef(CONFIG_LTE_LC_MODEM_SLEEP_MODULE xmodemsleep.c)
 zephyr_library_sources_ifdef(CONFIG_LTE_LC_TAU_PRE_WARNING_MODULE xt3412.c)
 zephyr_library_sources_ifdef(CONFIG_LTE_LC_DNS_FALLBACK_MODULE dns.c)
+zephyr_library_sources_ifdef(CONFIG_LTE_LC_ENV_EVAL_MODULE enveval.c)