Kenji Arai / mbed-os_TYBLE16

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Dependents:   TYBLE16_simple_data_logger TYBLE16_MP3_Air

features/FEATURE_BLE/ble/GapAdvertisingParams.h@0:5b88d5760320, 2019-12-17 (annotated)

Committer:
kenjiArai
Date:
Tue Dec 17 23:23:45 2019 +0000
Revision:
0:5b88d5760320
mbed-os5 only for TYBLE16

Who changed what in which revision?

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