[mle] new API to trigger search for better parent (#8018)

This commit adds `otThreadSearchForBetterParent()` to start the
process on a child to search for a better parent while staying
attached to its current parent. This commit also adds a related CLI
command `parent search`.

include/openthread/instance.h

@@ -53,7 +53,7 @@ extern "C" {
  * @note This number versions both OpenThread platform and user APIs.
  *
  */
-#define OPENTHREAD_API_VERSION (234)
+#define OPENTHREAD_API_VERSION (235)
 
 /**
  * @addtogroup api-instance

include/openthread/thread.h

@@ -855,6 +855,17 @@ otError otThreadGetParentAverageRssi(otInstance *aInstance, int8_t *aParentRssi)
  */
 otError otThreadGetParentLastRssi(otInstance *aInstance, int8_t *aLastRssi);
 
+/**
+ * Starts the process for child to search for a better parent while staying attached to its current parent.
+ *
+ * Must be used when device is attached as a child.
+ *
+ * @retval OT_ERROR_NONE           Successfully started the process to search for a better parent.
+ * @retval OT_ERROR_INVALID_STATE  Device role is not child.
+ *
+ */
+otError otThreadSearchForBetterParent(otInstance *aInstance);
+
 /**
  * Gets the IPv6 counters.
  *

src/cli/cli.cpp

@@ -4253,23 +4253,43 @@ template <> otError Interpreter::Process<Cmd("panid")>(Arg aArgs[])
 
 template <> otError Interpreter::Process<Cmd("parent")>(Arg aArgs[])
 {
-    OT_UNUSED_VARIABLE(aArgs);
+    otError error = OT_ERROR_NONE;
 
-    otError      error = OT_ERROR_NONE;
-    otRouterInfo parentInfo;
+    if (aArgs[0].IsEmpty())
+    {
+        otRouterInfo parentInfo;
 
-    SuccessOrExit(error = otThreadGetParentInfo(GetInstancePtr(), &parentInfo));
-    OutputFormat("Ext Addr: ");
-    OutputExtAddressLine(parentInfo.mExtAddress);
-    OutputLine("Rloc: %x", parentInfo.mRloc16);
-    OutputLine("Link Quality In: %d", parentInfo.mLinkQualityIn);
-    OutputLine("Link Quality Out: %d", parentInfo.mLinkQualityOut);
-    OutputLine("Age: %d", parentInfo.mAge);
-    OutputLine("Version: %d", parentInfo.mVersion);
+        SuccessOrExit(error = otThreadGetParentInfo(GetInstancePtr(), &parentInfo));
+        OutputFormat("Ext Addr: ");
+        OutputExtAddressLine(parentInfo.mExtAddress);
+        OutputLine("Rloc: %x", parentInfo.mRloc16);
+        OutputLine("Link Quality In: %d", parentInfo.mLinkQualityIn);
+        OutputLine("Link Quality Out: %d", parentInfo.mLinkQualityOut);
+        OutputLine("Age: %d", parentInfo.mAge);
+        OutputLine("Version: %d", parentInfo.mVersion);
 #if OPENTHREAD_CONFIG_MAC_CSL_RECEIVER_ENABLE
-    OutputLine("CSL clock accuracy: %d", parentInfo.mCslClockAccuracy);
-    OutputLine("CSL uncertainty: %d", parentInfo.mCslUncertainty);
+        OutputLine("CSL clock accuracy: %d", parentInfo.mCslClockAccuracy);
+        OutputLine("CSL uncertainty: %d", parentInfo.mCslUncertainty);
 #endif
+    }
+    /**
+     * @cli parent search
+     * @code
+     * parent search
+     * Done
+     * @endcode
+     * @par api_copy
+     * #otThreadSearchForBetterParent
+     */
+    else if (aArgs[0] == "search")
+    {
+        error = otThreadSearchForBetterParent(GetInstancePtr());
+    }
+    else
+    {
+        error = OT_ERROR_INVALID_ARGS;
+    }
+
 exit:
     return error;
 }

src/core/api/thread_api.cpp

@@ -377,6 +377,11 @@ exit:
     return error;
 }
 
+otError otThreadSearchForBetterParent(otInstance *aInstance)
+{
+    return AsCoreType(aInstance).Get<Mle::Mle>().SearchForBetterParent();
+}
+
 otError otThreadSetEnabled(otInstance *aInstance, bool aEnabled)
 {
     Error error = kErrorNone;

src/core/thread/mle.cpp

@@ -524,6 +524,17 @@ exit:
     return error;
 }
 
+Error Mle::SearchForBetterParent(void)
+{
+    Error error = kErrorNone;
+
+    VerifyOrExit(IsChild(), error = kErrorInvalidState);
+    Attach(kBetterParent);
+
+exit:
+    return error;
+}
+
 void Mle::Attach(AttachMode aMode)
 {
     VerifyOrExit(!IsDisabled() && !IsAttaching());

src/core/thread/mle.hpp

@@ -436,6 +436,16 @@ public:
      */
     Router &GetParentCandidate(void) { return mParentCandidate; }
 
+    /**
+     * This method starts the process for child to search for a better parent while staying attached to its current
+     * parent
+     *
+     * @retval kErrorNone          Successfully started the process to search for a better parent.
+     * @retval kErrorInvalidState  Device role is not child.
+     *
+     */
+    Error SearchForBetterParent(void);
+
     /**
      * This method indicates whether or not an IPv6 address is an RLOC.
      *