[channel-manager] add cli/api functions to modify the CCA failure rate threshold (#6400)

I have found that the default channel manager CCA failure rate
threshold is not necessarily ideal, and some experimentation is
required to determine a good threshold depending on network
characteristics and packet size/periodicity.

For example, I have a network that experiences ~40% packet loss, yet
only ever reports a maximum 4% CCA failure rate, well below the
default of 10%.

This commit adds functions to get/set the threshold, the API layer,
CLI hooks, and CLI documentation.

include/openthread/channel_manager.h

@@ -213,6 +213,25 @@ uint32_t otChannelManagerGetFavoredChannels(otInstance *aInstance);
  */
 void otChannelManagerSetFavoredChannels(otInstance *aInstance, uint32_t aChannelMask);
 
+/**
+ * This function gets the CCA failure rate threshold
+ *
+ * @param[in]  aInstance     A pointer to an OpenThread instance.
+ *
+ * @returns  The CCA failure rate threshold. Value 0 maps to 0% and 0xffff maps to 100%.
+ *
+ */
+uint16_t otChannelManagerGetCcaFailureRateThreshold(otInstance *aInstance);
+
+/**
+ * This function sets the CCA failure rate threshold
+ *
+ * @param[in]  aInstance     A pointer to an OpenThread instance.
+ * @param[in]  aThreshold    A CCA failure rate threshold. Value 0 maps to 0% and 0xffff maps to 100%.
+ *
+ */
+void otChannelManagerSetCcaFailureRateThreshold(otInstance *aInstance, uint16_t aThreshold);
+
 /**
  * @}
  *

include/openthread/instance.h

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

src/cli/cli.cpp

@@ -716,6 +716,7 @@ otError Interpreter::ProcessChannel(uint8_t aArgsLength, char *aArgs[])
 
                 OutputLine("delay: %d", otChannelManagerGetDelay(mInstance));
                 OutputLine("interval: %u", otChannelManagerGetAutoChannelSelectionInterval(mInstance));
+                OutputLine("cca threshold: 0x%04x", otChannelManagerGetCcaFailureRateThreshold(mInstance));
                 OutputLine("supported: %s", supportedMask.ToString().AsCString());
                 OutputLine("favored: %s", supportedMask.ToString().AsCString());
             }
@@ -776,6 +777,14 @@ otError Interpreter::ProcessChannel(uint8_t aArgsLength, char *aArgs[])
             SuccessOrExit(error = ParseAsUint32(aArgs[2], mask));
             otChannelManagerSetFavoredChannels(mInstance, mask);
         }
+        else if (strcmp(aArgs[1], "threshold") == 0)
+        {
+            uint16_t threshold;
+
+            VerifyOrExit(aArgsLength > 2, error = OT_ERROR_INVALID_ARGS);
+            SuccessOrExit(error = ParseAsUint16(aArgs[2], threshold));
+            otChannelManagerSetCcaFailureRateThreshold(mInstance, threshold);
+        }
         else
         {
             ExitNow(error = OT_ERROR_INVALID_ARGS);

src/core/api/channel_manager_api.cpp

@@ -136,4 +136,18 @@ void otChannelManagerSetFavoredChannels(otInstance *aInstance, uint32_t aChannel
     return instance.Get<Utils::ChannelManager>().SetFavoredChannels(aChannelMask);
 }
 
+uint16_t otChannelManagerGetCcaFailureRateThreshold(otInstance *aInstance)
+{
+    Instance &instance = *static_cast<Instance *>(aInstance);
+
+    return instance.Get<Utils::ChannelManager>().GetCcaFailureRateThreshold();
+}
+
+void otChannelManagerSetCcaFailureRateThreshold(otInstance *aInstance, uint16_t aThreshold)
+{
+    Instance &instance = *static_cast<Instance *>(aInstance);
+
+    return instance.Get<Utils::ChannelManager>().SetCcaFailureRateThreshold(aThreshold);
+}
+
 #endif // OPENTHREAD_CONFIG_CHANNEL_MANAGER_ENABLE && OPENTHREAD_FTD

src/core/config/channel_manager.h

@@ -124,7 +124,8 @@
 /**
  * @def OPENTHREAD_CONFIG_CHANNEL_MANAGER_CCA_FAILURE_THRESHOLD
  *
- * Minimum CCA failure rate threshold on current channel before Channel Manager starts channel selection attempt.
+ * Default minimum CCA failure rate threshold on current channel before Channel Manager starts channel selection
+ * attempt.
  *
  * Value 0 maps to 0% and 0xffff maps to 100%.
  *

src/core/utils/channel_manager.cpp

@@ -57,6 +57,7 @@ ChannelManager::ChannelManager(Instance &aInstance)
     , mTimer(aInstance, ChannelManager::HandleTimer)
     , mAutoSelectInterval(kDefaultAutoSelectInterval)
     , mAutoSelectEnabled(false)
+    , mCcaFailureRateThreshold(kCcaFailureRateThreshold)
 {
 }
 
@@ -231,10 +232,10 @@ exit:
 bool ChannelManager::ShouldAttemptChannelChange(void)
 {
     uint16_t ccaFailureRate = Get<Mac::Mac>().GetCcaFailureRate();
-    bool     shouldAttempt  = (ccaFailureRate >= kCcaFailureRateThreshold);
+    bool     shouldAttempt  = (ccaFailureRate >= mCcaFailureRateThreshold);
 
     otLogInfoUtil("ChannelManager: CCA-err-rate: 0x%04x %s 0x%04x, selecting channel: %s", ccaFailureRate,
-                  shouldAttempt ? ">=" : "<", kCcaFailureRateThreshold, shouldAttempt ? "yes" : "no");
+                  shouldAttempt ? ">=" : "<", mCcaFailureRateThreshold, shouldAttempt ? "yes" : "no");
 
     return shouldAttempt;
 }
@@ -348,6 +349,13 @@ void ChannelManager::SetFavoredChannels(uint32_t aChannelMask)
     otLogInfoUtil("ChannelManager: Favored channels: %s", mFavoredChannelMask.ToString().AsCString());
 }
 
+void ChannelManager::SetCcaFailureRateThreshold(uint16_t aThreshold)
+{
+    mCcaFailureRateThreshold = aThreshold;
+
+    otLogInfoUtil("ChannelManager: CCA threshold: 0x%04x", mCcaFailureRateThreshold);
+}
+
 } // namespace Utils
 } // namespace ot
 

src/core/utils/channel_manager.hpp

@@ -227,6 +227,22 @@ public:
      */
     void SetFavoredChannels(uint32_t aChannelMask);
 
+    /**
+     * This method gets the CCA failure rate threshold
+     *
+     * @returns  The CCA failure rate threshold
+     *
+     */
+    uint16_t GetCcaFailureRateThreshold(void) const { return mCcaFailureRateThreshold; }
+
+    /**
+     * This method sets the CCA failure rate threshold
+     *
+     * @param[in]  aThreshold  A CCA failure rate threshold.
+     *
+     */
+    void SetCcaFailureRateThreshold(uint16_t aThreshold);
+
 private:
     enum
     {
@@ -281,6 +297,7 @@ private:
     TimerMilli       mTimer;
     uint32_t         mAutoSelectInterval;
     bool             mAutoSelectEnabled;
+    uint16_t         mCcaFailureRateThreshold;
 };
 
 /**