BA / SerialCom

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Fork of OmniWheels by Gustav Atmel

mbed-os/features/FEATURE_BLE/ble/GapScanningParams.h@1:9c5af431a1f1, 2018-05-01 (annotated)

Committer:
gustavatmel
Date:
Tue May 01 15:47:08 2018 +0000
Revision:
1:9c5af431a1f1
sdf

Who changed what in which revision?

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