Mistake on this page?
Report an issue in GitHub or email us
ScanParameters.h
1 /* mbed Microcontroller Library
2  * Copyright (c) 2006-2020 ARM Limited
3  *
4  * SPDX-License-Identifier: Apache-2.0
5  *
6  * Licensed under the Apache License, Version 2.0 (the "License");
7  * you may not use this file except in compliance with the License.
8  * You may obtain a copy of the License at
9  *
10  * http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing, software
13  * distributed under the License is distributed on an "AS IS" BASIS,
14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15  * See the License for the specific language governing permissions and
16  * limitations under the License.
17  */
18 
19 #ifndef MBED_GAP_SCAN_PARAMETERS_H__
20 #define MBED_GAP_SCAN_PARAMETERS_H__
21 
22 #include <cstdint>
23 
24 #include "ble/common/blecommon.h"
25 #include "ble/common/BLETypes.h"
26 
27 namespace ble {
28 
29 /**
30  * @addtogroup ble
31  * @{
32  * @addtogroup gap
33  * @{
34  */
35 
36 /**
37  * Parameters defining the scan process.
38  *
39  * The scan process is defined by two main parameters:
40  * - The scan window that defines how long the device should scan.
41  * - The scan window that defines how frequently the device should scan.
42  *
43  * To scan continuously, the scan window and the scan interval should have the
44  * same value.
45  *
46  * To get extra data from the advertising device, the scanner can send scan
47  * requests to the advertiser; the advertiser may respond with scan responses.
48  * It is possible to select what type of address is used to issue the scan request.
49  *
50  * With Bluetooth 5, devices can advertise on more physical channels, and by
51  * extension, they can scan on more physical channels. It is possible to define
52  * independent scan parameters for every scannable physical channel.
53  */
55 public:
56 
57  /**
58  * Scan configuration of a physical channel.
59  */
61  /**
62  * Construct a phy_configuration_t.
63  * @param scan_interval The scan interval.
64  * @param scan_window The scan window.
65  * @param active_scanning True if scan request should be sent and false
66  * otherwise.
67  */
69  scan_interval_t scan_interval = scan_interval_t::min(),
70  scan_window_t scan_window = scan_window_t::min(),
71  bool active_scanning = false
72  ) :
73  interval(scan_interval),
74  window(scan_window),
75  active_scanning(active_scanning)
76  {
77  if (window.value() > interval.value()) {
78  interval = window;
79  }
80  }
81 
82  /**
83  * Get the scan interval.
84  */
85  const scan_window_t &getInterval() const
86  {
87  return interval;
88  }
89 
90  /**
91  * Get the scan window.
92  */
93  const scan_interval_t &getWindow() const
94  {
95  return window;
96  }
97 
98  /**
99  * Return if active scanning is set.
100  */
101  bool isActiveScanningSet() const
102  {
103  return active_scanning;
104  }
105 
106  private:
107  scan_interval_t interval;
108  scan_window_t window;
109  bool active_scanning;
110  };
111 
112  /**
113  * Construct a ScanParameters object that operates on a selected PHY.
114  *
115  * @param phy The phy to configure.
116  * @param scan_interval The scan interval.
117  * @param scan_window The scan window.
118  * @param active_scanning active scanning flag.
119  * @param own_address_type Address type used in scan requests.
120  * @param scanning_filter_policy Filter applied.
121  */
123  phy_t phy = phy_t::LE_1M,
124  scan_window_t scan_interval = scan_interval_t::min(),
125  scan_interval_t scan_window = scan_window_t::min(),
126  bool active_scanning = false,
127  own_address_type_t own_address_type = own_address_type_t::RANDOM,
128  scanning_filter_policy_t scanning_filter_policy = scanning_filter_policy_t::NO_FILTER
129  ) :
130  own_address_type(own_address_type),
131  scanning_filter_policy(scanning_filter_policy),
132  phys(phy),
133  phy_1m_configuration(),
134  phy_coded_configuration()
135  {
136  phy_configuration_t conf(scan_interval, scan_window, active_scanning);
137  if (phy == phy_t::LE_1M) {
138  phy_1m_configuration = conf;
139  }
140 #if BLE_FEATURE_PHY_MANAGEMENT
141  else if (phy == phy_t::LE_CODED) {
142  phy_coded_configuration = conf;
143  }
144 #endif // BLE_FEATURE_PHY_MANAGEMENT
145  }
146 
147  /**
148  * Set the address type used for scan requests.
149  * @param address The type of address to use during scan requests.
150  * @return A reference to this object.
151  */
152  ScanParameters &setOwnAddressType(own_address_type_t address)
153  {
154  own_address_type = address;
155  return *this;
156  }
157 
158  /**
159  * Get the address type used during scan requests.
160  */
161  own_address_type_t getOwnAddressType() const
162  {
163  return own_address_type;
164  }
165 
166  /**
167  * Set the filter to apply during scanning.
168  * @param filter_policy The filter to apply during scanning.
169  * @return A reference to this object.
170  */
171  ScanParameters &setFilter(scanning_filter_policy_t filter_policy)
172  {
173  scanning_filter_policy = filter_policy;
174  return *this;
175  }
176 
177  /**
178  * Get the filter to use during scanning
179  */
180  scanning_filter_policy_t getFilter() const
181  {
182 #if BLE_FEATURE_WHITELIST
183  return scanning_filter_policy;
184 #else
185  return scanning_filter_policy_t::NO_FILTER;
186 #endif // BLE_FEATURE_WHITELIST
187  }
188 
189  /**
190  * Enable or disable PHYs that should be used during scanning.
191  * @param enable_1m True to enable the 1M phy and false to disable it.
192  * @param enable_coded True to enable the coded phy and false to disable it.
193  * @return A reference to this object.
194  */
195  ScanParameters &setPhys(bool enable_1m, bool enable_coded)
196  {
197 #if BLE_FEATURE_PHY_MANAGEMENT
198  phys.set_1m(enable_1m);
199  phys.set_coded(enable_coded);
200 #endif // BLE_FEATURE_PHY_MANAGEMENT
201  return *this;
202  }
203 
204  /**
205  * Get the PHYs to use during scanning.
206  */
208  {
209  return phys;
210  }
211 
212  /**
213  * Set the 1M scan configuration.
214  * @param interval The scan interval to use.
215  * @param window The scan window to use.
216  * @param active_scanning The active scanning flag.
217  * @return A reference to this object.
218  */
220  scan_interval_t interval,
221  scan_window_t window,
222  bool active_scanning
223  )
224  {
225  phys.set_1m(true);
226  phy_1m_configuration = phy_configuration_t(
227  interval, window, active_scanning
228  );
229  return *this;
230  }
231 
232  /**
233  * Get the 1M scan configuration.
234  */
236  {
237  return phy_1m_configuration;
238  }
239 
240  /**
241  * Set the coded PHY scan configuration.
242  * @param interval The scan interval to use.
243  * @param window The scan window to use.
244  * @param active_scanning The active scanning flag.
245  * @return A reference to this object.
246  */
248  scan_interval_t interval,
249  scan_window_t window,
250  bool active_scanning
251  )
252  {
253 #if BLE_FEATURE_PHY_MANAGEMENT
254  phys.set_coded(true);
255  phy_coded_configuration = phy_configuration_t(
256  interval, window, active_scanning
257  );
258 #endif // BLE_FEATURE_PHY_MANAGEMENT
259  return *this;
260  }
261 
262  /**
263  * Get the coded PHY scan configuration.
264  */
266  {
267  return phy_1m_configuration;
268  }
269 
270 private:
271  own_address_type_t own_address_type;
272  scanning_filter_policy_t scanning_filter_policy;
273 
274  phy_set_t phys;
275 
276  phy_configuration_t phy_1m_configuration;
277  phy_configuration_t phy_coded_configuration;
278 };
279 
280 /**
281  * @}
282  * @}
283  */
284 
285 } // namespace ble
286 
287 #endif /* ifndef MBED_GAP_SCAN_PARAMETERS_H__ */
ScanParameters & setCodedPhyConfiguration(scan_interval_t interval, scan_window_t window, bool active_scanning)
Set the coded PHY scan configuration.
own_address_type_t getOwnAddressType() const
Get the address type used during scan requests.
phy_configuration_t getCodedPhyConfiguration() const
Get the coded PHY scan configuration.
Scan configuration of a physical channel.
scanning_filter_policy_t getFilter() const
Get the filter to use during scanning.
ScanParameters & set1mPhyConfiguration(scan_interval_t interval, scan_window_t window, bool active_scanning)
Set the 1M scan configuration.
const scan_interval_t & getWindow() const
Get the scan window.
ScanParameters & setFilter(scanning_filter_policy_t filter_policy)
Set the filter to apply during scanning.
ScanParameters & setPhys(bool enable_1m, bool enable_coded)
Enable or disable PHYs that should be used during scanning.
Parameters defining the scan process.
const scan_window_t & getInterval() const
Get the scan interval.
Type that describes a bluetooth PHY(sical) transport.
ScanParameters & setOwnAddressType(own_address_type_t address)
Set the address type used for scan requests.
Type that describe a set of PHY(sical) transports.
ScanParameters(phy_t phy=phy_t::LE_1M, scan_window_t scan_interval=scan_interval_t::min(), scan_interval_t scan_window=scan_window_t::min(), bool active_scanning=false, own_address_type_t own_address_type=own_address_type_t::RANDOM, scanning_filter_policy_t scanning_filter_policy=scanning_filter_policy_t::NO_FILTER)
Construct a ScanParameters object that operates on a selected PHY.
phy_set_t getPhys() const
Get the PHYs to use during scanning.
Entry namespace for all BLE API definitions.
bool isActiveScanningSet() const
Return if active scanning is set.
phy_configuration_t get1mPhyConfiguration() const
Get the 1M scan configuration.
phy_configuration_t(scan_interval_t scan_interval=scan_interval_t::min(), scan_window_t scan_window=scan_window_t::min(), bool active_scanning=false)
Construct a phy_configuration_t.
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.