Mistake on this page?
Report an issue in GitHub or email us
ScanParameters.h
1 /* mbed Microcontroller Library
2  * Copyright (c) 2018-2018 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_SCAN_PARAMETERS_H__
18 #define MBED_GAP_SCAN_PARAMETERS_H__
19 
20 #include <stdint.h>
21 #include "ble/blecommon.h"
22 #include "BLETypes.h"
23 
24 namespace ble {
25 
26 /**
27  * @addtogroup ble
28  * @{
29  * @addtogroup gap
30  * @{
31  */
32 
33 /**
34  * Parameters defining the scan process.
35  *
36  * The scan process is defined by two main parameters:
37  * - The scan window that defines how long the device should scan.
38  * - The scan window that defines how frequently the device should scan.
39  *
40  * To scan continuously, the scan window and the scan interval should have the
41  * same value.
42  *
43  * To get extra data from the advertising device, the scanner can send scan
44  * requests to the advertiser; the advertiser may respond with scan responses.
45  * It is possible to select what type of address is used to issue the scan request.
46  *
47  * With Bluetooth 5, devices can advertise on more physical channels, and by
48  * extension, they can scan on more physical channels. It is possible to define
49  * independent scan parameters for every scannable physical channel.
50  */
52 public:
53 
54  /**
55  * Scan configuration of a physical channel.
56  */
58  /**
59  * Construct a phy_configuration_t.
60  * @param scan_interval The scan interval.
61  * @param scan_window The scan window.
62  * @param active_scanning True if scan request should be sent and false
63  * otherwise.
64  */
66  scan_interval_t scan_interval = scan_interval_t::min(),
67  scan_window_t scan_window = scan_window_t::min(),
68  bool active_scanning = false
69  ) :
70  interval(scan_interval),
71  window(scan_window),
72  active_scanning(active_scanning)
73  {
74  if (window.value() > interval.value()) {
75  interval = window;
76  }
77  }
78 
79  /**
80  * Get the scan interval.
81  */
82  const scan_window_t &getInterval() const
83  {
84  return interval;
85  }
86 
87  /**
88  * Get the scan window.
89  */
90  const scan_interval_t &getWindow() const
91  {
92  return window;
93  }
94 
95  /**
96  * Return if active scanning is set.
97  */
98  bool isActiveScanningSet() const
99  {
100  return active_scanning;
101  }
102 
103  private:
104  scan_window_t interval;
105  scan_interval_t window;
106  bool active_scanning;
107  };
108 
109  /**
110  * Construct a ScanParameters object that operates on a selected PHY.
111  *
112  * @param phy The phy to configure.
113  * @param scan_interval The scan interval.
114  * @param scan_window The scan window.
115  * @param active_scanning active scanning flag.
116  * @param own_address_type Address type used in scan requests.
117  * @param scanning_filter_policy Filter applied.
118  */
120  phy_t phy = phy_t::LE_1M,
121  scan_window_t scan_interval = scan_interval_t::min(),
122  scan_interval_t scan_window = scan_window_t::min(),
123  bool active_scanning = false,
126  ) :
127  own_address_type(own_address_type),
128  scanning_filter_policy(scanning_filter_policy),
129  phys(phy),
130  phy_1m_configuration(),
131  phy_coded_configuration()
132  {
133  phy_configuration_t conf(scan_interval, scan_window, active_scanning);
134  if (phy == phy_t::LE_1M) {
135  phy_1m_configuration = conf;
136  }
137 #if BLE_FEATURE_PHY_MANAGEMENT
138  else if (phy == phy_t::LE_CODED) {
139  phy_coded_configuration = conf;
140  }
141 #endif // BLE_FEATURE_PHY_MANAGEMENT
142  }
143 
144  /**
145  * Set the address type used for scan requests.
146  * @param address The type of address to use during scan requests.
147  * @return A reference to this object.
148  */
150  {
151  own_address_type = address;
152  return *this;
153  }
154 
155  /**
156  * Get the address type used during scan requests.
157  */
159  {
160  return own_address_type;
161  }
162 
163  /**
164  * Set the filter to apply during scanning.
165  * @param filter_policy The filter to apply during scanning.
166  * @return A reference to this object.
167  */
169  {
170  scanning_filter_policy = filter_policy;
171  return *this;
172  }
173 
174  /**
175  * Get the filter to use during scanning
176  */
178  {
179 #if BLE_FEATURE_WHITELIST
180  return scanning_filter_policy;
181 #else
183 #endif // BLE_FEATURE_WHITELIST
184  }
185 
186  /**
187  * Enable or disable PHYs that should be used during scanning.
188  * @param enable_1m True to enable the 1M phy and false to disable it.
189  * @param enable_coded True to enable the coded phy and false to disable it.
190  * @return A reference to this object.
191  */
192  ScanParameters &setPhys(bool enable_1m, bool enable_coded)
193  {
194 #if BLE_FEATURE_PHY_MANAGEMENT
195  phys.set_1m(enable_1m);
196  phys.set_coded(enable_coded);
197 #endif // BLE_FEATURE_PHY_MANAGEMENT
198  return *this;
199  }
200 
201  /**
202  * Get the PHYs to use during scanning.
203  */
205  {
206  return phys;
207  }
208 
209  /**
210  * Set the 1M scan configuration.
211  * @param interval The scan interval to use.
212  * @param window The scan window to use.
213  * @param active_scanning The active scanning flag.
214  * @return A reference to this object.
215  */
217  scan_interval_t interval,
218  scan_window_t window,
219  bool active_scanning
220  )
221  {
222  phys.set_1m(true);
223  phy_1m_configuration = phy_configuration_t(
224  interval, window, active_scanning
225  );
226  return *this;
227  }
228 
229  /**
230  * Get the 1M scan configuration.
231  */
233  {
234  return phy_1m_configuration;
235  }
236 
237  /**
238  * Set the coded PHY scan configuration.
239  * @param interval The scan interval to use.
240  * @param window The scan window to use.
241  * @param active_scanning The active scanning flag.
242  * @return A reference to this object.
243  */
245  scan_interval_t interval,
246  scan_window_t window,
247  bool active_scanning
248  )
249  {
250 #if BLE_FEATURE_PHY_MANAGEMENT
251  phys.set_coded(true);
252  phy_coded_configuration = phy_configuration_t(
253  interval, window, active_scanning
254  );
255 #endif // BLE_FEATURE_PHY_MANAGEMENT
256  return *this;
257  }
258 
259  /**
260  * Get the coded PHY scan configuration.
261  */
263  {
264  return phy_1m_configuration;
265  }
266 
267 private:
268  own_address_type_t own_address_type;
269  scanning_filter_policy_t scanning_filter_policy;
270 
271  phy_set_t phys;
272 
273  phy_configuration_t phy_1m_configuration;
274  phy_configuration_t phy_coded_configuration;
275 };
276 
277 /**
278  * @}
279  * @}
280  */
281 
282 } // namespace ble
283 
284 #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.
Use the random device address.
Definition: Types.h:547
scanning_filter_policy_t getFilter() const
Get the filter to use during scanning.
Rep value() const
Return the duration in TB units.
Definition: Duration.h:165
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.
Scanning policy filter mode.
Definition: Types.h:426
ScanParameters & setFilter(scanning_filter_policy_t filter_policy)
Set the filter to apply during scanning.
LE Coded PHY.
Definition: BLETypes.h:677
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.
Definition: BLETypes.h:628
ScanParameters & setOwnAddressType(own_address_type_t address)
Set the address type used for scan requests.
Type that describe a set of PHY(sical) transports.
Definition: BLETypes.h:693
Accept all advertising packets except directed advertising packets not addressed to this device...
Definition: Types.h:433
1Mbit/s LE.
Definition: BLETypes.h:643
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.
static Duration min()
Return the minimum duration.
Definition: Duration.h:200
Type used to model the own address used during the following GAP operations: advertising, scanning and initiating.
Definition: Types.h:536
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.