[mac] enable wake-up frame periodic sniffing

When `OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE` is enabled:

- APIs are available to configure and enable wake-up frames sniffing.
- `SubMac::HandleWedTimer` periodically schedules receive slots on
  wake-up channel.
- Wake-up frames are processed.
- Upon reception of a wake-up frame, WUL is stopped.

include/openthread/instance.h

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

include/openthread/link.h

@@ -1126,6 +1126,76 @@ uint8_t otLinkGetWakeupChannel(otInstance *aInstance);
  */
 otError otLinkSetWakeupChannel(otInstance *aInstance, uint8_t aChannel);
 
+/**
+ * Enables or disables listening for wake-up frames.
+ *
+ * Requires `OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE`.
+ *
+ * @param[in]  aInstance     A pointer to an OpenThread instance.
+ * @param[in]  aEnable       true to enable listening for wake-up frames, or false otherwise.
+ *
+ * @retval OT_ERROR_NONE          Successfully enabled / disabled the listening for wake-up frames.
+ * @retval OT_ERROR_INVALID_STATE Could not enable listening for wake-up frames due to bad configuration.
+ */
+otError otLinkSetWedListenEnabled(otInstance *aInstance, bool aEnable);
+
+/**
+ * Returns whether listening for wake-up frames is enabled.
+ *
+ * Requires `OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE`.
+ *
+ * @param[in]  aInstance     A pointer to an OpenThread instance.
+ *
+ * @retval TRUE   If listening for wake-up frames is enabled.
+ * @retval FALSE  If listening for wake-up frames is not enabled.
+ */
+bool otLinkIsWedListenEnabled(otInstance *aInstance);
+
+/**
+ * Gets the WED listen interval in microseconds.
+ *
+ * Requires `OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE`.
+ *
+ * @param[in]  aInstance      A pointer to an OpenThread instance.
+ *
+ * @returns The WED listen interval in microseconds.
+ */
+uint32_t otLinkGetWedListenInterval(otInstance *aInstance);
+
+/**
+ * Sets the WED listen interval in microseconds.
+ *
+ * Requires `OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE`.
+ *
+ * @param[in]  aInstance      A pointer to an OpenThread instance.
+ * @param[in]  aInterval      The WED listen interval in microseconds.
+ */
+void otLinkSetWedListenInterval(otInstance *aInstance, uint32_t aInterval);
+
+/**
+ * Gets the WED listen duration.
+ *
+ * Requires `OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE`.
+ *
+ * @param[in]  aInstance      A pointer to an OpenThread instance.
+ *
+ * @returns The WED listen duration in microseconds.
+ */
+uint16_t otLinkGetWedListenDuration(otInstance *aInstance);
+
+/**
+ * Sets the WED listen duration in microseconds.
+ *
+ * Requires `OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE`.
+ *
+ * @param[in]  aInstance      A pointer to an OpenThread instance.
+ * @param[in]  aDuration      The WED listen duration in microseconds.
+ *
+ * @retval OT_ERROR_NONE           Successfully set the WED listen duration.
+ * @retval OT_ERROR_INVALID_ARGS   Invalid WED listen duration.
+ */
+otError otLinkSetWedListenDuration(otInstance *aInstance, uint16_t aDuration);
+
 /**
  * @}
  */

src/cli/README.md

