Mistake on this page?
Report an issue in GitHub or email us
AdvertisingParameters.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_ADVERTISING_PARAMETERS_H__
20 #define MBED_ADVERTISING_PARAMETERS_H__
21 
22 #include <algorithm>
23 
24 #include "ble/common/BLETypes.h"
25 #include "ble/common/blecommon.h"
26 #include "ble/common/SafeEnum.h"
27 
28 namespace ble {
29 
30 /**
31  * @addtogroup ble
32  * @{
33  * @addtogroup gap
34  * @{
35  */
36 
37 /**
38  * Parameters defining the advertising process.
39  *
40  * @par Legacy advertising:
41  *
42  * Advertising parameters for legacy advertising are a mainly defined by a pair
43  * of values:
44  * - The Advertising mode modeled after advertising_type_t. It defines
45  * whether the device is connectable and scannable. You can set this value at
46  * construction time, update it with setType() and query it with getType().
47  * - Time interval between advertisement. You can set it at construction time,
48  * update it with setPrimaryInterval() and obtain it from getMinPrimaryInterval()
49  * and getMaxPrimaryInterval().
50  *
51  * In addition, it is possible to adjust other parameters:
52  * - You can select the advertising channels with setPrimaryChannels() and
53  * queried them with getChannel37(), getChannel38() and getChannel39().
54  * - You can set the address type used by the local device with setOwnAddressType()
55  * and query it by getOwnAddressType().
56  * - You can set the filter policy for scan and connection requests with
57  * setFilter() and query it with getFilter().
58  *
59  * For directed advertising, you can set the address of the target with the help
60  * of setPeer() and query it with getPeerAddress() and getPeerAddressType().
61  *
62  * @par Extended advertising:
63  *
64  * To use extended advertising features, first disable legacy advertising
65  * with setUseLegacyPDU().
66  *
67  * Extended advertising adds new features to BLE advertising:
68  * - Control the advertising power with setTxPower().
69  * - Include the Tx power in advertising packet with includeTxPowerInHeader().
70  * - Set a secondary phy_t channel with setPhy().
71  * - Enable scan requests notification to let the application be aware of any
72  * incoming scan requests with setScanRequestNotification().
73  * - Advertise anonymously with setAnonymousAdvertising()
74  *
75  * @par Fluent interface:
76  *
77  * This API is designed for usability. You can construct
78  * it and pass it in place. To achieve this, the fluent interface pattern
79  * is used. Every setter returns a reference to the object modified and can be
80  * chained.
81  *
82  * @code
83  void setAdvertisingParameters(ble::PalGap& gap) {
84  using namespace ble;
85  gap.setAdvertisingParameters(
86  LEGACY_ADVERTISING_HANDLE,
87  AdvertisingParameters()
88  .setType(advertising_type_t::ADV_CONNECTABLE_UNDIRECTED)
89  .setPrimaryInterval(millisecond_t(200), millisecond_t(500))
90  .setOwnAddressType(own_address_type_t::RANDOM)
91  .setUseLegacyPDU(false)
92  .setPhy(phy_t::LE_1M, phy_t::LE_CODED)
93  );
94  }
95  * @endcode
96  *
97  * @see ble::Gap::createAdvertisingSet(), ble::Gap::setAdvertisingParameters()
98  */
100 
101  /**
102  * Default minimum advertising interval.
103  */
104  static const uint32_t DEFAULT_ADVERTISING_INTERVAL_MIN = 0x400;
105 
106  /**
107  * Default maximum advertising interval.
108  */
109  static const uint32_t DEFAULT_ADVERTISING_INTERVAL_MAX = 0x800;
110 
111  /**
112  * Minimum Advertising interval for scannable and nonconnectable
113  * undirected events in 625us units.
114  *
115  * @note Equal to 100ms.
116  */
117  static const uint32_t GAP_ADV_PARAMS_INTERVAL_MIN_NONCON = 0x00A0;
118 
119 public:
120  /**
121  * Construct an instance of GapAdvertisingParams.
122  *
123  * @param[in] advType Type of advertising.
124  * @param[in] minInterval, maxInterval Time interval between two advertisement.
125  * A range is provided to the LE subsystem, so it can adjust the advertising
126  * interval with other transmission happening on the BLE radio.
127  * @param[in] useLegacyPDU If true legacy PDU shall be used for advertising.
128  *
129  * @note If CONNECTABLE_UNDIRECTED or CONNECTABLE_DIRECTED advertising is used
130  * you must use legacy PDU.
131  *
132  * @note If values in input are out of range, they will be normalized.
133  *
134  * @note If type selected is incompatible with non legacy PDU, legacy PDU will be used.
135  */
137  advertising_type_t advType = advertising_type_t::CONNECTABLE_UNDIRECTED,
138  adv_interval_t minInterval = adv_interval_t(DEFAULT_ADVERTISING_INTERVAL_MIN),
139  adv_interval_t maxInterval = adv_interval_t(DEFAULT_ADVERTISING_INTERVAL_MAX),
140  bool useLegacyPDU = true
141  ) :
142  _advType(advType),
143  _minInterval(minInterval),
144  _maxInterval(maxInterval),
145  _peerAddressType(target_peer_address_type_t::PUBLIC),
146  _ownAddressType(own_address_type_t::RANDOM),
147  _policy(advertising_filter_policy_t::NO_FILTER),
148  _primaryPhy(phy_t::LE_1M),
149  _secondaryPhy(phy_t::LE_1M),
150  _peerAddress(),
151  _txPower(127),
152  _maxSkip(0),
153  _channel37(true),
154  _channel38(true),
155  _channel39(true),
156  _anonymous(false),
157  _notifyOnScan(false),
158  _legacyPDU(useLegacyPDU),
159  _includeHeaderTxPower(false)
160  {
161  normalize();
162  }
163 
164  /**
165  * Construct an instance of GapAdvertisingParams.
166  *
167  * @param[in] advType Type of advertising.
168  * @param[in] useLegacyPDU If true legacy PDU shall be used for advertising.
169  *
170  * @note If CONNECTABLE_UNDIRECTED or CONNECTABLE_DIRECTED advertising is used
171  * you must use legacy PDU.
172  *
173  * @note If type selected is incompatible with non legacy PDU, legacy PDU will be used.
174  */
176  advertising_type_t advType,
177  bool useLegacyPDU
178  ) :
179  _advType(advType),
180  _minInterval(adv_interval_t(DEFAULT_ADVERTISING_INTERVAL_MIN)),
181  _maxInterval(adv_interval_t(DEFAULT_ADVERTISING_INTERVAL_MAX)),
182  _peerAddressType(target_peer_address_type_t::PUBLIC),
183  _ownAddressType(own_address_type_t::RANDOM),
184  _policy(advertising_filter_policy_t::NO_FILTER),
185  _primaryPhy(phy_t::LE_1M),
186  _secondaryPhy(phy_t::LE_1M),
187  _peerAddress(),
188  _txPower(127),
189  _maxSkip(0),
190  _channel37(true),
191  _channel38(true),
192  _channel39(true),
193  _anonymous(false),
194  _notifyOnScan(false),
195  _legacyPDU(useLegacyPDU),
196  _includeHeaderTxPower(false)
197  {
198  normalize();
199  }
200 
201 public:
202  /**
203  * Update the advertising type and whether to use legacy PDU.
204  *
205  * @note If legacy PDU is not used then you cannot use
206  * CONNECTABLE_UNDIRECTED nor CONNECTABLE_DIRECTED.
207  *
208  * @param[in] newAdvType The new advertising type.
209  *
210  * @param[in] legacy If true, legacy PDU will be used.
211  *
212  * @return reference to this object.
213  */
214  AdvertisingParameters &setType(advertising_type_t newAdvType, bool legacy)
215  {
216  if (newAdvType == advertising_type_t::CONNECTABLE_UNDIRECTED ||
217  newAdvType == advertising_type_t::CONNECTABLE_DIRECTED) {
218  /* these types can only be used with legacy PDUs */
219  MBED_ASSERT(legacy);
220  }
221  _advType = newAdvType;
222  _legacyPDU = legacy;
223  return *this;
224  }
225 
226  /**
227  * Update the advertising type.
228  *
229  * @note If legacy PDU is not used then you cannot use
230  * CONNECTABLE_UNDIRECTED nor CONNECTABLE_DIRECTED.
231  *
232  * @param[in] newAdvType The new advertising type.
233  *
234  * @return reference to this object.
235  */
236  AdvertisingParameters &setType(advertising_type_t newAdvType)
237  {
238  if (newAdvType == advertising_type_t::CONNECTABLE_UNDIRECTED ||
239  newAdvType == advertising_type_t::CONNECTABLE_DIRECTED) {
240  /* these types can only be used with legacy PDUs */
241  MBED_ASSERT(_legacyPDU);
242  }
243  _advType = newAdvType;
244  return *this;
245  }
246 
247  /**
248  * Return the advertising type.
249  *
250  * @return Advertising type.
251  */
252  advertising_type_t getType() const
253  {
254  return _advType;
255  }
256 
257  /** Set the advertising intervals on the primary channels.
258  *
259  * @param[in] min, max Time interval between two advertisements.
260  * A range is provided to the LE subsystem, so it can adjust the advertising
261  * interval with other transmission happening on the BLE radio.
262  *
263  * @return reference to this object.
264  */
266  adv_interval_t min, adv_interval_t max
267  )
268  {
269  _minInterval = min;
270  _maxInterval = max;
271  return *this;
272  }
273 
274  /** Get the minimum advertising intervals on the primary channels.
275  *
276  * @return The lower bound of the primary interval selected.
277  */
278  adv_interval_t getMinPrimaryInterval() const
279  {
280  return _minInterval;
281  }
282 
283  /** Get the maximum advertising intervals on the primary channels.
284  *
285  * @return The higher bound of the primary interval selected.
286  */
287  adv_interval_t getMaxPrimaryInterval() const
288  {
289  return _maxInterval;
290  }
291 
292  /** Set which channels are to be used for primary advertising.
293  * At least must be used. If all are set to disabled, all channels will be used.
294  *
295  * @param channel37 Use channel 37.
296  * @param channel38 Use channel 38.
297  * @param channel39 Use channel 39.
298  *
299  * @return a reference to this object.
300  */
302  bool channel37, bool channel38, bool channel39
303  )
304  {
305  if (!channel37 && !channel38 && !channel39) {
306  channel37 = channel38 = channel39 = true;
307  }
308  _channel37 = channel37;
309  _channel38 = channel38;
310  _channel39 = channel39;
311  return *this;
312  }
313 
314  /** Check if channel 37 is used for primary advertising.
315  *
316  * @return True if channel used.
317  */
318  bool getChannel37() const
319  {
320  return _channel37;
321  }
322 
323  /** Check if channel 38 is used for primary advertising.
324  *
325  * @return True if channel used.
326  */
327  bool getChannel38() const
328  {
329  return _channel38;
330  }
331 
332  /** Check if channel 39 is used for primary advertising.
333  *
334  * @return True if channel used.
335  */
336  bool getChannel39() const
337  {
338  return _channel39;
339  }
340 
341  /** Get what type of address is to be used as your own address during advertising.
342  *
343  * @return a reference to this object.
344  */
345  AdvertisingParameters &setOwnAddressType(own_address_type_t addressType)
346  {
347  _ownAddressType = addressType;
348  return *this;
349  }
350 
351  /** Get what type of address is to be used as your own address during advertising.
352  *
353  * @return Addres tpe used.
354  */
355  own_address_type_t getOwnAddressType() const
356  {
357  return _ownAddressType;
358  }
359 
360  /** Set peer address and type used during directed advertising.
361  *
362  * @param address Peer's address bytes.
363  * @param addressType Peer's address type.
364  *
365  * @return a reference to this object.
366  */
368  const address_t &address,
369  target_peer_address_type_t addressType
370  )
371  {
372  _peerAddress = address;
373  _peerAddressType = addressType;
374  return *this;
375  };
376 
377  /** Get the peer address used during directed advertising.
378  *
379  * @return Address of the peer targeted by directed advertising.
380  */
381  const address_t &getPeerAddress() const
382  {
383  return _peerAddress;
384  };
385 
386 
387  /** Get the peer address type used during directed advertising.
388  *
389  * @return The type of address of the peer targeted by directed advertising.
390  */
391  target_peer_address_type_t getPeerAddressType() const
392  {
393  return _peerAddressType;
394  };
395 
396  /** Set the filter policy of whitelist use during advertising;
397  *
398  * @param mode Policy to use.
399  *
400  * @return A reference to this object.
401  */
402  AdvertisingParameters &setFilter(advertising_filter_policy_t mode)
403  {
404  _policy = mode;
405  return *this;
406  }
407 
408  /** Get the filter policy of whitelist use during advertising;
409  *
410  * @return Policy used.
411  */
412  advertising_filter_policy_t getFilter() const
413  {
414 #if BLE_FEATURE_WHITELIST
415  return _policy;
416 #else
417  return advertising_filter_policy_t::NO_FILTER;
418 #endif // BLE_FEATURE_WHITELIST
419  }
420 
421  /* Extended advertising parameters */
422 
423  /** Get PHYs used on primary and secondary advertising channels.
424  *
425  * @param primaryPhy Primary advertising channels PHY.
426  * @param secondaryPhy Secondary advertising channels PHY.
427  *
428  * @return A reference to this.
429  */
430  AdvertisingParameters &setPhy(phy_t primaryPhy, phy_t secondaryPhy)
431  {
432  _primaryPhy = primaryPhy;
433  _secondaryPhy = secondaryPhy;
434  return *this;
435  }
436 
437  /** Get PHY used for primary advertising.
438  *
439  * @return PHY used for primary advertising.
440  */
442  {
443  return _primaryPhy;
444  }
445 
446  /** Get PHY used for secondary advertising.
447  *
448  * @return PHY used for secondary advertising.
449  */
451  {
452  return _secondaryPhy;
453  }
454 
455  /** Set the advertising TX power.
456  *
457  * @param txPower Advertising TX power.
458  *
459  * @return A reference to this object.
460  */
461  AdvertisingParameters &setTxPower(advertising_power_t txPower)
462  {
463  _txPower = txPower;
464  return *this;
465  }
466 
467  /** Get the advertising TX power.
468  *
469  * @return Advertising TX power.
470  */
471  advertising_power_t getTxPower() const
472  {
473  return _txPower;
474  }
475 
476  /** Set how many events can be skipped on the secondary channel.
477  *
478  * @param eventNumber Number of events that can be skipped.
479  *
480  * @return A reference to this object.
481  */
483  {
484  _maxSkip = eventNumber;
485  return *this;
486  }
487 
488  /** Return how many events can be skipped on the secondary channel.
489  *
490  * @return How many events can be skipped on the secondary channel.
491  */
492  uint8_t getSecondaryMaxSkip() const
493  {
494  return _maxSkip;
495  }
496 
497  /** Enabled or disable the callback that notifies the user about a scan request.
498  *
499  * @param enable Enable callback if true.
500  *
501  * @return A reference to this object.
502  *
503  * @see ::ble::Gap::EventHandler::onScanRequestReceived()
504  */
506  {
507  _notifyOnScan = enable;
508  return *this;
509  }
510 
511  /** Return of the callback for scan request is enabled.
512  *
513  * @return True if callback is enabled.
514  */
516  {
517  return _notifyOnScan;
518  }
519 
520  /** Use legacy PDU during advertising.
521  *
522  * @param enable If true, legacy PDU will be used.
523  *
524  * @note If CONNECTABLE_UNDIRECTED or CONNECTABLE_DIRECTED advertising is used
525  * you must use legacy PDU.
526  *
527  * @return A reference to this object.
528  */
530  {
531  if (!enable) {
532  /* these types can only be used with legacy PDUs */
533  MBED_ASSERT((_advType != advertising_type_t::CONNECTABLE_UNDIRECTED) &&
534  (_advType != advertising_type_t::CONNECTABLE_DIRECTED));
535  }
536 
537  _legacyPDU = enable;
538  return *this;
539  }
540 
541  /** Check if legacy PDU is used during advertising.
542  *
543  * @return True legacy PDU will be used.
544  */
545  bool getUseLegacyPDU() const
546  {
547  return _legacyPDU;
548  }
549 
550  /** Set if TX power should be included in the header.
551  *
552  * @param enable If true, include the TX power in the header.
553  *
554  * @return A reference to this object.
555  */
557  {
558  _includeHeaderTxPower = enable;
559  return *this;
560  }
561 
562  /** Check if TX power should be included in the header.
563  *
564  * @return True if TX power is included in the header.
565  */
566  bool getTxPowerInHeader() const
567  {
568  return _includeHeaderTxPower;
569  }
570 
571  /** Advertise without your own address.
572  *
573  * @param enable Advertising anonymous if true.
574  *
575  * @note You may not use anonymous advertising with periodic advertising on the same set.
576  *
577  * @return reference to this object.
578  */
580  {
581  _anonymous = enable;
582  return *this;
583  }
584 
585  /** Check if advertising is anonymous.
586  *
587  * @return True if advertising is anonymous.
588  */
590  {
591  return _anonymous;
592  }
593 
594 private:
595  /**
596  * Enforce limits on parameters.
597  */
598  void normalize()
599  {
600  /* Min interval is slightly larger than in other modes. */
601  if (_advType == advertising_type_t::NON_CONNECTABLE_UNDIRECTED) {
602  _minInterval = adv_interval_t(std::max(_minInterval.value(), GAP_ADV_PARAMS_INTERVAL_MIN_NONCON));
603  _maxInterval = adv_interval_t(std::max(_maxInterval.value(), GAP_ADV_PARAMS_INTERVAL_MIN_NONCON));
604  }
605  if (_advType == advertising_type_t::CONNECTABLE_DIRECTED ||
606  _advType == advertising_type_t::CONNECTABLE_UNDIRECTED) {
607  _legacyPDU = true;
608  }
609  }
610 
611 private:
612  advertising_type_t _advType;
613  /* The advertising interval in ADV duration units (in other words, 0.625ms). */
614  adv_interval_t _minInterval;
615  /* The advertising max interval in ADV duration units (in other words, 0.625ms) used in extended advertising. */
616  adv_interval_t _maxInterval;
617 
618  target_peer_address_type_t _peerAddressType;
619  own_address_type_t _ownAddressType;
620  advertising_filter_policy_t _policy;
621  phy_t _primaryPhy;
622  phy_t _secondaryPhy;
623  address_t _peerAddress;
624  advertising_power_t _txPower;
625  uint8_t _maxSkip;
626  bool _channel37:1;
627  bool _channel38:1;
628  bool _channel39:1;
629  bool _anonymous:1;
630  bool _notifyOnScan:1;
631  bool _legacyPDU:1;
632  bool _includeHeaderTxPower:1;
633 };
634 
635 /**
636  * @}
637  * @}
638  */
639 
640 } // namespace ble
641 
642 #endif /* ifndef MBED_ADVERTISING_PARAMETERS_H__ */
bool getChannel37() const
Check if channel 37 is used for primary advertising.
AdvertisingParameters & setType(advertising_type_t newAdvType)
Update the advertising type.
AdvertisingParameters & setType(advertising_type_t newAdvType, bool legacy)
Update the advertising type and whether to use legacy PDU.
advertising_filter_policy_t getFilter() const
Get the filter policy of whitelist use during advertising;.
AdvertisingParameters & setScanRequestNotification(bool enable=true)
Enabled or disable the callback that notifies the user about a scan request.
AdvertisingParameters & setPeer(const address_t &address, target_peer_address_type_t addressType)
Set peer address and type used during directed advertising.
own_address_type_t getOwnAddressType() const
Get what type of address is to be used as your own address during advertising.
advertising_power_t getTxPower() const
Get the advertising TX power.
phy_t getSecondaryPhy() const
Get PHY used for secondary advertising.
AdvertisingParameters & setTxPower(advertising_power_t txPower)
Set the advertising TX power.
AdvertisingParameters(advertising_type_t advType, bool useLegacyPDU)
Construct an instance of GapAdvertisingParams.
const address_t & getPeerAddress() const
Get the peer address used during directed advertising.
bool getChannel38() const
Check if channel 38 is used for primary advertising.
target_peer_address_type_t getPeerAddressType() const
Get the peer address type used during directed advertising.
AdvertisingParameters & setOwnAddressType(own_address_type_t addressType)
Get what type of address is to be used as your own address during advertising.
MAC address data type.
AdvertisingParameters & setPhy(phy_t primaryPhy, phy_t secondaryPhy)
Get PHYs used on primary and secondary advertising channels.
Type that describes a bluetooth PHY(sical) transport.
AdvertisingParameters & setPrimaryChannels(bool channel37, bool channel38, bool channel39)
Set which channels are to be used for primary advertising.
adv_interval_t getMaxPrimaryInterval() const
Get the maximum advertising intervals on the primary channels.
AdvertisingParameters(advertising_type_t advType=advertising_type_t::CONNECTABLE_UNDIRECTED, adv_interval_t minInterval=adv_interval_t(DEFAULT_ADVERTISING_INTERVAL_MIN), adv_interval_t maxInterval=adv_interval_t(DEFAULT_ADVERTISING_INTERVAL_MAX), bool useLegacyPDU=true)
Construct an instance of GapAdvertisingParams.
#define MBED_ASSERT(expr)
MBED_ASSERT Declare runtime assertions: results in runtime error if condition is false.
Definition: mbed_assert.h:65
AdvertisingParameters & setPrimaryInterval(adv_interval_t min, adv_interval_t max)
Set the advertising intervals on the primary channels.
advertising_type_t getType() const
Return the advertising type.
uint8_t getSecondaryMaxSkip() const
Return how many events can be skipped on the secondary channel.
phy_t getPrimaryPhy() const
Get PHY used for primary advertising.
bool getUseLegacyPDU() const
Check if legacy PDU is used during advertising.
adv_interval_t getMinPrimaryInterval() const
Get the minimum advertising intervals on the primary channels.
Parameters defining the advertising process.
AdvertisingParameters & includeTxPowerInHeader(bool enable=true)
Set if TX power should be included in the header.
AdvertisingParameters & setSecondaryMaxSkip(uint8_t eventNumber)
Set how many events can be skipped on the secondary channel.
AdvertisingParameters & setFilter(advertising_filter_policy_t mode)
Set the filter policy of whitelist use during advertising;.
AdvertisingParameters & setUseLegacyPDU(bool enable=true)
Use legacy PDU during advertising.
bool getTxPowerInHeader() const
Check if TX power should be included in the header.
Entry namespace for all BLE API definitions.
AdvertisingParameters & setAnonymousAdvertising(bool enable)
Advertise without your own address.
bool getAnonymousAdvertising() const
Check if advertising is anonymous.
bool getScanRequestNotification() const
Return of the callback for scan request is enabled.
bool getChannel39() const
Check if channel 39 is used for primary advertising.
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.