Alex Cordonnier / BLE_API

High level Bluetooth Low Energy API and radio abstraction layer

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__ */