1 /* 2 * Copyright (c) 2016, The OpenThread Authors. 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions are met: 7 * 1. Redistributions of source code must retain the above copyright 8 * notice, this list of conditions and the following disclaimer. 9 * 2. Redistributions in binary form must reproduce the above copyright 10 * notice, this list of conditions and the following disclaimer in the 11 * documentation and/or other materials provided with the distribution. 12 * 3. Neither the name of the copyright holder nor the 13 * names of its contributors may be used to endorse or promote products 14 * derived from this software without specific prior written permission. 15 * 16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 26 * POSSIBILITY OF SUCH DAMAGE. 27 */ 28 29 /** 30 * @file 31 * This file includes definitions for jam detector. 32 */ 33 34 #ifndef JAM_DETECTOR_HPP_ 35 #define JAM_DETECTOR_HPP_ 36 37 #include "openthread-core-config.h" 38 39 #if OPENTHREAD_CONFIG_JAM_DETECTION_ENABLE 40 41 #include <stdint.h> 42 43 #include "common/callback.hpp" 44 #include "common/locator.hpp" 45 #include "common/non_copyable.hpp" 46 #include "common/notifier.hpp" 47 #include "common/timer.hpp" 48 49 namespace ot { 50 51 class ThreadNetif; 52 53 namespace Utils { 54 55 class JamDetector : public InstanceLocator, private NonCopyable 56 { 57 friend class ot::Notifier; 58 59 public: 60 /** 61 * Pointer is called if jam state changes (assuming jamming detection is enabled). 62 * 63 * @param[in] aJamState `true` if jam is detected, `false` if jam is cleared. 64 * @param[in] aContext A pointer to application-specific context. 65 */ 66 typedef void (*Handler)(bool aJamState, void *aContext); 67 68 /** 69 * Initializes the object. 70 * 71 * @param[in] aInstance A reference to the OpenThread instance. 72 */ 73 explicit JamDetector(Instance &aInstance); 74 75 /** 76 * Start the jamming detection. 77 * 78 * @param[in] aHandler A pointer to a function called when jamming is detected. 79 * @param[in] aContext A pointer to application-specific context. 80 * 81 * @retval kErrorNone Successfully started the jamming detection. 82 * @retval kErrorAlready Jam detection has been started before. 83 */ 84 Error Start(Handler aHandler, void *aContext); 85 86 /** 87 * Stop the jamming detection. 88 * 89 * @retval kErrorNone Successfully stopped the jamming detection. 90 * @retval kErrorAlready Jam detection is already stopped. 91 */ 92 Error Stop(void); 93 94 /** 95 * Get the Jam Detection Status 96 * 97 * @returns The Jam Detection status (true if enabled, false otherwise). 98 */ IsEnabled(void) const99 bool IsEnabled(void) const { return mEnabled; } 100 101 /** 102 * Get the current jam state. 103 * 104 * @returns The jamming state (`true` if jam is detected, `false` otherwise). 105 */ GetState(void) const106 bool GetState(void) const { return mJamState; } 107 108 /** 109 * Set the Jam Detection RSSI Threshold (in dBm). 110 * 111 * @param[in] aThreshold The RSSI threshold. 112 */ 113 void SetRssiThreshold(int8_t aThreshold); 114 115 /** 116 * Get the Jam Detection RSSI Threshold (in dBm). 117 * 118 * @returns The Jam Detection RSSI Threshold. 119 */ GetRssiThreshold(void) const120 int8_t GetRssiThreshold(void) const { return mRssiThreshold; } 121 122 /** 123 * Set the Jam Detection Detection Window (in seconds). 124 * 125 * @param[in] aWindow The Jam Detection window (valid range is 1 to 63) 126 * 127 * @retval kErrorNone Successfully set the window. 128 * @retval kErrorInvalidArgs The given input parameter not within valid range (1-63) 129 */ 130 Error SetWindow(uint8_t aWindow); 131 132 /** 133 * Get the Jam Detection Detection Window (in seconds). 134 * 135 * @returns The Jam Detection Window. 136 */ GetWindow(void) const137 uint8_t GetWindow(void) const { return mWindow; } 138 139 /** 140 * Set the Jam Detection Busy Period (in seconds). 141 * 142 * The number of aggregate seconds within the detection window where the RSSI must be above 143 * threshold to trigger detection. 144 * 145 * @param[in] aBusyPeriod The Jam Detection busy period (should be non-zero and 146 less than or equal to Jam Detection Window) 147 * 148 * @retval kErrorNone Successfully set the window. 149 * @retval kErrorInvalidArgs The given input is not within the valid range. 150 */ 151 Error SetBusyPeriod(uint8_t aBusyPeriod); 152 153 /** 154 * Get the Jam Detection Busy Period (in seconds) 155 * 156 * @returns The Jam Detection Busy Period 157 */ GetBusyPeriod(void) const158 uint8_t GetBusyPeriod(void) const { return mBusyPeriod; } 159 160 /** 161 * Get the current history bitmap. 162 * 163 * This value provides information about current state of jamming detection 164 * module for monitoring/debugging purpose. It provides a 64-bit value where 165 * each bit corresponds to one second interval starting with bit 0 for the 166 * most recent interval and bit 63 for the oldest intervals (63 earlier). 167 * The bit is set to 1 if the jamming detection module observed/detected 168 * high signal level during the corresponding one second interval. 169 * 170 * @returns The current history bitmap. 171 */ GetHistoryBitmap(void) const172 uint64_t GetHistoryBitmap(void) const { return mHistoryBitmap; } 173 174 private: 175 static constexpr uint8_t kMaxWindow = 63; // Max window size 176 static constexpr int8_t kDefaultRssiThreshold = 0; 177 178 static constexpr uint16_t kMaxSampleInterval = 256; // in ms 179 static constexpr uint16_t kMinSampleInterval = 2; // in ms 180 static constexpr uint32_t kMaxRandomDelay = 4; // in ms 181 182 void CheckState(void); 183 void SetJamState(bool aNewState); 184 void HandleTimer(void); 185 void UpdateHistory(bool aDidExceedThreshold); 186 void UpdateJamState(void); 187 void HandleNotifierEvents(Events aEvents); 188 189 using SampleTimer = TimerMilliIn<JamDetector, &JamDetector::HandleTimer>; 190 191 Callback<Handler> mCallback; // Callback to inform about jamming state 192 SampleTimer mTimer; // RSSI sample timer 193 uint64_t mHistoryBitmap; // History bitmap, each bit correspond to 1 sec interval 194 TimeMilli mCurSecondStartTime; // Start time for current 1 sec interval 195 uint16_t mSampleInterval; // Current sample interval 196 uint8_t mWindow : 6; // Window (in sec) to monitor jamming 197 uint8_t mBusyPeriod : 6; // BusyPeriod (in sec) with mWindow to alert jamming 198 bool mEnabled : 1; // If jam detection is enabled 199 bool mAlwaysAboveThreshold : 1; // State for current 1 sec interval 200 bool mJamState : 1; // Current jam state 201 int8_t mRssiThreshold; // RSSI threshold for jam detection 202 }; 203 204 /** 205 * @} 206 */ 207 208 } // namespace Utils 209 } // namespace ot 210 211 #endif // OPENTHREAD_CONFIG_JAM_DETECTION_ENABLE 212 213 #endif // JAM_DETECTOR_HPP_ 214