[mle] rename RouterRoleEnabled to RouterEligible (#4363)

include/openthread/thread_ftd.h

@@ -123,24 +123,27 @@ uint16_t otThreadGetMaxAllowedChildren(otInstance *aInstance);
 otError otThreadSetMaxAllowedChildren(otInstance *aInstance, uint16_t aMaxChildren);
 
 /**
- * This function indicates whether or not the Router Role is enabled.
+ * This method indicates whether or not the device is router-eligible.
  *
  * @param[in]  aInstance A pointer to an OpenThread instance.
  *
- * @retval TRUE   If the Router Role is enabled.
- * @retval FALSE  If the Router Role is not enabled.
+ * @retval TRUE   If device is router-eligible.
+ * @retval FALSE  If device is not router-eligible.
  *
  */
-bool otThreadIsRouterRoleEnabled(otInstance *aInstance);
+bool otThreadIsRouterEligible(otInstance *aInstance);
 
 /**
- * This function sets whether or not the Router Role is enabled.
+ * This function sets whether or not the device is router-eligible.
  *
- * @param[in]  aInstance A pointer to an OpenThread instance.
- * @param[in]  aEnabled  TRUE if the Router Role is enabled, FALSE otherwise.
+ * If @p aEligible is false and the device is currently operating as a router, this call will cause the device to
+ * detach and attempt to reattach as a child.
+ *
+ * @param[in]  aInstance  A pointer to an OpenThread instance.
+ * @param[in]  aEligible  TRUE to configure the device as router-eligible, FALSE otherwise.
  *
  */
-void otThreadSetRouterRoleEnabled(otInstance *aInstance, bool aEnabled);
+void otThreadSetRouterEligible(otInstance *aInstance, bool aEligible);
 
 /**
  * Set the preferred Router Id.

src/cli/README.md

@@ -63,7 +63,7 @@ OpenThread test scripts use the CLI to execute test cases.
 * [route](#route-add-prefix-s-prf)
 * [router](#router-list)
 * [routerdowngradethreshold](#routerdowngradethreshold)
-* [routerrole](#routerrole)
+* [routereligible](#routereligible)
 * [routerselectionjitter](#routerselectionjitter)
 * [routerupgradethreshold](#routerupgradethreshold)
 * [scan](#scan-channel)
@@ -1175,31 +1175,31 @@ Set the ROUTER_DOWNGRADE_THRESHOLD value.
 Done
 ```
 
-### routerrole
+### routereligible
 
 Indicates whether the router role is enabled or disabled.
 
 ```bash
-> routerrole
+> routereligible
 Enabled
 Done
 ```
 
-### routerrole enable
+### routereligible enable
 
 Enable the router role.
 
 ```bash
-> routerrole enable
+> routereligible enable
 Done
 ```
 
-### routerrole disable
+### routereligible disable
 
 Disable the router role.
 
 ```bash
-> routerrole disable
+> routereligible disable
 Done
 ```
 

src/cli/cli.cpp

@@ -202,7 +202,7 @@ const struct Command Interpreter::sCommands[] = {
 #if OPENTHREAD_FTD
     {"router", &Interpreter::ProcessRouter},
     {"routerdowngradethreshold", &Interpreter::ProcessRouterDowngradeThreshold},
-    {"routerrole", &Interpreter::ProcessRouterRole},
+    {"routereligible", &Interpreter::ProcessRouterEligible},
     {"routerselectionjitter", &Interpreter::ProcessRouterSelectionJitter},
     {"routerupgradethreshold", &Interpreter::ProcessRouterUpgradeThreshold},
 #endif
@@ -2760,13 +2760,13 @@ exit:
     AppendResult(error);
 }
 
-void Interpreter::ProcessRouterRole(int argc, char *argv[])
+void Interpreter::ProcessRouterEligible(int argc, char *argv[])
 {
     otError error = OT_ERROR_NONE;
 
     if (argc == 0)
     {
-        if (otThreadIsRouterRoleEnabled(mInstance))
+        if (otThreadIsRouterEligible(mInstance))
         {
             mServer->OutputFormat("Enabled\r\n");
         }
@@ -2777,11 +2777,11 @@ void Interpreter::ProcessRouterRole(int argc, char *argv[])
     }
     else if (strcmp(argv[0], "enable") == 0)
     {
-        otThreadSetRouterRoleEnabled(mInstance, true);
+        otThreadSetRouterEligible(mInstance, true);
     }
     else if (strcmp(argv[0], "disable") == 0)
     {
-        otThreadSetRouterRoleEnabled(mInstance, false);
+        otThreadSetRouterEligible(mInstance, false);
     }
     else
     {

src/cli/cli.hpp

@@ -314,7 +314,7 @@ private:
 #if OPENTHREAD_FTD
     void ProcessRouter(int argc, char *argv[]);
     void ProcessRouterDowngradeThreshold(int argc, char *argv[]);
-    void ProcessRouterRole(int argc, char *argv[]);
+    void ProcessRouterEligible(int argc, char *argv[]);
     void ProcessRouterSelectionJitter(int argc, char *argv[]);
     void ProcessRouterUpgradeThreshold(int argc, char *argv[]);
 #endif

src/core/api/thread_ftd_api.cpp

@@ -58,18 +58,18 @@ otError otThreadSetMaxAllowedChildren(otInstance *aInstance, uint16_t aMaxChildr
     return instance.Get<ChildTable>().SetMaxChildrenAllowed(aMaxChildren);
 }
 
-bool otThreadIsRouterRoleEnabled(otInstance *aInstance)
+bool otThreadIsRouterEligible(otInstance *aInstance)
 {
     Instance &instance = *static_cast<Instance *>(aInstance);
 
-    return instance.Get<Mle::MleRouter>().IsRouterRoleEnabled();
+    return instance.Get<Mle::MleRouter>().IsRouterEligible();
 }
 
-void otThreadSetRouterRoleEnabled(otInstance *aInstance, bool aEnabled)
+void otThreadSetRouterEligible(otInstance *aInstance, bool aEligible)
 {
     Instance &instance = *static_cast<Instance *>(aInstance);
 
-    instance.Get<Mle::MleRouter>().SetRouterRoleEnabled(aEnabled);
+    instance.Get<Mle::MleRouter>().SetRouterEligible(aEligible);
 }
 
 otError otThreadSetPreferredRouterId(otInstance *aInstance, uint8_t aRouterId)

src/core/thread/announce_sender.cpp

@@ -138,7 +138,7 @@ void AnnounceSender::CheckState(void)
         break;
 
     case OT_DEVICE_ROLE_CHILD:
-        if (mle.IsRouterRoleEnabled() && mle.IsRxOnWhenIdle())
+        if (mle.IsRouterEligible() && mle.IsRxOnWhenIdle())
         {
             period = kReedTxInterval;
             break;

src/core/thread/mle_router.cpp

@@ -71,7 +71,7 @@ MleRouter::MleRouter(Instance &aInstance)
     , mRouterDowngradeThreshold(kRouterDowngradeThreshold)
     , mLeaderWeight(kLeaderWeight)
     , mFixedLeaderPartitionId(0)
-    , mRouterRoleEnabled(true)
+    , mRouterEligible(true)
     , mAddressSolicitPending(false)
     , mPreviousPartitionIdRouter(0)
     , mPreviousPartitionId(0)
@@ -97,14 +97,14 @@ void MleRouter::HandlePartitionChange(void)
     mRouterTable.Clear();
 }
 
-bool MleRouter::IsRouterRoleEnabled(void) const
+bool MleRouter::IsRouterEligible(void) const
 {
-    return mRouterRoleEnabled && IsFullThreadDevice();
+    return mRouterEligible && IsFullThreadDevice();
 }
 
-void MleRouter::SetRouterRoleEnabled(bool aEnabled)
+void MleRouter::SetRouterEligible(bool aEligible)
 {
-    mRouterRoleEnabled = aEnabled;
+    mRouterEligible = aEligible;
 
     switch (mRole)
     {
@@ -113,12 +113,12 @@ void MleRouter::SetRouterRoleEnabled(bool aEnabled)
         break;
 
     case OT_DEVICE_ROLE_CHILD:
-        Get<Mac::Mac>().SetBeaconEnabled(mRouterRoleEnabled);
+        Get<Mac::Mac>().SetBeaconEnabled(mRouterEligible);
         break;
 
     case OT_DEVICE_ROLE_ROUTER:
     case OT_DEVICE_ROLE_LEADER:
-        if (!mRouterRoleEnabled)
+        if (!mRouterEligible)
         {
             BecomeDetached();
         }
@@ -133,7 +133,7 @@ otError MleRouter::BecomeRouter(ThreadStatusTlv::Status aStatus)
 
     VerifyOrExit(mRole != OT_DEVICE_ROLE_DISABLED, error = OT_ERROR_INVALID_STATE);
     VerifyOrExit(mRole != OT_DEVICE_ROLE_ROUTER, error = OT_ERROR_NONE);
-    VerifyOrExit(IsRouterRoleEnabled(), error = OT_ERROR_NOT_CAPABLE);
+    VerifyOrExit(IsRouterEligible(), error = OT_ERROR_NOT_CAPABLE);
 
     otLogInfoMle("Attempt to become router");
 
@@ -170,7 +170,7 @@ otError MleRouter::BecomeLeader(void)
     VerifyOrExit(!Get<MeshCoP::ActiveDataset>().IsPartiallyComplete(), error = OT_ERROR_INVALID_STATE);
     VerifyOrExit(mRole != OT_DEVICE_ROLE_DISABLED, error = OT_ERROR_INVALID_STATE);
     VerifyOrExit(mRole != OT_DEVICE_ROLE_LEADER, error = OT_ERROR_NONE);
-    VerifyOrExit(IsRouterRoleEnabled(), error = OT_ERROR_NOT_CAPABLE);
+    VerifyOrExit(IsRouterEligible(), error = OT_ERROR_NOT_CAPABLE);
 
     mRouterTable.Clear();
 
@@ -223,7 +223,7 @@ otError MleRouter::HandleChildStart(AttachMode aMode)
     StopLeader();
     mStateUpdateTimer.Start(kStateUpdatePeriod);
 
-    if (mRouterRoleEnabled)
+    if (mRouterEligible)
     {
         Get<Mac::Mac>().SetBeaconEnabled(true);
     }
@@ -1580,7 +1580,7 @@ otError MleRouter::HandleParentRequest(const Message &aMessage, const Ip6::Messa
 
     LogMleMessage("Receive Parent Request", aMessageInfo.GetPeerAddr());
 
-    VerifyOrExit(IsRouterRoleEnabled(), error = OT_ERROR_INVALID_STATE);
+    VerifyOrExit(IsRouterEligible(), error = OT_ERROR_INVALID_STATE);
 
     // A Router MUST NOT send an MLE Parent Response if:
 
@@ -2080,7 +2080,7 @@ otError MleRouter::HandleChildIdRequest(const Message &         aMessage,
 
     LogMleMessage("Receive Child ID Request", aMessageInfo.GetPeerAddr());
 
-    VerifyOrExit(IsRouterRoleEnabled(), error = OT_ERROR_INVALID_STATE);
+    VerifyOrExit(IsRouterEligible(), error = OT_ERROR_INVALID_STATE);
 
     // only process message when operating as a child, router, or leader
     VerifyOrExit(IsAttached(), error = OT_ERROR_INVALID_STATE);

src/core/thread/mle_router_ftd.hpp

@@ -86,24 +86,24 @@ public:
     explicit MleRouter(Instance &aInstance);
 
     /**
-     * This method indicates whether or not the Router Role is enabled.
+     * This method indicates whether or not the device is router-eligible.
      *
-     * @retval true   If the Router Role is enabled.
-     * @retval false  If the Router Role is not enabled.
+     * @retval true   If device is router-eligible.
+     * @retval false  If device is not router-eligible.
      *
      */
-    bool IsRouterRoleEnabled(void) const;
+    bool IsRouterEligible(void) const;
 
     /**
-     * This method sets whether or not the Router Role is enabled.
+     * This method sets whether or not the device is router-eligible.
      *
-     * If @p aEnable is false and the device is currently operating as a router, this call will cause the device to
+     * If @p aEligible is false and the device is currently operating as a router, this call will cause the device to
      * detach and attempt to reattach as a child.
      *
-     * @param[in]  aEnabled  TRUE to enable the Router Role, FALSE otherwise.
+     * @param[in]  aEligible  TRUE to configure device router-eligible, FALSE otherwise.
      *
      */
-    void SetRouterRoleEnabled(bool aEnabled);
+    void SetRouterEligible(bool aEligible);
 
     /**
      * This method indicates whether a node is the only router on the network.
@@ -784,7 +784,7 @@ private:
     uint8_t  mRouterDowngradeThreshold;
     uint8_t  mLeaderWeight;
     uint32_t mFixedLeaderPartitionId; ///< only for certification testing
-    bool     mRouterRoleEnabled : 1;
+    bool     mRouterEligible : 1;
     bool     mAddressSolicitPending : 1;
 
     uint8_t mRouterId;

src/core/thread/mle_router_mtd.hpp

@@ -60,7 +60,7 @@ public:
     {
     }
 
-    bool IsRouterRoleEnabled(void) const { return false; }
+    bool IsRouterEligible(void) const { return false; }
 
     bool IsSingleton(void) const { return false; }
 

src/core/thread/network_data_local.cpp

@@ -356,7 +356,7 @@ otError Local::SendServerDataNotification(void)
 #if OPENTHREAD_FTD
 
     // Don't send this Server Data Notification if the device is going to upgrade to Router
-    if (Get<Mle::MleRouter>().IsFullThreadDevice() && Get<Mle::MleRouter>().IsRouterRoleEnabled() &&
+    if (Get<Mle::MleRouter>().IsFullThreadDevice() && Get<Mle::MleRouter>().IsRouterEligible() &&
         (Get<Mle::MleRouter>().GetRole() < OT_DEVICE_ROLE_ROUTER) &&
         (Get<RouterTable>().GetActiveRouterCount() < Get<Mle::MleRouter>().GetRouterUpgradeThreshold()))
     {

src/ncp/ncp_base_ftd.cpp

@@ -294,17 +294,17 @@ exit:
 
 template <> otError NcpBase::HandlePropertyGet<SPINEL_PROP_THREAD_ROUTER_ROLE_ENABLED>(void)
 {
-    return mEncoder.WriteBool(otThreadIsRouterRoleEnabled(mInstance));
+    return mEncoder.WriteBool(otThreadIsRouterEligible(mInstance));
 }
 
 template <> otError NcpBase::HandlePropertySet<SPINEL_PROP_THREAD_ROUTER_ROLE_ENABLED>(void)
 {
-    bool    enabled;
+    bool    eligible;
     otError error = OT_ERROR_NONE;
 
-    SuccessOrExit(error = mDecoder.ReadBool(enabled));
+    SuccessOrExit(error = mDecoder.ReadBool(eligible));
 
-    otThreadSetRouterRoleEnabled(mInstance, enabled);
+    otThreadSetRouterEligible(mInstance, eligible);
 
 exit:
     return error;

tools/harness-thci/OpenThread.py

@@ -257,16 +257,16 @@ class OpenThread(IThci):
             ModuleHelper.WriteIntoDebugLogger('sendCommand() Error: ' + str(e))
             raise
 
-    def __disableRouterRole(self):
+    def __disableRouterEligible(self):
         """disable router role
         """
-        print('call __disableRouterRole')
+        print('call __disableRouterEligible')
         try:
-            cmd = 'routerrole disable'
+            cmd = 'routereligible disable'
             self.__sendCommand(cmd)
         except Exception as e:
             ModuleHelper.WriteIntoDebugLogger(
-                '__disableRouterRole() Error: ' + str(e)
+                '__disableRouterEligible() Error: ' + str(e)
             )
 
     def __setDeviceMode(self, mode):
@@ -1085,7 +1085,7 @@ class OpenThread(IThci):
                 print('join as FED')
                 mode = 'rsdn'
                 # always remain an ED, never request to be a router
-                self.__disableRouterRole()
+                self.__disableRouterEligible()
             elif eRoleId == Thread_Device_Role.EndDevice_MED:
                 print('join as MED')
                 mode = 'rsn'