Simon Cooksey / mbed-os

Pinned to some recent date

features/FEATURE_BLE/ble/GapAdvertisingParams.h@0:fb7af294d5d9, 2016-11-17 (annotated)

Committer:
Simon Cooksey
Date:
Thu Nov 17 16:43:53 2016 +0000
Revision:
0:fb7af294d5d9
Initial commit

Who changed what in which revision?

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