[wed] send Parent Request when receiving a wake-up frame

This commit implements a new `EnhCslSender` module which combines functionality from `CslTxScheduler` and `IndirectSender` for MTD devices. For now it's only used for communication with Wake-up Parent, but can be extended in the future to schedule messages for other synchronized neighbors. In `Mac`, a new `kOperationTransmitDataEnhCsl` operation is added which mimics `kOperationTransmitDataCsl`. When a wake-up frame is received: - Schedule modified Parent Request to Wake-up Coordinator - Suppress Announce messages - Suppress data polling - Pause MLE attach backoff
edmont · Nov 14, 2024 · 32506eb · 32506eb
1 parent ec7e02d
commit 32506eb
Show file tree

Hide file tree

Showing 17 changed files with 1,066 additions and 32 deletions.
diff --git a/src/core/BUILD.gn b/src/core/BUILD.gn
@@ -641,6 +641,8 @@ openthread_core_files = [
   "thread/dua_manager.hpp",
   "thread/energy_scan_server.cpp",
   "thread/energy_scan_server.hpp",
+  "thread/enh_csl_sender.cpp",
+  "thread/enh_csl_sender.hpp",
   "thread/indirect_sender.cpp",
   "thread/indirect_sender.hpp",
   "thread/indirect_sender_frame_context.hpp",

diff --git a/src/core/CMakeLists.txt b/src/core/CMakeLists.txt
@@ -213,6 +213,7 @@ set(COMMON_SOURCES
     thread/discover_scanner.cpp
     thread/dua_manager.cpp
     thread/energy_scan_server.cpp
+    thread/enh_csl_sender.cpp
     thread/indirect_sender.cpp
     thread/key_manager.cpp
     thread/link_metrics.cpp

diff --git a/src/core/common/locator.hpp b/src/core/common/locator.hpp
@@ -81,7 +81,7 @@ template <class InstanceGetProvider> class GetProvider
      *
      * @returns A reference to the `Type` object of the instance.
      */
-    template <typename Type> inline Type &Get(void) const; // Implemented in `locator_getters.hpp`.
+    template <typename Type> inline Type &Get(void) const;
 
 protected:
     GetProvider(void) = default;

diff --git a/src/core/config/mac.h b/src/core/config/mac.h
@@ -558,6 +558,25 @@
 #define OPENTHREAD_CONFIG_MAC_DATA_POLL_TIMEOUT 100
 #endif
 
+/**
+ * @def OPENTHREAD_CONFIG_MAC_CSL_WAKEUP_INTERVAL
+ *
+ * Periodicity of wake-up frame transmission by WC (in units of 10 symbols).
+ */
+#ifndef OPENTHREAD_CONFIG_MAC_CSL_WAKEUP_INTERVAL
+#define OPENTHREAD_CONFIG_MAC_CSL_WAKEUP_INTERVAL 47
+#endif
+
+/**
+ * @def OPENTHREAD_CONFIG_MAC_ENH_CSL_TX_ATTEMPTS
+ *
+ * Maximum number of TX attempts for the enhanced CSL communication before considering the peer de-synchronized.
+ *
+ */
+#ifndef OPENTHREAD_CONFIG_MAC_ENH_CSL_TX_ATTEMPTS
+#define OPENTHREAD_CONFIG_MAC_ENH_CSL_TX_ATTEMPTS 8
+#endif
+
 /**
  * @}
  */

diff --git a/src/core/instance/instance.hpp b/src/core/instance/instance.hpp
@@ -836,6 +836,10 @@ template <> inline MeshCoP::Leader &Instance::Get(void) { return mLeader; }
 template <> inline MeshCoP::JoinerRouter &Instance::Get(void) { return mJoinerRouter; }
 #endif // OPENTHREAD_FTD
 
+#if OPENTHREAD_MTD && OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE
+template <> inline EnhCslSender &Instance::Get(void) { return mMeshForwarder.mEnhCslSender; }
+#endif
+
 template <> inline AnnounceBeginServer &Instance::Get(void) { return mAnnounceBegin; }
 
 template <> inline DataPollSender &Instance::Get(void) { return mMeshForwarder.mDataPollSender; }

diff --git a/src/core/mac/mac.cpp b/src/core/mac/mac.cpp
@@ -203,6 +203,9 @@ bool Mac::IsInTransmitState(void) const
 #if OPENTHREAD_CONFIG_MAC_CSL_TRANSMITTER_ENABLE
     case kOperationTransmitDataCsl:
 #endif
+#endif
+#if OPENTHREAD_MTD && OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE
+    case kOperationTransmitDataEnhCsl:
 #endif
     case kOperationTransmitBeacon:
     case kOperationTransmitPoll:
@@ -521,6 +524,20 @@ void Mac::RequestCslFrameTransmission(uint32_t aDelay)
 #endif
 #endif // OPENTHREAD_FTD
 
+#if OPENTHREAD_MTD && OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE
+void Mac::RequestEnhCslFrameTransmission(uint32_t aDelay)
+{
+    VerifyOrExit(mEnabled);
+
+    mEnhCslTxFireTime = TimerMilli::GetNow() + aDelay;
+
+    StartOperation(kOperationTransmitDataEnhCsl);
+
+exit:
+    return;
+}
+#endif
+
 Error Mac::RequestDataPollTransmission(void)
 {
     Error error = kErrorNone;
@@ -546,6 +563,13 @@ void Mac::UpdateIdleMode(void)
 
     VerifyOrExit(mOperation == kOperationIdle);
 
+#if OPENTHREAD_MTD && OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE
+    if (IsPending(kOperationTransmitDataEnhCsl))
+    {
+        mTimer.FireAt(mEnhCslTxFireTime);
+    }
+#endif
+
     if (!mRxOnWhenIdle)
     {
 #if OPENTHREAD_CONFIG_MAC_STAY_AWAKE_BETWEEN_FRAGMENTS
@@ -646,6 +670,12 @@ void Mac::PerformNextOperation(void)
     {
         mOperation = kOperationTransmitDataCsl;
     }
+#endif
+#if OPENTHREAD_MTD && OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE
+    else if (IsPending(kOperationTransmitDataEnhCsl) && TimerMilli::GetNow() >= mEnhCslTxFireTime)
+    {
+        mOperation = kOperationTransmitDataEnhCsl;
+    }
 #endif
     else if (IsPending(kOperationActiveScan))
     {
@@ -710,6 +740,9 @@ void Mac::PerformNextOperation(void)
 #if OPENTHREAD_CONFIG_MAC_CSL_TRANSMITTER_ENABLE
     case kOperationTransmitDataCsl:
 #endif
+#endif
+#if OPENTHREAD_MTD && OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE
+    case kOperationTransmitDataEnhCsl:
 #endif
     case kOperationTransmitPoll:
         BeginTransmit();
@@ -1023,6 +1056,23 @@ void Mac::BeginTransmit(void)
 #endif
 #endif // OPENTHREAD_FTD
 
+#if OPENTHREAD_MTD && OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE
+    case kOperationTransmitDataEnhCsl:
+        txFrames.SetChannel(mRadioChannel);
+        txFrames.SetMaxCsmaBackoffs(kMaxCsmaBackoffsCsl);
+        txFrames.SetMaxFrameRetries(kMaxFrameRetriesCsl);
+        frame = Get<EnhCslSender>().HandleFrameRequest(txFrames);
+        VerifyOrExit(frame != nullptr);
+
+        // If the frame is marked as retransmission, then data sequence number is already set.
+        if (!frame->IsARetransmission())
+        {
+            frame->SetSequence(mDataSequence++);
+        }
+
+        break;
+#endif
+
     default:
         OT_ASSERT(false);
     }
@@ -1457,14 +1507,25 @@ void Mac::HandleTransmitDone(TxFrame &aFrame, RxFrame *aAckFrame, Error aError)
             mRetryHistogram.mTxIndirectRetrySuccess[mLinks.GetTransmitRetries()]++;
         }
 #endif
-
         DumpDebg("TX", aFrame.GetHeader(), aFrame.GetLength());
         FinishOperation();
         Get<DataPollHandler>().HandleSentFrame(aFrame, aError);
         PerformNextOperation();
         break;
 #endif // OPENTHREAD_FTD
 
+#if OPENTHREAD_MTD && OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE
+    case kOperationTransmitDataEnhCsl:
+        mCounters.mTxData++;
+
+        DumpDebg("TX", aFrame.GetHeader(), aFrame.GetLength());
+        FinishOperation();
+        Get<EnhCslSender>().HandleSentFrame(aFrame, aError);
+        PerformNextOperation();
+
+        break;
+#endif
+
     default:
         OT_ASSERT(false);
     }
@@ -1491,6 +1552,12 @@ void Mac::HandleTimer(void)
         break;
 
     case kOperationIdle:
+#if OPENTHREAD_MTD && OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE
+        if (IsPending(kOperationTransmitDataEnhCsl))
+        {
+            PerformNextOperation();
+        }
+#endif
         if (!mRxOnWhenIdle)
         {
 #if OPENTHREAD_CONFIG_MAC_STAY_AWAKE_BETWEEN_FRAGMENTS
@@ -1606,7 +1673,8 @@ Error Mac::ProcessReceiveSecurity(RxFrame &aFrame, const Address &aSrcAddr, Neig
         {
             uint32_t sequence;
 
-            // TODO: Avoid generating a new key if a wake-up frame was recently received already
+            // Avoid generating a new key if a wake-up frame was recently received already
+            VerifyOrExit(!Get<Mle::Mle>().IsWakeupParentPresent(), error = kErrorInvalidState);
 
             IgnoreError(aFrame.GetKeyId(keyid));
             sequence = BigEndian::ReadUint32(aFrame.GetKeySource());
@@ -2237,6 +2305,9 @@ const char *Mac::OperationToString(Operation aOperation)
 #if OPENTHREAD_CONFIG_MAC_CSL_TRANSMITTER_ENABLE
         "TransmitDataCsl", // (8) kOperationTransmitDataCsl
 #endif
+#endif
+#if OPENTHREAD_MTD && OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE
+        "TransmitDataEnhCsl", // kOperationTransmitDataEnhCsl
 #endif
     };
 
@@ -2560,14 +2631,17 @@ void Mac::UpdateWakeupListening(void)
 
 Error Mac::HandleWakeupFrame(const RxFrame &aFrame)
 {
-    Error               error = kErrorNone;
+    Error               error             = kErrorNone;
+    constexpr uint32_t  kWakeupIntervalUs = kDefaultWedListenInterval * kUsPerTenSymbols;
     const ConnectionIe *connectionIe;
     uint32_t            rvTimeUs;
     uint64_t            rvTimestampUs;
     uint32_t            attachDelayMs;
     uint64_t            radioNowUs;
     uint8_t             retryInterval;
     uint8_t             retryCount;
+    Neighbor           *coord;
+    Address             coordAddress;
 
     VerifyOrExit(mWakeupListenEnabled && aFrame.IsWakeupFrame());
     connectionIe  = aFrame.GetConnectionIe();
@@ -2601,8 +2675,21 @@ Error Mac::HandleWakeupFrame(const RxFrame &aFrame)
     // Stop receiving more wake up frames
     IgnoreError(SetWakeupListenEnabled(false));
 
-    // TODO: start MLE attach process with the WC
-    OT_UNUSED_VARIABLE(attachDelayMs);
+    IgnoreError(aFrame.GetSrcAddr(coordAddress));
+    Get<Mle::Mle>().InitParentCandidate(coordAddress.GetExtended());
+    coord = &Get<Mle::MleRouter>().GetParentCandidate();
+    coord->SetEnhCslPeriod(kDefaultWedListenInterval * retryInterval);
+    coord->SetEnhCslPhase(0);
+    coord->SetEnhCslSynchronized(true);
+    coord->SetEnhCslLastHeard(TimerMilli::GetNow());
+    // Rendezvous time is the time when the WC begins listening for the connection request from the awakened WED.
+    // Since EnhCslSender schedules a frame's PHR at `LastRxTimestamp + Phase + n*Period`, increase the timestamp
+    // by SHR length and the CSL uncertainty to make sure SHR begins while the WC is already listening.
+    coord->SetEnhLastRxTimestamp(rvTimestampUs + kRadioHeaderShrDuration + Get<Radio>().GetCslUncertainty() * 10);
+    coord->SetEnhCslMaxTxAttempts(retryCount);
+
+    Get<Mle::Mle>().AttachToWakeupParent(coordAddress.GetExtended(), TimerMilli::GetNow() + attachDelayMs,
+                                         kWakeupIntervalUs * retryInterval * retryCount / 1000);
 
 exit:
     return error;

diff --git a/src/core/mac/mac.hpp b/src/core/mac/mac.hpp
@@ -91,6 +91,7 @@ constexpr uint16_t kMinCslIePeriod = OPENTHREAD_CONFIG_MAC_CSL_MIN_PERIOD;
 
 constexpr uint32_t kDefaultWedListenInterval = OPENTHREAD_CONFIG_WED_LISTEN_INTERVAL;
 constexpr uint32_t kDefaultWedListenDuration = OPENTHREAD_CONFIG_WED_LISTEN_DURATION;
+constexpr uint16_t kDefaultWakeupInterval    = OPENTHREAD_CONFIG_MAC_CSL_WAKEUP_INTERVAL;
 
 /**
  * Defines the function pointer called on receiving an IEEE 802.15.4 Beacon during an Active Scan.
@@ -213,6 +214,16 @@ class Mac : public InstanceLocator, private NonCopyable
     void RequestCslFrameTransmission(uint32_t aDelay);
 #endif
 
+#endif
+
+#if OPENTHREAD_MTD && OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE
+    /**
+     * Requests `Mac` to start an enhanced CSL tx operation after a delay of @p aDelay time.
+     *
+     * @param[in]  aDelay  Delay time for `Mac` to start an enhanced CSL tx, in units of milliseconds.
+     *
+     */
+    void RequestEnhCslFrameTransmission(uint32_t aDelay);
 #endif
 
     /**
@@ -776,6 +787,9 @@ class Mac : public InstanceLocator, private NonCopyable
 #if OPENTHREAD_CONFIG_MAC_CSL_TRANSMITTER_ENABLE
         kOperationTransmitDataCsl,
 #endif
+#endif
+#if OPENTHREAD_MTD && OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE
+        kOperationTransmitDataEnhCsl,
 #endif
     };
 
@@ -898,8 +912,9 @@ class Mac : public InstanceLocator, private NonCopyable
 #endif
     uint8_t mWakeupChannel;
 #if OPENTHREAD_MTD && OPENTHREAD_CONFIG_WAKEUP_END_DEVICE_ENABLE
-    uint32_t mWakeupListenInterval;
-    uint32_t mWakeupListenDuration;
+    uint32_t  mWakeupListenInterval;
+    uint32_t  mWakeupListenDuration;
+    TimeMilli mEnhCslTxFireTime;
 #endif
     union
     {