[channel-monitor] add public OT API to enable/disable channel monitoring (#2623)

include/openthread/channel_monitor.h

@@ -62,6 +62,34 @@ extern "C" {
  *
  */
 
+/**
+ * This function enables/disables the Channel Monitoring operation.
+ *
+ * Once operation starts, any previously collected data is cleared. However, after operation is disabled, the previous
+ * collected data is still valid and can be read.
+ *
+ * @note OpenThread core internally enables/disables the Channel Monitoring operation when the IPv6 interface is
+ * brought up/down (i.e., call to `otIp6SetEnabled()`).
+ *
+ * @param[in]  aInstance       A pointer to an OpenThread instance.
+ * @param[in]  aEnabled        TRUE to enable/start Channel Monitoring operation, FALSE to disable/stop it.
+ *
+ * @retval OT_ERROR_NONE      Channel Monitoring state changed successfully
+ * @retval OT_ERROR_ALREADY   Channel Monitoring is already in the same state.
+ *
+ */
+otError otChannelMonitorSetEnabled(otInstance *aInstance, bool aEnabled);
+
+/**
+ * This function indicates whether the Channel Monitoring operation is enabled and running.
+ *
+ * @param[in]  aInstance       A pointer to an OpenThread instance.
+ *
+ * @returns TRUE if the Channel Monitoring operation is enabled, FALSE otherwise.
+ *
+ */
+bool otChannelMonitorIsEnabled(otInstance *aInstance);
+
 /**
  * Get channel monitoring sample interval in milliseconds.
  *

src/core/api/channel_monitor_api.cpp

@@ -40,6 +40,20 @@ using namespace ot;
 
 #if OPENTHREAD_ENABLE_CHANNEL_MONITOR
 
+otError otChannelMonitorSetEnabled(otInstance *aInstance, bool aEnabled)
+{
+    Utils::ChannelMonitor monitor = static_cast<Instance *>(aInstance)->GetChannelMonitor();
+
+    return aEnabled ? monitor.Start() : monitor.Stop();
+}
+
+bool otChannelMonitorIsEnabled(otInstance *aInstance)
+{
+    Instance &instance = *static_cast<Instance *>(aInstance);
+
+    return instance.GetChannelMonitor().IsRunning();
+}
+
 uint32_t otChannelMonitorGetSampleInterval(otInstance *aInstance)
 {
     OT_UNUSED_VARIABLE(aInstance);

src/core/utils/channel_monitor.cpp

@@ -59,17 +59,29 @@ ChannelMonitor::ChannelMonitor(Instance &aInstance)
     memset(mChannelQuality, 0, sizeof(mChannelQuality));
 }
 
-void ChannelMonitor::Start(void)
+otError ChannelMonitor::Start(void)
 {
+    otError error = OT_ERROR_NONE;
+
+    VerifyOrExit(!IsRunning(), error = OT_ERROR_ALREADY);
     Clear();
     mTimer.Start(kTimerInterval);
     otLogDebgUtil(GetInstance(), "ChannelMonitor: Starting");
+
+exit:
+    return error;
 }
 
-void ChannelMonitor::Stop(void)
+otError ChannelMonitor::Stop(void)
 {
+    otError error = OT_ERROR_NONE;
+
+    VerifyOrExit(IsRunning(), error = OT_ERROR_ALREADY);
     mTimer.Stop();
     otLogDebgUtil(GetInstance(), "ChannelMonitor: Stopping");
+
+exit:
+    return error;
 }
 
 void ChannelMonitor::Clear(void)

src/core/utils/channel_monitor.hpp

@@ -106,18 +106,32 @@ public:
     /**
      * This method starts the Channel Monitoring operation.
      *
-     * All previous data is cleared when the Channel Monitoring operation starts.
+     * Once started, any previously collected data is cleared.
+     *
+     * @retval OT_ERROR_NONE      Channel Monitoring started successfully.
+     * @retval OT_ERROR_ALREADY   Channel Monitoring has already been started.
      *
      */
-    void Start(void);
+    otError Start(void);
 
     /**
      * This method stops the Channel Monitoring operation.
      *
-     * The previous data is still valid and can be read while the operation is stopped.
+     * @note After `Stop()`, the previous data is still valid and can be read.
+     *
+     * @retval OT_ERROR_NONE      Channel Monitoring stopped successfully.
+     * @retval OT_ERROR_ALREADY   Channel Monitoring has already been stopped.
      *
      */
-    void Stop(void);
+    otError Stop(void);
+
+    /**
+     * This method indicates whether the Channel Monitoring operation is started and running.
+     *
+     * @returns TRUE if the Channel Monitoring operation is running, FALSE otherwise.
+     *
+     */
+    bool IsRunning(void) const { return mTimer.IsRunning(); }
 
     /**
      * This method clears all currently stored data.