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

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.