Marco Zecchini / Mbed OS Example_RTOS

Rtos API example

mbed-os/features/FEATURE_BLE/ble/GapAdvertisingParams.h@0:9fca2b23d0ba, 2019-02-23 (annotated)

Committer:
marcozecchini
Date:
Sat Feb 23 12:13:36 2019 +0000
Revision:
0:9fca2b23d0ba
final commit

Who changed what in which revision?

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