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/locator.hpp" 44 #include "common/non_copyable.hpp" 45 #include "common/notifier.hpp" 46 #include "common/timer.hpp" 47 48 namespace ot { 49 50 class ThreadNetif; 51 52 namespace Utils { 53 54 class JamDetector : public InstanceLocator, private NonCopyable 55 { 56 friend class ot::Notifier; 57 58 public: 59 /** 60 * This function pointer is called if jam state changes (assuming jamming detection is enabled). 61 * 62 * @param[in] aJamState `true` if jam is detected, `false` if jam is cleared. 63 * @param[in] aContext A pointer to application-specific context. 64 * 65 */ 66 typedef void (*Handler)(bool aJamState, void *aContext); 67 68 /** 69 * This constructor initializes the object. 70 * 71 * @param[in] aInstance A reference to the OpenThread instance. 72 * 73 */ 74 explicit JamDetector(Instance &aInstance); 75 76 /** 77 * Start the jamming detection. 78 * 79 * @param[in] aHandler A pointer to a function called when jamming is detected. 80 * @param[in] aContext A pointer to application-specific context. 81 * 82 * @retval kErrorNone Successfully started the jamming detection. 83 * @retval kErrorAlready Jam detection has been started before. 84 * 85 */ 86 Error Start(Handler aHandler, void *aContext); 87 88 /** 89 * Stop the jamming detection. 90 * 91 * @retval kErrorNone Successfully stopped the jamming detection. 92 * @retval kErrorAlready Jam detection is already stopped. 93 * 94 */ 95 Error Stop(void); 96 97 /** 98 * Get the Jam Detection Status 99 * 100 * @returns The Jam Detection status (true if enabled, false otherwise). 101 */ IsEnabled(void) const102 bool IsEnabled(void) const { return mEnabled; } 103 104 /** 105 * Get the current jam state. 106 * 107 * @returns The jamming state (`true` if jam is detected, `false` otherwise). 108 */ GetState(void) const109 bool GetState(void) const { return mJamState; } 110 111 /** 112 * Set the Jam Detection RSSI Threshold (in dBm). 113 * 114 * @param[in] aThreshold The RSSI threshold. 115 * 116 */ 117 void SetRssiThreshold(int8_t aThreshold); 118 119 /** 120 * Get the Jam Detection RSSI Threshold (in dBm). 121 * 122 * @returns The Jam Detection RSSI Threshold. 123 */ GetRssiThreshold(void) const124 int8_t GetRssiThreshold(void) const { return mRssiThreshold; } 125 126 /** 127 * Set the Jam Detection Detection Window (in seconds). 128 * 129 * @param[in] aWindow The Jam Detection window (valid range is 1 to 63) 130 * 131 * @retval kErrorNone Successfully set the window. 132 * @retval kErrorInvalidArgs The given input parameter not within valid range (1-63) 133 * 134 */ 135 Error SetWindow(uint8_t aWindow); 136 137 /** 138 * Get the Jam Detection Detection Window (in seconds). 139 * 140 * @returns The Jam Detection Window. 141 */ GetWindow(void) const142 uint8_t GetWindow(void) const { return mWindow; } 143 144 /** 145 * Set the Jam Detection Busy Period (in seconds). 146 * 147 * The number of aggregate seconds within the detection window where the RSSI must be above 148 * threshold to trigger detection. 149 * 150 * @param[in] aBusyPeriod The Jam Detection busy period (should be non-zero and 151 less than or equal to Jam Detection Window) 152 * 153 * @retval kErrorNone Successfully set the window. 154 * @retval kErrorInvalidArgs The given input is not within the valid range. 155 * 156 */ 157 Error SetBusyPeriod(uint8_t aBusyPeriod); 158 159 /** 160 * Get the Jam Detection Busy Period (in seconds) 161 * 162 * @returns The Jam Detection Busy Period 163 */ GetBusyPeriod(void) const164 uint8_t GetBusyPeriod(void) const { return mBusyPeriod; } 165 166 /** 167 * Get the current history bitmap. 168 * 169 * This value provides information about current state of jamming detection 170 * module for monitoring/debugging purpose. It provides a 64-bit value where 171 * each bit corresponds to one second interval starting with bit 0 for the 172 * most recent interval and bit 63 for the oldest intervals (63 earlier). 173 * The bit is set to 1 if the jamming detection module observed/detected 174 * high signal level during the corresponding one second interval. 175 * 176 * @returns The current history bitmap. 177 */ GetHistoryBitmap(void) const178 uint64_t GetHistoryBitmap(void) const { return mHistoryBitmap; } 179 180 private: 181 static constexpr uint8_t kMaxWindow = 63; // Max window size 182 static constexpr int8_t kDefaultRssiThreshold = 0; 183 184 static constexpr uint16_t kMaxSampleInterval = 256; // in ms 185 static constexpr uint16_t kMinSampleInterval = 2; // in ms 186 static constexpr uint32_t kMaxRandomDelay = 4; // in ms 187 188 void CheckState(void); 189 void SetJamState(bool aNewState); 190 static void HandleTimer(Timer &aTimer); 191 void HandleTimer(void); 192 void UpdateHistory(bool aDidExceedThreshold); 193 void UpdateJamState(void); 194 void HandleNotifierEvents(Events aEvents); 195 196 Handler mHandler; // Handler/callback to inform about jamming state 197 void * mContext; // Context for handler/callback 198 TimerMilli mTimer; // RSSI sample timer 199 uint64_t mHistoryBitmap; // History bitmap, each bit correspond to 1 sec interval 200 TimeMilli mCurSecondStartTime; // Start time for current 1 sec interval 201 uint16_t mSampleInterval; // Current sample interval 202 uint8_t mWindow : 6; // Window (in sec) to monitor jamming 203 uint8_t mBusyPeriod : 6; // BusyPeriod (in sec) with mWindow to alert jamming 204 bool mEnabled : 1; // If jam detection is enabled 205 bool mAlwaysAboveThreshold : 1; // State for current 1 sec interval 206 bool mJamState : 1; // Current jam state 207 int8_t mRssiThreshold; // RSSI threshold for jam detection 208 }; 209 210 /** 211 * @} 212 * 213 */ 214 215 } // namespace Utils 216 } // namespace ot 217 218 #endif // OPENTHREAD_CONFIG_JAM_DETECTION_ENABLE 219 220 #endif // JAM_DETECTOR_HPP_ 221