Wang Xinglu / BLE_API

High level Bluetooth Low Energy API and radio abstraction layer

Dependencies:   nRF51822

Dependents:   LinkNode_LIS3DH

Fork of BLE_API by Bluetooth Low Energy

hw/BLEDevice.h@46:33d87f468a0d, 2014-05-23 (annotated)

Committer:
Rohit Grover
Date:
Fri May 23 15:21:47 2014 +0100
Revision:
46:33d87f468a0d
Parent:
42:06e75fee52cf
Child:
48:ec0c28e62abf
simplification of the API used to setup GAP advertising

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 40:d405c9b1419d 55 ble_error_t setAdvertisingData(const GapAdvertisingData &ADStructures,
Rohit Grover 40:d405c9b1419d 56 const GapAdvertisingData &scanResponse);
Rohit Grover 40:d405c9b1419d 57 ble_error_t setAdvertisingData(const GapAdvertisingData &ADStructures);
Rohit Grover 46:33d87f468a0d 58
Rohit Grover 46:33d87f468a0d 59 /**
Rohit Grover 46:33d87f468a0d 60 * @param[in] advType
Rohit Grover 46:33d87f468a0d 61 * The GAP advertising mode to use for this device. Valid
Rohit Grover 46:33d87f468a0d 62 * values are defined in AdvertisingType:
Rohit Grover 46:33d87f468a0d 63 *
Rohit Grover 46:33d87f468a0d 64 * \par ADV_NON_CONNECTABLE_UNDIRECTED
Rohit Grover 46:33d87f468a0d 65 * All connections to the peripheral device will be refused.
Rohit Grover 46:33d87f468a0d 66 *
Rohit Grover 46:33d87f468a0d 67 * \par ADV_CONNECTABLE_DIRECTED
Rohit Grover 46:33d87f468a0d 68 * Only connections from a pre-defined central device will be
Rohit Grover 46:33d87f468a0d 69 * accepted.
Rohit Grover 46:33d87f468a0d 70 *
Rohit Grover 46:33d87f468a0d 71 * \par ADV_CONNECTABLE_UNDIRECTED
Rohit Grover 46:33d87f468a0d 72 * Any central device can connect to this peripheral.
Rohit Grover 46:33d87f468a0d 73 *
Rohit Grover 46:33d87f468a0d 74 * \par ADV_SCANNABLE_UNDIRECTED
Rohit Grover 46:33d87f468a0d 75 * Any central device can connect to this peripheral, and
Rohit Grover 46:33d87f468a0d 76 * the secondary Scan Response payload will be included or
Rohit Grover 46:33d87f468a0d 77 * available to central devices.
Rohit Grover 46:33d87f468a0d 78 *
Rohit Grover 46:33d87f468a0d 79 * \par
Rohit Grover 46:33d87f468a0d 80 * See Bluetooth Core Specification 4.0 (Vol. 3), Part C,
Rohit Grover 46:33d87f468a0d 81 * Section 9.3 and Core Specification 4.0 (Vol. 6), Part B,
Rohit Grover 46:33d87f468a0d 82 * Section 2.3.1 for further information on GAP connection
Rohit Grover 46:33d87f468a0d 83 * modes
Rohit Grover 46:33d87f468a0d 84 */
Rohit Grover 46:33d87f468a0d 85 void setAdvertisingType(GapAdvertisingParams::AdvertisingType);
Rohit Grover 46:33d87f468a0d 86
Rohit Grover 46:33d87f468a0d 87 /**
Rohit Grover 46:33d87f468a0d 88 * @param[in] interval
Rohit Grover 46:33d87f468a0d 89 * Advertising interval between 0x0020 and 0x4000 in 0.625ms
Rohit Grover 46:33d87f468a0d 90 * units (20ms to 10.24s). If using non-connectable mode
Rohit Grover 46:33d87f468a0d 91 * (ADV_NON_CONNECTABLE_UNDIRECTED) this min value is
Rohit Grover 46:33d87f468a0d 92 * 0x00A0 (100ms). To reduce the likelihood of collisions, the
Rohit Grover 46:33d87f468a0d 93 * link layer perturbs this interval by a pseudo-random delay
Rohit Grover 46:33d87f468a0d 94 * with a range of 0 ms to 10 ms for each advertising event.
Rohit Grover 46:33d87f468a0d 95 *
Rohit Grover 46:33d87f468a0d 96 * \par
Rohit Grover 46:33d87f468a0d 97 * Decreasing this value will allow central devices to detect
Rohit Grover 46:33d87f468a0d 98 * your peripheral faster at the expense of more power being
Rohit Grover 46:33d87f468a0d 99 * used by the radio due to the higher data transmit rate.
Rohit Grover 46:33d87f468a0d 100 *
Rohit Grover 46:33d87f468a0d 101 * \par
Rohit Grover 46:33d87f468a0d 102 * This field must be set to 0 if connectionMode is equal
Rohit Grover 46:33d87f468a0d 103 * to ADV_CONNECTABLE_DIRECTED
Rohit Grover 46:33d87f468a0d 104 *
Rohit Grover 46:33d87f468a0d 105 * \par
Rohit Grover 46:33d87f468a0d 106 * See Bluetooth Core Specification, Vol 3., Part C,
Rohit Grover 46:33d87f468a0d 107 * Appendix A for suggested advertising intervals.
Rohit Grover 46:33d87f468a0d 108 */
Rohit Grover 46:33d87f468a0d 109 void setAdvertisingInterval(uint16_t interval);
Rohit Grover 46:33d87f468a0d 110
Rohit Grover 46:33d87f468a0d 111 /**
Rohit Grover 46:33d87f468a0d 112 * @param[in] timeout
Rohit Grover 46:33d87f468a0d 113 * Advertising timeout between 0x1 and 0x3FFF (1 and 16383)
Rohit Grover 46:33d87f468a0d 114 * in seconds. Enter 0 to disable the advertising timeout.
Rohit Grover 46:33d87f468a0d 115 */
Rohit Grover 46:33d87f468a0d 116 void setAdvertisingTimeout(uint16_t timeout);
Rohit Grover 46:33d87f468a0d 117
Rohit Grover 46:33d87f468a0d 118 /**
Rohit Grover 46:33d87f468a0d 119 * Please refer to the APIs above.
Rohit Grover 46:33d87f468a0d 120 */
Rohit Grover 46:33d87f468a0d 121 void setAdvertisingParams(const GapAdvertisingParams &advParams);
Rohit Grover 46:33d87f468a0d 122
Rohit Grover 46:33d87f468a0d 123 ble_error_t startAdvertising(void);
Rohit Grover 36:9ec94579bb78 124 ble_error_t stopAdvertising(void);
Rohit Grover 46:33d87f468a0d 125
Rohit Grover 36:9ec94579bb78 126 ble_error_t disconnect(void);
Rohit Grover 35:f3b0c1192cf7 127
Rohit Grover 41:7ae5c71cd44c 128 public:
Rohit Grover 46:33d87f468a0d 129 BLEDevice() : transport(createBLEDeviceInstance()), advParams() {
Rohit Grover 41:7ae5c71cd44c 130 /* empty */
Rohit Grover 41:7ae5c71cd44c 131 }
Rohit Grover 41:7ae5c71cd44c 132
Rohit Grover 41:7ae5c71cd44c 133 private:
Rohit Grover 46:33d87f468a0d 134 BLEDeviceInstanceBase *transport; /* handle to the device specific backend*/
Rohit Grover 46:33d87f468a0d 135 GapAdvertisingParams advParams;
Rohit Grover 46:33d87f468a0d 136
Rohit Grover 46:33d87f468a0d 137
Rohit Grover 46:33d87f468a0d 138 /**
Rohit Grover 46:33d87f468a0d 139 * DEPRECATED
Rohit Grover 46:33d87f468a0d 140 */
Rohit Grover 46:33d87f468a0d 141 public:
Rohit Grover 46:33d87f468a0d 142 ble_error_t startAdvertising(const GapAdvertisingParams &advParams);
Rohit Grover 41:7ae5c71cd44c 143 };
Rohit Grover 41:7ae5c71cd44c 144
Rohit Grover 41:7ae5c71cd44c 145 /**
Rohit Grover 41:7ae5c71cd44c 146 * The interface for the transport object to be created by the target library's
Rohit Grover 41:7ae5c71cd44c 147 * createBLEDeviceInstance().
Rohit Grover 41:7ae5c71cd44c 148 */
Rohit Grover 41:7ae5c71cd44c 149 class BLEDeviceInstanceBase
Rohit Grover 41:7ae5c71cd44c 150 {
Rohit Grover 41:7ae5c71cd44c 151 public:
Rohit Grover 34:da2ea8cd6216 152 virtual Gap& getGap() = 0;
Rohit Grover 34:da2ea8cd6216 153 virtual GattServer& getGattServer() = 0;
Rohit Grover 41:7ae5c71cd44c 154 virtual ble_error_t init(void) = 0;
Rohit Grover 41:7ae5c71cd44c 155 virtual ble_error_t reset(void) = 0;
ktownsend 29:011e95ce78b8 156 };
ktownsend 29:011e95ce78b8 157
Rohit Grover 41:7ae5c71cd44c 158
Rohit Grover 41:7ae5c71cd44c 159 /* BLEDevice methods. Most of these simply forward the calls to the underlying
Rohit Grover 41:7ae5c71cd44c 160 * transport.*/
Rohit Grover 41:7ae5c71cd44c 161
Rohit Grover 41:7ae5c71cd44c 162 inline ble_error_t
Rohit Grover 41:7ae5c71cd44c 163 BLEDevice::init() {
Rohit Grover 41:7ae5c71cd44c 164 return transport->init();
Rohit Grover 41:7ae5c71cd44c 165 }
Rohit Grover 41:7ae5c71cd44c 166
Rohit Grover 41:7ae5c71cd44c 167 inline ble_error_t
Rohit Grover 41:7ae5c71cd44c 168 BLEDevice::reset(void) {
Rohit Grover 41:7ae5c71cd44c 169 return transport->reset();
Rohit Grover 41:7ae5c71cd44c 170 }
Rohit Grover 41:7ae5c71cd44c 171
Rohit Grover 39:a57137537521 172 inline ble_error_t
Rohit Grover 39:a57137537521 173 BLEDevice::setAddress(Gap::addr_type_t type, const uint8_t address[6]) {
Rohit Grover 41:7ae5c71cd44c 174 return transport->getGap().setAddress(type, address);
Rohit Grover 36:9ec94579bb78 175 }
Rohit Grover 36:9ec94579bb78 176
Rohit Grover 39:a57137537521 177 inline ble_error_t
Rohit Grover 40:d405c9b1419d 178 BLEDevice::setAdvertisingData(const GapAdvertisingData &ADStructures,
Rohit Grover 40:d405c9b1419d 179 const GapAdvertisingData &scanResponse) {
Rohit Grover 41:7ae5c71cd44c 180 return transport->getGap().setAdvertisingData(ADStructures, scanResponse);
Rohit Grover 36:9ec94579bb78 181 }
Rohit Grover 36:9ec94579bb78 182
Rohit Grover 39:a57137537521 183 inline ble_error_t
Rohit Grover 40:d405c9b1419d 184 BLEDevice::setAdvertisingData(const GapAdvertisingData &ADStructures) {
Rohit Grover 36:9ec94579bb78 185 GapAdvertisingData scanResponse;
Rohit Grover 41:7ae5c71cd44c 186 return transport->getGap().setAdvertisingData(ADStructures, scanResponse);
Rohit Grover 36:9ec94579bb78 187 }
Rohit Grover 36:9ec94579bb78 188
Rohit Grover 46:33d87f468a0d 189 inline void
Rohit Grover 46:33d87f468a0d 190 BLEDevice::setAdvertisingType(GapAdvertisingParams::AdvertisingType advType) {
Rohit Grover 46:33d87f468a0d 191 advParams.setAdvertisingType(advType);
Rohit Grover 46:33d87f468a0d 192 }
Rohit Grover 46:33d87f468a0d 193
Rohit Grover 46:33d87f468a0d 194 inline void
Rohit Grover 46:33d87f468a0d 195 BLEDevice::setAdvertisingInterval(uint16_t interval) {
Rohit Grover 46:33d87f468a0d 196 advParams.setInterval(interval);
Rohit Grover 46:33d87f468a0d 197 }
Rohit Grover 46:33d87f468a0d 198
Rohit Grover 46:33d87f468a0d 199 inline void
Rohit Grover 46:33d87f468a0d 200 BLEDevice::setAdvertisingTimeout(uint16_t timeout) {
Rohit Grover 46:33d87f468a0d 201 advParams.setTimeout(timeout);
Rohit Grover 46:33d87f468a0d 202 }
Rohit Grover 46:33d87f468a0d 203
Rohit Grover 46:33d87f468a0d 204 inline void
Rohit Grover 46:33d87f468a0d 205 BLEDevice::setAdvertisingParams(const GapAdvertisingParams &newAdvParams) {
Rohit Grover 46:33d87f468a0d 206 advParams = newAdvParams;
Rohit Grover 46:33d87f468a0d 207 }
Rohit Grover 46:33d87f468a0d 208
Rohit Grover 39:a57137537521 209 inline ble_error_t
Rohit Grover 46:33d87f468a0d 210 BLEDevice::startAdvertising(void) {
Rohit Grover 41:7ae5c71cd44c 211 return transport->getGap().startAdvertising(advParams);
Rohit Grover 36:9ec94579bb78 212 }
Rohit Grover 36:9ec94579bb78 213
Rohit Grover 39:a57137537521 214 inline ble_error_t
Rohit Grover 39:a57137537521 215 BLEDevice::stopAdvertising(void) {
Rohit Grover 41:7ae5c71cd44c 216 return transport->getGap().stopAdvertising();
Rohit Grover 36:9ec94579bb78 217 }
Rohit Grover 36:9ec94579bb78 218
Rohit Grover 39:a57137537521 219 inline ble_error_t
Rohit Grover 39:a57137537521 220 BLEDevice::disconnect(void) {
Rohit Grover 41:7ae5c71cd44c 221 return transport->getGap().disconnect();
Rohit Grover 36:9ec94579bb78 222 }
Rohit Grover 36:9ec94579bb78 223
Rohit Grover 46:33d87f468a0d 224 /* DEPRECATED */
Rohit Grover 46:33d87f468a0d 225 inline ble_error_t
Rohit Grover 46:33d87f468a0d 226 BLEDevice::startAdvertising(const GapAdvertisingParams &_advParams) {
Rohit Grover 46:33d87f468a0d 227 return transport->getGap().startAdvertising(_advParams);
Rohit Grover 46:33d87f468a0d 228 }
Rohit Grover 46:33d87f468a0d 229
Rohit Grover 34:da2ea8cd6216 230 #endif // ifndef __BLE_DEVICE_H__