@@ -133,7 +133,7 @@ Done
 - [vendor](#vendor-name)
 - [verhoeff](#verhoeff-calculate)
 - [version](#version)
-- [wakeupchannel](#wakeupchannel)
+- [wakeup](#wakeup-channel)
 
 ## OpenThread Command Details
 
@@ -4393,25 +4393,94 @@ Factory Diagnostics module is enabled only when building OpenThread with `OPENTH
 
 [diag]: ../../src/core/diags/README.md
 
-### wakeupchannel
+### wakeup channel
 
 Get the wake-up channel.
 
 Requires `OPENTHREAD_CONFIG_WAKEUP_COORDINATOR_ENABLE` or `OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE`.
 
 ```bash
-> wakeupchannel
+> wakeup channel
 12
 Done
 ```
 
-### wakeupchannel \<channel\>
+### wakeup channel \<channel\>
 
 Set the wake-up channel.
 
 Requires `OPENTHREAD_CONFIG_WAKEUP_COORDINATOR_ENABLE` or `OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE`.
 
 ```bash
-> wakeupchannel 12
+> wakeup channel 12
+Done
+```
+
+### wakeup interval
+
+Get the wake-up listen interval.
+
+Requires `OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE`.
+
+```bash
+> wakeup interval
+1000000
+Done
+```
+
+### wakeup interval \<interval\>
+
+Set the wake-up listen interval.
+
+Requires `OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE`.
+
+```bash
+> wakeup interval 1000000
+Done
+```
+
+### wakeup duration
+
+Get the wake-up listen duration.
+
+Requires `OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE`.
+
+```bash
+> wakeup duration
+8000
+Done
+```
+
+### wakeup duration \<duration\>
+
+Set the wake-up listen duration.
+
+Requires `OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE`.
+
+```bash
+> wakeup duration 8000
+Done
+```
+
+### wakeup listen
+
+Show the state of wake-up listening feature.
+
+`OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE` is required.
+
+```bash
+> wakeup listen
+Enabled
+Done
+```
+
+### wakeup listen \[enable|disable\]
+
+Enable/disable listening for wake-up frames.
+
+`OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE` is required.
+
+```bash
+> wakeup listen enable
 Done
 ```

src/cli/cli.cpp

@@ -8199,25 +8199,113 @@ template <> otError Interpreter::Process<Cmd("verhoeff")>(Arg aArgs[])
 #endif // OPENTHREAD_CONFIG_VERHOEFF_CHECKSUM_ENABLE
 
 #if OPENTHREAD_CONFIG_WAKEUP_COORDINATOR_ENABLE || OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_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[])
+template <> otError Interpreter::Process<Cmd("wakeup")>(Arg aArgs[])
 {
-    return ProcessGetSet(aArgs, otLinkGetWakeupChannel, otLinkSetWakeupChannel);
+    otError error = OT_ERROR_NONE;
+
+    /**
+     * @cli wakeup channel (get,set)
+     * @code
+     * wakeup channel
+     * 12
+     * Done
+     * @endcode
+     * @code
+     * wakeup channel 12
+     * Done
+     * @endcode
+     * @cparam wakeup channel [@ca{channel}]
+     * Use `channel` to set the wake-up channel.
+     * @par
+     * Gets or sets the wake-up channel value.
+     * @sa otLinkGetWakeupChannel
+     * @sa otLinkSetWakeupChannel
+     */
+    if (aArgs[0] == "channel")
+    {
+        error = ProcessGetSet(aArgs + 1, otLinkGetWakeupChannel, otLinkSetWakeupChannel);
+    }
+#if OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE
+    /**
+     * @cli wakeup interval (get,set)
+     * @code
+     * wakeup interval
+     * 12
+     * Done
+     * @endcode
+     * @code
+     * wakeup interval 1000000
+     * Done
+     * @endcode
+     * @cparam wakeup interval @ca{interval}
+     * @par
+     * Gets or sets the wake-up interval value.
+     * @sa otLinkGetWedListenInterval
+     * @sa otLinkSetWedListenInterval
+     */
+    else if (aArgs[0] == "interval")
+    {
+        error = ProcessGetSet(aArgs + 1, otLinkGetWedListenInterval, otLinkSetWedListenInterval);
+    }
+    /**
+     * @cli wakeup duration (get,set)
+     * @code
+     * wakeup duration
+     * 8000
+     * Done
+     * @endcode
+     * @code
+     * wakeup duration 8000
+     * Done
+     * @endcode
+     * @cparam wakeup duration @ca{duration}
+     * @par
+     * Gets or sets the wake-up duration value.
+     * @sa otLinkGetWedListenDuration
+     * @sa otLinkSetWedListenDuration
+     */
+    else if (aArgs[0] == "duration")
+    {
+        error = ProcessGetSet(aArgs + 1, otLinkGetWedListenDuration, otLinkSetWedListenDuration);
+    }
+    /**
+     * @cli wakeup listen (enable,disable)
+     * @code
+     * wakeup listen
+     * disabled
+     * Done
+     * @endcode
+     * @code
+     * wakeup listen
+     * enabled
+     * Done
+     * @endcode
+     * @code
+     * wakeup listen enable
+     * Done
+     * @endcode
+     * @code
+     * wakeup listen disable
+     * Done
+     * @endcode
+     * @cparam wakeup listen @ca{enable}
+     * @par
+     * Gets or sets current wake-up listening link state.
+     * @sa otLinkIsWedListenEnabled
+     * @sa otLinkSetWedListenEnabled
+     */
+    else if (aArgs[0] == "listen")
+    {
+        error = ProcessEnableDisable(aArgs + 1, otLinkIsWedListenEnabled, otLinkSetWedListenEnabled);
+    }
+#endif // OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE
+    else
+    {
+        ExitNow(error = OT_ERROR_INVALID_ARGS);
+    }
+
+exit:
+    return error;
 }
 #endif // OPENTHREAD_CONFIG_WAKEUP_COORDINATOR_ENABLE || OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE
 
@@ -8530,6 +8618,11 @@ otError Interpreter::ProcessCommand(Arg aArgs[])
 #endif
 #endif // OPENTHREAD_FTD || OPENTHREAD_MTD
         CmdEntry("version"),
+#if OPENTHREAD_FTD || OPENTHREAD_MTD
+#if OPENTHREAD_CONFIG_WAKEUP_COORDINATOR_ENABLE || OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE
+        CmdEntry("wakeup"),
+#endif
+#endif
     };
 
 #undef CmdEntry

src/core/BUILD.gn

@@ -508,6 +508,7 @@ openthread_core_files = [
   "mac/sub_mac.hpp",
   "mac/sub_mac_callbacks.cpp",
   "mac/sub_mac_csl_receiver.cpp",
+  "mac/sub_mac_wed.cpp",
   "meshcop/announce_begin_client.cpp",
   "meshcop/announce_begin_client.hpp",
   "meshcop/border_agent.cpp",
@@ -777,6 +778,8 @@ openthread_radio_sources = [
   "mac/mac_types.cpp",
   "mac/sub_mac.cpp",
   "mac/sub_mac_callbacks.cpp",
+  "mac/sub_mac_csl_receiver.cpp",
+  "mac/sub_mac_wed.cpp",
   "radio/radio.cpp",
   "radio/radio_callbacks.cpp",
   "radio/radio_platform.cpp",

src/core/CMakeLists.txt

@@ -146,6 +146,7 @@ set(COMMON_SOURCES
     mac/sub_mac.cpp
     mac/sub_mac_callbacks.cpp
     mac/sub_mac_csl_receiver.cpp
+    mac/sub_mac_wed.cpp
     meshcop/announce_begin_client.cpp
     meshcop/border_agent.cpp
     meshcop/commissioner.cpp
@@ -295,6 +296,7 @@ set(RADIO_COMMON_SOURCES
     mac/sub_mac.cpp
     mac/sub_mac_callbacks.cpp
     mac/sub_mac_csl_receiver.cpp
+    mac/sub_mac_wed.cpp
     radio/radio.cpp
     radio/radio_callbacks.cpp
     radio/radio_platform.cpp