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