[dataset] add support for Wake-up channel

- Add Wake-up Channel TLV to the dataset.
- Add CLI support to handle the wake-up channel.
- Add MAC support for wake-up channel (to be used for sending
  wake-up frames).

include/openthread/dataset.h

@@ -213,6 +213,7 @@ typedef struct otOperationalDatasetComponents
     bool mIsPskcPresent;             ///< TRUE if PSKc is present, FALSE otherwise.
     bool mIsSecurityPolicyPresent;   ///< TRUE if Security Policy is present, FALSE otherwise.
     bool mIsChannelMaskPresent;      ///< TRUE if Channel Mask is present, FALSE otherwise.
+    bool mIsWakeupChannelPresent;    ///< TRUE if Wake-up Channel is present, FALSE otherwise.
 } otOperationalDatasetComponents;
 
 /**
@@ -243,6 +244,7 @@ typedef struct otOperationalDataset
     uint32_t                       mDelay;            ///< Delay Timer
     otPanId                        mPanId;            ///< PAN ID
     uint16_t                       mChannel;          ///< Channel
+    uint16_t                       mWakeupChannel;    ///< Wake-up Channel
     otPskc                         mPskc;             ///< PSKc
     otSecurityPolicy               mSecurityPolicy;   ///< Security Policy
     otChannelMask                  mChannelMask;      ///< Channel Mask
@@ -310,6 +312,7 @@ typedef enum otMeshcopTlvType
     OT_MESHCOP_TLV_PERIOD                   = 55,  ///< meshcop Period TLV
     OT_MESHCOP_TLV_SCAN_DURATION            = 56,  ///< meshcop Scan Duration TLV
     OT_MESHCOP_TLV_ENERGY_LIST              = 57,  ///< meshcop Energy List TLV
+    OT_MESHCOP_TLV_WAKEUP_CHANNEL           = 74,  ///< meshcop Wake-up Channel TLV
     OT_MESHCOP_TLV_DISCOVERYREQUEST         = 128, ///< meshcop Discovery Request TLV
     OT_MESHCOP_TLV_DISCOVERYRESPONSE        = 129, ///< meshcop Discovery Response TLV
     OT_MESHCOP_TLV_JOINERADVERTISEMENT      = 241, ///< meshcop Joiner Advertisement TLV

include/openthread/instance.h

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

include/openthread/link.h

@@ -1204,6 +1204,29 @@ otError otLinkSetRegion(otInstance *aInstance, uint16_t aRegionCode);
  */
 otError otLinkGetRegion(otInstance *aInstance, uint16_t *aRegionCode);
 
