Marco Zecchini / Mbed OS Example_RTOS

Rtos API example

mbed-os/features/FEATURE_BLE/ble/GapScanningParams.h@0:9fca2b23d0ba, 2019-02-23 (annotated)

Committer:
marcozecchini
Date:
Sat Feb 23 12:13:36 2019 +0000
Revision:
0:9fca2b23d0ba
final commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
marcozecchini 0:9fca2b23d0ba 1 /* mbed Microcontroller Library
marcozecchini 0:9fca2b23d0ba 2 * Copyright (c) 2006-2013 ARM Limited
marcozecchini 0:9fca2b23d0ba 3 *
marcozecchini 0:9fca2b23d0ba 4 * Licensed under the Apache License, Version 2.0 (the "License");
marcozecchini 0:9fca2b23d0ba 5 * you may not use this file except in compliance with the License.
marcozecchini 0:9fca2b23d0ba 6 * You may obtain a copy of the License at
marcozecchini 0:9fca2b23d0ba 7 *
marcozecchini 0:9fca2b23d0ba 8 * http://www.apache.org/licenses/LICENSE-2.0
marcozecchini 0:9fca2b23d0ba 9 *
marcozecchini 0:9fca2b23d0ba 10 * Unless required by applicable law or agreed to in writing, software
marcozecchini 0:9fca2b23d0ba 11 * distributed under the License is distributed on an "AS IS" BASIS,
marcozecchini 0:9fca2b23d0ba 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
marcozecchini 0:9fca2b23d0ba 13 * See the License for the specific language governing permissions and
marcozecchini 0:9fca2b23d0ba 14 * limitations under the License.
marcozecchini 0:9fca2b23d0ba 15 */
marcozecchini 0:9fca2b23d0ba 16
marcozecchini 0:9fca2b23d0ba 17 #ifndef MBED_GAP_SCANNING_PARAMS_H__
marcozecchini 0:9fca2b23d0ba 18 #define MBED_GAP_SCANNING_PARAMS_H__
marcozecchini 0:9fca2b23d0ba 19
marcozecchini 0:9fca2b23d0ba 20 /**
marcozecchini 0:9fca2b23d0ba 21 * @addtogroup ble
marcozecchini 0:9fca2b23d0ba 22 * @{
marcozecchini 0:9fca2b23d0ba 23 * @addtogroup gap
marcozecchini 0:9fca2b23d0ba 24 * @{
marcozecchini 0:9fca2b23d0ba 25 */
marcozecchini 0:9fca2b23d0ba 26
marcozecchini 0:9fca2b23d0ba 27 /**
marcozecchini 0:9fca2b23d0ba 28 * Parameters defining the scan process.
marcozecchini 0:9fca2b23d0ba 29 *
marcozecchini 0:9fca2b23d0ba 30 * Four distinct parameters define the scan procedure:
marcozecchini 0:9fca2b23d0ba 31 * - Scan window: Period during which the scanner listens to advertising
marcozecchini 0:9fca2b23d0ba 32 * channels. That value is in the range of 2.5ms to 10.24s. This value
marcozecchini 0:9fca2b23d0ba 33 * can be set at construction time, updated by calling setWindow() and
marcozecchini 0:9fca2b23d0ba 34 * retrieved by invoking getWindow().
marcozecchini 0:9fca2b23d0ba 35 *
marcozecchini 0:9fca2b23d0ba 36 * - Scan interval: Interval between the start of two consecutive scan windows.
marcozecchini 0:9fca2b23d0ba 37 * That value shall be greater or equal to the scan window value. The
marcozecchini 0:9fca2b23d0ba 38 * maximum allowed value is 10.24ms. The scan interval value can be set at
marcozecchini 0:9fca2b23d0ba 39 * construction time, updated with a call to setInterval() and queried by a
marcozecchini 0:9fca2b23d0ba 40 * call to getInterval().
marcozecchini 0:9fca2b23d0ba 41 *
marcozecchini 0:9fca2b23d0ba 42 * - Timeout: The duration of the scan procedure if any. It can be set at
marcozecchini 0:9fca2b23d0ba 43 * construction time, updated with setTimeout() and obtained from
marcozecchini 0:9fca2b23d0ba 44 * getTimeout().
marcozecchini 0:9fca2b23d0ba 45 *
marcozecchini 0:9fca2b23d0ba 46 * - Active scanning: If set, then the scanner sends scan requests to a scannable
marcozecchini 0:9fca2b23d0ba 47 * or connectable advertiser. Advertisers may respond to the scan request
marcozecchini 0:9fca2b23d0ba 48 * by a scan response containing the scan response payload. If not set, then
marcozecchini 0:9fca2b23d0ba 49 * the scanner does not send any request. This flag is set at construction
marcozecchini 0:9fca2b23d0ba 50 * time, may be updated with the help of setActiveScanning() and retrieved
marcozecchini 0:9fca2b23d0ba 51 * by getActiveScanning().
marcozecchini 0:9fca2b23d0ba 52 *
marcozecchini 0:9fca2b23d0ba 53 * @note If the scan window's duration is equal to the scan interval, then the
marcozecchini 0:9fca2b23d0ba 54 * device listens continuously during the scan procedure.
marcozecchini 0:9fca2b23d0ba 55 */
marcozecchini 0:9fca2b23d0ba 56 class GapScanningParams {
marcozecchini 0:9fca2b23d0ba 57 public:
marcozecchini 0:9fca2b23d0ba 58 /**
marcozecchini 0:9fca2b23d0ba 59 * Minimum Scan interval in 625us units - 2.5ms.
marcozecchini 0:9fca2b23d0ba 60 */
marcozecchini 0:9fca2b23d0ba 61 static const unsigned SCAN_INTERVAL_MIN = 0x0004;
marcozecchini 0:9fca2b23d0ba 62
marcozecchini 0:9fca2b23d0ba 63 /**
marcozecchini 0:9fca2b23d0ba 64 * Maximum Scan interval in 625us units - 10.24s.
marcozecchini 0:9fca2b23d0ba 65 */
marcozecchini 0:9fca2b23d0ba 66 static const unsigned SCAN_INTERVAL_MAX = 0x4000;
marcozecchini 0:9fca2b23d0ba 67
marcozecchini 0:9fca2b23d0ba 68 /**
marcozecchini 0:9fca2b23d0ba 69 * Minimum Scan window in 625us units - 2.5ms.
marcozecchini 0:9fca2b23d0ba 70 */
marcozecchini 0:9fca2b23d0ba 71 static const unsigned SCAN_WINDOW_MIN = 0x0004;
marcozecchini 0:9fca2b23d0ba 72
marcozecchini 0:9fca2b23d0ba 73 /**
marcozecchini 0:9fca2b23d0ba 74 * Maximum Scan window in 625us units - 10.24s.
marcozecchini 0:9fca2b23d0ba 75 */
marcozecchini 0:9fca2b23d0ba 76 static const unsigned SCAN_WINDOW_MAX = 0x4000;
marcozecchini 0:9fca2b23d0ba 77
marcozecchini 0:9fca2b23d0ba 78 /**
marcozecchini 0:9fca2b23d0ba 79 * Minimum Scan duration in seconds.
marcozecchini 0:9fca2b23d0ba 80 */
marcozecchini 0:9fca2b23d0ba 81 static const unsigned SCAN_TIMEOUT_MIN = 0x0001;
marcozecchini 0:9fca2b23d0ba 82
marcozecchini 0:9fca2b23d0ba 83 /**
marcozecchini 0:9fca2b23d0ba 84 * Maximum Scan duration in seconds.
marcozecchini 0:9fca2b23d0ba 85 */
marcozecchini 0:9fca2b23d0ba 86 static const unsigned SCAN_TIMEOUT_MAX = 0xFFFF;
marcozecchini 0:9fca2b23d0ba 87
marcozecchini 0:9fca2b23d0ba 88 public:
marcozecchini 0:9fca2b23d0ba 89 /**
marcozecchini 0:9fca2b23d0ba 90 * Construct an instance of GapScanningParams.
marcozecchini 0:9fca2b23d0ba 91 *
marcozecchini 0:9fca2b23d0ba 92 * @param[in] interval Milliseconds interval between the start of two
marcozecchini 0:9fca2b23d0ba 93 * consecutive scan windows. The value passed is between the scan
marcozecchini 0:9fca2b23d0ba 94 * window value and 10.24 seconds.
marcozecchini 0:9fca2b23d0ba 95 *
marcozecchini 0:9fca2b23d0ba 96 * @param[in] window Milliseconds period during which the device
marcozecchini 0:9fca2b23d0ba 97 * listens to advertising channels. The value of the scan window is in
marcozecchini 0:9fca2b23d0ba 98 * the range of 2.5ms to 10.24s.
marcozecchini 0:9fca2b23d0ba 99 *
marcozecchini 0:9fca2b23d0ba 100 * @param[in] timeout Duration in seconds of the scan procedure. The special
marcozecchini 0:9fca2b23d0ba 101 * value 0 may be used when the scan procedure is not time bounded.
marcozecchini 0:9fca2b23d0ba 102 *
marcozecchini 0:9fca2b23d0ba 103 * @param[in] activeScanning If true, then the scanner sends scan requests to
marcozecchini 0:9fca2b23d0ba 104 * to scannable or connectable advertiser. Advertisers may respond to the
marcozecchini 0:9fca2b23d0ba 105 * scan request by a scan response containing the scan response payload. If
marcozecchini 0:9fca2b23d0ba 106 * false, the scanner does not send any request.
marcozecchini 0:9fca2b23d0ba 107 *
marcozecchini 0:9fca2b23d0ba 108 * @note If interval is equal to window
marcozecchini 0:9fca2b23d0ba 109 */
marcozecchini 0:9fca2b23d0ba 110 GapScanningParams(
marcozecchini 0:9fca2b23d0ba 111 uint16_t interval = SCAN_INTERVAL_MAX,
marcozecchini 0:9fca2b23d0ba 112 uint16_t window = SCAN_WINDOW_MAX,
marcozecchini 0:9fca2b23d0ba 113 uint16_t timeout = 0,
marcozecchini 0:9fca2b23d0ba 114 bool activeScanning = false
marcozecchini 0:9fca2b23d0ba 115 );
marcozecchini 0:9fca2b23d0ba 116
marcozecchini 0:9fca2b23d0ba 117 /**
marcozecchini 0:9fca2b23d0ba 118 * Number of microseconds in 0.625 milliseconds.
marcozecchini 0:9fca2b23d0ba 119 */
marcozecchini 0:9fca2b23d0ba 120 static const uint16_t UNIT_0_625_MS = 625;
marcozecchini 0:9fca2b23d0ba 121
marcozecchini 0:9fca2b23d0ba 122 /**
marcozecchini 0:9fca2b23d0ba 123 * Convert milliseconds to units of 0.625ms.
marcozecchini 0:9fca2b23d0ba 124 *
marcozecchini 0:9fca2b23d0ba 125 * @param[in] durationInMillis Milliseconds to convert.
marcozecchini 0:9fca2b23d0ba 126 *
marcozecchini 0:9fca2b23d0ba 127 * @return The value of @p durationInMillis in units of 0.625ms.
marcozecchini 0:9fca2b23d0ba 128 */
marcozecchini 0:9fca2b23d0ba 129 static uint16_t MSEC_TO_SCAN_DURATION_UNITS(uint32_t durationInMillis)
marcozecchini 0:9fca2b23d0ba 130 {
marcozecchini 0:9fca2b23d0ba 131 return (durationInMillis * 1000) / UNIT_0_625_MS;
marcozecchini 0:9fca2b23d0ba 132 }
marcozecchini 0:9fca2b23d0ba 133
marcozecchini 0:9fca2b23d0ba 134 /**
marcozecchini 0:9fca2b23d0ba 135 * Update the scan interval.
marcozecchini 0:9fca2b23d0ba 136 *
marcozecchini 0:9fca2b23d0ba 137 * @param[in] newIntervalInMS New scan interval in milliseconds.
marcozecchini 0:9fca2b23d0ba 138 *
marcozecchini 0:9fca2b23d0ba 139 * @return BLE_ERROR_NONE if the new scan interval was set successfully.
marcozecchini 0:9fca2b23d0ba 140 */
marcozecchini 0:9fca2b23d0ba 141 ble_error_t setInterval(uint16_t newIntervalInMS);
marcozecchini 0:9fca2b23d0ba 142
marcozecchini 0:9fca2b23d0ba 143 /**
marcozecchini 0:9fca2b23d0ba 144 * Update the scan window.
marcozecchini 0:9fca2b23d0ba 145 *
marcozecchini 0:9fca2b23d0ba 146 * @param[in] newWindowInMS New scan window in milliseconds.
marcozecchini 0:9fca2b23d0ba 147 *
marcozecchini 0:9fca2b23d0ba 148 * @return BLE_ERROR_NONE if the new scan window was set successfully.
marcozecchini 0:9fca2b23d0ba 149 */
marcozecchini 0:9fca2b23d0ba 150 ble_error_t setWindow(uint16_t newWindowInMS);
marcozecchini 0:9fca2b23d0ba 151
marcozecchini 0:9fca2b23d0ba 152 /**
marcozecchini 0:9fca2b23d0ba 153 * Update the scan timeout.
marcozecchini 0:9fca2b23d0ba 154 *
marcozecchini 0:9fca2b23d0ba 155 * @param[in] newTimeout New scan timeout in seconds.
marcozecchini 0:9fca2b23d0ba 156 *
marcozecchini 0:9fca2b23d0ba 157 * @return BLE_ERROR_NONE if the new scan window was set successfully.
marcozecchini 0:9fca2b23d0ba 158 */
marcozecchini 0:9fca2b23d0ba 159 ble_error_t setTimeout(uint16_t newTimeout);
marcozecchini 0:9fca2b23d0ba 160
marcozecchini 0:9fca2b23d0ba 161 /**
marcozecchini 0:9fca2b23d0ba 162 * Update the active scanning flag.
marcozecchini 0:9fca2b23d0ba 163 *
marcozecchini 0:9fca2b23d0ba 164 * @param[in] activeScanning New boolean value of active scanning.
marcozecchini 0:9fca2b23d0ba 165 */
marcozecchini 0:9fca2b23d0ba 166 void setActiveScanning(bool activeScanning);
marcozecchini 0:9fca2b23d0ba 167
marcozecchini 0:9fca2b23d0ba 168 public:
marcozecchini 0:9fca2b23d0ba 169 /**
marcozecchini 0:9fca2b23d0ba 170 * Get the scan interval.
marcozecchini 0:9fca2b23d0ba 171 *
marcozecchini 0:9fca2b23d0ba 172 * @return the scan interval in units of 0.625ms.
marcozecchini 0:9fca2b23d0ba 173 */
marcozecchini 0:9fca2b23d0ba 174 uint16_t getInterval(void) const
marcozecchini 0:9fca2b23d0ba 175 {
marcozecchini 0:9fca2b23d0ba 176 return _interval;
marcozecchini 0:9fca2b23d0ba 177 }
marcozecchini 0:9fca2b23d0ba 178
marcozecchini 0:9fca2b23d0ba 179 /**
marcozecchini 0:9fca2b23d0ba 180 * Get the scan window.
marcozecchini 0:9fca2b23d0ba 181 *
marcozecchini 0:9fca2b23d0ba 182 * @return the scan window in units of 0.625ms.
marcozecchini 0:9fca2b23d0ba 183 */
marcozecchini 0:9fca2b23d0ba 184 uint16_t getWindow(void) const
marcozecchini 0:9fca2b23d0ba 185 {
marcozecchini 0:9fca2b23d0ba 186 return _window;
marcozecchini 0:9fca2b23d0ba 187 }
marcozecchini 0:9fca2b23d0ba 188
marcozecchini 0:9fca2b23d0ba 189 /**
marcozecchini 0:9fca2b23d0ba 190 * Get the scan timeout.
marcozecchini 0:9fca2b23d0ba 191 *
marcozecchini 0:9fca2b23d0ba 192 * @return The scan timeout in seconds.
marcozecchini 0:9fca2b23d0ba 193 */
marcozecchini 0:9fca2b23d0ba 194 uint16_t getTimeout(void) const
marcozecchini 0:9fca2b23d0ba 195 {
marcozecchini 0:9fca2b23d0ba 196 return _timeout;
marcozecchini 0:9fca2b23d0ba 197 }
marcozecchini 0:9fca2b23d0ba 198
marcozecchini 0:9fca2b23d0ba 199 /**
marcozecchini 0:9fca2b23d0ba 200 * Check whether active scanning is set.
marcozecchini 0:9fca2b23d0ba 201 *
marcozecchini 0:9fca2b23d0ba 202 * @return True if active scanning is set, false otherwise.
marcozecchini 0:9fca2b23d0ba 203 */
marcozecchini 0:9fca2b23d0ba 204 bool getActiveScanning(void) const
marcozecchini 0:9fca2b23d0ba 205 {
marcozecchini 0:9fca2b23d0ba 206 return _activeScanning;
marcozecchini 0:9fca2b23d0ba 207 }
marcozecchini 0:9fca2b23d0ba 208
marcozecchini 0:9fca2b23d0ba 209 private:
marcozecchini 0:9fca2b23d0ba 210 /**
marcozecchini 0:9fca2b23d0ba 211 * Scan interval in units of 625us (between 2.5ms and 10.24s).
marcozecchini 0:9fca2b23d0ba 212 */
marcozecchini 0:9fca2b23d0ba 213 uint16_t _interval;
marcozecchini 0:9fca2b23d0ba 214
marcozecchini 0:9fca2b23d0ba 215 /**
marcozecchini 0:9fca2b23d0ba 216 * Scan window in units of 625us (between 2.5ms and 10.24s).
marcozecchini 0:9fca2b23d0ba 217 */
marcozecchini 0:9fca2b23d0ba 218 uint16_t _window;
marcozecchini 0:9fca2b23d0ba 219
marcozecchini 0:9fca2b23d0ba 220 /**
marcozecchini 0:9fca2b23d0ba 221 * Scan timeout between 0x0001 and 0xFFFF in seconds; 0x0000 disables timeout.
marcozecchini 0:9fca2b23d0ba 222 */
marcozecchini 0:9fca2b23d0ba 223 uint16_t _timeout;
marcozecchini 0:9fca2b23d0ba 224
marcozecchini 0:9fca2b23d0ba 225 /**
marcozecchini 0:9fca2b23d0ba 226 * Obtain the peer device's advertising data and (if possible) scanResponse.
marcozecchini 0:9fca2b23d0ba 227 */
marcozecchini 0:9fca2b23d0ba 228 bool _activeScanning;
marcozecchini 0:9fca2b23d0ba 229
marcozecchini 0:9fca2b23d0ba 230 private:
marcozecchini 0:9fca2b23d0ba 231 /* Disallow copy constructor. */
marcozecchini 0:9fca2b23d0ba 232 GapScanningParams(const GapScanningParams &);
marcozecchini 0:9fca2b23d0ba 233 GapScanningParams& operator =(const GapScanningParams &in);
marcozecchini 0:9fca2b23d0ba 234 };
marcozecchini 0:9fca2b23d0ba 235
marcozecchini 0:9fca2b23d0ba 236 /**
marcozecchini 0:9fca2b23d0ba 237 * @}
marcozecchini 0:9fca2b23d0ba 238 * @}
marcozecchini 0:9fca2b23d0ba 239 */
marcozecchini 0:9fca2b23d0ba 240
marcozecchini 0:9fca2b23d0ba 241 #endif /* ifndef MBED_GAP_SCANNING_PARAMS_H__ */