[thread-direct] rename WAKEUP_COORDINATOR/END_DEVICE for Thread Direct

The WAKEUP_COORDINATOR and WAKEUP_END_DEVICE feature flags and their
associated symbols are renamed to THREAD_DIRECT_WAKE_INITIATOR and
THREAD_DIRECT_WAKE_LISTENER to align with the Thread Direct
specification terminology.

`src/core/config/wakeup.h` is replaced by `src/core/config/thread_direct.h`,
which consolidates all Thread Direct configuration under a single header.
Only the configuration flags needed by code landing in this PR are
included.

Removes `include/openthread/provisional/link.h` and its associated
doc-group entry, which contained provisional WED-era types
(`otWakeupId`, `otWakeupType`, `otWakeupRequest`) that are superseded
by the Thread Direct public API.

Author: suveshpratapa

doc/ot_api_doc.h

@@ -182,8 +182,6 @@
  *
  * @{
  *
- * @defgroup api-provisional-link        Link
- *
  * @}
  *
  * @}

etc/cmake/options.cmake

@@ -267,13 +267,14 @@ ot_option(OT_TCP OPENTHREAD_CONFIG_TCP_ENABLE "TCP")
 ot_option(OT_TIME_SYNC OPENTHREAD_CONFIG_TIME_SYNC_ENABLE "time synchronization service")
 ot_option(OT_TREL OPENTHREAD_CONFIG_RADIO_LINK_TREL_ENABLE "TREL radio link for Thread over Infrastructure feature")
 ot_option(OT_TREL_MANAGE_DNSSD OPENTHREAD_CONFIG_TREL_MANAGE_DNSSD_ENABLE "TREL to manage DNSSD and peer discovery")
+ot_option(OT_THREAD_DIRECT_WAKE_INITIATOR OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_INITIATOR_ENABLE "Thread Direct wake initiator")
+ot_option(OT_THREAD_DIRECT_WAKE_LISTENER OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_LISTENER_ENABLE "Thread Direct wake listener")
 ot_option(OT_TX_BEACON_PAYLOAD OPENTHREAD_CONFIG_MAC_OUTGOING_BEACON_PAYLOAD_ENABLE "tx beacon payload")
 ot_option(OT_TX_QUEUE_STATS OPENTHREAD_CONFIG_TX_QUEUE_STATISTICS_ENABLE "tx queue statistics")
 ot_option(OT_UDP_FORWARD OPENTHREAD_CONFIG_UDP_FORWARD_ENABLE "UDP forward")
 ot_option(OT_UPTIME OPENTHREAD_CONFIG_UPTIME_ENABLE "uptime")
 ot_option(OT_VERHOEFF_CHECKSUM OPENTHREAD_CONFIG_VERHOEFF_CHECKSUM_ENABLE "verhoeff checksum")
-ot_option(OT_WAKEUP_COORDINATOR OPENTHREAD_CONFIG_WAKEUP_COORDINATOR_ENABLE "wake-up coordinator")
-ot_option(OT_WAKEUP_END_DEVICE OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE "wake-up end device")
+
 ot_option(OT_SPINEL_CP_RESET_FAIL_CALLBACK_ENABLE OPENTHREAD_SPINEL_CONFIG_COPROCESSOR_RESET_FAILURE_CALLBACK_ENABLE "CP reset failure callback")
 
 option(OT_DOC "build OpenThread documentation")

examples/platforms/utils/mac_frame.cpp

