mirror of
https://github.com/espressif/openthread.git
synced 2026-09-13 04:30:08 +00:00
[utils] implementing channel monitoring feature (#2451)
This commits introduces channel monitoring feature which monitors signal level on all channels to help determine the cleaner channels (channels with less interference). When enabled and started, `ChannelMonitor` class will perform a zero-duration Energy Scan collecting a single RSSI sample per channel, every sample interval (which is a build-time configurable parameter). The RSSI samples are then compared with a (build-time configurable) RSSI threshold. As an indicator of channel quality, the `ChannelMonitor` class maintains and provides the average rate/percentage of RSS samples that are above the threshold within (approximately) a specified sample window length.
This commit is contained in:
Abtin Keshavarzian
committed by
Jonathan Hui
Jonathan Hui
parent
5841410c72
commit
3043674f4f
@@ -764,6 +764,38 @@ AC_SUBST(OPENTHREAD_ENABLE_JAM_DETECTION)
|
||||
AM_CONDITIONAL([OPENTHREAD_ENABLE_JAM_DETECTION], [test "${enable_jam_detection}" = "yes"])
|
||||
AC_DEFINE_UNQUOTED([OPENTHREAD_ENABLE_JAM_DETECTION],[${OPENTHREAD_ENABLE_JAM_DETECTION}],[Define to 1 if you want to use jam detection feature])
|
||||
|
||||
#
|
||||
# Channel Monitor
|
||||
#
|
||||
|
||||
AC_ARG_ENABLE(channel_monitor,
|
||||
[AS_HELP_STRING([--enable-channel-monitor],[Enable Channel Monitor support @<:@default=no@:>@.])],
|
||||
[
|
||||
case "${enableval}" in
|
||||
|
||||
no|yes)
|
||||
enable_channel_monitor=${enableval}
|
||||
;;
|
||||
|
||||
*)
|
||||
AC_MSG_ERROR([Invalid value ${enable_channel_monitor} for --enable-channel-monitor])
|
||||
;;
|
||||
esac
|
||||
],
|
||||
[enable_channel_monitor=no])
|
||||
|
||||
if test "$enable_channel_monitor" = "yes"; then
|
||||
OPENTHREAD_ENABLE_CHANNEL_MONITOR=1
|
||||
else
|
||||
OPENTHREAD_ENABLE_CHANNEL_MONITOR=0
|
||||
fi
|
||||
|
||||
AC_MSG_CHECKING([whether to enable channel monitor])
|
||||
AC_MSG_RESULT(${enable_channel_monitor})
|
||||
AC_SUBST(OPENTHREAD_ENABLE_CHANNEL_MONITOR)
|
||||
AM_CONDITIONAL([OPENTHREAD_ENABLE_CHANNEL_MONITOR], [test "${enable_channel_monitor}" = "yes"])
|
||||
AC_DEFINE_UNQUOTED([OPENTHREAD_ENABLE_CHANNEL_MONITOR],[${OPENTHREAD_ENABLE_CHANNEL_MONITOR}],[Define to 1 if you want to use channel monitor feature])
|
||||
|
||||
#
|
||||
# MAC Filter (include AddressFilter and RssInFilter)
|
||||
#
|
||||
@@ -1540,6 +1572,7 @@ AC_MSG_NOTICE([
|
||||
OpenThread Joiner support : ${enable_joiner}
|
||||
OpenThread DTLS support : ${enable_dtls}
|
||||
OpenThread Jam Detection support : ${enable_jam_detection}
|
||||
OpenThread Channel Monitor support : ${enable_channel_monitor}
|
||||
OpenThread MAC Filter support : ${enable_mac_filter}
|
||||
OpenThread Diagnostics support : ${enable_diag}
|
||||
OpenThread Child Supervision support : ${enable_child_supervision}
|
||||
|
||||
@@ -182,6 +182,7 @@ SOURCES_COMMON = \
|
||||
thread/thread_netif.cpp \
|
||||
thread/tmf_proxy.cpp \
|
||||
thread/topology.cpp \
|
||||
utils/channel_monitor.cpp \
|
||||
utils/child_supervision.cpp \
|
||||
utils/jam_detector.cpp \
|
||||
utils/missing_strlcpy.c \
|
||||
@@ -293,6 +294,7 @@ HEADERS_COMMON = \
|
||||
thread/thread_uri_paths.hpp \
|
||||
thread/tmf_proxy.hpp \
|
||||
thread/topology.hpp \
|
||||
utils/channel_monitor.hpp \
|
||||
utils/child_supervision.hpp \
|
||||
utils/slaac_address.hpp \
|
||||
utils/jam_detector.hpp \
|
||||
|
||||
@@ -70,6 +70,9 @@ Instance::Instance(void) :
|
||||
#endif
|
||||
#if OPENTHREAD_CONFIG_ENABLE_DYNAMIC_LOG_LEVEL
|
||||
mLogLevel(static_cast<otLogLevel>(OPENTHREAD_CONFIG_LOG_LEVEL)),
|
||||
#endif
|
||||
#if OPENTHREAD_ENABLE_CHANNEL_MONITOR
|
||||
mChannelMonitor(*this),
|
||||
#endif
|
||||
mMessagePool(*this),
|
||||
mIsInitialized(false)
|
||||
@@ -392,4 +395,11 @@ template<> Utils::SupervisionListener &Instance::Get(void)
|
||||
return GetThreadNetif().GetSupervisionListener();
|
||||
}
|
||||
|
||||
#if OPENTHREAD_ENABLE_CHANNEL_MONITOR
|
||||
template<> Utils::ChannelMonitor &Instance::Get(void)
|
||||
{
|
||||
return GetChannelMonitor();
|
||||
}
|
||||
#endif
|
||||
|
||||
} // namespace ot
|
||||
|
||||
@@ -53,7 +53,11 @@
|
||||
#endif
|
||||
#include "common/notifier.hpp"
|
||||
#include "net/ip6.hpp"
|
||||
#include "thread/link_quality.hpp"
|
||||
#include "thread/thread_netif.hpp"
|
||||
#if OPENTHREAD_ENABLE_CHANNEL_MONITOR
|
||||
#include "utils/channel_monitor.hpp"
|
||||
#endif
|
||||
|
||||
/**
|
||||
* @addtogroup core-instance
|
||||
@@ -300,6 +304,16 @@ public:
|
||||
Coap::ApplicationCoap &GetApplicationCoap(void) { return mApplicationCoap; }
|
||||
#endif
|
||||
|
||||
#if OPENTHREAD_ENABLE_CHANNEL_MONITOR
|
||||
/**
|
||||
* This method returns a reference to ChannelMonitor object.
|
||||
*
|
||||
* @returns A reference to the ChannelMonitor object.
|
||||
*
|
||||
*/
|
||||
Utils::ChannelMonitor &GetChannelMonitor(void) { return mChannelMonitor; }
|
||||
#endif
|
||||
|
||||
/**
|
||||
* This method returns a reference to message pool object.
|
||||
*
|
||||
@@ -364,6 +378,10 @@ private:
|
||||
otLogLevel mLogLevel;
|
||||
#endif
|
||||
|
||||
#if OPENTHREAD_ENABLE_CHANNEL_MONITOR
|
||||
Utils::ChannelMonitor mChannelMonitor;
|
||||
#endif
|
||||
|
||||
MessagePool mMessagePool;
|
||||
bool mIsInitialized;
|
||||
};
|
||||
|
||||
@@ -912,7 +912,54 @@
|
||||
#define OPENTHREAD_CONFIG_ENABLE_STEERING_DATA_SET_OOB 0
|
||||
#endif
|
||||
|
||||
/*
|
||||
/**
|
||||
* @def OPENTHREAD_CONFIG_CHANNEL_MONITOR_SAMPLE_INTERVAL
|
||||
*
|
||||
* The sample interval in milliseconds used by Channel Monitoring feature.
|
||||
|
||||
* When enabled, a zero-duration Energy Scan is performed, collecting a single RSSI sample per channel during each
|
||||
* interval.
|
||||
*
|
||||
* Applicable only if Channel Monitoring feature is enabled (i.e., `OPENTHREAD_ENABLE_CHANNEL_MONITOR` is set).
|
||||
*
|
||||
*/
|
||||
#ifndef OPENTHREAD_CONFIG_CHANNEL_MONITOR_SAMPLE_INTERVAL
|
||||
#define OPENTHREAD_CONFIG_CHANNEL_MONITOR_SAMPLE_INTERVAL 41000
|
||||
#endif
|
||||
|
||||
/**
|
||||
* @def OPENTHREAD_CONFIG_CHANNEL_MONITOR_RSS_THRESHOLD
|
||||
*
|
||||
* The RSSI threshold in dBm used by Channel Monitoring feature.
|
||||
*
|
||||
* The RSSI samples are compared with the given threshold. Channel monitoring reports the average rate of RSS samples
|
||||
* that are above this threshold within an observation window (per channel).
|
||||
*
|
||||
* It is recommended that this value is set to same value as the CCA threshold used by radio.
|
||||
*
|
||||
* Applicable only if Channel Monitoring feature is enabled (i.e., `OPENTHREAD_ENABLE_CHANNEL_MONITOR` is set).
|
||||
*
|
||||
*/
|
||||
#ifndef OPENTHREAD_CONFIG_CHANNEL_MONITOR_RSS_THRESHOLD
|
||||
#define OPENTHREAD_CONFIG_CHANNEL_MONITOR_RSS_THRESHOLD -75
|
||||
#endif
|
||||
|
||||
/**
|
||||
* @def OPENTHREAD_CONFIG_CHANNEL_MONITOR_SAMPLE_WINDOW
|
||||
*
|
||||
* The averaging sample window length (in units of channel sample interval) used by Channel Monitoring feature.
|
||||
*
|
||||
* Channel monitoring will sample all channels every sample interval. It maintains the average rate of RSS samples
|
||||
* that are above the RSS threshold within (approximately) this sample window.
|
||||
*
|
||||
* Applicable only if Channel Monitoring feature is enabled (i.e., `OPENTHREAD_ENABLE_CHANNEL_MONITOR` is set).
|
||||
*
|
||||
*/
|
||||
#ifndef OPENTHREAD_CONFIG_CHANNEL_MONITOR_SAMPLE_WINDOW
|
||||
#define OPENTHREAD_CONFIG_CHANNEL_MONITOR_SAMPLE_WINDOW 960
|
||||
#endif
|
||||
|
||||
/**
|
||||
* @def OPENTHREAD_CONFIG_CHILD_SUPERVISION_INTERVAL
|
||||
*
|
||||
* The default supervision interval in seconds used by parent. Set to zero to disable the supervision process on the
|
||||
|
||||
@@ -125,6 +125,9 @@ otError ThreadNetif::Up(void)
|
||||
mCoap.Start(kCoapUdpPort);
|
||||
#if OPENTHREAD_ENABLE_DNS_CLIENT
|
||||
mDnsClient.Start();
|
||||
#endif
|
||||
#if OPENTHREAD_ENABLE_CHANNEL_MONITOR
|
||||
GetInstance().GetChannelMonitor().Start();
|
||||
#endif
|
||||
mChildSupervisor.Start();
|
||||
mMleRouter.Enable();
|
||||
@@ -139,6 +142,9 @@ otError ThreadNetif::Down(void)
|
||||
mCoap.Stop();
|
||||
#if OPENTHREAD_ENABLE_DNS_CLIENT
|
||||
mDnsClient.Stop();
|
||||
#endif
|
||||
#if OPENTHREAD_ENABLE_CHANNEL_MONITOR
|
||||
GetInstance().GetChannelMonitor().Stop();
|
||||
#endif
|
||||
mChildSupervisor.Stop();
|
||||
mMleRouter.Disable();
|
||||
|
||||
@@ -0,0 +1,208 @@
|
||||
/*
|
||||
* Copyright (c) 2018, The OpenThread Authors.
|
||||
* All rights reserved.
|
||||
*
|
||||
* Redistribution and use in source and binary forms, with or without
|
||||
* modification, are permitted provided that the following conditions are met:
|
||||
* 1. Redistributions of source code must retain the above copyright
|
||||
* notice, this list of conditions and the following disclaimer.
|
||||
* 2. Redistributions in binary form must reproduce the above copyright
|
||||
* notice, this list of conditions and the following disclaimer in the
|
||||
* documentation and/or other materials provided with the distribution.
|
||||
* 3. Neither the name of the copyright holder nor the
|
||||
* names of its contributors may be used to endorse or promote products
|
||||
* derived from this software without specific prior written permission.
|
||||
*
|
||||
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
||||
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||||
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
||||
* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
|
||||
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
||||
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
||||
* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
||||
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
||||
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
||||
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
||||
* POSSIBILITY OF SUCH DAMAGE.
|
||||
*/
|
||||
|
||||
/**
|
||||
* @file
|
||||
* This file implements the channel monitoring module.
|
||||
*/
|
||||
|
||||
#include "channel_monitor.hpp"
|
||||
|
||||
#include "common/code_utils.hpp"
|
||||
#include "common/logging.hpp"
|
||||
#include "common/owner-locator.hpp"
|
||||
|
||||
#if OPENTHREAD_ENABLE_CHANNEL_MONITOR
|
||||
|
||||
namespace ot {
|
||||
namespace Utils {
|
||||
|
||||
const uint32_t ChannelMonitor::mScanChannelMasks[kNumChannelMasks] =
|
||||
{
|
||||
OT_CHANNEL_11_MASK | OT_CHANNEL_15_MASK | OT_CHANNEL_19_MASK | OT_CHANNEL_23_MASK,
|
||||
OT_CHANNEL_12_MASK | OT_CHANNEL_16_MASK | OT_CHANNEL_20_MASK | OT_CHANNEL_24_MASK,
|
||||
OT_CHANNEL_13_MASK | OT_CHANNEL_17_MASK | OT_CHANNEL_21_MASK | OT_CHANNEL_25_MASK,
|
||||
OT_CHANNEL_14_MASK | OT_CHANNEL_18_MASK | OT_CHANNEL_22_MASK | OT_CHANNEL_26_MASK,
|
||||
};
|
||||
|
||||
ChannelMonitor::ChannelMonitor(Instance &aInstance):
|
||||
InstanceLocator(aInstance),
|
||||
mChannelMaskIndex(0),
|
||||
mSampleCount(0),
|
||||
mTimer(aInstance, &ChannelMonitor::HandleTimer, this)
|
||||
{
|
||||
memset(mChannelQuality, 0, sizeof(mChannelQuality));
|
||||
}
|
||||
|
||||
void ChannelMonitor::Start(void)
|
||||
{
|
||||
Clear();
|
||||
mTimer.Start(kTimerInterval);
|
||||
otLogDebgMac(GetInstance(), "ChannelMonitor: Starting");
|
||||
}
|
||||
|
||||
void ChannelMonitor::Stop(void)
|
||||
{
|
||||
mTimer.Stop();
|
||||
otLogDebgMac(GetInstance(), "ChannelMonitor: Stopping");
|
||||
}
|
||||
|
||||
void ChannelMonitor::Clear(void)
|
||||
{
|
||||
mChannelMaskIndex = 0;
|
||||
mSampleCount = 0;
|
||||
memset(mChannelQuality, 0, sizeof(mChannelQuality));
|
||||
|
||||
otLogDebgMac(GetInstance(), "ChannelMonitor: Clearing data");
|
||||
}
|
||||
|
||||
uint16_t ChannelMonitor::GetChannelQuality(uint8_t aChannel) const
|
||||
{
|
||||
uint16_t quality = 0;
|
||||
|
||||
VerifyOrExit((OT_RADIO_CHANNEL_MIN <= aChannel) && (aChannel <= OT_RADIO_CHANNEL_MAX));
|
||||
quality = mChannelQuality[aChannel - OT_RADIO_CHANNEL_MIN];
|
||||
|
||||
exit:
|
||||
return quality;
|
||||
}
|
||||
|
||||
void ChannelMonitor::RestartTimer(void)
|
||||
{
|
||||
uint16_t interval = kTimerInterval;
|
||||
int16_t jitter;
|
||||
|
||||
jitter = (otPlatRandomGet() % (2 * kMaxJitterInterval)) - kMaxJitterInterval;
|
||||
|
||||
if (jitter >= kTimerInterval)
|
||||
{
|
||||
jitter = kTimerInterval - 1;
|
||||
}
|
||||
|
||||
if (jitter <= -kTimerInterval)
|
||||
{
|
||||
jitter = -kTimerInterval + 1;
|
||||
}
|
||||
|
||||
interval += jitter;
|
||||
mTimer.StartAt(mTimer.GetFireTime(), interval);
|
||||
|
||||
otLogDebgMac(GetInstance(), "ChannelMonitor: Timer interval %u, jitter %d", interval, jitter);
|
||||
}
|
||||
|
||||
void ChannelMonitor::HandleTimer(Timer &aTimer)
|
||||
{
|
||||
aTimer.GetOwner<ChannelMonitor>().HandleTimer();
|
||||
}
|
||||
|
||||
void ChannelMonitor::HandleTimer(void)
|
||||
{
|
||||
GetInstance().Get<Mac::Mac>().EnergyScan(mScanChannelMasks[mChannelMaskIndex], 0,
|
||||
&ChannelMonitor::HandleEnergyScanResult, this);
|
||||
RestartTimer();
|
||||
}
|
||||
|
||||
void ChannelMonitor::HandleEnergyScanResult(void *aContext, otEnergyScanResult *aResult)
|
||||
{
|
||||
static_cast<ChannelMonitor *>(aContext)->HandleEnergyScanResult(aResult);
|
||||
}
|
||||
|
||||
void ChannelMonitor::HandleEnergyScanResult(otEnergyScanResult *aResult)
|
||||
{
|
||||
if (aResult == NULL)
|
||||
{
|
||||
if (mChannelMaskIndex == kNumChannelMasks - 1)
|
||||
{
|
||||
mChannelMaskIndex = 0;
|
||||
mSampleCount++;
|
||||
LogResults();
|
||||
}
|
||||
else
|
||||
{
|
||||
mChannelMaskIndex++;
|
||||
}
|
||||
}
|
||||
else
|
||||
{
|
||||
uint8_t channelIndex = (aResult->mChannel - OT_RADIO_CHANNEL_MIN);
|
||||
uint32_t newAverage = mChannelQuality[channelIndex];
|
||||
uint32_t newValue = 0;
|
||||
uint32_t weight;
|
||||
|
||||
assert(channelIndex < kNumChannels);
|
||||
|
||||
otLogDebgMac(GetInstance(), "ChannelMonitor: channel: %d, rssi:%d", aResult->mChannel, aResult->mMaxRssi);
|
||||
|
||||
if (aResult->mMaxRssi != OT_RADIO_RSSI_INVALID)
|
||||
{
|
||||
newValue = (aResult->mMaxRssi >= kRssThreshold) ? kMaxQualityIndicator : 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.
|
||||
|
||||
if (mSampleCount >= kSampleWindow)
|
||||
{
|
||||
weight = kSampleWindow - 1;
|
||||
}
|
||||
else
|
||||
{
|
||||
weight = mSampleCount;
|
||||
}
|
||||
|
||||
newAverage = (newAverage * weight + newValue) / (weight + 1);
|
||||
|
||||
mChannelQuality[channelIndex] = static_cast<uint16_t>(newAverage);
|
||||
}
|
||||
}
|
||||
|
||||
void ChannelMonitor::LogResults(void)
|
||||
{
|
||||
otLogInfoMac(
|
||||
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
|
||||
);
|
||||
}
|
||||
|
||||
} // namespace Utils
|
||||
} // namespace ot
|
||||
|
||||
#endif // #if OPENTHREAD_ENABLE_CHANNEL_MONITOR
|
||||
@@ -0,0 +1,192 @@
|
||||
/*
|
||||
* Copyright (c) 2018, The OpenThread Authors.
|
||||
* All rights reserved.
|
||||
*
|
||||
* Redistribution and use in source and binary forms, with or without
|
||||
* modification, are permitted provided that the following conditions are met:
|
||||
* 1. Redistributions of source code must retain the above copyright
|
||||
* notice, this list of conditions and the following disclaimer.
|
||||
* 2. Redistributions in binary form must reproduce the above copyright
|
||||
* notice, this list of conditions and the following disclaimer in the
|
||||
* documentation and/or other materials provided with the distribution.
|
||||
* 3. Neither the name of the copyright holder nor the
|
||||
* names of its contributors may be used to endorse or promote products
|
||||
* derived from this software without specific prior written permission.
|
||||
*
|
||||
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
||||
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||||
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
||||
* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
|
||||
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
||||
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
||||
* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
||||
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
||||
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
||||
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
||||
* POSSIBILITY OF SUCH DAMAGE.
|
||||
*/
|
||||
|
||||
/**
|
||||
* @file
|
||||
* This file includes definitions for channel monitoring module.
|
||||
*/
|
||||
|
||||
#ifndef CHANNEL_MONITOR_HPP_
|
||||
#define CHANNEL_MONITOR_HPP_
|
||||
|
||||
#include "openthread-core-config.h"
|
||||
|
||||
#include <openthread/platform/radio.h>
|
||||
#include <openthread/types.h>
|
||||
|
||||
#include "common/locator.hpp"
|
||||
#include "common/timer.hpp"
|
||||
|
||||
namespace ot {
|
||||
namespace Utils {
|
||||
|
||||
/**
|
||||
* @addtogroup utils-channel-monitor
|
||||
*
|
||||
* @brief
|
||||
* This module includes definitions monitoring quality of channels.
|
||||
*
|
||||
* @{
|
||||
*/
|
||||
|
||||
#if OPENTHREAD_ENABLE_CHANNEL_MONITOR
|
||||
|
||||
/**
|
||||
* This class implements the channel monitoring logic.
|
||||
*
|
||||
* Channel Monitoring will periodically monitor all channels to help determine the cleaner channels (channels
|
||||
* with less interference).
|
||||
*
|
||||
* When Channel Monitoring is active, every `kSampleInterval`, a zero-duration Energy Scan is performed on every
|
||||
* channel collecting a single RSSI sample per channel. The RSSI samples are compared with a pre-specified RSSI
|
||||
* threshold `kRssThreshold`. As an indicator of channel quality, the `ChannelMonitor` maintains and provides the
|
||||
* average rate/percentage of RSS samples that are above the threshold within (approximately) a specified sample window.
|
||||
*
|
||||
*/
|
||||
class ChannelMonitor : public InstanceLocator
|
||||
{
|
||||
public:
|
||||
|
||||
enum
|
||||
{
|
||||
/**
|
||||
* The channel RSSI sample interval in milliseconds.
|
||||
*
|
||||
*/
|
||||
kSampleInterval = OPENTHREAD_CONFIG_CHANNEL_MONITOR_SAMPLE_INTERVAL,
|
||||
|
||||
/**
|
||||
* The RSSI threshold in dBm.
|
||||
*
|
||||
* It is recommended that this value is set to same value as the CCA threshold used by radio.
|
||||
*
|
||||
*/
|
||||
kRssThreshold = OPENTHREAD_CONFIG_CHANNEL_MONITOR_RSS_THRESHOLD,
|
||||
|
||||
/**
|
||||
* The averaging sample window length (in units of sample interval).
|
||||
*
|
||||
*/
|
||||
kSampleWindow = OPENTHREAD_CONFIG_CHANNEL_MONITOR_SAMPLE_WINDOW,
|
||||
};
|
||||
|
||||
/**
|
||||
* This constructor initializes the object.
|
||||
*
|
||||
* @param[in] aInstance A reference to the OpenThread instance.
|
||||
*
|
||||
*/
|
||||
ChannelMonitor(Instance &aInstance);
|
||||
|
||||
/**
|
||||
* This method starts the Channel Monitoring operation.
|
||||
*
|
||||
* All previous data is cleared when the Channel Monitoring operation starts.
|
||||
*
|
||||
*/
|
||||
void Start(void);
|
||||
|
||||
/**
|
||||
* This method stops the Channel Monitoring operation.
|
||||
*
|
||||
* The previous data is still valid and can be read while the operation is stopped.
|
||||
*
|
||||
*/
|
||||
void Stop(void);
|
||||
|
||||
/**
|
||||
* This method clears all currently stored data.
|
||||
*
|
||||
*/
|
||||
void Clear(void);
|
||||
|
||||
/**
|
||||
* This method returns the total number of RSS samples (per channel) taken so far.
|
||||
*
|
||||
* @returns total number of RSS samples taken so far.
|
||||
*
|
||||
*/
|
||||
uint32_t GetSampleCount(void) const { return mSampleCount; }
|
||||
|
||||
/**
|
||||
* This method returns the current channel quality value for a given channel.
|
||||
*
|
||||
* The channel quality value represents the average rate/percentage of RSS samples that were above RSS threshold
|
||||
* `kRssThreshold` ("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.
|
||||
*
|
||||
* Max value of `0xffff` indicates all RSS samples were above RSS threshold (i.e. 100% of samples were "bad").
|
||||
*
|
||||
* @param[in] aChannel The channel for which to get the link quality.
|
||||
*
|
||||
* @returns the current channel quality value for the given channel.
|
||||
*
|
||||
*/
|
||||
uint16_t GetChannelQuality(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,
|
||||
};
|
||||
|
||||
void RestartTimer(void);
|
||||
static void HandleTimer(Timer &aTimer);
|
||||
void HandleTimer(void);
|
||||
static void HandleEnergyScanResult(void *aContext, otEnergyScanResult *aResult);
|
||||
void HandleEnergyScanResult(otEnergyScanResult *aResult);
|
||||
void LogResults(void);
|
||||
|
||||
static const uint32_t mScanChannelMasks[kNumChannelMasks];
|
||||
|
||||
uint8_t mChannelMaskIndex : 2;
|
||||
uint32_t mSampleCount : 30;
|
||||
uint16_t mChannelQuality[kNumChannels];
|
||||
TimerMilli mTimer;
|
||||
};
|
||||
|
||||
#endif // OPENTHREAD_ENABLE_CHANNEL_MONITOR
|
||||
|
||||
/**
|
||||
* @}
|
||||
*
|
||||
*/
|
||||
|
||||
} // namespace Utils
|
||||
} // namespace ot
|
||||
|
||||
#endif // CHANNEL_MONITOR_HPP_
|
||||
Reference in New Issue
Block a user