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  } else if (phy == phy_t::LE_CODED) {
137  phy_coded_configuration = conf;
138  }
139  }
140 
141  /**
142  * Set the address type used for scan requests.
143  * @param address The type of address to use during scan requests.
144  * @return A reference to this object.
145  */
147  {
148  own_address_type = address;
149  return *this;
150  }
151 
152  /**
153  * Get the address type used during scan requests.
154  */
156  {
157  return own_address_type;
158  }
159 
160  /**
161  * Set the filter to apply during scanning.
162  * @param filter_policy The filter to apply during scanning.
163  * @return A reference to this object.
164  */
166  {
167  scanning_filter_policy = filter_policy;
168  return *this;
169  }
170 
171  /**
172  * Get the filter to use during scanning
173  */
175  {
176  return scanning_filter_policy;
177  }
178 
179  /**
180  * Enable or disable PHYs that should be used during scanning.
181  * @param enable_1m True to enable the 1M phy and false to disable it.
182  * @param enable_coded True to enable the coded phy and false to disable it.
183  * @return A reference to this object.
184  */
185  ScanParameters &setPhys(bool enable_1m, bool enable_coded)
186  {
187  phys.set_1m(enable_1m);
188  phys.set_coded(enable_coded);
189  return *this;
190  }
191 
192  /**
193  * Get the PHYs to use during scanning.
194  */
196  {
197  return phys;
198  }
199 
200  /**
201  * Set the 1M scan configuration.
202  * @param interval The scan interval to use.
203  * @param window The scan window to use.
204  * @param active_scanning The active scanning flag.
205  * @return A reference to this object.
206  */
208  scan_interval_t interval,
209  scan_window_t window,
210  bool active_scanning
211  )
212  {
213  phys.set_1m(true);
214  phy_1m_configuration = phy_configuration_t(
215  interval, window, active_scanning
216  );
217  return *this;
218  }
219 
220  /**
221  * Get the 1M scan configuration.
222  */
224  {
225  return phy_1m_configuration;
226  }
227 
228  /**
229  * Set the coded PHY scan configuration.
230  * @param interval The scan interval to use.
231  * @param window The scan window to use.
232  * @param active_scanning The active scanning flag.
233  * @return A reference to this object.
234  */
236  scan_interval_t interval,
237  scan_window_t window,
238  bool active_scanning
239  )
240  {
241  phys.set_coded(true);
242  phy_coded_configuration = phy_configuration_t(
243  interval, window, active_scanning
244  );
245  return *this;
246  }
247 
248  /**
249  * Get the coded PHY scan configuration.
250  */
252  {
253  return phy_1m_configuration;
254  }
255 
256 private:
257  own_address_type_t own_address_type;
258  scanning_filter_policy_t scanning_filter_policy;
259 
260  phy_set_t phys;
261 
262  phy_configuration_t phy_1m_configuration;
263  phy_configuration_t phy_coded_configuration;
264 };
265 
266 /**
267  * @}
268  * @}
269  */
270 
271 } // namespace ble
272 
273 #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:673
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:624
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:689
Accept all advertising packets except directed advertising packets not addressed to this device...
Definition: Types.h:433
1Mbit/s LE.
Definition: BLETypes.h:639
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.
Definition: ArrayView.h:37
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.