Cataract Gemuese / BLE_API

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.

Fork of BLE_API by Bluetooth Low Energy

ble/GapAdvertisingParams.h@1174:551333f70bc9, 2016-04-06 (annotated)

Committer:
vcoubard
Date:
Wed Apr 06 19:15:21 2016 +0100
Revision:
1174:551333f70bc9
Parent:
1048:efb29faf12fc
Child:
1179:4ab722f8dca0
Synchronized with git rev 7f198461

Author: Andres Amaya Garcia

Add missing docs and fix doxy warnings in GapAdvertisingParams.h

Who changed what in which revision?

UserRevisionLine numberNew contents of line
vcoubard 1174:551333f70bc9 1 /* mbed Microcontroller Library
vcoubard 1174:551333f70bc9 2 * Copyright (c) 2006-2013 ARM Limited
vcoubard 1174:551333f70bc9 3 *
vcoubard 1174:551333f70bc9 4 * Licensed under the Apache License, Version 2.0 (the "License");
vcoubard 1174:551333f70bc9 5 * you may not use this file except in compliance with the License.
vcoubard 1174:551333f70bc9 6 * You may obtain a copy of the License at
vcoubard 1174:551333f70bc9 7 *
vcoubard 1174:551333f70bc9 8 * http://www.apache.org/licenses/LICENSE-2.0
vcoubard 1174:551333f70bc9 9 *
vcoubard 1174:551333f70bc9 10 * Unless required by applicable law or agreed to in writing, software
vcoubard 1174:551333f70bc9 11 * distributed under the License is distributed on an "AS IS" BASIS,
vcoubard 1174:551333f70bc9 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
vcoubard 1174:551333f70bc9 13 * See the License for the specific language governing permissions and
vcoubard 1174:551333f70bc9 14 * limitations under the License.
vcoubard 1174:551333f70bc9 15 */
vcoubard 1174:551333f70bc9 16
vcoubard 1174:551333f70bc9 17 #ifndef __GAP_ADVERTISING_PARAMS_H__
vcoubard 1174:551333f70bc9 18 #define __GAP_ADVERTISING_PARAMS_H__
vcoubard 1174:551333f70bc9 19
vcoubard 1174:551333f70bc9 20 /**
vcoubard 1174:551333f70bc9 21 * This class provides a wrapper for the core advertising parameters,
vcoubard 1174:551333f70bc9 22 * including the advertising type (Connectable Undirected,
vcoubard 1174:551333f70bc9 23 * Non Connectable Undirected and so on), as well as the advertising and
vcoubard 1174:551333f70bc9 24 * timeout intervals.
vcoubard 1174:551333f70bc9 25 */
vcoubard 1174:551333f70bc9 26 class GapAdvertisingParams {
vcoubard 1174:551333f70bc9 27 public:
vcoubard 1174:551333f70bc9 28 /**
vcoubard 1174:551333f70bc9 29 * Minimum Advertising interval for connectable undirected and connectable
vcoubard 1174:551333f70bc9 30 * directed events in 625us units - 20ms.
vcoubard 1174:551333f70bc9 31 */
vcoubard 1174:551333f70bc9 32 static const unsigned GAP_ADV_PARAMS_INTERVAL_MIN = 0x0020;
vcoubard 1174:551333f70bc9 33 /**
vcoubard 1174:551333f70bc9 34 * Minimum Advertising interval for scannable and non-connectable
vcoubard 1174:551333f70bc9 35 * undirected events in 625us units - 100ms.
vcoubard 1174:551333f70bc9 36 */
vcoubard 1174:551333f70bc9 37 static const unsigned GAP_ADV_PARAMS_INTERVAL_MIN_NONCON = 0x00A0;
vcoubard 1174:551333f70bc9 38 /**
vcoubard 1174:551333f70bc9 39 * Maximum Advertising interval in 625us units - 10.24s.
vcoubard 1174:551333f70bc9 40 */
vcoubard 1174:551333f70bc9 41 static const unsigned GAP_ADV_PARAMS_INTERVAL_MAX = 0x4000;
vcoubard 1174:551333f70bc9 42 /**
vcoubard 1174:551333f70bc9 43 * Maximum advertising timeout seconds.
vcoubard 1174:551333f70bc9 44 */
vcoubard 1174:551333f70bc9 45 static const unsigned GAP_ADV_PARAMS_TIMEOUT_MAX = 0x3FFF;
vcoubard 1174:551333f70bc9 46
vcoubard 1174:551333f70bc9 47 /**
vcoubard 1174:551333f70bc9 48 * Encapsulates the peripheral advertising modes, which determine how
vcoubard 1174:551333f70bc9 49 * the device appears to other central devices in hearing range.
vcoubard 1174:551333f70bc9 50 */
vcoubard 1174:551333f70bc9 51 enum AdvertisingType_t {
vcoubard 1174:551333f70bc9 52 ADV_CONNECTABLE_UNDIRECTED, /**< Vol 3, Part C, Section 9.3.4 and Vol 6, Part B, Section 2.3.1.1. */
vcoubard 1174:551333f70bc9 53 ADV_CONNECTABLE_DIRECTED, /**< Vol 3, Part C, Section 9.3.3 and Vol 6, Part B, Section 2.3.1.2. */
vcoubard 1174:551333f70bc9 54 ADV_SCANNABLE_UNDIRECTED, /**< Include support for Scan Response payloads, see Vol 6, Part B, Section 2.3.1.4. */
vcoubard 1174:551333f70bc9 55 ADV_NON_CONNECTABLE_UNDIRECTED /**< Vol 3, Part C, Section 9.3.2 and Vol 6, Part B, Section 2.3.1.3. */
vcoubard 1174:551333f70bc9 56 };
vcoubard 1174:551333f70bc9 57 /**
vcoubard 1174:551333f70bc9 58 * Type alias for GapAdvertisingParams::AdvertisingType_t.
vcoubard 1174:551333f70bc9 59 *
vcoubard 1174:551333f70bc9 60 * @deprecated This type alias will be dropped in future releases.
vcoubard 1174:551333f70bc9 61 */
vcoubard 1174:551333f70bc9 62 typedef enum AdvertisingType_t AdvertisingType;
vcoubard 1174:551333f70bc9 63
vcoubard 1174:551333f70bc9 64 public:
vcoubard 1174:551333f70bc9 65 /**
vcoubard 1174:551333f70bc9 66 * Construct an instance of GapAdvertisingParams.
vcoubard 1174:551333f70bc9 67 *
vcoubard 1174:551333f70bc9 68 * @param[in] advType
vcoubard 1174:551333f70bc9 69 * Type of advertising. Default is
vcoubard 1174:551333f70bc9 70 * GapAdvertisingParams::ADV_CONNECTABLE_UNDIRECTED.
vcoubard 1174:551333f70bc9 71 * @param[in] interval
vcoubard 1174:551333f70bc9 72 * Advertising interval in units of 0.625ms. Default is
vcoubard 1174:551333f70bc9 73 * GapAdvertisingParams::GAP_ADV_PARAMS_INTERVAL_MIN_NONCON.
vcoubard 1174:551333f70bc9 74 * @param[in] timeout
vcoubard 1174:551333f70bc9 75 * Advertising timeout. Default is 0.
vcoubard 1174:551333f70bc9 76 */
vcoubard 1174:551333f70bc9 77 GapAdvertisingParams(AdvertisingType_t advType = ADV_CONNECTABLE_UNDIRECTED,
vcoubard 1174:551333f70bc9 78 uint16_t interval = GAP_ADV_PARAMS_INTERVAL_MIN_NONCON,
vcoubard 1174:551333f70bc9 79 uint16_t timeout = 0) : _advType(advType), _interval(interval), _timeout(timeout) {
vcoubard 1174:551333f70bc9 80 /* Interval checks. */
vcoubard 1174:551333f70bc9 81 if (_advType == ADV_CONNECTABLE_DIRECTED) {
vcoubard 1174:551333f70bc9 82 /* Interval must be 0 in directed connectable mode. */
vcoubard 1174:551333f70bc9 83 _interval = 0;
vcoubard 1174:551333f70bc9 84 } else if (_advType == ADV_NON_CONNECTABLE_UNDIRECTED) {
vcoubard 1174:551333f70bc9 85 /* Min interval is slightly larger than in other modes. */
vcoubard 1174:551333f70bc9 86 if (_interval < GAP_ADV_PARAMS_INTERVAL_MIN_NONCON) {
vcoubard 1174:551333f70bc9 87 _interval = GAP_ADV_PARAMS_INTERVAL_MIN_NONCON;
vcoubard 1174:551333f70bc9 88 }
vcoubard 1174:551333f70bc9 89 if (_interval > GAP_ADV_PARAMS_INTERVAL_MAX) {
vcoubard 1174:551333f70bc9 90 _interval = GAP_ADV_PARAMS_INTERVAL_MAX;
vcoubard 1174:551333f70bc9 91 }
vcoubard 1174:551333f70bc9 92 } else {
vcoubard 1174:551333f70bc9 93 /* Stay within interval limits. */
vcoubard 1174:551333f70bc9 94 if (_interval < GAP_ADV_PARAMS_INTERVAL_MIN) {
vcoubard 1174:551333f70bc9 95 _interval = GAP_ADV_PARAMS_INTERVAL_MIN;
vcoubard 1174:551333f70bc9 96 }
vcoubard 1174:551333f70bc9 97 if (_interval > GAP_ADV_PARAMS_INTERVAL_MAX) {
vcoubard 1174:551333f70bc9 98 _interval = GAP_ADV_PARAMS_INTERVAL_MAX;
vcoubard 1174:551333f70bc9 99 }
vcoubard 1174:551333f70bc9 100 }
vcoubard 1174:551333f70bc9 101
vcoubard 1174:551333f70bc9 102 /* Timeout checks. */
vcoubard 1174:551333f70bc9 103 if (timeout) {
vcoubard 1174:551333f70bc9 104 /* Stay within timeout limits. */
vcoubard 1174:551333f70bc9 105 if (_timeout > GAP_ADV_PARAMS_TIMEOUT_MAX) {
vcoubard 1174:551333f70bc9 106 _timeout = GAP_ADV_PARAMS_TIMEOUT_MAX;
vcoubard 1174:551333f70bc9 107 }
vcoubard 1174:551333f70bc9 108 }
vcoubard 1174:551333f70bc9 109 }
vcoubard 1174:551333f70bc9 110
vcoubard 1174:551333f70bc9 111 static const uint16_t UNIT_0_625_MS = 625; /**< Number of microseconds in 0.625 milliseconds. */
vcoubard 1174:551333f70bc9 112 /**
vcoubard 1174:551333f70bc9 113 * Convert milliseconds to units of 0.625ms.
vcoubard 1174:551333f70bc9 114 *
vcoubard 1174:551333f70bc9 115 * @param[in] durationInMillis
vcoubard 1174:551333f70bc9 116 * The number of milliseconds to convert.
vcoubard 1174:551333f70bc9 117 *
vcoubard 1174:551333f70bc9 118 * @return The value of @p durationInMillis in units of 0.625ms.
vcoubard 1174:551333f70bc9 119 */
vcoubard 1174:551333f70bc9 120 static uint16_t MSEC_TO_ADVERTISEMENT_DURATION_UNITS(uint32_t durationInMillis) {
vcoubard 1174:551333f70bc9 121 return (durationInMillis * 1000) / UNIT_0_625_MS;
vcoubard 1174:551333f70bc9 122 }
vcoubard 1174:551333f70bc9 123 /**
vcoubard 1174:551333f70bc9 124 * Convert units of 0.625ms to milliseconds.
vcoubard 1174:551333f70bc9 125 *
vcoubard 1174:551333f70bc9 126 * @param[in] gapUnits
vcoubard 1174:551333f70bc9 127 * The number of units of 0.625ms to convert.
vcoubard 1174:551333f70bc9 128 *
vcoubard 1174:551333f70bc9 129 * @return The value of @p gapUnits in milliseconds.
vcoubard 1174:551333f70bc9 130 */
vcoubard 1174:551333f70bc9 131 static uint16_t ADVERTISEMENT_DURATION_UNITS_TO_MS(uint16_t gapUnits) {
vcoubard 1174:551333f70bc9 132 return (gapUnits * UNIT_0_625_MS) / 1000;
vcoubard 1174:551333f70bc9 133 }
vcoubard 1174:551333f70bc9 134
vcoubard 1174:551333f70bc9 135 /**
vcoubard 1174:551333f70bc9 136 * Get the advertising type.
vcoubard 1174:551333f70bc9 137 *
vcoubard 1174:551333f70bc9 138 * @return The advertising type.
vcoubard 1174:551333f70bc9 139 */
vcoubard 1174:551333f70bc9 140 AdvertisingType_t getAdvertisingType(void) const {
vcoubard 1174:551333f70bc9 141 return _advType;
vcoubard 1174:551333f70bc9 142 }
vcoubard 1174:551333f70bc9 143
vcoubard 1174:551333f70bc9 144 /**
vcoubard 1174:551333f70bc9 145 * Get the advertising interval in milliseconds.
vcoubard 1174:551333f70bc9 146 *
vcoubard 1174:551333f70bc9 147 * @return The advertisement interval (in milliseconds).
vcoubard 1174:551333f70bc9 148 */
vcoubard 1174:551333f70bc9 149 uint16_t getInterval(void) const {
vcoubard 1174:551333f70bc9 150 return ADVERTISEMENT_DURATION_UNITS_TO_MS(_interval);
vcoubard 1174:551333f70bc9 151 }
vcoubard 1174:551333f70bc9 152
vcoubard 1174:551333f70bc9 153 /**
vcoubard 1174:551333f70bc9 154 * Get the advertisement interval in units of 0.625ms.
vcoubard 1174:551333f70bc9 155 *
vcoubard 1174:551333f70bc9 156 * @return The advertisement interval in advertisement duration units (0.625ms units).
vcoubard 1174:551333f70bc9 157 */
vcoubard 1174:551333f70bc9 158 uint16_t getIntervalInADVUnits(void) const {
vcoubard 1174:551333f70bc9 159 return _interval;
vcoubard 1174:551333f70bc9 160 }
vcoubard 1174:551333f70bc9 161
vcoubard 1174:551333f70bc9 162 /**
vcoubard 1174:551333f70bc9 163 * Get The advertising timeout.
vcoubard 1174:551333f70bc9 164 *
vcoubard 1174:551333f70bc9 165 * @return The advertising timeout (in seconds).
vcoubard 1174:551333f70bc9 166 */
vcoubard 1174:551333f70bc9 167 uint16_t getTimeout(void) const {
vcoubard 1174:551333f70bc9 168 return _timeout;
vcoubard 1174:551333f70bc9 169 }
vcoubard 1174:551333f70bc9 170
vcoubard 1174:551333f70bc9 171 /**
vcoubard 1174:551333f70bc9 172 * Set the advertising type.
vcoubard 1174:551333f70bc9 173 *
vcoubard 1174:551333f70bc9 174 * @param[in] newAdvType
vcoubard 1174:551333f70bc9 175 * The new advertising type.
vcoubard 1174:551333f70bc9 176 */
vcoubard 1174:551333f70bc9 177 void setAdvertisingType(AdvertisingType_t newAdvType) {
vcoubard 1174:551333f70bc9 178 _advType = newAdvType;
vcoubard 1174:551333f70bc9 179 }
vcoubard 1174:551333f70bc9 180
vcoubard 1174:551333f70bc9 181 /**
vcoubard 1174:551333f70bc9 182 * Set the advertising interval in milliseconds.
vcoubard 1174:551333f70bc9 183 *
vcoubard 1174:551333f70bc9 184 * @param[in] newInterval
vcoubard 1174:551333f70bc9 185 * The new advertising interval in milliseconds.
vcoubard 1174:551333f70bc9 186 */
vcoubard 1174:551333f70bc9 187 void setInterval(uint16_t newInterval) {
vcoubard 1174:551333f70bc9 188 _interval = MSEC_TO_ADVERTISEMENT_DURATION_UNITS(newInterval);
vcoubard 1174:551333f70bc9 189 }
vcoubard 1174:551333f70bc9 190
vcoubard 1174:551333f70bc9 191 /**
vcoubard 1174:551333f70bc9 192 * Set the advertising timeout.
vcoubard 1174:551333f70bc9 193 *
vcoubard 1174:551333f70bc9 194 * @param[in] newTimeout
vcoubard 1174:551333f70bc9 195 * The new advertising timeout (in seconds).
vcoubard 1174:551333f70bc9 196 */
vcoubard 1174:551333f70bc9 197 void setTimeout(uint16_t newTimeout) {
vcoubard 1174:551333f70bc9 198 _timeout = newTimeout;
vcoubard 1174:551333f70bc9 199 }
vcoubard 1174:551333f70bc9 200
vcoubard 1174:551333f70bc9 201 private:
vcoubard 1174:551333f70bc9 202 AdvertisingType_t _advType; /**< The advertising type. */
vcoubard 1174:551333f70bc9 203 uint16_t _interval; /**< The advertising interval in ADV duration units (i.e. 0.625ms). */
vcoubard 1174:551333f70bc9 204 uint16_t _timeout; /**< The advertising timeout in seconds. */
vcoubard 1174:551333f70bc9 205 };
vcoubard 1174:551333f70bc9 206
vcoubard 1174:551333f70bc9 207 #endif /* ifndef __GAP_ADVERTISING_PARAMS_H__ */