[thread-direct] add MAC-layer Thread Direct wake initiator and listener hooks

Introduces the core MAC-layer behavior for both the Wake Initiator (WI)
and Wake Listener (WL) roles.

Wake Initiator: `WakeupTxScheduler` now builds and transmits Thread Direct
Wake Commands using `GenerateThreadDirectWakeCommand()`

Wake Listener: `Mac::HandleWakeupFrame` replaces its earlier
`kErrorNotImplemented` stub with the full receive path: security verification
via the wake key, and dispatch of `OT_THREAD_DIRECT_EVENT_WAKE_RECEIVED` through
`DirectHandler`.

`DirectHandler` centralizes the Thread Direct event callback and SCA (SLW/RAM)
parameter storage.

Author: suveshpratapa

examples/platforms/utils/mac_frame.cpp

@@ -318,11 +318,7 @@ otError otMacFrameProcessTransmitSecurity(otRadioFrame *aFrame, otRadioContext *
     uint32_t          frameCounter;
     bool              processKeyId;
 
-    processKeyId =
-#if OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_INITIATOR_ENABLE
-        otMacFrameIsKeyIdMode2(aFrame) ||
-#endif
-        otMacFrameIsKeyIdMode1(aFrame);
+    processKeyId = otMacFrameIsKeyIdMode1(aFrame);
 
     VerifyOrExit(otMacFrameIsSecurityEnabled(aFrame) && processKeyId && !aFrame->mInfo.mTxInfo.mIsSecurityProcessed);
 
@@ -455,3 +451,23 @@ bool otMacFrameSrcAddrMatchCslReceiverPeer(const otRadioFrame *aFrame, const otR
 exit:
     return matches;
 }
+
+#if OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_INITIATOR_ENABLE
+
+bool otMacFrameIsTdWakeCommand(otRadioFrame *aFrame)
+{
+    uint8_t keyId;
+
+    if (!otMacFrameIsCommand(aFrame) || otMacFrameIsAckRequested(aFrame) || !otMacFrameIsSecurityEnabled(aFrame) ||
+        !otMacFrameIsKeyIdMode1(aFrame))
+    {
+        return false;
+    }
+
+    keyId = otMacFrameGetKeyId(aFrame);
+
+    return keyId == OT_MAC_FRAME_WAKE_KEY_INDEX ||
+           (keyId >= OT_MAC_FRAME_GUEST_WAKE_KEY_INDEX_MIN && keyId <= OT_MAC_FRAME_GUEST_WAKE_KEY_INDEX_MAX);
+}
+
+#endif // OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_INITIATOR_ENABLE

examples/platforms/utils/mac_frame.h

@@ -401,6 +401,21 @@ otError otMacFrameProcessTransmitSecurity(otRadioFrame *aFrame, otRadioContext *
  */
 bool otMacFrameSrcAddrMatchCslReceiverPeer(const otRadioFrame *aFrame, const otRadioContext *aRadioContext);
 
+#if OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_INITIATOR_ENABLE
+/**
+ * Tell if @p aFrame is a Thread Direct Wake Command frame.
+ *
+ * A TD Wake Command is a MAC Command with no ACK request and wake key index 129 or 130-192
+ * in the Auxiliary Security Header (stamped by the stack before transmit).
+ *
+ * @param[in] aFrame  A pointer to the frame.
+ *
+ * @retval true   The frame is a TD Wake Command.
+ * @retval false  The frame is not a TD Wake Command.
+ */
+bool otMacFrameIsTdWakeCommand(otRadioFrame *aFrame);
+#endif
+
 #ifdef __cplusplus
 } // extern "C"
 #endif

include/openthread/BUILD.gn

@@ -132,6 +132,7 @@ source_set("openthread") {
     "tcp.h",
     "tcp_ext.h",
     "thread.h",
+    "thread_direct.h",
     "thread_ftd.h",
     "trel.h",
     "udp.h",

include/openthread/dataset.h

@@ -207,7 +207,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.
+    bool mIsWakeupChannelPresent;    ///< TRUE if Wake Channel is present, FALSE otherwise.
 } otOperationalDatasetComponents;
 
 /**
@@ -227,20 +227,20 @@ typedef struct otTimestamp
  */
 typedef struct otOperationalDataset
 {
-    otTimestamp                    mActiveTimestamp;  ///< Active Timestamp
-    otTimestamp                    mPendingTimestamp; ///< Pending Timestamp
-    otNetworkKey                   mNetworkKey;       ///< Network Key
-    otNetworkName                  mNetworkName;      ///< Network Name
-    otExtendedPanId                mExtendedPanId;    ///< Extended PAN ID
-    otMeshLocalPrefix              mMeshLocalPrefix;  ///< Mesh Local Prefix
-    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
-    otOperationalDatasetComponents mComponents;       ///< Specifies which components are set in the Dataset.
+    otTimestamp       mActiveTimestamp;  ///< Active Timestamp
+    otTimestamp       mPendingTimestamp; ///< Pending Timestamp
+    otNetworkKey      mNetworkKey;       ///< Network Key
+    otNetworkName     mNetworkName;      ///< Network Name
+    otExtendedPanId   mExtendedPanId;    ///< Extended PAN ID
+    otMeshLocalPrefix mMeshLocalPrefix;  ///< Mesh Local Prefix
+    uint32_t          mDelay;            ///< Delay Timer
+    otPanId           mPanId;            ///< PAN ID
+    uint16_t          mChannel;          ///< Channel
+    uint16_t mWakeupChannel; ///< Wake Channel (always 20; see OPENTHREAD_CONFIG_THREAD_DIRECT_DEFAULT_WAKE_CHANNEL)
+    otPskc   mPskc;          ///< PSKc
+    otSecurityPolicy               mSecurityPolicy; ///< Security Policy
+    otChannelMask                  mChannelMask;    ///< Channel Mask
+    otOperationalDatasetComponents mComponents;     ///< Specifies which components are set in the Dataset.
 } otOperationalDataset;
 
 /**
@@ -303,7 +303,7 @@ typedef enum otMeshcopTlvType
     OT_MESHCOP_TLV_SCAN_DURATION            = 56,  ///< meshcop Scan Duration TLV
     OT_MESHCOP_TLV_ENERGY_LIST              = 57,  ///< meshcop Energy List TLV
     OT_MESHCOP_TLV_THREAD_DOMAIN_NAME       = 59,  ///< meshcop Thread Domain Name TLV
-    OT_MESHCOP_TLV_WAKEUP_CHANNEL           = 74,  ///< meshcop Wake-up Channel TLV
+    OT_MESHCOP_TLV_WAKEUP_CHANNEL           = 74,  ///< meshcop Wake Channel TLV (always 20 for Thread Direct)
     OT_MESHCOP_TLV_ADMITTER_STATE           = 90,  ///< meshcop Admitter State TLV
     OT_MESHCOP_TLV_ENROLLER_ID              = 91,  ///< meshcop Enroller ID TLV
     OT_MESHCOP_TLV_ENROLLER_MODE            = 92,  ///< meshcop Enroller Mode TLV

include/openthread/instance.h

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

include/openthread/thread_direct.h

@@ -0,0 +1,240 @@
+/*
+ *  Copyright (c) 2025, The OpenThread Authors.
+ *  All rights reserved.
+ *
+ *  Redistribution and use in source and binary forms, with or without
+ *  modification, are permitted provided that the following conditions are met:
+ *  1. Redistributions of source code must retain the above copyright
+ *     notice, this list of conditions and the following disclaimer.
+ *  2. Redistributions in binary form must reproduce the above copyright
+ *     notice, this list of conditions and the following disclaimer in the
+ *     documentation and/or other materials provided with the distribution.
+ *  3. Neither the name of the copyright holder nor the
+ *     names of its contributors may be used to endorse or promote products
+ *     derived from this software without specific prior written permission.
+ *
+ *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ *  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ *  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ *  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ *  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ *  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ *  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ *  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ *  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ *  POSSIBILITY OF SUCH DAMAGE.
+ */
+
+/**
+ * @file
+ *   This file defines the OpenThread API for Thread Direct,
+ *   a MAC-layer peer-to-peer link between Thread devices.
+ */
+
+#ifndef OPENTHREAD_THREAD_DIRECT_H_
+#define OPENTHREAD_THREAD_DIRECT_H_
+
+#include <stdbool.h>
+#include <stdint.h>
+
+#include <openthread/error.h>
+#include <openthread/instance.h>
+#include <openthread/platform/radio.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @addtogroup api-thread-direct
+ *
+ * @brief
+ *   This module includes functions for Thread Direct.
+ *
+ * @{
+ *
+ */
+
+/**
+ * Represents a 16-byte guest Wake Key provisioned out-of-band (key indices 130-192).
+ */
+typedef struct otThreadDirectWakeKey
+{
+    uint8_t m8[16]; ///< Key material (16 bytes).
+} otThreadDirectWakeKey;
+
+/**
+ * Represents the state of an established Thread Direct peer.
+ *
+ * The @p mWake* fields are populated on OT_THREAD_DIRECT_EVENT_WAKE_RECEIVED;
+ * the @p mSlw* and @p mTd* fields are populated on LINKED/UNLINKED events.
+ */
+typedef struct otThreadDirectPeerInfo
+{
+    otExtAddress mExtAddress;            ///< Peer extended address.
+    uint16_t     mTdShortAddress;        ///< TD short address [0xFE00, 0xFFFE], or OT_RADIO_INVALID_SHORT_ADDR.
+    uint16_t     mSlwPeriodSlots;        ///< Peer's SLW period in 160 us slots (0 = not configured).
+    uint16_t     mSlwPhaseSlots;         ///< Peer's SLW phase in 160 us slots.
+    uint16_t     mSupervisionIntervalMs; ///< Supervision interval from TD Link Command, in milliseconds.
+    uint8_t      mServicesBitmap;        ///< Services bitmap: bit 0 = peer has SRP server.
+
+    /* Fields below are valid only for OT_THREAD_DIRECT_EVENT_WAKE_RECEIVED. */
+    uint8_t  mWakeType;          ///< Wake type: 0=link, 1=power-outage, 2=connectionless.
+    uint32_t mWakeRvTimeUs;      ///< Rendezvous time (us from end-of-frame to connection window open).
+    uint8_t  mWakeRetryCount;    ///< Retry count from the Wake Frame (number of WI retries).
+    uint8_t  mWakeRetryInterval; ///< Retry interval (units of WI wake interval).
+} otThreadDirectPeerInfo;
+
+/**
+ * Represents a Thread Direct link event.
+ */
+typedef enum otThreadDirectEvent
+{
+    OT_THREAD_DIRECT_EVENT_LINK_FAILED   = 0, ///< Wake attempt failed (timeout or authentication failure).
+    OT_THREAD_DIRECT_EVENT_WAKE_RECEIVED = 1, ///< WL received a TD Wake Command from a WI peer.
+} otThreadDirectEvent;
+
+/**
+ * Pointer to a function called on Thread Direct link events.
+ *
+ * @param[in] aEvent     The event type.
+ * @param[in] aPeerInfo  Peer information at the time of the event.  May be NULL for LINK_FAILED
+ *                       if no peer entry was established.
+ * @param[in] aContext   Application-specific context pointer passed to
+ *                       otThreadDirectSetEventCallback().
+ */
+typedef void (*otThreadDirectEventCallback)(otThreadDirectEvent           aEvent,
+                                            const otThreadDirectPeerInfo *aPeerInfo,
+                                            void                         *aContext);
+
+/**
+ * Registers a callback for Thread Direct link events.
+ *
+ * Valid for both WI and WL roles.  A subsequent call replaces any previously
+ * registered callback.  Pass NULL to clear.
+ *
+ * Requires `OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_INITIATOR_ENABLE` or
+ * `OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_LISTENER_ENABLE`.
+ *
+ * @param[in] aInstance  The OpenThread instance.
+ * @param[in] aCallback  The callback function pointer, or NULL to clear.
+ * @param[in] aContext   Application-specific context pointer passed to @p aCallback.
+ */
+void otThreadDirectSetEventCallback(otInstance *aInstance, otThreadDirectEventCallback aCallback, void *aContext);
+
+/**
+ * Thread Direct wake frame type, carried in the Wake Frame payload.
+ *
+ * The numeric values match the wire encoding.
+ */
+typedef enum
+{
+    OT_THREAD_DIRECT_WAKE_TYPE_LINK           = 0, ///< Wake Frame requesting TD link establishment.
+    OT_THREAD_DIRECT_WAKE_TYPE_POWER_OUTAGE   = 1, ///< Wake Frame signaling a power outage event.
+    OT_THREAD_DIRECT_WAKE_TYPE_CONNECTIONLESS = 2, ///< Connectionless Wake Frame (no link establishment).
+} otThreadDirectWakeType;
+
+/**
+ * Starts a Thread Direct wake burst targeting @p aExtAddress.
+ *
+ * Transmits Wake Frames of type @p aWakeType at @p aIntervalUs for @p aDurationMs.
+ * When @p aWakeType is OT_THREAD_DIRECT_WAKE_TYPE_LINK, a connection window is opened
+ * after the burst; the registered event callback (see otThreadDirectSetEventCallback())
+ * fires OT_THREAD_DIRECT_EVENT_LINK_FAILED if the window expires without a response.
+ *
+ * Pass @p aIntervalUs = 0 to use OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_INTERVAL_US.
+ * Pass @p aDurationMs = 0 to use OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_DURATION_MS.
+ *
+ * Wake Frames are secured with the key identified by @p aKeyIndex.  Pass 0 or 129 for
+ * the network-derived Wake Key (HMAC-SHA256(NetworkKey, "Thread-Wake")).  Pass an index
+ * in [130, 192] to use a guest Wake Key previously provisioned via
+ * otThreadDirectSetGuestWakeKey().
+ *
+ * @param[in] aInstance    The OpenThread instance.
+ * @param[in] aExtAddress  Extended address of the Wake Listener.
+ * @param[in] aWakeType    Wake frame type.
+ * @param[in] aIntervalUs  Inter-frame interval in us (0 = default).
+ * @param[in] aDurationMs  Wake burst duration in ms (0 = default).
+ * @param[in] aKeyIndex    Key index: 0 or 129 for the network-derived Wake Key;
+ *                         [130, 192] to use a provisioned guest Wake Key.
+ *
+ * @retval OT_ERROR_NONE             Wake burst started.
+ * @retval OT_ERROR_INVALID_ARGS     @p aExtAddress is NULL, or @p aIntervalUs, @p aDurationMs,
+ *                                   or @p aKeyIndex is out of range.
+ * @retval OT_ERROR_INVALID_STATE    A wake burst is already in progress, or @p aKeyIndex is a
+ *                                   guest index for which no key has been provisioned.
+ *
+ * Requires `OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_INITIATOR_ENABLE`.
+ */
+otError otThreadDirectWakeup(otInstance            *aInstance,
+                             const otExtAddress    *aExtAddress,
+                             otThreadDirectWakeType aWakeType,
+                             uint16_t               aIntervalUs,
+                             uint16_t               aDurationMs,
+                             uint8_t                aKeyIndex);
+
+/**
+ * Initiates Thread Direct link teardown to the peer identified by @p aExtAddress.
+ * Sends a TD frame carrying an empty SCA LTV (SCA teardown).
+ *
+ * @param[in] aInstance    The OpenThread instance.
+ * @param[in] aExtAddress  Extended address of the peer to unlink.
+ *
+ * @retval OT_ERROR_NONE          Teardown initiated.
+ * @retval OT_ERROR_NOT_FOUND     No established link to @p aExtAddress.
+ * @retval OT_ERROR_NOT_IMPLEMENTED  Feature is not implemented.
+ */
+otError otThreadDirectUnlink(otInstance *aInstance, const otExtAddress *aExtAddress);
+
+/**
+ * Enables or disables Wake Listener mode.
+ *
+ * When enabled the WL periodically calls otPlatRadioReceiveAt() on Wake Channel 20
+ * according to the configured listen interval and duration.
+ *
+ * @param[in] aInstance  The OpenThread instance.
+ * @param[in] aEnable    TRUE to enable WL listen mode; FALSE to disable.
+ *
+ * @retval OT_ERROR_NONE  Mode updated.
+ *
+ * Requires `OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_LISTENER_ENABLE`.
+ */
+otError otThreadDirectWakeListenerEnable(otInstance *aInstance, bool aEnable);
+
+/**
+ * Returns whether WL wake channel listening is currently active.
+ *
+ * Requires `OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_LISTENER_ENABLE`.
+ *
+ * @param[in] aInstance  The OpenThread instance.
+ *
+ * @returns TRUE if the WL is listening for TD Wake Commands, FALSE otherwise.
+ */
+bool otThreadDirectIsWakeListenerEnabled(otInstance *aInstance);
+
+/**
+ * Returns whether a WI wake burst is currently in progress.
+ *
+ * TRUE covers both the active TX burst phase and the connection window that
+ * immediately follows, during which the WI waits for a TD Link Command from
+ * the WL.
+ *
+ * Requires `OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_INITIATOR_ENABLE`.
+ *
+ * @param[in] aInstance  The OpenThread instance.
+ *
+ * @returns TRUE if a wake burst or connection window is active, FALSE otherwise.
+ */
+bool otThreadDirectIsWakeBurstActive(otInstance *aInstance);
+
+/**
+ * @}
+ *
+ */
+
+#ifdef __cplusplus
+} // extern "C"
+#endif
+
+#endif // OPENTHREAD_THREAD_DIRECT_H_

src/core/BUILD.gn

@@ -377,6 +377,7 @@ openthread_core_files = [
   "api/tcp_api.cpp",
   "api/tcp_ext_api.cpp",
   "api/thread_api.cpp",
+  "api/thread_direct_api.cpp",
   "api/thread_ftd_api.cpp",
   "api/trel_api.cpp",
   "api/udp_api.cpp",
@@ -521,6 +522,8 @@ openthread_core_files = [
   "mac/channel_mask.hpp",
   "mac/data_poll_handler.cpp",
   "mac/data_poll_handler.hpp",
+  "mac/direct_handler.cpp",
+  "mac/direct_handler.hpp",
   "mac/data_poll_sender.cpp",
   "mac/data_poll_sender.hpp",
   "mac/link_raw.cpp",