+/**
+ * This function gets the Wake-up channel.
+ *
+ * @param[in]  aInstance      A pointer to an OpenThread instance.
+ *
+ * @returns The Wake-up channel.
+ *
+ */
+uint8_t otLinkGetWakeupChannel(otInstance *aInstance);
+
+/**
+ * Sets the Wake-up channel.
+ *
+ * @param[in]  aInstance      A pointer to an OpenThread instance.
+ * @param[in]  aChannel       The Wake-up sample channel. Channel value should be `0` (Set Wake-up Channel unspecified)
+ *                            or within the range [1, 10] (if 915-MHz supported) and [11, 26] (if 2.4 GHz supported).
+ *
+ * @retval OT_ERROR_NONE           Successfully set the Wake-up channel.
+ * @retval OT_ERROR_INVALID_ARGS   Invalid @p aChannel.
+ *
+ */
+otError otLinkSetWakeupChannel(otInstance *aInstance, uint8_t aChannel);
+
 /**
  * @}
  *

src/cli/README.md

@@ -133,6 +133,7 @@ Done
 - [vendor](#vendor-name)
 - [verhoeff](#verhoeff-calculate)
 - [version](#version)
+- [wakeupchannel](#wakeupchannel)
 
 ## OpenThread Command Details
 
@@ -4371,3 +4372,22 @@ Done
 Factory Diagnostics module is enabled only when building OpenThread with `OPENTHREAD_CONFIG_DIAG_ENABLE=1` option. Go [diagnostics module][diag] for more information.
 
 [diag]: ../../src/core/diags/README.md
+
+### wakeupchannel
+
+Get the wake-up channel.
+
+```bash
+> wakeupchannel
+12
+Done
+```
+
+### wakeupchannel \<channel\>
+
+Set the wake-up channel.
+
+```bash
+> wakeupchannel 12
+Done
+```

src/cli/README_DATASET.md

@@ -19,6 +19,7 @@ The Active Operational Dataset includes parameters that are currently in use acr
 
 - Active Timestamp
 - Channel
+- Wake-up Channel
 - Channel Mask
 - Extended PAN ID
 - Mesh-Local Prefix
@@ -46,6 +47,7 @@ The Pending Operational Dataset is used to communicate changes to the Active Ope
    > dataset
    Active Timestamp: 1
    Channel: 15
+   Wake-up Channel: 16
    Channel Mask: 0x07fff800
    Ext PAN ID: 39758ec8144b07fb
    Mesh Local Prefix: fdf1:f1ad:d079:7dc0::/64
@@ -105,6 +107,7 @@ After the device successfully attaches to a Thread network, the device will retr
    > dataset active
    Active Timestamp: 1
    Channel: 15
+   Wake-up Channel: 16
    Channel Mask: 0x07fff800
    Ext PAN ID: 39758ec8144b07fb
    Mesh Local Prefix: fdf1:f1ad:d079:7dc0::/64
@@ -303,6 +306,7 @@ Normally, an active Commissioner will set a new Pending Operational Dataset. For
 - [securitypolicy](#securitypolicy)
 - [tlvs](#tlvs)
 - [updater](#updater)
+    - [wakeupchannel](#wakeupchannel)
 
 ## Command Details
 
@@ -336,6 +340,7 @@ pskc
 securitypolicy
 set
 tlvs
+wakeupchannel
 Done
 ```
 
@@ -349,6 +354,7 @@ Print Active Operational Dataset in human-readable form.
 > dataset active
 Active Timestamp: 1
 Channel: 15
+Wake-up Channel: 16
 Channel Mask: 0x07fff800
 Ext PAN ID: 39758ec8144b07fb
 Mesh Local Prefix: fdf1:f1ad:d079:7dc0::/64
@@ -364,7 +370,7 @@ Print Active Operational Dataset as hex-encoded TLVs.
 
 ```bash
 > dataset active -x
-0e080000000000010000000300000f35060004001fffe0020839758ec8144b07fb0708fdf1f1add0797dc00510f366cec7a446bab978d90d27abe38f23030f4f70656e5468726561642d353933380102593804103ca67c969efb0d0c74a4d8ee923b576c0c0402a0f7f8
+0e08000000000001000000030000164a0300001735060004001fffe00208b182e6a17996cecc0708fd3f363fa8f1b0bc0510ebb6f6a447c96e1542176df3a834ac0e030f4f70656e5468726561642d3663393901026c99041096e9cdfe1eb1363a3676e2b94df0271b0c0402a0f7f8
 Done
 ```
 
@@ -828,3 +834,22 @@ Done
 Disabled
 Done
 ```
+
+### wakeupchannel
+
+Usage: `wakeupchannel [channel]`
+
+Get wake-up channel.
+
+```bash
+> dataset wakeupchannel
+13
+Done
+```
+
+Set wake-up channel.
+
+```bash
+> dataset wakeupchannel 13
+Done
+```

src/cli/cli.cpp

@@ -8206,6 +8206,28 @@ template <> otError Interpreter::Process<Cmd("verhoeff")>(Arg aArgs[])
 
 #endif // OPENTHREAD_CONFIG_VERHOEFF_CHECKSUM_ENABLE
 
+
+/**
+ * @cli wakeupchannel (get,set)
+ * @code
+ * wakeupchannel
+ * 12
+ * Done
+ * @endcode
+ * @code
+ * wakeupchannel 12
+ * Done
+ * @endcode
+ * @cparam wakeupchannel [@ca{channel}]
+ * Use `channel` to set the wake-up channel.
+ * @par
+ * Gets or sets the wake-up channel value.
+ */
+template <> otError Interpreter::Process<Cmd("wakeupchannel")>(Arg aArgs[])
+{ 
+    return ProcessGetSet(aArgs, otLinkGetWakeupChannel, otLinkSetWakeupChannel);
+}
+
 #endif // OPENTHREAD_FTD || OPENTHREAD_MTD
 
 void Interpreter::Initialize(otInstance *aInstance, otCliOutputCallback aCallback, void *aContext)

