EL4121 Embedded System / mbed-os

mbed-os

Dependents:   cobaLCDJoyMotor_Thread odometry_omni_3roda_v3 odometry_omni_3roda_v1 odometry_omni_3roda_v2 ... more

features/FEATURE_BLE/ble/GapAdvertisingParams.h@0:b74591d5ab33, 2017-12-11 (annotated)

Committer:
be_bryan
Date:
Mon Dec 11 17:54:04 2017 +0000
Revision:
0:b74591d5ab33
motor ++

Who changed what in which revision?

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