[mle] add API for changing number of child router links (#8410)

Multicast has been proven to work unreliably with a low value of
OPENTHREAD_CONFIG_MLE_CHILD_ROUTER_LINKS for big dense networks.
Since there is no silver bullet value that suits all installations,
this commit makes it possible to configure its value at runtime.

Signed-off-by: Markus Becker <[email protected]>

include/openthread/instance.h

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

include/openthread/thread_ftd.h

@@ -355,6 +355,35 @@ uint8_t otThreadGetRouterUpgradeThreshold(otInstance *aInstance);
  */
 void otThreadSetRouterUpgradeThreshold(otInstance *aInstance, uint8_t aThreshold);
 
+/**
+ * Get the MLE_CHILD_ROUTER_LINKS parameter used in the REED role.
+ *
+ * This parameter specifies the max number of neighboring routers with which the device (as an FED)
+ *  will try to establish link.
+ *
+ * @param[in]  aInstance A pointer to an OpenThread instance.
+ *
+ * @returns The MLE_CHILD_ROUTER_LINKS value.
+ *
+ * @sa otThreadSetChildRouterLinks
+ *
+ */
+uint8_t otThreadGetChildRouterLinks(otInstance *aInstance);
+
+/**
+ * Set the MLE_CHILD_ROUTER_LINKS parameter used in the REED role.
+ *
+ * @param[in]  aInstance         A pointer to an OpenThread instance.
+ * @param[in]  aChildRouterLinks The MLE_CHILD_ROUTER_LINKS value.
+ *
+ * @retval OT_ERROR_NONE           Successfully set the value.
+ * @retval OT_ERROR_INVALID_STATE  Thread protocols are enabled.
+ *
+ * @sa otThreadGetChildRouterLinks
+ *
+ */
+otError otThreadSetChildRouterLinks(otInstance *aInstance, uint8_t aChildRouterLinks);
+
 /**
  * Release a Router ID that has been allocated by the device in the Leader role.
  *

src/cli/README.md

@@ -104,6 +104,7 @@ Done
 - [routereligible](#routereligible)
 - [routerselectionjitter](#routerselectionjitter)
 - [routerupgradethreshold](#routerupgradethreshold)
+- [childrouterlinks](#childrouterlinks)
 - [scan](#scan-channel)
 - [service](#service)
 - [singleton](#singleton)
@@ -2791,6 +2792,25 @@ Set the ROUTER_UPGRADE_THRESHOLD value.
 Done
 ```
 
+### childrouterlinks
+
+Get the MLE_CHILD_ROUTER_LINKS value.
+
+```bash
+> childrouterlinks
+16
+Done
+```
+
+### childrouterlinks \<number_of_links\>
+
+Set the MLE_CHILD_ROUTER_LINKS value.
+
+```bash
+> childrouterlinks 16
+Done
+```
+
 ### scan \[channel\]
 
 Perform an IEEE 802.15.4 Active Scan.

src/cli/cli.cpp

@@ -6175,6 +6175,12 @@ template <> otError Interpreter::Process<Cmd("routerupgradethreshold")>(Arg aArg
 {
     return ProcessGetSet(aArgs, otThreadGetRouterUpgradeThreshold, otThreadSetRouterUpgradeThreshold);
 }
+
+template <> otError Interpreter::Process<Cmd("childrouterlinks")>(Arg aArgs[])
+{
+    return ProcessGetSet(aArgs, otThreadGetChildRouterLinks, otThreadSetChildRouterLinks);
+}
+
 #endif // OPENTHREAD_FTD
 
 template <> otError Interpreter::Process<Cmd("scan")>(Arg aArgs[])
@@ -7321,6 +7327,7 @@ otError Interpreter::ProcessCommand(Arg aArgs[])
         CmdEntry("child"),
         CmdEntry("childip"),
         CmdEntry("childmax"),
+        CmdEntry("childrouterlinks"),
 #endif
 #if OPENTHREAD_CONFIG_CHILD_SUPERVISION_ENABLE
         CmdEntry("childsupervision"),

src/core/api/thread_ftd_api.cpp

@@ -143,6 +143,16 @@ void otThreadSetRouterUpgradeThreshold(otInstance *aInstance, uint8_t aThreshold
     AsCoreType(aInstance).Get<Mle::MleRouter>().SetRouterUpgradeThreshold(aThreshold);
 }
 
+uint8_t otThreadGetChildRouterLinks(otInstance *aInstance)
+{
+    return AsCoreType(aInstance).Get<Mle::MleRouter>().GetChildRouterLinks();
+}
+
+otError otThreadSetChildRouterLinks(otInstance *aInstance, uint8_t aChildRouterLinks)
+{
+    return AsCoreType(aInstance).Get<Mle::MleRouter>().SetChildRouterLinks(aChildRouterLinks);
+}
+
 otError otThreadReleaseRouterId(otInstance *aInstance, uint8_t aRouterId)
 {
     Error error = kErrorNone;

src/core/thread/mle_router.cpp

@@ -85,6 +85,7 @@ MleRouter::MleRouter(Instance &aInstance)
     , mPreviousPartitionIdTimeout(0)
     , mRouterSelectionJitter(kRouterSelectionJitter)
     , mRouterSelectionJitterTimeout(0)
+    , mChildRouterLinks(kChildRouterLinks)
     , mLinkRequestDelay(0)
     , mParentPriority(kParentPriorityUnspecified)
 #if OPENTHREAD_CONFIG_BACKBONE_ROUTER_ENABLE
@@ -1281,7 +1282,7 @@ Error MleRouter::HandleAdvertisement(RxInfo &aRxInfo, uint16_t aSourceAddress, c
             VerifyOrExit(router != nullptr);
 
             if (!router->IsStateValid() && !router->IsStateLinkRequest() &&
-                (mRouterTable.GetNeighborCount() < kChildRouterLinks))
+                (mRouterTable.GetNeighborCount() < mChildRouterLinks))
             {
                 router->SetExtAddress(extAddr);
                 router->GetLinkInfo().Clear();
@@ -3488,6 +3489,16 @@ exit:
     InformPreviousChannel();
 }
 
+Error MleRouter::SetChildRouterLinks(uint8_t aChildRouterLinks)
+{
+    Error error = kErrorNone;
+
+    VerifyOrExit(IsDisabled(), error = kErrorInvalidState);
+    mChildRouterLinks = aChildRouterLinks;
+exit:
+    return error;
+}
+
 bool MleRouter::IsExpectedToBecomeRouterSoon(void) const
 {
     static constexpr uint8_t kMaxDelay = 10;

src/core/thread/mle_router.hpp

@@ -296,6 +296,24 @@ public:
      */
     void SetRouterDowngradeThreshold(uint8_t aThreshold) { mRouterDowngradeThreshold = aThreshold; }
 
+    /**
+     * This method returns the MLE_CHILD_ROUTER_LINKS value.
+     *
+     * @returns The MLE_CHILD_ROUTER_LINKS value.
+     *
+     */
+    uint8_t GetChildRouterLinks(void) const { return mChildRouterLinks; }
+
+    /**
+     * This method sets the MLE_CHILD_ROUTER_LINKS value.
+     *
+     * @param[in]  aChildRouterLinks  The MLE_CHILD_ROUTER_LINKS value.
+     *
+     * @retval kErrorNone          Successfully set the value.
+     * @retval kErrorInvalidState  Thread protocols are enabled.
+     */
+    Error SetChildRouterLinks(uint8_t aChildRouterLinks);
+
     /**
      * This method returns if the REED is expected to become Router soon.
      *
@@ -642,6 +660,8 @@ private:
     uint8_t mRouterSelectionJitter;        ///< The variable to save the assigned jitter value.
     uint8_t mRouterSelectionJitterTimeout; ///< The Timeout prior to request/release Router ID.
 
+    uint8_t mChildRouterLinks;
+
     uint8_t mLinkRequestDelay;
 
     int8_t mParentPriority; ///< The assigned parent priority value, -2 means not assigned.