Mistake on this page?
Report an issue in GitHub or email us
GapAdvertisingParams.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_GAP_ADVERTISING_PARAMS_H__
18 #define MBED_GAP_ADVERTISING_PARAMS_H__
19 
20 /**
21  * @addtogroup ble
22  * @{
23  * @addtogroup gap
24  * @{
25  */
26 
27 /**
28  * Parameters defining the advertising process.
29  *
30  * Advertising parameters are a triplet of three value:
31  * - The Advertising mode modeled after AdvertisingType_t. It defines
32  * if the device is connectable and scannable. This value can be set at
33  * construction time, updated with setAdvertisingType() and queried by
34  * getAdvertisingType().
35  * - Time interval between advertisement. It can be set at construction time,
36  * updated by setInterval() and obtained from getInterval().
37  * - Duration of the advertising process. As others, it can be set at
38  * construction time, modified by setTimeout() and retrieved by getTimeout().
39  */
41 public:
42 
43  /**
44  * Minimum Advertising interval for connectable undirected and connectable
45  * directed events in 625us units.
46  *
47  * @note Equal to 20 ms.
48  */
49  static const unsigned GAP_ADV_PARAMS_INTERVAL_MIN = 0x0020;
50 
51  /**
52  * Minimum Advertising interval for scannable and nonconnectable
53  * undirected events in 625us units.
54  *
55  * @note Equal to 100ms.
56  */
57  static const unsigned GAP_ADV_PARAMS_INTERVAL_MIN_NONCON = 0x00A0;
58 
59  /**
60  * Maximum Advertising interval in 625us units.
61  *
62  * @note Equal to 10.24s.
63  */
64  static const unsigned GAP_ADV_PARAMS_INTERVAL_MAX = 0x4000;
65 
66  /**
67  * Maximum advertising timeout allowed; in seconds.
68  */
69  static const unsigned GAP_ADV_PARAMS_TIMEOUT_MAX = 0x3FFF;
70 
71  /**
72  * Encapsulates the peripheral advertising modes.
73  *
74  * It determine how the device appears to other scanner and peripheral
75  * devices in the scanning range.
76  */
78  /**
79  * Device is connectable, scannable and doesn't expect connection from a
80  * specific peer.
81  *
82  * @see Vol 3, Part C, Section 9.3.4 and Vol 6, Part B, Section 2.3.1.1.
83  */
85 
86  /**
87  * Device is connectable and expects connection from a specific peer.
88  *
89  * @see Vol 3, Part C, Section 9.3.3 and Vol 6, Part B, Section 2.3.1.2.
90  */
92 
93  /**
94  * Device is scannable but not connectable.
95  *
96  * @see Vol 6, Part B, Section 2.3.1.4.
97  */
99 
100  /**
101  * Device is not connectable and not scannable.
102  *
103  * @see Vol 3, Part C, Section 9.3.2 and Vol 6, Part B, Section 2.3.1.3.
104  */
106  };
107 
108  /**
109  * Alias for GapAdvertisingParams::AdvertisingType_t.
110  *
111  * @deprecated Future releases will drop this type alias.
112  */
114 
115 public:
116  /**
117  * Construct an instance of GapAdvertisingParams.
118  *
119  * @param[in] advType Type of advertising.
120  * @param[in] interval Time interval between two advertisement in units of
121  * 0.625ms.
122  * @param[in] timeout Duration in seconds of the advertising process. A
123  * value of 0 indicate that there is no timeout of the advertising process.
124  *
125  * @note If value in input are out of range, they will be normalized.
126  */
129  uint16_t interval = GAP_ADV_PARAMS_INTERVAL_MIN_NONCON,
130  uint16_t timeout = 0
131  ) :
132  _advType(advType),
133  _interval(interval),
134  _timeout(timeout)
135  {
136  /* Interval checks. */
137  if (_advType == ADV_CONNECTABLE_DIRECTED) {
138  /* Interval must be 0 in directed connectable mode. */
139  _interval = 0;
140  } else if (_advType == ADV_NON_CONNECTABLE_UNDIRECTED) {
141  /* Min interval is slightly larger than in other modes. */
142  if (_interval < GAP_ADV_PARAMS_INTERVAL_MIN_NONCON) {
144  }
145  if (_interval > GAP_ADV_PARAMS_INTERVAL_MAX) {
146  _interval = GAP_ADV_PARAMS_INTERVAL_MAX;
147  }
148  } else {
149  /* Stay within interval limits. */
150  if (_interval < GAP_ADV_PARAMS_INTERVAL_MIN) {
151  _interval = GAP_ADV_PARAMS_INTERVAL_MIN;
152  }
153  if (_interval > GAP_ADV_PARAMS_INTERVAL_MAX) {
154  _interval = GAP_ADV_PARAMS_INTERVAL_MAX;
155  }
156  }
157 
158  /* Timeout checks. */
159  if (timeout) {
160  /* Stay within timeout limits. */
161  if (_timeout > GAP_ADV_PARAMS_TIMEOUT_MAX) {
162  _timeout = GAP_ADV_PARAMS_TIMEOUT_MAX;
163  }
164  }
165  }
166 
167  /**
168  * Number of microseconds in 0.625 milliseconds.
169  */
170  static const uint16_t UNIT_0_625_MS = 625;
171 
172  /**
173  * Convert milliseconds to units of 0.625ms.
174  *
175  * @param[in] durationInMillis Number of milliseconds to convert.
176  *
177  * @return The value of @p durationInMillis in units of 0.625ms.
178  */
179  static uint16_t MSEC_TO_ADVERTISEMENT_DURATION_UNITS(uint32_t durationInMillis)
180  {
181  return (durationInMillis * 1000) / UNIT_0_625_MS;
182  }
183 
184  /**
185  * Convert units of 0.625ms to milliseconds.
186  *
187  * @param[in] gapUnits The number of units of 0.625ms to convert.
188  *
189  * @return The value of @p gapUnits in milliseconds.
190  */
191  static uint16_t ADVERTISEMENT_DURATION_UNITS_TO_MS(uint16_t gapUnits)
192  {
193  return (gapUnits * UNIT_0_625_MS) / 1000;
194  }
195 
196  /**
197  * Get the advertising type.
198  *
199  * @return The advertising type.
200  */
202  {
203  return _advType;
204  }
205 
206  /**
207  * Get the advertising interval in milliseconds.
208  *
209  * @return The advertisement interval (in milliseconds).
210  */
211  uint16_t getInterval(void) const
212  {
213  return ADVERTISEMENT_DURATION_UNITS_TO_MS(_interval);
214  }
215 
216  /**
217  * Get the advertisement interval in units of 0.625ms.
218  *
219  * @return The advertisement interval in advertisement duration units
220  * (0.625ms units).
221  */
222  uint16_t getIntervalInADVUnits(void) const
223  {
224  return _interval;
225  }
226 
227  /**
228  * Get the advertising timeout.
229  *
230  * @return The advertising timeout (in seconds).
231  */
232  uint16_t getTimeout(void) const
233  {
234  return _timeout;
235  }
236 
237  /**
238  * Update the advertising type.
239  *
240  * @param[in] newAdvType The new advertising type.
241  */
243  {
244  _advType = newAdvType;
245  }
246 
247  /**
248  * Update the advertising interval in milliseconds.
249  *
250  * @param[in] newInterval The new advertising interval in milliseconds.
251  */
252  void setInterval(uint16_t newInterval)
253  {
254  _interval = MSEC_TO_ADVERTISEMENT_DURATION_UNITS(newInterval);
255  }
256 
257  /**
258  * Update the advertising timeout.
259  *
260  * @param[in] newTimeout The new advertising timeout (in seconds).
261  *
262  * @note 0 is a special value meaning the advertising process never ends.
263  */
264  void setTimeout(uint16_t newTimeout)
265  {
266  _timeout = newTimeout;
267  }
268 
269 private:
270  /**
271  * The advertising type.
272  */
273  AdvertisingType_t _advType;
274 
275  /**
276  * The advertising interval in ADV duration units (in other words, 0.625ms).
277  */
278  uint16_t _interval;
279 
280  /**
281  * The advertising timeout in seconds.
282  */
283  uint16_t _timeout;
284 };
285 
286 /**
287  * @}
288  * @}
289  */
290 
291 #endif /* ifndef MBED_GAP_ADVERTISING_PARAMS_H__ */
Device is connectable and expects connection from a specific peer.
static uint16_t MSEC_TO_ADVERTISEMENT_DURATION_UNITS(uint32_t durationInMillis)
Convert milliseconds to units of 0.625ms.
void setAdvertisingType(AdvertisingType_t newAdvType)
Update the advertising type.
Parameters defining the advertising process.
AdvertisingType_t getAdvertisingType(void) const
Get the advertising type.
void setTimeout(uint16_t newTimeout)
Update the advertising timeout.
Device is scannable but not connectable.
void setInterval(uint16_t newInterval)
Update the advertising interval in milliseconds.
GapAdvertisingParams(AdvertisingType_t advType=ADV_CONNECTABLE_UNDIRECTED, uint16_t interval=GAP_ADV_PARAMS_INTERVAL_MIN_NONCON, uint16_t timeout=0)
Construct an instance of GapAdvertisingParams.
uint16_t getIntervalInADVUnits(void) const
Get the advertisement interval in units of 0.625ms.
static const unsigned GAP_ADV_PARAMS_INTERVAL_MIN
Minimum Advertising interval for connectable undirected and connectable directed events in 625us unit...
static const unsigned GAP_ADV_PARAMS_INTERVAL_MIN_NONCON
Minimum Advertising interval for scannable and nonconnectable undirected events in 625us units...
static const unsigned GAP_ADV_PARAMS_TIMEOUT_MAX
Maximum advertising timeout allowed; in seconds.
Device is not connectable and not scannable.
AdvertisingType_t
Encapsulates the peripheral advertising modes.
uint16_t getTimeout(void) const
Get the advertising timeout.
uint16_t getInterval(void) const
Get the advertising interval in milliseconds.
static const unsigned GAP_ADV_PARAMS_INTERVAL_MAX
Maximum Advertising interval in 625us units.
static uint16_t ADVERTISEMENT_DURATION_UNITS_TO_MS(uint16_t gapUnits)
Convert units of 0.625ms to milliseconds.
Device is connectable, scannable and doesn&#39;t expect connection from a specific peer.
static const uint16_t UNIT_0_625_MS
Number of microseconds in 0.625 milliseconds.
enum AdvertisingType_t AdvertisingType
Alias for GapAdvertisingParams::AdvertisingType_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.