From 4ce6a4708d2847374e2ec110511638f4dc51753c Mon Sep 17 00:00:00 2001 From: Eduardo Montoya Date: Mon, 8 Aug 2022 20:42:39 +0200 Subject: [PATCH] [api] allow CSL receiver to gather parent CSL capabilities (#7991) This commit extends the Thread API to allow a CSL Receiver application to adjust its CSL parameters depending on the parent capabilities. Specifically, it might decide to switch to polling operation instead of CSL synchronization when the attached parent does not support CSL Transmitter role (Thread Version 2) or it advertises poor CSL accuracy or uncertainty. --- include/openthread/instance.h | 2 +- include/openthread/thread.h | 8 ++++++++ src/cli/README.md | 10 +++++++++- src/cli/cli.cpp | 6 +++++- src/core/api/thread_api.cpp | 5 +++++ src/lib/spinel/spinel.h | 5 ++++- src/ncp/ncp_base_mtd.cpp | 5 +++++ 7 files changed, 37 insertions(+), 4 deletions(-) diff --git a/include/openthread/instance.h b/include/openthread/instance.h index 26bdb949a..974860fea 100644 --- a/include/openthread/instance.h +++ b/include/openthread/instance.h @@ -53,7 +53,7 @@ extern "C" { * @note This number versions both OpenThread platform and user APIs. * */ -#define OPENTHREAD_API_VERSION (231) +#define OPENTHREAD_API_VERSION (232) /** * @addtogroup api-instance diff --git a/include/openthread/thread.h b/include/openthread/thread.h index d98ad66a9..ef9cbd1de 100644 --- a/include/openthread/thread.h +++ b/include/openthread/thread.h @@ -138,6 +138,14 @@ typedef struct uint8_t mAge; ///< Time last heard bool mAllocated : 1; ///< Router ID allocated or not bool mLinkEstablished : 1; ///< Link established with Router ID or not + uint8_t mVersion; ///< Thread version + + /** + * Parent CSL parameters are only relevant when OPENTHREAD_CONFIG_MAC_CSL_RECEIVER_ENABLE is enabled. + * + */ + uint8_t mCslClockAccuracy; ///< CSL clock accuracy, in ± ppm + uint8_t mCslUncertainty; ///< CSL uncertainty, in ±10 us } otRouterInfo; /** diff --git a/src/cli/README.md b/src/cli/README.md index c088da474..d1455b8fe 100644 --- a/src/cli/README.md +++ b/src/cli/README.md @@ -1995,7 +1995,7 @@ Done Get the diagnostic information for a Thread Router as parent. -Note: When operating as a Thread Router, this command will return the cached information from when the device was previously attached as a Thread Child. Returning cached information is necessary to support the Thread Test Harness - Test Scenario 8.2.x requests the former parent (i.e. Joiner Router's) MAC address even if the device has already promoted to a router. +Note: When operating as a Thread Router when `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` is enabled, this command will return the cached information from when the device was previously attached as a Thread Child. Returning cached information is necessary to support the Thread Test Harness - Test Scenario 8.2.x requests the former parent (i.e. Joiner Router's) MAC address even if the device has already promoted to a router. ```bash > parent @@ -2004,9 +2004,17 @@ Rloc: 5c00 Link Quality In: 3 Link Quality Out: 3 Age: 20 +Version: 4 Done ``` +Note: When `OPENTHREAD_CONFIG_MAC_CSL_RECEIVER_ENABLE` is enabled, this command will return two extra lines with information relevant for CSL Receiver operation. + +```bash +CSL clock accuracy: 20 +CSL uncertainty: 5 +``` + ### parentpriority Get the assigned parent priority value, -2 means not assigned. diff --git a/src/cli/cli.cpp b/src/cli/cli.cpp index 1825b7ea9..73866d3c2 100644 --- a/src/cli/cli.cpp +++ b/src/cli/cli.cpp @@ -3787,7 +3787,11 @@ template <> otError Interpreter::Process(Arg aArgs[]) OutputLine("Link Quality In: %d", parentInfo.mLinkQualityIn); OutputLine("Link Quality Out: %d", parentInfo.mLinkQualityOut); OutputLine("Age: %d", parentInfo.mAge); - + OutputLine("Version: %d", parentInfo.mVersion); +#if OPENTHREAD_CONFIG_MAC_CSL_RECEIVER_ENABLE + OutputLine("CSL clock accuracy: %d", parentInfo.mCslClockAccuracy); + OutputLine("CSL uncertainty: %d", parentInfo.mCslUncertainty); +#endif exit: return error; } diff --git a/src/core/api/thread_api.cpp b/src/core/api/thread_api.cpp index bec8c0633..190d035c3 100644 --- a/src/core/api/thread_api.cpp +++ b/src/core/api/thread_api.cpp @@ -368,6 +368,11 @@ otError otThreadGetParentInfo(otInstance *aInstance, otRouterInfo *aParentInfo) aParentInfo->mAge = static_cast(Time::MsecToSec(TimerMilli::GetNow() - parent->GetLastHeard())); aParentInfo->mAllocated = true; aParentInfo->mLinkEstablished = parent->IsStateValid(); + aParentInfo->mVersion = parent->GetVersion(); +#if OPENTHREAD_CONFIG_MAC_CSL_RECEIVER_ENABLE + aParentInfo->mCslClockAccuracy = parent->GetCslClockAccuracy(); + aParentInfo->mCslUncertainty = parent->GetCslUncertainty(); +#endif #if !OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE exit: diff --git a/src/lib/spinel/spinel.h b/src/lib/spinel/spinel.h index bc1b8d564..845385756 100644 --- a/src/lib/spinel/spinel.h +++ b/src/lib/spinel/spinel.h @@ -2295,7 +2295,7 @@ enum SPINEL_PROP_THREAD_LEADER_ADDR = SPINEL_PROP_THREAD__BEGIN + 0, /// Thread Parent Info - /** Format: `ESLccCC` - Read only + /** Format: `ESLccCCCCC` - Read only * * `E`: Extended address * `S`: RLOC16 @@ -2304,6 +2304,9 @@ enum * `c`: Last RSSI (in dBm) * `C`: Link Quality In * `C`: Link Quality Out + * `C`: Version + * `C`: CSL clock accuracy + * `C`: CSL uncertainty * */ SPINEL_PROP_THREAD_PARENT = SPINEL_PROP_THREAD__BEGIN + 1, diff --git a/src/ncp/ncp_base_mtd.cpp b/src/ncp/ncp_base_mtd.cpp index e2dbb5323..aa717ee57 100644 --- a/src/ncp/ncp_base_mtd.cpp +++ b/src/ncp/ncp_base_mtd.cpp @@ -806,6 +806,11 @@ template <> otError NcpBase::HandlePropertyGet(void) SuccessOrExit(error = mEncoder.WriteInt8(lastRssi)); SuccessOrExit(error = mEncoder.WriteUint8(parentInfo.mLinkQualityIn)); SuccessOrExit(error = mEncoder.WriteUint8(parentInfo.mLinkQualityOut)); + SuccessOrExit(error = mEncoder.WriteUint8(parentInfo.mVersion)); +#if OPENTHREAD_CONFIG_MAC_CSL_RECEIVER_ENABLE + SuccessOrExit(error = mEncoder.WriteUint8(parentInfo.mCslClockAccuracy)); + SuccessOrExit(error = mEncoder.WriteUint8(parentInfo.mCslUncertainty)); +#endif } else {