[thread-direct] add secure wake initiator and listener

- Remove legacy WED/P2P provisional headers
- Remove `mle_p2p.cpp` (Thread Direct uses MAC-layer handshake)
- Add Thread Direct public API (`thread_direct.h`) and platform API (`platform/thread_direct.h`)
- `WakeupTxScheduler` handles wake initiator burst scheduling with wake key index 129 (network-derived) and 130-192 (guest keys)
- Add `sub_mac_wl` for wake listener receive path, rename `sub_mac_wed.cpp` to `sub_mac_wl.cpp`
- Add `DirectHandler` for WI/WL paths with stubs for upcoming implementation
- Add `DirectPeer`/`DirectPeerTable` replacing legacy `peer`/`peer_table`
- Changes to `MeshForwarder::Start` and `Mle::BecomeDetached` to respect rx-off-when-idle for Thread Direct devices
- Add CLI support (`cli_td`)
- Add Spinel/NCP stubs for Thread Direct properties

Author: suveshpratapa

etc/cmake/options.cmake

@@ -242,7 +242,7 @@ ot_option(OT_NETDIAG_CLIENT OPENTHREAD_CONFIG_TMF_NETDIAG_CLIENT_ENABLE "Network
 ot_option(OT_NETDIAG_VENDOR_INFO OPENTHREAD_CONFIG_NET_DIAG_VENDOR_INFO_SET_API_ENABLE "Allow setting vendor info at runtime")
 ot_option(OT_OPERATIONAL_DATASET_AUTO_INIT OPENTHREAD_CONFIG_OPERATIONAL_DATASET_AUTO_INIT "operational dataset auto init")
 ot_option(OT_OTNS OPENTHREAD_CONFIG_OTNS_ENABLE "OTNS")
-ot_option(OT_P2P OPENTHREAD_CONFIG_P2P_ENABLE "peer to peer")
+
 ot_option(OT_PING_SENDER OPENTHREAD_CONFIG_PING_SENDER_ENABLE "ping sender" ${OT_APP_CLI})
 ot_option(OT_PLATFORM_BOOTLOADER_MODE OPENTHREAD_CONFIG_PLATFORM_BOOTLOADER_MODE_ENABLE "platform bootloader mode")
 ot_option(OT_PLATFORM_DNSSD OPENTHREAD_CONFIG_PLATFORM_DNSSD_ENABLE "platform dnssd")
@@ -266,13 +266,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/simulation/radio.c

@@ -1161,6 +1161,33 @@ void otPlatRadioSetMacFrameCounter(otInstance *aInstance, uint32_t aMacFrameCoun
     sRadioContext.mMacFrameCounter = aMacFrameCounter;
 }
 
+#if OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_INITIATOR_ENABLE || OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_LISTENER_ENABLE
+void otPlatRadioSetWakeKey(otInstance *aInstance, uint8_t aKeyIndex, const otMacKeyMaterial *aWakeKey)
+{
+    OT_UNUSED_VARIABLE(aInstance);
+    OT_UNUSED_VARIABLE(aKeyIndex);
+    OT_UNUSED_VARIABLE(aWakeKey);
+}
+#endif
+
+#if OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_INITIATOR_ENABLE
+static uint32_t sWakeFrameCounter;
+
+void otPlatRadioSetWakeFrameCounter(otInstance *aInstance, uint32_t aWakeFrameCounter)
+{
+    OT_UNUSED_VARIABLE(aInstance);
+
+    sWakeFrameCounter = aWakeFrameCounter;
+}
+
+uint32_t otPlatRadioGetWakeFrameCounter(otInstance *aInstance)
+{
+    OT_UNUSED_VARIABLE(aInstance);
+
+    return sWakeFrameCounter;
+}
+#endif
+
 otError otPlatRadioSetChannelMaxTransmitPower(otInstance *aInstance, uint8_t aChannel, int8_t aMaxPower)
 {
     OT_UNUSED_VARIABLE(aInstance);

examples/platforms/utils/mac_frame.cpp

@@ -318,11 +318,7 @@ otError otMacFrameProcessTransmitSecurity(otRadioFrame *aFrame, otRadioContext *
     uint32_t          frameCounter;
     bool              processKeyId;
 
-    processKeyId =
-#if OPENTHREAD_CONFIG_WAKEUP_COORDINATOR_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

@@ -112,12 +112,11 @@ source_set("openthread") {
     "platform/radio.h",
     "platform/settings.h",
     "platform/spi-slave.h",
+    "platform/thread_direct.h",
     "platform/time.h",
     "platform/toolchain.h",
     "platform/trel.h",
     "platform/udp.h",
-    "provisional/link.h",
-    "provisional/p2p.h",
     "radio_stats.h",
     "random_crypto.h",
     "random_noncrypto.h",
@@ -133,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 (603)
+#define OPENTHREAD_API_VERSION (604)
 
 /**
  * @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/platform/radio.h

@@ -744,6 +744,65 @@ void otPlatRadioSetMacFrameCounter(otInstance *aInstance, uint32_t aMacFrameCoun
  */
 void otPlatRadioSetMacFrameCounterIfLarger(otInstance *aInstance, uint32_t aMacFrameCounter);
 
+/**
+ * IEEE 802.15.4 key index reserved for the default Thread Direct Wake Key (network-derived).
+ *
+ * This value (129) is outside the range used for standard Thread MAC keys (1-128). It is
+ * carried in the key index field of TD Wake Frames that use the network-derived wake key.
+ */
+#define OT_MAC_FRAME_WAKE_KEY_INDEX 129
+
+/**
+ * Lowest key index valid for a Thread Direct guest Wake Key.
+ */
+#define OT_MAC_FRAME_GUEST_WAKE_KEY_INDEX_MIN 130
+
+/**
+ * Highest key index valid for a Thread Direct guest Wake Key.
+ */
+#define OT_MAC_FRAME_GUEST_WAKE_KEY_INDEX_MAX 192
+
+/**
+ * Registers or removes a Thread Direct Wake Key at the given key index.
+ *
+ * Is used when radio provides `OT_RADIO_CAPS_TRANSMIT_SEC` capability. When the platform
+ * processes a TX frame whose key index matches `aKeyIndex`, it uses `aWakeKey` to perform
+ * AES-CCM encryption rather than the standard Thread MAC key set registered via
+ * `otPlatRadioSetMacKey`.
+ *
+ * `aKeyIndex` must be `OT_MAC_FRAME_WAKE_KEY_INDEX` (129) for the default network-derived
+ * wake key, or in [`OT_MAC_FRAME_GUEST_WAKE_KEY_INDEX_MIN`,
+ * `OT_MAC_FRAME_GUEST_WAKE_KEY_INDEX_MAX`] (130-192) for a guest wake key.
+ *
+ * Passing `aWakeKey` as NULL removes any previously registered key at `aKeyIndex`.
+ *
+ * @param[in]   aInstance   A pointer to an OpenThread instance.
+ * @param[in]   aKeyIndex   Key index (129 for default, 130-192 for guest keys).
+ * @param[in]   aWakeKey    Key material to register, or NULL to remove.
+ */
+void otPlatRadioSetWakeKey(otInstance *aInstance, uint8_t aKeyIndex, const otMacKeyMaterial *aWakeKey);
+
+/**
+ * Sets the Thread Direct wake frame counter value.
+ *
+ * Is used when radio provides `OT_RADIO_CAPS_TRANSMIT_SEC` capability.
+ *
+ * @param[in]   aInstance           A pointer to an OpenThread instance.
+ * @param[in]   aWakeFrameCounter   The wake frame counter value.
+ */
+void otPlatRadioSetWakeFrameCounter(otInstance *aInstance, uint32_t aWakeFrameCounter);
+
+/**
+ * Gets the current Thread Direct wake frame counter value.
+ *
+ * Is used when radio provides `OT_RADIO_CAPS_TRANSMIT_SEC` capability.
+ *
+ * @param[in]   aInstance  A pointer to an OpenThread instance.
+ *
+ * @returns The current wake frame counter value.
+ */
+uint32_t otPlatRadioGetWakeFrameCounter(otInstance *aInstance);
+
 /**
  * Get the current time in microseconds referenced to a continuous monotonic
  * local radio clock (64 bits width).