Microbug / BLE_API

Fork of BLE_API by Bluetooth Low Energy

Committer:
Rohit Grover
Date:
Fri May 23 17:45:16 2014 +0100
Revision:
49:03a51f0006f8
Parent:
48:ec0c28e62abf
Child:
63:653378e782ea
simplify the api for accumulating advertising payload

Who changed what in which revision?

UserRevisionLine numberNew contents of line
ktownsend 29:011e95ce78b8 1 /* mbed Microcontroller Library
ktownsend 29:011e95ce78b8 2 * Copyright (c) 2006-2013 ARM Limited
ktownsend 29:011e95ce78b8 3 *
ktownsend 29:011e95ce78b8 4 * Licensed under the Apache License, Version 2.0 (the "License");
ktownsend 29:011e95ce78b8 5 * you may not use this file except in compliance with the License.
ktownsend 29:011e95ce78b8 6 * You may obtain a copy of the License at
ktownsend 29:011e95ce78b8 7 *
ktownsend 29:011e95ce78b8 8 * http://www.apache.org/licenses/LICENSE-2.0
ktownsend 29:011e95ce78b8 9 *
ktownsend 29:011e95ce78b8 10 * Unless required by applicable law or agreed to in writing, software
ktownsend 29:011e95ce78b8 11 * distributed under the License is distributed on an "AS IS" BASIS,
ktownsend 29:011e95ce78b8 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
ktownsend 29:011e95ce78b8 13 * See the License for the specific language governing permissions and
ktownsend 29:011e95ce78b8 14 * limitations under the License.
ktownsend 29:011e95ce78b8 15 */
Rohit Grover 34:da2ea8cd6216 16
ktownsend 29:011e95ce78b8 17 #ifndef __BLE_DEVICE_H__
ktownsend 29:011e95ce78b8 18 #define __BLE_DEVICE_H__
ktownsend 29:011e95ce78b8 19
ktownsend 29:011e95ce78b8 20 #include "mbed.h"
ktownsend 29:011e95ce78b8 21 #include "blecommon.h"
ktownsend 29:011e95ce78b8 22 #include "hw/Gap.h"
ktownsend 29:011e95ce78b8 23 #include "hw/GattServer.h"
ktownsend 29:011e95ce78b8 24
Rohit Grover 41:7ae5c71cd44c 25 class BLEDeviceInstanceBase; /* forward declaration */
Rohit Grover 41:7ae5c71cd44c 26
Rohit Grover 41:7ae5c71cd44c 27 /**
Rohit Grover 41:7ae5c71cd44c 28 * BLEDevice uses composition to hide an interface object encapsulating the
Rohit Grover 41:7ae5c71cd44c 29 * backend transport.
Rohit Grover 41:7ae5c71cd44c 30 *
Rohit Grover 41:7ae5c71cd44c 31 * The following API is used to create the singleton interface object. An
Rohit Grover 41:7ae5c71cd44c 32 * implementation for this function must be provided by the device-specific
Rohit Grover 41:7ae5c71cd44c 33 * library, otherwise there will be a linker error.
Rohit Grover 41:7ae5c71cd44c 34 */
Rohit Grover 41:7ae5c71cd44c 35 extern BLEDeviceInstanceBase *createBLEDeviceInstance(void);
Rohit Grover 41:7ae5c71cd44c 36
Rohit Grover 41:7ae5c71cd44c 37 /**
Rohit Grover 41:7ae5c71cd44c 38 * The base class used to abstract away BLE capable radio transceivers or SOCs,
Rohit Grover 41:7ae5c71cd44c 39 * to enable this BLE API to work with any radio transparently.
Rohit Grover 41:7ae5c71cd44c 40 */
ktownsend 29:011e95ce78b8 41 class BLEDevice
ktownsend 29:011e95ce78b8 42 {
Rohit Grover 34:da2ea8cd6216 43 public:
Rohit Grover 41:7ae5c71cd44c 44 ble_error_t init();
Rohit Grover 41:7ae5c71cd44c 45 ble_error_t reset(void);
Rohit Grover 35:f3b0c1192cf7 46
Rohit Grover 35:f3b0c1192cf7 47 /* GAP specific APIs */
Rohit Grover 35:f3b0c1192cf7 48 public:
Rohit Grover 37:7e8de07642e0 49 /**
Rohit Grover 37:7e8de07642e0 50 * Set the BTLE MAC address and type.
Rohit Grover 37:7e8de07642e0 51 * @return
Rohit Grover 37:7e8de07642e0 52 */
Rohit Grover 38:02cf26a2a4db 53 ble_error_t setAddress(Gap::addr_type_t type, const uint8_t address[6]);
Rohit Grover 35:f3b0c1192cf7 54
Rohit Grover 46:33d87f468a0d 55 /**
Rohit Grover 46:33d87f468a0d 56 * @param[in] advType
Rohit Grover 46:33d87f468a0d 57 * The GAP advertising mode to use for this device. Valid
Rohit Grover 46:33d87f468a0d 58 * values are defined in AdvertisingType:
Rohit Grover 46:33d87f468a0d 59 *
Rohit Grover 46:33d87f468a0d 60 * \par ADV_NON_CONNECTABLE_UNDIRECTED
Rohit Grover 46:33d87f468a0d 61 * All connections to the peripheral device will be refused.
Rohit Grover 46:33d87f468a0d 62 *
Rohit Grover 46:33d87f468a0d 63 * \par ADV_CONNECTABLE_DIRECTED
Rohit Grover 46:33d87f468a0d 64 * Only connections from a pre-defined central device will be
Rohit Grover 46:33d87f468a0d 65 * accepted.
Rohit Grover 46:33d87f468a0d 66 *
Rohit Grover 46:33d87f468a0d 67 * \par ADV_CONNECTABLE_UNDIRECTED
Rohit Grover 46:33d87f468a0d 68 * Any central device can connect to this peripheral.
Rohit Grover 46:33d87f468a0d 69 *
Rohit Grover 46:33d87f468a0d 70 * \par ADV_SCANNABLE_UNDIRECTED
Rohit Grover 46:33d87f468a0d 71 * Any central device can connect to this peripheral, and
Rohit Grover 46:33d87f468a0d 72 * the secondary Scan Response payload will be included or
Rohit Grover 46:33d87f468a0d 73 * available to central devices.
Rohit Grover 46:33d87f468a0d 74 *
Rohit Grover 46:33d87f468a0d 75 * \par
Rohit Grover 46:33d87f468a0d 76 * See Bluetooth Core Specification 4.0 (Vol. 3), Part C,
Rohit Grover 46:33d87f468a0d 77 * Section 9.3 and Core Specification 4.0 (Vol. 6), Part B,
Rohit Grover 46:33d87f468a0d 78 * Section 2.3.1 for further information on GAP connection
Rohit Grover 46:33d87f468a0d 79 * modes
Rohit Grover 46:33d87f468a0d 80 */
Rohit Grover 46:33d87f468a0d 81 void setAdvertisingType(GapAdvertisingParams::AdvertisingType);
Rohit Grover 46:33d87f468a0d 82
Rohit Grover 46:33d87f468a0d 83 /**
Rohit Grover 46:33d87f468a0d 84 * @param[in] interval
Rohit Grover 46:33d87f468a0d 85 * Advertising interval between 0x0020 and 0x4000 in 0.625ms
Rohit Grover 46:33d87f468a0d 86 * units (20ms to 10.24s). If using non-connectable mode
Rohit Grover 46:33d87f468a0d 87 * (ADV_NON_CONNECTABLE_UNDIRECTED) this min value is
Rohit Grover 46:33d87f468a0d 88 * 0x00A0 (100ms). To reduce the likelihood of collisions, the
Rohit Grover 46:33d87f468a0d 89 * link layer perturbs this interval by a pseudo-random delay
Rohit Grover 46:33d87f468a0d 90 * with a range of 0 ms to 10 ms for each advertising event.
Rohit Grover 46:33d87f468a0d 91 *
Rohit Grover 46:33d87f468a0d 92 * \par
Rohit Grover 46:33d87f468a0d 93 * Decreasing this value will allow central devices to detect
Rohit Grover 46:33d87f468a0d 94 * your peripheral faster at the expense of more power being
Rohit Grover 46:33d87f468a0d 95 * used by the radio due to the higher data transmit rate.
Rohit Grover 46:33d87f468a0d 96 *
Rohit Grover 46:33d87f468a0d 97 * \par
Rohit Grover 46:33d87f468a0d 98 * This field must be set to 0 if connectionMode is equal
Rohit Grover 46:33d87f468a0d 99 * to ADV_CONNECTABLE_DIRECTED
Rohit Grover 46:33d87f468a0d 100 *
Rohit Grover 46:33d87f468a0d 101 * \par
Rohit Grover 46:33d87f468a0d 102 * See Bluetooth Core Specification, Vol 3., Part C,
Rohit Grover 46:33d87f468a0d 103 * Appendix A for suggested advertising intervals.
Rohit Grover 46:33d87f468a0d 104 */
Rohit Grover 46:33d87f468a0d 105 void setAdvertisingInterval(uint16_t interval);
Rohit Grover 46:33d87f468a0d 106
Rohit Grover 46:33d87f468a0d 107 /**
Rohit Grover 46:33d87f468a0d 108 * @param[in] timeout
Rohit Grover 46:33d87f468a0d 109 * Advertising timeout between 0x1 and 0x3FFF (1 and 16383)
Rohit Grover 46:33d87f468a0d 110 * in seconds. Enter 0 to disable the advertising timeout.
Rohit Grover 46:33d87f468a0d 111 */
Rohit Grover 46:33d87f468a0d 112 void setAdvertisingTimeout(uint16_t timeout);
Rohit Grover 46:33d87f468a0d 113
Rohit Grover 46:33d87f468a0d 114 /**
Rohit Grover 46:33d87f468a0d 115 * Please refer to the APIs above.
Rohit Grover 46:33d87f468a0d 116 */
Rohit Grover 46:33d87f468a0d 117 void setAdvertisingParams(const GapAdvertisingParams &advParams);
Rohit Grover 46:33d87f468a0d 118
Rohit Grover 49:03a51f0006f8 119 void clearAdvertisingPayload(void);
Rohit Grover 49:03a51f0006f8 120 ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::Flags flags);
Rohit Grover 49:03a51f0006f8 121 ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::Appearance app);
Rohit Grover 49:03a51f0006f8 122 ble_error_t accumulateAdvertisingPayloadTxPower(int8_t power);
Rohit Grover 49:03a51f0006f8 123 ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::DataType type,
Rohit Grover 49:03a51f0006f8 124 const uint8_t *data,
Rohit Grover 49:03a51f0006f8 125 uint8_t len);
Rohit Grover 49:03a51f0006f8 126
Rohit Grover 46:33d87f468a0d 127 ble_error_t startAdvertising(void);
Rohit Grover 36:9ec94579bb78 128 ble_error_t stopAdvertising(void);
Rohit Grover 46:33d87f468a0d 129
Rohit Grover 36:9ec94579bb78 130 ble_error_t disconnect(void);
Rohit Grover 35:f3b0c1192cf7 131
Rohit Grover 49:03a51f0006f8 132 private:
Rohit Grover 49:03a51f0006f8 133 /**
Rohit Grover 49:03a51f0006f8 134 * Internal helper to udpate the transport backend with advertising data
Rohit Grover 49:03a51f0006f8 135 * before starting to advertise.
Rohit Grover 49:03a51f0006f8 136 */
Rohit Grover 49:03a51f0006f8 137 ble_error_t setAdvertisingDataForTransport(void);
Rohit Grover 49:03a51f0006f8 138
Rohit Grover 41:7ae5c71cd44c 139 public:
Rohit Grover 49:03a51f0006f8 140 BLEDevice() : transport(createBLEDeviceInstance()),
Rohit Grover 49:03a51f0006f8 141 advParams(),
Rohit Grover 49:03a51f0006f8 142 advPayload(),
Rohit Grover 49:03a51f0006f8 143 scanResponse(),
Rohit Grover 49:03a51f0006f8 144 needToUpdateAdvData(true) {
Rohit Grover 49:03a51f0006f8 145 advPayload.clear();
Rohit Grover 49:03a51f0006f8 146 scanResponse.clear();
Rohit Grover 41:7ae5c71cd44c 147 }
Rohit Grover 41:7ae5c71cd44c 148
Rohit Grover 41:7ae5c71cd44c 149 private:
Rohit Grover 49:03a51f0006f8 150 BLEDeviceInstanceBase *const transport; /* the device specific backend */
Rohit Grover 46:33d87f468a0d 151
Rohit Grover 49:03a51f0006f8 152 GapAdvertisingParams advParams;
Rohit Grover 49:03a51f0006f8 153 GapAdvertisingData advPayload;
Rohit Grover 49:03a51f0006f8 154 GapAdvertisingData scanResponse;
Rohit Grover 49:03a51f0006f8 155 bool needToUpdateAdvData; /* Accumulation of AD structures
Rohit Grover 49:03a51f0006f8 156 * in the advertisement payload should eventually
Rohit Grover 49:03a51f0006f8 157 * result in a call to the target's
Rohit Grover 49:03a51f0006f8 158 * setAdvertisingData() before the server begins
Rohit Grover 49:03a51f0006f8 159 * advertising. This flag marks the status of the
Rohit Grover 49:03a51f0006f8 160 * pending update.*/
Rohit Grover 46:33d87f468a0d 161
Rohit Grover 46:33d87f468a0d 162 /**
Rohit Grover 46:33d87f468a0d 163 * DEPRECATED
Rohit Grover 46:33d87f468a0d 164 */
Rohit Grover 46:33d87f468a0d 165 public:
Rohit Grover 48:ec0c28e62abf 166 ble_error_t setAdvertisingData(const GapAdvertisingData &ADStructures,
Rohit Grover 48:ec0c28e62abf 167 const GapAdvertisingData &scanResponse);
Rohit Grover 48:ec0c28e62abf 168 ble_error_t setAdvertisingData(const GapAdvertisingData &ADStructures);
Rohit Grover 48:ec0c28e62abf 169
Rohit Grover 46:33d87f468a0d 170 ble_error_t startAdvertising(const GapAdvertisingParams &advParams);
Rohit Grover 41:7ae5c71cd44c 171 };
Rohit Grover 41:7ae5c71cd44c 172
Rohit Grover 41:7ae5c71cd44c 173 /**
Rohit Grover 41:7ae5c71cd44c 174 * The interface for the transport object to be created by the target library's
Rohit Grover 41:7ae5c71cd44c 175 * createBLEDeviceInstance().
Rohit Grover 41:7ae5c71cd44c 176 */
Rohit Grover 41:7ae5c71cd44c 177 class BLEDeviceInstanceBase
Rohit Grover 41:7ae5c71cd44c 178 {
Rohit Grover 41:7ae5c71cd44c 179 public:
Rohit Grover 34:da2ea8cd6216 180 virtual Gap& getGap() = 0;
Rohit Grover 34:da2ea8cd6216 181 virtual GattServer& getGattServer() = 0;
Rohit Grover 41:7ae5c71cd44c 182 virtual ble_error_t init(void) = 0;
Rohit Grover 41:7ae5c71cd44c 183 virtual ble_error_t reset(void) = 0;
ktownsend 29:011e95ce78b8 184 };
ktownsend 29:011e95ce78b8 185
Rohit Grover 41:7ae5c71cd44c 186
Rohit Grover 41:7ae5c71cd44c 187 /* BLEDevice methods. Most of these simply forward the calls to the underlying
Rohit Grover 41:7ae5c71cd44c 188 * transport.*/
Rohit Grover 41:7ae5c71cd44c 189
Rohit Grover 41:7ae5c71cd44c 190 inline ble_error_t
Rohit Grover 41:7ae5c71cd44c 191 BLEDevice::init() {
Rohit Grover 41:7ae5c71cd44c 192 return transport->init();
Rohit Grover 41:7ae5c71cd44c 193 }
Rohit Grover 41:7ae5c71cd44c 194
Rohit Grover 41:7ae5c71cd44c 195 inline ble_error_t
Rohit Grover 41:7ae5c71cd44c 196 BLEDevice::reset(void) {
Rohit Grover 41:7ae5c71cd44c 197 return transport->reset();
Rohit Grover 41:7ae5c71cd44c 198 }
Rohit Grover 41:7ae5c71cd44c 199
Rohit Grover 39:a57137537521 200 inline ble_error_t
Rohit Grover 39:a57137537521 201 BLEDevice::setAddress(Gap::addr_type_t type, const uint8_t address[6]) {
Rohit Grover 41:7ae5c71cd44c 202 return transport->getGap().setAddress(type, address);
Rohit Grover 36:9ec94579bb78 203 }
Rohit Grover 36:9ec94579bb78 204
Rohit Grover 46:33d87f468a0d 205 inline void
Rohit Grover 46:33d87f468a0d 206 BLEDevice::setAdvertisingType(GapAdvertisingParams::AdvertisingType advType) {
Rohit Grover 46:33d87f468a0d 207 advParams.setAdvertisingType(advType);
Rohit Grover 46:33d87f468a0d 208 }
Rohit Grover 46:33d87f468a0d 209
Rohit Grover 46:33d87f468a0d 210 inline void
Rohit Grover 46:33d87f468a0d 211 BLEDevice::setAdvertisingInterval(uint16_t interval) {
Rohit Grover 46:33d87f468a0d 212 advParams.setInterval(interval);
Rohit Grover 46:33d87f468a0d 213 }
Rohit Grover 46:33d87f468a0d 214
Rohit Grover 46:33d87f468a0d 215 inline void
Rohit Grover 46:33d87f468a0d 216 BLEDevice::setAdvertisingTimeout(uint16_t timeout) {
Rohit Grover 46:33d87f468a0d 217 advParams.setTimeout(timeout);
Rohit Grover 46:33d87f468a0d 218 }
Rohit Grover 46:33d87f468a0d 219
Rohit Grover 46:33d87f468a0d 220 inline void
Rohit Grover 46:33d87f468a0d 221 BLEDevice::setAdvertisingParams(const GapAdvertisingParams &newAdvParams) {
Rohit Grover 46:33d87f468a0d 222 advParams = newAdvParams;
Rohit Grover 46:33d87f468a0d 223 }
Rohit Grover 46:33d87f468a0d 224
Rohit Grover 49:03a51f0006f8 225 inline void
Rohit Grover 49:03a51f0006f8 226 BLEDevice::clearAdvertisingPayload(void) {
Rohit Grover 49:03a51f0006f8 227 needToUpdateAdvData = true;
Rohit Grover 49:03a51f0006f8 228 advPayload.clear();
Rohit Grover 49:03a51f0006f8 229 }
Rohit Grover 49:03a51f0006f8 230
Rohit Grover 49:03a51f0006f8 231 inline ble_error_t
Rohit Grover 49:03a51f0006f8 232 BLEDevice::accumulateAdvertisingPayload(GapAdvertisingData::Flags flags) {
Rohit Grover 49:03a51f0006f8 233 needToUpdateAdvData = true;
Rohit Grover 49:03a51f0006f8 234 return advPayload.addFlags(flags);
Rohit Grover 49:03a51f0006f8 235 }
Rohit Grover 49:03a51f0006f8 236
Rohit Grover 49:03a51f0006f8 237 inline ble_error_t
Rohit Grover 49:03a51f0006f8 238 BLEDevice::accumulateAdvertisingPayload(GapAdvertisingData::Appearance app) {
Rohit Grover 49:03a51f0006f8 239 needToUpdateAdvData = true;
Rohit Grover 49:03a51f0006f8 240 return advPayload.addAppearance(app);
Rohit Grover 49:03a51f0006f8 241 }
Rohit Grover 49:03a51f0006f8 242
Rohit Grover 49:03a51f0006f8 243 inline ble_error_t
Rohit Grover 49:03a51f0006f8 244 BLEDevice::accumulateAdvertisingPayloadTxPower(int8_t txPower) {
Rohit Grover 49:03a51f0006f8 245 needToUpdateAdvData = true;
Rohit Grover 49:03a51f0006f8 246 return advPayload.addTxPower(txPower);
Rohit Grover 49:03a51f0006f8 247 }
Rohit Grover 49:03a51f0006f8 248
Rohit Grover 49:03a51f0006f8 249 inline ble_error_t
Rohit Grover 49:03a51f0006f8 250 BLEDevice::accumulateAdvertisingPayload(GapAdvertisingData::DataType type,
Rohit Grover 49:03a51f0006f8 251 const uint8_t *data,
Rohit Grover 49:03a51f0006f8 252 uint8_t len) {
Rohit Grover 49:03a51f0006f8 253 needToUpdateAdvData = true;
Rohit Grover 49:03a51f0006f8 254 return advPayload.addData(type, data, len);
Rohit Grover 49:03a51f0006f8 255 }
Rohit Grover 49:03a51f0006f8 256
Rohit Grover 39:a57137537521 257 inline ble_error_t
Rohit Grover 46:33d87f468a0d 258 BLEDevice::startAdvertising(void) {
Rohit Grover 49:03a51f0006f8 259 if (needToUpdateAdvData) {
Rohit Grover 49:03a51f0006f8 260 setAdvertisingDataForTransport();
Rohit Grover 49:03a51f0006f8 261 needToUpdateAdvData = false;
Rohit Grover 49:03a51f0006f8 262 }
Rohit Grover 49:03a51f0006f8 263
Rohit Grover 41:7ae5c71cd44c 264 return transport->getGap().startAdvertising(advParams);
Rohit Grover 36:9ec94579bb78 265 }
Rohit Grover 36:9ec94579bb78 266
Rohit Grover 39:a57137537521 267 inline ble_error_t
Rohit Grover 39:a57137537521 268 BLEDevice::stopAdvertising(void) {
Rohit Grover 41:7ae5c71cd44c 269 return transport->getGap().stopAdvertising();
Rohit Grover 36:9ec94579bb78 270 }
Rohit Grover 36:9ec94579bb78 271
Rohit Grover 39:a57137537521 272 inline ble_error_t
Rohit Grover 39:a57137537521 273 BLEDevice::disconnect(void) {
Rohit Grover 41:7ae5c71cd44c 274 return transport->getGap().disconnect();
Rohit Grover 36:9ec94579bb78 275 }
Rohit Grover 36:9ec94579bb78 276
Rohit Grover 49:03a51f0006f8 277 inline ble_error_t
Rohit Grover 49:03a51f0006f8 278 BLEDevice::setAdvertisingDataForTransport(void) {
Rohit Grover 49:03a51f0006f8 279 return transport->getGap().setAdvertisingData(advPayload, scanResponse);
Rohit Grover 49:03a51f0006f8 280 }
Rohit Grover 49:03a51f0006f8 281
Rohit Grover 48:ec0c28e62abf 282 /*
Rohit Grover 48:ec0c28e62abf 283 * ALL OF THE FOLLOWING METHODS ARE DEPRECATED
Rohit Grover 48:ec0c28e62abf 284 */
Rohit Grover 48:ec0c28e62abf 285
Rohit Grover 48:ec0c28e62abf 286 inline ble_error_t
Rohit Grover 48:ec0c28e62abf 287 BLEDevice::setAdvertisingData(const GapAdvertisingData &ADStructures,
Rohit Grover 48:ec0c28e62abf 288 const GapAdvertisingData &scanResponse) {
Rohit Grover 48:ec0c28e62abf 289 return transport->getGap().setAdvertisingData(ADStructures, scanResponse);
Rohit Grover 48:ec0c28e62abf 290 }
Rohit Grover 48:ec0c28e62abf 291
Rohit Grover 48:ec0c28e62abf 292 inline ble_error_t
Rohit Grover 48:ec0c28e62abf 293 BLEDevice::setAdvertisingData(const GapAdvertisingData &ADStructures) {
Rohit Grover 48:ec0c28e62abf 294 GapAdvertisingData scanResponse;
Rohit Grover 48:ec0c28e62abf 295 return transport->getGap().setAdvertisingData(ADStructures, scanResponse);
Rohit Grover 48:ec0c28e62abf 296 }
Rohit Grover 48:ec0c28e62abf 297
Rohit Grover 46:33d87f468a0d 298 inline ble_error_t
Rohit Grover 46:33d87f468a0d 299 BLEDevice::startAdvertising(const GapAdvertisingParams &_advParams) {
Rohit Grover 46:33d87f468a0d 300 return transport->getGap().startAdvertising(_advParams);
Rohit Grover 46:33d87f468a0d 301 }
Rohit Grover 46:33d87f468a0d 302
Rohit Grover 34:da2ea8cd6216 303 #endif // ifndef __BLE_DEVICE_H__