[IM] Support put ReadClient to on hold when device is sleeping

Author: erjiaqing

src/app/ReadClient.cpp

@@ -223,6 +223,8 @@ const char * ReadClient::GetStateStr() const
         return "AwaitingSubscribeResponse";
     case ClientState::SubscriptionActive:
         return "SubscriptionActive";
+    case ClientState::IdleSubscription:
+        return "IdleSubscription";
     }
 #endif // CHIP_DETAIL_LOGGING
     return "N/A";
@@ -427,6 +429,31 @@ CHIP_ERROR ReadClient::GenerateDataVersionFilterList(DataVersionFilterIBs::Build
     return CHIP_NO_ERROR;
 }
 
+CHIP_ERROR ReadClient::WakeUp()
+{
+    VerifyOrReturnError(IsIdle(), CHIP_ERROR_INCORRECT_STATE, "Not a valid subscription.");
+    VerifyOrReturnError(mPeerActivePeriod != System::Clock::kZero, CHIP_ERROR_INCORRECT_STATE, "The device should not sleep.");
+    MoveToState(ClientState::Idle);
+    Close(CHIP_ERROR_TIMEOUT);
+    return CHIP_NO_ERROR;
+}
+
+void ReadClient::UpdateActivePeriod(System::Clock::Timeout aActivePeriod)
+{
+    mPeerActivePeriod = aActivePeriod;
+}
+
+CHIP_ERROR ReadClient::TouchPeerActiveTime(System::Clock::Timeout aActivePeriod)
+{
+    System::Clock::Timestamp time;
+
+    ReturnLogErrorOnFailure(System::SystemClock().GetClock_RealTime(time));
+
+    mPeerActiveUntilTimestamp = time + aActivePeriod;
+
+    return CHIP_NO_ERROR;
+}
+
 CHIP_ERROR ReadClient::OnMessageReceived(Messaging::ExchangeContext * apExchangeContext, const PayloadHeader & aPayloadHeader,
                                          System::PacketBufferHandle && aPayload)
 {
@@ -894,6 +921,24 @@ void ReadClient::OnLivenessTimeoutCallback(System::Layer * apSystemLayer, void *
                  "Subscription Liveness timeout with SubscriptionID = 0x%08" PRIx32 ", Peer = %02x:" ChipLogFormatX64,
                  _this->mSubscriptionId, _this->GetFabricIndex(), ChipLogValueX64(_this->GetPeerNodeId()));
 
+    if (mPeerActivePeriod != System::Clock::kZero)
+    {
+        // If device is sleeping, we mark the subscription as "IdleSubscription", and trigger resubscription on `WakeUp`.
+        System::Clock::Timestamp time;
+        CHIP_ERROR error = System::SystemClock().GetClock_RealTime(time);
+        if (error != CHIP_NO_ERROR)
+        {
+            ChipLogError(DataManagement, "Failed to get current time: %s", ErrorStr(error));
+            _this->Close(error, false);
+        }
+        if (time > mPeerActiveUntilTimestamp)
+        {
+            ChipLogProgress(DataManagement, "Peer is not active now, mark the subscription as IdleSubscription.");
+            MoveToState(ClientState::IdleSubscription);
+            return;
+        }
+    }
+
     // We didn't get a message from the server on time; it's possible that it no
     // longer has a useful CASE session to us.  Mark defunct all sessions that
     // have not seen peer activity in at least as long as our session.
@@ -998,6 +1043,18 @@ CHIP_ERROR ReadClient::SendSubscribeRequestImpl(const ReadPrepareParams & aReadP
         mReadPrepareParams.mSessionHolder = aReadPrepareParams.mSessionHolder;
     }
 
+    mPeerActivePeriod = aReadPrepareParams.mActivePeriod;
+    if (mPeerActivePeriod != System::Clock::kZero)
+    {
+        System::Clock::Timestamp time;
+        ReturnErrorOnFailure(System::SystemClock().GetClock_RealTime(time));
+        mPeerActiveUntilTimestamp = mPeerActivePeriod;
+    }
+    else
+    {
+        mPeerActiveUntilTimestamp = System::Clock::kZero;
+    }
+
     mMinIntervalFloorSeconds = aReadPrepareParams.mMinIntervalFloorSeconds;
 
     // Todo: Remove the below, Update span in ReadPrepareParams

src/app/ReadClient.h

@@ -323,6 +323,37 @@ class ReadClient : public Messaging::ExchangeDelegate
      */
     CHIP_ERROR SendRequest(ReadPrepareParams & aReadPrepareParams);
 
+    /**
+     *  Wake up the sleeping subscription.
+     *
+     *  When subscriptiing to ICD, the subscriber is expected to set the `mActivePeriod`
+     * in `ReadPrepareParams`.
+     *
+     *  @retval #others fail to send read request
+     *  @retval #CHIP_NO_ERROR Successfully waked up the subscription.
+     *  @retval #CHIP_ERROR_INCORRECT_STATE The transcation is not an active subscription
+     */
+    CHIP_ERROR WakeUp();
+
+    /**
+     *  Update the active period of the device. This method **will not** update the
+     * timestamp used to determine whether the device is idle.
+     *
+     *  A Zero period means the device will always be active.
+     */
+    void UpdateActivePeriod(System::Clock::Timeout aActivePeriod);
+
+    /**
+     *  Update the time used to determine whether the device is idle to the period from now.
+     * This method **will not** update the active period for future wake-ups.
+     *
+     *  A zero period means the device will sleep immediately.
+     *
+     *  @retval #CHIP_NO_ERROR Successfully updated the active time.
+     *  @retval #others failed to update the active time.
+     */
+    CHIP_ERROR TouchPeerActiveTime(System::Clock::Timeout aActivePeriod);
+
     void OnUnsolicitedReportData(Messaging::ExchangeContext * apExchangeContext, System::PacketBufferHandle && aPayload);
 
     void OnUnsolicitedMessageFromPublisher()
@@ -477,6 +508,7 @@ class ReadClient : public Messaging::ExchangeDelegate
         AwaitingInitialReport,     ///< The client is waiting for initial report
         AwaitingSubscribeResponse, ///< The client is waiting for subscribe response
         SubscriptionActive,        ///< The client is maintaining subscription
+        IdleSubscription,          ///< The client is ICD and is sleeping
     };
 
     enum class ReportType
