From df45240665b4fa187a3448a064b2d48a72f32263 Mon Sep 17 00:00:00 2001 From: Abtin Keshavarzian Date: Mon, 16 Apr 2018 11:17:09 -0700 Subject: [PATCH] [channel-monitor] use "channel occupancy" instead of "quality" This commit changes the API names (and spinel properties and documentation) related to "channel monitor" feature to use "channel occupancy" instead of the term "channel quality" to represent the rate/percentage of RSSI samples which are higher than a threshold. --- .../spinel-feature-channel-monitor.md | 6 +-- include/openthread/channel_monitor.h | 17 +++---- src/core/api/channel_monitor_api.cpp | 4 +- src/core/utils/channel_monitor.cpp | 48 +++++++++---------- src/core/utils/channel_monitor.hpp | 28 +++++------ src/ncp/ncp_base.cpp | 2 +- src/ncp/ncp_base.hpp | 2 +- src/ncp/ncp_base_mtd.cpp | 4 +- src/ncp/spinel.c | 4 +- src/ncp/spinel.h | 8 ++-- 10 files changed, 62 insertions(+), 61 deletions(-) diff --git a/doc/spinel-protocol-src/spinel-feature-channel-monitor.md b/doc/spinel-protocol-src/spinel-feature-channel-monitor.md index 8125c307f..a9d7c1cdf 100644 --- a/doc/spinel-protocol-src/spinel-feature-channel-monitor.md +++ b/doc/spinel-protocol-src/spinel-feature-channel-monitor.md @@ -49,7 +49,7 @@ Total number of RSSI samples (per channel) taken by the channel monitoring module since its start (since Thread network interface was enabled). -### PROP 4618: SPINEL_PROP_CHANNEL_MONITOR_CHANNEL_QUALITY (#prop-channel-monitor-channel-quality) +### PROP 4618: SPINEL_PROP_CHANNEL_MONITOR_CHANNEL_OCCUPANCY (#prop-channel-monitor-channel-occupancy) * Type: Read-Only * Packing-Encoding: `A(t(cU))` @@ -57,9 +57,9 @@ was enabled). Data per item is: * `C`: Channel - * `U`: Channel quality indicator + * `U`: Channel occupancy indicator -The channel quality value represents the average rate/percentage of +The channel occupancy value represents the average rate/percentage of RSSI samples that were above RSSI threshold ("bad" RSSI samples) within (approximately) latest sample window RSSI samples. diff --git a/include/openthread/channel_monitor.h b/include/openthread/channel_monitor.h index 042e8b45a..669b8cf9d 100644 --- a/include/openthread/channel_monitor.h +++ b/include/openthread/channel_monitor.h @@ -56,7 +56,8 @@ extern "C" { * When channel monitoring is active, a zero-duration Energy Scan is performed, collecting a single RSSI sample on * every channel per sample interval. The RSSI samples are compared with a pre-specified RSSI threshold. As an * indicator of channel quality, the channel monitoring module maintains and provides the average rate/percentage of - * RSSI samples that are above the threshold within (approximately) a specified sample window. + * RSSI samples that are above the threshold within (approximately) a specified sample window (referred to as channel + * occupancy). * * @{ * @@ -134,25 +135,25 @@ uint32_t otChannelMonitorGetSampleWindow(otInstance *aInstance); uint32_t otChannelMonitorGetSampleCount(otInstance *aInstance); /** - * Gets the current channel quality value for a given channel. + * Gets the current channel occupancy for a given channel. * - * The channel quality value represents the average rate/percentage of RSSI samples that were above RSSI threshold + * The channel occupancy value represents the average rate/percentage of RSSI samples that were above RSSI threshold * ("bad" RSSI samples). * * For the first "sample window" samples, the average is maintained as the actual percentage (i.e., ratio of number * of "bad" samples by total number of samples). After "window" samples, the averager uses an exponentially - * weighted moving average. Practically, this means the quality is representative of up to `3 * window` last samples - * with highest weight given to latest `kSampleWindow` samples. + * weighted moving average. Practically, this means the average is representative of up to `3 * window` last samples + * with highest weight given to the latest `kSampleWindow` samples. * * Max value of `0xffff` indicates all RSSI samples were above RSSI threshold (i.e. 100% of samples were "bad"). * * @param[in] aInstance A pointer to an OpenThread instance. - * @param[in] aChannel The channel for which to get the link quality. + * @param[in] aChannel The channel for which to get the link occupancy. * - * @returns The current channel quality value for the given channel. + * @returns The current channel occupancy for the given channel. * */ -uint16_t otChannelMonitorGetChannelQuality(otInstance *aInstance, uint8_t aChannel); +uint16_t otChannelMonitorGetChannelOccupancy(otInstance *aInstance, uint8_t aChannel); /** * @} diff --git a/src/core/api/channel_monitor_api.cpp b/src/core/api/channel_monitor_api.cpp index 48bbb2546..48b0b5ab7 100644 --- a/src/core/api/channel_monitor_api.cpp +++ b/src/core/api/channel_monitor_api.cpp @@ -82,11 +82,11 @@ uint32_t otChannelMonitorGetSampleCount(otInstance *aInstance) return instance.GetChannelMonitor().GetSampleCount(); } -uint16_t otChannelMonitorGetChannelQuality(otInstance *aInstance, uint8_t aChannel) +uint16_t otChannelMonitorGetChannelOccupancy(otInstance *aInstance, uint8_t aChannel) { Instance &instance = *static_cast(aInstance); - return instance.GetChannelMonitor().GetChannelQuality(aChannel); + return instance.GetChannelMonitor().GetChannelOccupancy(aChannel); } #endif // OPENTHREAD_ENABLE_CHANNEL_MONITOR diff --git a/src/core/utils/channel_monitor.cpp b/src/core/utils/channel_monitor.cpp index 42efe564b..9ddb878bf 100644 --- a/src/core/utils/channel_monitor.cpp +++ b/src/core/utils/channel_monitor.cpp @@ -56,7 +56,7 @@ ChannelMonitor::ChannelMonitor(Instance &aInstance) , mSampleCount(0) , mTimer(aInstance, &ChannelMonitor::HandleTimer, this) { - memset(mChannelQuality, 0, sizeof(mChannelQuality)); + memset(mChannelOccupancy, 0, sizeof(mChannelOccupancy)); } otError ChannelMonitor::Start(void) @@ -88,20 +88,20 @@ void ChannelMonitor::Clear(void) { mChannelMaskIndex = 0; mSampleCount = 0; - memset(mChannelQuality, 0, sizeof(mChannelQuality)); + memset(mChannelOccupancy, 0, sizeof(mChannelOccupancy)); otLogDebgUtil(GetInstance(), "ChannelMonitor: Clearing data"); } -uint16_t ChannelMonitor::GetChannelQuality(uint8_t aChannel) const +uint16_t ChannelMonitor::GetChannelOccupancy(uint8_t aChannel) const { - uint16_t quality = 0; + uint16_t occupancy = 0; VerifyOrExit((OT_RADIO_CHANNEL_MIN <= aChannel) && (aChannel <= OT_RADIO_CHANNEL_MAX)); - quality = mChannelQuality[aChannel - OT_RADIO_CHANNEL_MIN]; + occupancy = mChannelOccupancy[aChannel - OT_RADIO_CHANNEL_MIN]; exit: - return quality; + return occupancy; } void ChannelMonitor::RestartTimer(void) @@ -162,7 +162,7 @@ void ChannelMonitor::HandleEnergyScanResult(otEnergyScanResult *aResult) else { uint8_t channelIndex = (aResult->mChannel - OT_RADIO_CHANNEL_MIN); - uint32_t newAverage = mChannelQuality[channelIndex]; + uint32_t newAverage = mChannelOccupancy[channelIndex]; uint32_t newValue = 0; uint32_t weight; @@ -172,19 +172,19 @@ void ChannelMonitor::HandleEnergyScanResult(otEnergyScanResult *aResult) if (aResult->mMaxRssi != OT_RADIO_RSSI_INVALID) { - newValue = (aResult->mMaxRssi >= kRssiThreshold) ? kMaxQualityIndicator : 0; + newValue = (aResult->mMaxRssi >= kRssiThreshold) ? kMaxOccupancy : 0; } - // `mChannelQuality` stores the average rate/percentage of RSS samples - // that are higher than a given RSS threshold ("bad" RSS samples). For - // the first `kSampleWindow` samples, the average is maintained as the - // actual percentage (i.e., ratio of number of "bad" samples by total - // number of samples). After `kSampleWindow` samples, the averager - // uses an exponentially weighted moving average logic with weight - // coefficient `1/kSampleWindow` for new values. Practically, this - // means the quality is representative of up to `3 * kSampleWindow` - // last samples with highest weight given to latest `kSampleWindow` - // samples. + // `mChannelOccupancy` stores the average rate/percentage of RSS + // samples that are higher than a given RSS threshold ("bad" RSS + // samples). For the first `kSampleWindow` samples, the average is + // maintained as the actual percentage (i.e., ratio of number of + // "bad" samples by total number of samples). After `kSampleWindow` + // samples, the averager uses an exponentially weighted moving + // average logic with weight coefficient `1/kSampleWindow` for new + // values. Practically, this means the average is representative + // of up to `3 * kSampleWindow` samples with highest weight given + // to the latest `kSampleWindow` samples. if (mSampleCount >= kSampleWindow) { @@ -197,7 +197,7 @@ void ChannelMonitor::HandleEnergyScanResult(otEnergyScanResult *aResult) newAverage = (newAverage * weight + newValue) / (weight + 1); - mChannelQuality[channelIndex] = static_cast(newAverage); + mChannelOccupancy[channelIndex] = static_cast(newAverage); } } @@ -206,11 +206,11 @@ void ChannelMonitor::LogResults(void) otLogInfoUtil( GetInstance(), "ChannelMonitor: %u [%02x %02x %02x %02x %02x %02x %02x %02x %02x %02x %02x %02x %02x %02x %02x %02x]", - mSampleCount, mChannelQuality[0] >> 8, mChannelQuality[1] >> 8, mChannelQuality[2] >> 8, - mChannelQuality[3] >> 8, mChannelQuality[4] >> 8, mChannelQuality[5] >> 8, mChannelQuality[6] >> 8, - mChannelQuality[7] >> 8, mChannelQuality[8] >> 8, mChannelQuality[9] >> 8, mChannelQuality[10] >> 8, - mChannelQuality[11] >> 8, mChannelQuality[12] >> 8, mChannelQuality[13] >> 8, mChannelQuality[14] >> 8, - mChannelQuality[15] >> 8); + mSampleCount, mChannelOccupancy[0] >> 8, mChannelOccupancy[1] >> 8, mChannelOccupancy[2] >> 8, + mChannelOccupancy[3] >> 8, mChannelOccupancy[4] >> 8, mChannelOccupancy[5] >> 8, mChannelOccupancy[6] >> 8, + mChannelOccupancy[7] >> 8, mChannelOccupancy[8] >> 8, mChannelOccupancy[9] >> 8, mChannelOccupancy[10] >> 8, + mChannelOccupancy[11] >> 8, mChannelOccupancy[12] >> 8, mChannelOccupancy[13] >> 8, mChannelOccupancy[14] >> 8, + mChannelOccupancy[15] >> 8); } } // namespace Utils diff --git a/src/core/utils/channel_monitor.hpp b/src/core/utils/channel_monitor.hpp index d54f7f0f3..0ce3f5dcd 100644 --- a/src/core/utils/channel_monitor.hpp +++ b/src/core/utils/channel_monitor.hpp @@ -66,7 +66,7 @@ namespace Utils { * channel collecting a single RSSI sample per channel. The RSSI samples are compared with a pre-specified RSSI * threshold `kRssiThreshold`. As an indicator of channel quality, the `ChannelMonitor` maintains and provides the * average rate/percentage of RSSI samples that are above the threshold within (approximately) a specified sample - * window. + * window (referred to as "channel occupancy"). * */ class ChannelMonitor : public InstanceLocator @@ -148,34 +148,34 @@ public: uint32_t GetSampleCount(void) const { return mSampleCount; } /** - * This method returns the current channel quality value for a given channel. + * This method returns the current channel occupancy for a given channel. * - * The channel quality value represents the average rate/percentage of RSSI samples that were above RSSI threshold + * The channel occupancy represents the average rate/percentage of RSSI samples that were above RSSI threshold * `kRssiThreshold` ("bad" RSSI samples). * * For the first `kSampleWindow` samples, the average is maintained as the actual percentage (i.e., ratio of number * of "bad" samples by total number of samples). After `kSampleWindow` samples, the averager uses an exponentially * weighted moving average logic with weight coefficient `1/kSampleWindow` for new values. Practically, this means - * the quality is representative of up to `3 * kSampleWindow` last samples with highest weight given to latest - * `kSampleWindow` samples. + * the occupancy is representative of up to `3 * kSampleWindow` last samples with highest weight given to the + * latest `kSampleWindow` samples. * * Max value of `0xffff` indicates all RSSI samples were above RSSI threshold (i.e. 100% of samples were "bad"). * - * @param[in] aChannel The channel for which to get the link quality. + * @param[in] aChannel The channel for which to get the link occupancy. * - * @returns the current channel quality value for the given channel. + * @returns the current channel occupancy for the given channel. * */ - uint16_t GetChannelQuality(uint8_t aChannel) const; + uint16_t GetChannelOccupancy(uint8_t aChannel) const; private: enum { - kNumChannels = (OT_RADIO_CHANNEL_MAX - OT_RADIO_CHANNEL_MIN + 1), - kNumChannelMasks = 4, - kTimerInterval = (kSampleInterval / kNumChannelMasks), - kMaxJitterInterval = 4096, - kMaxQualityIndicator = 0xffff, + kNumChannels = (OT_RADIO_CHANNEL_MAX - OT_RADIO_CHANNEL_MIN + 1), + kNumChannelMasks = 4, + kTimerInterval = (kSampleInterval / kNumChannelMasks), + kMaxJitterInterval = 4096, + kMaxOccupancy = 0xffff, }; void RestartTimer(void); @@ -189,7 +189,7 @@ private: uint8_t mChannelMaskIndex : 2; uint32_t mSampleCount : 30; - uint16_t mChannelQuality[kNumChannels]; + uint16_t mChannelOccupancy[kNumChannels]; TimerMilli mTimer; }; diff --git a/src/ncp/ncp_base.cpp b/src/ncp/ncp_base.cpp index fa1f41977..dcb47b28e 100644 --- a/src/ncp/ncp_base.cpp +++ b/src/ncp/ncp_base.cpp @@ -161,7 +161,7 @@ const NcpBase::PropertyHandlerEntry NcpBase::mGetPropertyHandlerTable[] = NCP_GET_PROP_HANDLER_ENTRY(CHANNEL_MONITOR_RSSI_THRESHOLD), NCP_GET_PROP_HANDLER_ENTRY(CHANNEL_MONITOR_SAMPLE_WINDOW), NCP_GET_PROP_HANDLER_ENTRY(CHANNEL_MONITOR_SAMPLE_COUNT), - NCP_GET_PROP_HANDLER_ENTRY(CHANNEL_MONITOR_CHANNEL_QUALITY), + NCP_GET_PROP_HANDLER_ENTRY(CHANNEL_MONITOR_CHANNEL_OCCUPANCY), #endif #if OPENTHREAD_ENABLE_LEGACY NCP_GET_PROP_HANDLER_ENTRY(NEST_LEGACY_ULA_PREFIX), diff --git a/src/ncp/ncp_base.hpp b/src/ncp/ncp_base.hpp index dd6551823..f4ca49d79 100644 --- a/src/ncp/ncp_base.hpp +++ b/src/ncp/ncp_base.hpp @@ -605,7 +605,7 @@ protected: NCP_GET_PROP_HANDLER(CHANNEL_MONITOR_RSSI_THRESHOLD); NCP_GET_PROP_HANDLER(CHANNEL_MONITOR_SAMPLE_WINDOW); NCP_GET_PROP_HANDLER(CHANNEL_MONITOR_SAMPLE_COUNT); - NCP_GET_PROP_HANDLER(CHANNEL_MONITOR_CHANNEL_QUALITY); + NCP_GET_PROP_HANDLER(CHANNEL_MONITOR_CHANNEL_OCCUPANCY); #endif #if OPENTHREAD_ENABLE_LEGACY diff --git a/src/ncp/ncp_base_mtd.cpp b/src/ncp/ncp_base_mtd.cpp index 65767b1d1..23f309e0b 100644 --- a/src/ncp/ncp_base_mtd.cpp +++ b/src/ncp/ncp_base_mtd.cpp @@ -1565,7 +1565,7 @@ otError NcpBase::GetPropertyHandler_CHANNEL_MONITOR_SAMPLE_COUNT(void) return mEncoder.WriteUint32(otChannelMonitorGetSampleCount(mInstance)); } -otError NcpBase::GetPropertyHandler_CHANNEL_MONITOR_CHANNEL_QUALITY(void) +otError NcpBase::GetPropertyHandler_CHANNEL_MONITOR_CHANNEL_OCCUPANCY(void) { otError error = OT_ERROR_NONE; @@ -1574,7 +1574,7 @@ otError NcpBase::GetPropertyHandler_CHANNEL_MONITOR_CHANNEL_QUALITY(void) SuccessOrExit(error = mEncoder.OpenStruct()); SuccessOrExit(error = mEncoder.WriteUint8(channel)); - SuccessOrExit(error = mEncoder.WriteUint16(otChannelMonitorGetChannelQuality(mInstance, channel))); + SuccessOrExit(error = mEncoder.WriteUint16(otChannelMonitorGetChannelOccupancy(mInstance, channel))); SuccessOrExit(error = mEncoder.CloseStruct()); } diff --git a/src/ncp/spinel.c b/src/ncp/spinel.c index ede17b583..dc3a10be6 100644 --- a/src/ncp/spinel.c +++ b/src/ncp/spinel.c @@ -1209,8 +1209,8 @@ spinel_prop_key_to_cstr(spinel_prop_key_t prop_key) ret = "PROP_CHANNEL_MONITOR_SAMPLE_COUNT"; break; - case SPINEL_PROP_CHANNEL_MONITOR_CHANNEL_QUALITY: - ret = "PROP_CHANNEL_MONITOR_CHANNEL_QUALITY"; + case SPINEL_PROP_CHANNEL_MONITOR_CHANNEL_OCCUPANCY: + ret = "PROP_CHANNEL_MONITOR_CHANNEL_OCCUPANCY"; break; case SPINEL_PROP_MAC_SCAN_STATE: diff --git a/src/ncp/spinel.h b/src/ncp/spinel.h index e046aabad..940652af7 100644 --- a/src/ncp/spinel.h +++ b/src/ncp/spinel.h @@ -768,7 +768,7 @@ typedef enum SPINEL_PROP_CHANNEL_MONITOR_SAMPLE_COUNT = SPINEL_PROP_PHY_EXT__BEGIN + 9, - /// Channel monitoring channel quality + /// Channel monitoring channel occupancy /** Format: `A(t(CU))` (read-only) * * Required capability: SPINEL_CAP_CHANNEL_MONITOR @@ -776,9 +776,9 @@ typedef enum * Data per item is: * * `C`: Channel - * `U`: Channel quality indicator + * `U`: Channel occupancy indicator * - * The channel quality value represents the average rate/percentage of + * The channel occupancy value represents the average rate/percentage of * RSSI samples that were above RSSI threshold ("bad" RSSI samples) within * (approximately) sample window latest RSSI samples. * @@ -786,7 +786,7 @@ typedef enum * threshold (i.e. 100% of samples were "bad"). * */ - SPINEL_PROP_CHANNEL_MONITOR_CHANNEL_QUALITY + SPINEL_PROP_CHANNEL_MONITOR_CHANNEL_OCCUPANCY = SPINEL_PROP_PHY_EXT__BEGIN + 10, SPINEL_PROP_PHY_EXT__END = 0x1300,