@@ -319,7 +319,7 @@ otError otMacFrameProcessTransmitSecurity(otRadioFrame *aFrame, otRadioContext *
     bool              processKeyId;
 
     processKeyId =
-#if OPENTHREAD_CONFIG_WAKEUP_COORDINATOR_ENABLE
+#if OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_INITIATOR_ENABLE
         otMacFrameIsKeyIdMode2(aFrame) ||
 #endif
         otMacFrameIsKeyIdMode1(aFrame);

include/openthread/BUILD.gn

@@ -117,7 +117,6 @@ source_set("openthread") {
     "platform/toolchain.h",
     "platform/trel.h",
     "platform/udp.h",
-    "provisional/link.h",
     "radio_stats.h",
     "random_crypto.h",
     "random_noncrypto.h",

include/openthread/instance.h

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

include/openthread/link.h

@@ -1115,35 +1115,38 @@ otError otLinkSetRegion(otInstance *aInstance, uint16_t aRegionCode);
 otError otLinkGetRegion(otInstance *aInstance, uint16_t *aRegionCode);
 
 /**
- * Gets the Wake-up channel.
+ * Gets the Thread Direct Wake Channel.
  *
- * Requires `OPENTHREAD_CONFIG_WAKEUP_COORDINATOR_ENABLE` or `OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE`.
+ * Requires `OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_INITIATOR_ENABLE` or
+ * `OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_LISTENER_ENABLE`.
  *
  * @param[in]  aInstance  A pointer to an OpenThread instance.
  *
- * @returns The Wake-up channel.
+ * @returns The Wake Channel (always 20).
  */
 uint8_t otLinkGetWakeupChannel(otInstance *aInstance);
 
 /**
- * Sets the Wake-up channel.
+ * Sets the Thread Direct Wake Channel.
  *
- * Requires `OPENTHREAD_CONFIG_WAKEUP_COORDINATOR_ENABLE` or `OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE`.
+ * Requires `OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_INITIATOR_ENABLE` or
+ * `OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_LISTENER_ENABLE`.
+ *
+ * The Thread Direct feature mandates channel 20 (`OPENTHREAD_CONFIG_THREAD_DIRECT_DEFAULT_WAKE_CHANNEL`)
+ * as the sole Wake Channel. Any other value returns `OT_ERROR_INVALID_ARGS`.
  *
  * @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,
- *                        which means the device will use the PAN channel) or within the range [1, 10] (if 915-MHz
- *                        supported) and [11, 26] (if 2.4 GHz supported).
+ * @param[in]  aChannel   The Wake Channel.  Must equal 20.
  *
- * @retval OT_ERROR_NONE           Successfully set the Wake-up channel.
- * @retval OT_ERROR_INVALID_ARGS   Invalid @p aChannel.
+ * @retval OT_ERROR_NONE           Successfully set the Wake Channel.
+ * @retval OT_ERROR_INVALID_ARGS   @p aChannel is not 20.
  */
 otError otLinkSetWakeupChannel(otInstance *aInstance, uint8_t aChannel);
 
 /**
  * Enables or disables listening for wake-up frames.
  *
- * Requires `OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE`.
+ * Requires `OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_LISTENER_ENABLE`.
  *
  * @param[in]  aInstance     A pointer to an OpenThread instance.
  * @param[in]  aEnable       true to enable listening for wake-up frames, or false otherwise.
@@ -1157,7 +1160,7 @@ otError otLinkSetWakeUpListenEnabled(otInstance *aInstance, bool aEnable);
 /**
  * Returns whether listening for wake-up frames is enabled.
  *
- * Requires `OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE`.
+ * Requires `OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_LISTENER_ENABLE`.
  *
  * @param[in]  aInstance     A pointer to an OpenThread instance.
  *
@@ -1169,7 +1172,7 @@ bool otLinkIsWakeupListenEnabled(otInstance *aInstance);
 /**
  * Get the wake-up listen parameters.
  *
- * Requires `OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE`.
+ * Requires `OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_LISTENER_ENABLE`.
  *
  * @param[in]  aInstance   A pointer to an OpenThread instance.
  * @param[out] aInterval   A pointer to return the wake-up listen interval in microseconds.
@@ -1183,7 +1186,7 @@ void otLinkGetWakeupListenParameters(otInstance *aInstance, uint32_t *aInterval,
  * The listen interval must be greater than the listen duration.
  * The listen duration must be greater or equal than the minimum supported.
  *
- * Requires `OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE`.
+ * Requires `OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_LISTENER_ENABLE`.
  *
  * @param[in]  aInstance   A pointer to an OpenThread instance.
  * @param[in]  aInterval   The wake-up listen interval in microseconds.

include/openthread/thread.h

@@ -223,16 +223,6 @@ typedef struct otThreadParentResponseInfo
  */
 typedef void (*otDetachGracefullyCallback)(void *aContext);
 
-/**
- * Informs the application about the result of waking a Wake-up End Device.
- *
- * @param[in] aError   OT_ERROR_NONE    Indicates that the Wake-up End Device has been added as a neighbor.
- *                     OT_ERROR_FAILED  Indicates that the Wake-up End Device has not received a wake-up frame, or it
- *                                      has failed the MLE procedure.
- * @param[in] aContext A pointer to application-specific context.
- */
-typedef void (*otWakeupCallback)(otError aError, void *aContext);
-
 /**
  * Starts Thread protocol operation.
  *
@@ -1100,36 +1090,6 @@ void otThreadSetStoreFrameCounterAhead(otInstance *aInstance, uint32_t aStoreFra
  */
 uint32_t otThreadGetStoreFrameCounterAhead(otInstance *aInstance);
 
-/**
- * Attempts to wake a Wake-up End Device.
- *
- * Requires `OPENTHREAD_CONFIG_WAKEUP_COORDINATOR_ENABLE` to be enabled.
- *
- * The wake-up starts with transmitting a wake-up frame sequence to the Wake-up End Device.
- * During the wake-up sequence, and for a short time after the last wake-up frame is sent, the Wake-up Coordinator keeps
- * its receiver on to be able to receive an initial mesh link establishment message from the WED.
- *
- * @warning The functionality implemented by this function is still in the design phase.
- *          Consequently, the prototype and semantics of this function are subject to change.
- *
- * @param[in] aInstance         A pointer to an OpenThread instance.
- * @param[in] aWedAddress       The extended address of the Wake-up End Device.
- * @param[in] aWakeupIntervalUs An interval between consecutive wake-up frames (in microseconds).
- * @param[in] aWakeupDurationMs Duration of the wake-up sequence (in milliseconds).
- * @param[in] aCallback         A pointer to function that is called when the wake-up succeeds or fails.
- * @param[in] aCallbackContext  A pointer to callback application-specific context.
- *
- * @retval OT_ERROR_NONE          Successfully started the wake-up.
- * @retval OT_ERROR_INVALID_STATE Another attachment request is still in progress.
- * @retval OT_ERROR_INVALID_ARGS  The wake-up interval or duration are invalid.
- */
-otError otThreadWakeup(otInstance         *aInstance,
-                       const otExtAddress *aWedAddress,
-                       uint16_t            aWakeupIntervalUs,
-                       uint16_t            aWakeupDurationMs,
-                       otWakeupCallback    aCallback,
-                       void               *aCallbackContext);
-
 /**
  * @}
  */

script/test

@@ -137,8 +137,10 @@ build_simulation()
         options+=("-DOT_LINK_METRICS_INITIATOR=ON")
         options+=("-DOT_LINK_METRICS_SUBJECT=ON")
         options+=("-DOT_LINK_METRICS_MANAGER=ON")
-        options+=("-DOT_WAKEUP_COORDINATOR=ON")
-        options+=("-DOT_WAKEUP_END_DEVICE=ON")
+        if [[ ${OT_NODE_TYPE} != rcp* ]]; then
+            options+=("-DOT_THREAD_DIRECT_WAKE_INITIATOR=ON")
+            options+=("-DOT_THREAD_DIRECT_WAKE_LISTENER=ON")
+        fi
     fi
 
     if [[ ${OT_NODE_TYPE} == cli* ]]; then
@@ -186,8 +188,8 @@ build_posix()
         options+=("-DOT_LINK_METRICS_INITIATOR=ON")
         options+=("-DOT_LINK_METRICS_SUBJECT=ON")
         options+=("-DOT_LINK_METRICS_MANAGER=ON")
-        options+=("-DOT_WAKEUP_COORDINATOR=ON")
-        options+=("-DOT_WAKEUP_END_DEVICE=ON")
+        options+=("-DOT_THREAD_DIRECT_WAKE_INITIATOR=ON")
+        options+=("-DOT_THREAD_DIRECT_WAKE_LISTENER=ON")
     fi
 
     if [[ ${FULL_LOGS} == 1 ]]; then

src/cli/cli.cpp

@@ -8213,7 +8213,7 @@ 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
+#if OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_INITIATOR_ENABLE || OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_LISTENER_ENABLE
 template <> otError Interpreter::Process<Cmd("wakeup")>(Arg aArgs[])
 {
     otError error = OT_ERROR_NONE;
@@ -8240,7 +8240,7 @@ template <> otError Interpreter::Process<Cmd("wakeup")>(Arg aArgs[])
     {
         error = ProcessGetSet(aArgs + 1, otLinkGetWakeupChannel, otLinkSetWakeupChannel);
     }
-#if OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE
+#if OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_LISTENER_ENABLE
     /**
      * @cli wakeup parameters (get,set)
      * @code
@@ -8303,34 +8303,7 @@ template <> otError Interpreter::Process<Cmd("wakeup")>(Arg aArgs[])
     {
         error = ProcessEnableDisable(aArgs + 1, otLinkIsWakeupListenEnabled, otLinkSetWakeUpListenEnabled);
     }
-#endif // OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE
-#if OPENTHREAD_CONFIG_WAKEUP_COORDINATOR_ENABLE
-    /**
-     * @cli wakeup wake
-     * @code
-     * wakeup wake 1ece0a6c4653a7c1 7500 1090
-     * Done
-     * @endcode
-     * @cparam wakeup wake @ca{extaddr} @ca{wakeup-interval} @ca{wakeup-duration}
-     * @par
-     * Wakes a Wake-up End Device identified by its MAC extended address, using the provided wake-up interval (in the
-     * units of microseconds), and wake-up duration (in the units of milliseconds).
-     */
-    else if (aArgs[0] == "wake")
-    {
-        otExtAddress extAddress;
-        uint16_t     wakeupIntervalUs;
-        uint16_t     wakeupDurationMs;
-
-        SuccessOrExit(error = aArgs[1].ParseAsHexString(extAddress.m8));
-        SuccessOrExit(error = aArgs[2].ParseAsUint16(wakeupIntervalUs));
-        SuccessOrExit(error = aArgs[3].ParseAsUint16(wakeupDurationMs));
-
-        SuccessOrExit(error = otThreadWakeup(GetInstancePtr(), &extAddress, wakeupIntervalUs, wakeupDurationMs,
-                                             HandleWakeupResult, this));
-        error = OT_ERROR_PENDING;
-    }
-#endif // OPENTHREAD_CONFIG_WAKEUP_COORDINATOR_ENABLE
+#endif // OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_LISTENER_ENABLE
     else
     {
         ExitNow(error = OT_ERROR_INVALID_ARGS);
@@ -8339,16 +8312,7 @@ template <> otError Interpreter::Process<Cmd("wakeup")>(Arg aArgs[])
 exit:
     return error;
 }
-#endif // OPENTHREAD_CONFIG_WAKEUP_COORDINATOR_ENABLE || OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE
-
-#if OPENTHREAD_CONFIG_WAKEUP_COORDINATOR_ENABLE
-void Interpreter::HandleWakeupResult(otError aError, void *aContext)
-{
-    static_cast<Interpreter *>(aContext)->HandleWakeupResult(aError);
-}
-
-void Interpreter::HandleWakeupResult(otError aError) { OutputResult(aError); }
-#endif
+#endif // OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_INITIATOR_ENABLE || OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_LISTENER_ENABLE
 
 #endif // OPENTHREAD_FTD || OPENTHREAD_MTD
 
@@ -8702,7 +8666,7 @@ otError Interpreter::ProcessCommand(Arg aArgs[])
 #endif // OPENTHREAD_FTD || OPENTHREAD_MTD
         CmdEntry("version"),
 #if OPENTHREAD_FTD || OPENTHREAD_MTD
-#if OPENTHREAD_CONFIG_WAKEUP_COORDINATOR_ENABLE || OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE
+#if OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_INITIATOR_ENABLE || OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_LISTENER_ENABLE
         CmdEntry("wakeup"),
 #endif
 #endif // OPENTHREAD_FTD || OPENTHREAD_MTD

src/cli/cli.hpp

@@ -364,11 +364,6 @@ class Interpreter : public otCliInterpreter, public OutputImplementer, public Ut
     static void HandleIp6Receive(otMessage *aMessage, void *aContext);
 #endif
 
-#if OPENTHREAD_CONFIG_WAKEUP_COORDINATOR_ENABLE
-    static void HandleWakeupResult(otError aError, void *aContext);
-    void        HandleWakeupResult(otError aError);
-#endif
-
 #endif // OPENTHREAD_FTD || OPENTHREAD_MTD
 
 #if OPENTHREAD_CONFIG_DIAG_ENABLE