@@ -500,7 +532,7 @@ class ReadClient : public Messaging::ExchangeDelegate
      *  Check if current read client is being used
      *
      */
-    bool IsIdle() const { return mState == ClientState::Idle; }
+    bool IsIdle() const { return mState == ClientState::Idle || mState == ClientState::IdleSubscription; }
     bool IsSubscriptionActive() const { return mState == ClientState::SubscriptionActive; }
     bool IsAwaitingInitialReport() const { return mState == ClientState::AwaitingInitialReport; }
     bool IsAwaitingSubscribeResponse() const { return mState == ClientState::AwaitingSubscribeResponse; }
@@ -612,6 +644,11 @@ class ReadClient : public Messaging::ExchangeDelegate
 
     System::Clock::Timeout mLivenessTimeoutOverride = System::Clock::kZero;
 
+    // When the liveness timeout fired after `mPeerActiveUntilTimestamp`, the ReadClient will enter "Sleep" state until WakeUp() is called.
+    // The Zero value means the device should always be active.
+    System::Clock::Timeout mPeerActivePeriod = System::Clock::kZero;
+    System::Clock::Timestamp mPeerActiveUntilTimestamp = System::Clock::kZero;
+
     // End Of Container (0x18) uses one byte.
     static constexpr uint16_t kReservedSizeForEndOfContainer = 1;
     // Reserved size for the uint8_t InteractionModelRevision flag, which takes up 1 byte for the control tag and 1 byte for the

src/app/ReadPrepareParams.h

@@ -47,6 +47,8 @@ struct ReadPrepareParams
     uint16_t mMaxIntervalCeilingSeconds = 0;
     bool mKeepSubscriptions             = false;
     bool mIsFabricFiltered              = true;
+    // The active period of the device, a Zero value means the device is always active.
+    System::Clock::Timeout mActivePeriod = System::Clock::kZero;
 
     ReadPrepareParams() {}
     ReadPrepareParams(const SessionHandle & sessionHandle) { mSessionHolder.Grab(sessionHandle); }
@@ -64,6 +66,7 @@ struct ReadPrepareParams
         mMaxIntervalCeilingSeconds         = other.mMaxIntervalCeilingSeconds;
         mTimeout                           = other.mTimeout;
         mIsFabricFiltered                  = other.mIsFabricFiltered;
+        mActivePeriod                      = other.mActivePeriod;
         other.mpEventPathParamsList        = nullptr;
         other.mEventPathParamsListSize     = 0;
         other.mpAttributePathParamsList    = nullptr;
@@ -88,6 +91,7 @@ struct ReadPrepareParams
         mMaxIntervalCeilingSeconds         = other.mMaxIntervalCeilingSeconds;
         mTimeout                           = other.mTimeout;
         mIsFabricFiltered                  = other.mIsFabricFiltered;
+        mActivePeriod                      = other.mActivePeriod;
         other.mpEventPathParamsList        = nullptr;
         other.mEventPathParamsListSize     = 0;
         other.mpAttributePathParamsList    = nullptr;