src/cli/cli_dataset.cpp

@@ -134,6 +134,12 @@ const Dataset::ComponentMapper *Dataset::LookupMapper(const char *aName) const
             &Dataset::OutputSecurityPolicy,
             &Dataset::ParseSecurityPolicy,
         },
+        {
+            "wakeupchannel",
+            &Components::mIsWakeupChannelPresent,
+            &Dataset::OutputWakeupChannel,
+            &Dataset::ParseWakeupChannel,
+        },
     };
 
     static_assert(BinarySearch::IsSorted(kMappers), "kMappers is not sorted");
@@ -182,6 +188,24 @@ void Dataset::OutputActiveTimestamp(const otOperationalDataset &aDataset)
  */
 void Dataset::OutputChannel(const otOperationalDataset &aDataset) { OutputLine("%u", aDataset.mChannel); }
 
+/**
+ * @cli dataset wakeupchannel (get,set)
+ * @code
+ * dataset wakeupchannel
+ * 13
+ * Done
+ * @endcode
+ * @code
+ * dataset wakeupchannel 13
+ * Done
+ * @endcode
+ * @cparam dataset wakeupchannel [@ca{channel-num}]
+ * Use the optional `channel-num` argument to set the wake-up channel.
+ * @par
+ * Gets or sets #otOperationalDataset::mWakeupChannel.
+ */
+void Dataset::OutputWakeupChannel(const otOperationalDataset &aDataset) { OutputLine("%u", aDataset.mWakeupChannel); }
+
 /**
  * @cli dataset channelmask (get,set)
  * @code
@@ -412,6 +436,11 @@ otError Dataset::ParseChannel(Arg *&aArgs, otOperationalDataset &aDataset)
     return aArgs++->ParseAsUint16(aDataset.mChannel);
 }
 
+otError Dataset::ParseWakeupChannel(Arg *&aArgs, otOperationalDataset &aDataset)
+{
+    return aArgs++->ParseAsUint16(aDataset.mWakeupChannel);
+}
+
 otError Dataset::ParseChannelMask(Arg *&aArgs, otOperationalDataset &aDataset)
 {
     return aArgs++->ParseAsUint32(aDataset.mChannelMask);
@@ -561,6 +590,7 @@ otError Dataset::Print(otOperationalDatasetTlvs &aDatasetTlvs)
         {"Pending Timestamp", "pendingtimestamp"},
         {"Active Timestamp", "activetimestamp"},
         {"Channel", "channel"},
+        {"Wake-up Channel", "wakeupchannel"},
         {"Channel Mask", "channelmask"},
         {"Delay", "delay"},
         {"Ext PAN ID", "extpanid"},

src/cli/cli_dataset.hpp

@@ -94,6 +94,7 @@ class Dataset : private Utils
 
     void OutputActiveTimestamp(const otOperationalDataset &aDataset);
     void OutputChannel(const otOperationalDataset &aDataset);
+    void OutputWakeupChannel(const otOperationalDataset &aDataset);
     void OutputChannelMask(const otOperationalDataset &aDataset);
     void OutputDelay(const otOperationalDataset &aDataset);
     void OutputExtendedPanId(const otOperationalDataset &aDataset);
@@ -107,6 +108,7 @@ class Dataset : private Utils
 
     otError ParseActiveTimestamp(Arg *&aArgs, otOperationalDataset &aDataset);
     otError ParseChannel(Arg *&aArgs, otOperationalDataset &aDataset);
+    otError ParseWakeupChannel(Arg *&aArgs, otOperationalDataset &aDataset);
     otError ParseChannelMask(Arg *&aArgs, otOperationalDataset &aDataset);
     otError ParseDelay(Arg *&aArgs, otOperationalDataset &aDataset);
     otError ParseExtendedPanId(Arg *&aArgs, otOperationalDataset &aDataset);

src/core/api/link_api.cpp

@@ -84,6 +84,27 @@ otError otLinkSetChannel(otInstance *aInstance, uint8_t aChannel)
     return error;
 }
 
+uint8_t otLinkGetWakeupChannel(otInstance *aInstance)
+{
+    return AsCoreType(aInstance).Get<Mac::Mac>().GetWakeupChannel();
+}
+
+otError otLinkSetWakeupChannel(otInstance *aInstance, uint8_t aChannel)
+{
+    Error error = kErrorNone;
+    Instance &instance = AsCoreType(aInstance);
+
+    VerifyOrExit(instance.Get<Mle::MleRouter>().IsDisabled(), error = kErrorInvalidState);
+
+    instance.Get<Mac::Mac>().SetWakeupChannel(aChannel);
+
+    instance.Get<MeshCoP::ActiveDatasetManager>().Clear();
+    instance.Get<MeshCoP::PendingDatasetManager>().Clear();
+
+exit:
+    return error;
+}
+
 uint32_t otLinkGetSupportedChannelMask(otInstance *aInstance)
 {
     return AsCoreType(aInstance).Get<Mac::Mac>().GetSupportedChannelMask().GetMask();

src/core/config/misc.h

@@ -517,6 +517,16 @@
 #endif // OPENTHREAD_CONFIG_RADIO_2P4GHZ_OQPSK_SUPPORT
 #endif // OPENTHREAD_CONFIG_DEFAULT_CHANNEL
 
+/**
+ * @def OPENTHREAD_CONFIG_DEFAULT_WAKEUP_CHANNEL
+ *
+ * The default IEEE 802.15.4 wake-up channel.
+ *
+ */
+#ifndef OPENTHREAD_CONFIG_DEFAULT_WAKEUP_CHANNEL
+#define OPENTHREAD_CONFIG_DEFAULT_WAKEUP_CHANNEL 11
+#endif // OPENTHREAD_CONFIG_DEFAULT_WAKEUP_CHANNEL
+
 /**
  * @def OPENTHREAD_CONFIG_OTNS_ENABLE
  *

src/core/mac/mac.cpp

@@ -97,6 +97,7 @@ Mac::Mac(Instance &aInstance)
     , mCslChannel(0)
     , mCslPeriod(0)
 #endif
+    , mWakeupChannel(OPENTHREAD_CONFIG_DEFAULT_WAKEUP_CHANNEL)
     , mActiveScanHandler(nullptr) // Initialize `mActiveScanHandler` and `mEnergyScanHandler` union
     , mScanHandlerContext(nullptr)
     , mLinks(aInstance)
@@ -107,6 +108,7 @@ Mac::Mac(Instance &aInstance)
 #if OPENTHREAD_CONFIG_MULTI_RADIO
     , mTxError(kErrorNone)
 #endif
+
 {
     ExtAddress randomExtAddress;
 
@@ -2414,5 +2416,10 @@ void Mac::SetRadioFilterEnabled(bool aFilterEnabled)
 }
 #endif
 
+void Mac::SetWakeupChannel(uint8_t aChannel)
+{
+    mWakeupChannel = aChannel;
+}
+
 } // namespace Mac
 } // namespace ot

src/core/mac/mac.hpp

@@ -751,6 +751,22 @@ class Mac : public InstanceLocator, private NonCopyable
      */
     Error GetRegion(uint16_t &aRegionCode) const;
 
+    /**
+     * This method gets the Wake-up channel.
+     *
+     * @returns Wake-up channel.
+     *
+     */
+    uint8_t GetWakeupChannel(void) const { return mWakeupChannel; }
+
+    /**
+     * This method sets the Wake-up channel.
+     *
+     * @param[in]  aChannel  The Wake-up channel.
+     *
+     */
+    void SetWakeupChannel(uint8_t aChannel);
+
 private:
     static constexpr uint16_t kMaxCcaSampleCount = OPENTHREAD_CONFIG_CCA_FAILURE_RATE_AVERAGING_WINDOW;
 
@@ -880,6 +896,7 @@ class Mac : public InstanceLocator, private NonCopyable
     uint8_t  mCslChannel;
     uint16_t mCslPeriod;
 #endif
+    uint8_t mWakeupChannel;
 
     union
     {