Microbug / 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

hw/BLEDevice.h@48:ec0c28e62abf, 2014-05-23 (annotated)

Committer:
Rohit Grover
Date:
Fri May 23 17:28:44 2014 +0100
Revision:
48:ec0c28e62abf
Parent:
46:33d87f468a0d
Child:
49:03a51f0006f8
mark BLEDevice::setAdvertisingData() as deprecated

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 46:33d87f468a0d 119 ble_error_t startAdvertising(void);
Rohit Grover 36:9ec94579bb78 120 ble_error_t stopAdvertising(void);
Rohit Grover 46:33d87f468a0d 121
Rohit Grover 36:9ec94579bb78 122 ble_error_t disconnect(void);
Rohit Grover 35:f3b0c1192cf7 123
Rohit Grover 41:7ae5c71cd44c 124 public:
Rohit Grover 46:33d87f468a0d 125 BLEDevice() : transport(createBLEDeviceInstance()), advParams() {
Rohit Grover 41:7ae5c71cd44c 126 /* empty */
Rohit Grover 41:7ae5c71cd44c 127 }
Rohit Grover 41:7ae5c71cd44c 128
Rohit Grover 41:7ae5c71cd44c 129 private:
Rohit Grover 46:33d87f468a0d 130 BLEDeviceInstanceBase *transport; /* handle to the device specific backend*/
Rohit Grover 46:33d87f468a0d 131 GapAdvertisingParams advParams;
Rohit Grover 46:33d87f468a0d 132
Rohit Grover 46:33d87f468a0d 133
Rohit Grover 46:33d87f468a0d 134 /**
Rohit Grover 46:33d87f468a0d 135 * DEPRECATED
Rohit Grover 46:33d87f468a0d 136 */
Rohit Grover 46:33d87f468a0d 137 public:
Rohit Grover 48:ec0c28e62abf 138 ble_error_t setAdvertisingData(const GapAdvertisingData &ADStructures,
Rohit Grover 48:ec0c28e62abf 139 const GapAdvertisingData &scanResponse);
Rohit Grover 48:ec0c28e62abf 140 ble_error_t setAdvertisingData(const GapAdvertisingData &ADStructures);
Rohit Grover 48:ec0c28e62abf 141
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 46:33d87f468a0d 177 inline void
Rohit Grover 46:33d87f468a0d 178 BLEDevice::setAdvertisingType(GapAdvertisingParams::AdvertisingType advType) {
Rohit Grover 46:33d87f468a0d 179 advParams.setAdvertisingType(advType);
Rohit Grover 46:33d87f468a0d 180 }
Rohit Grover 46:33d87f468a0d 181
Rohit Grover 46:33d87f468a0d 182 inline void
Rohit Grover 46:33d87f468a0d 183 BLEDevice::setAdvertisingInterval(uint16_t interval) {
Rohit Grover 46:33d87f468a0d 184 advParams.setInterval(interval);
Rohit Grover 46:33d87f468a0d 185 }
Rohit Grover 46:33d87f468a0d 186
Rohit Grover 46:33d87f468a0d 187 inline void
Rohit Grover 46:33d87f468a0d 188 BLEDevice::setAdvertisingTimeout(uint16_t timeout) {
Rohit Grover 46:33d87f468a0d 189 advParams.setTimeout(timeout);
Rohit Grover 46:33d87f468a0d 190 }
Rohit Grover 46:33d87f468a0d 191
Rohit Grover 46:33d87f468a0d 192 inline void
Rohit Grover 46:33d87f468a0d 193 BLEDevice::setAdvertisingParams(const GapAdvertisingParams &newAdvParams) {
Rohit Grover 46:33d87f468a0d 194 advParams = newAdvParams;
Rohit Grover 46:33d87f468a0d 195 }
Rohit Grover 46:33d87f468a0d 196
Rohit Grover 39:a57137537521 197 inline ble_error_t
Rohit Grover 46:33d87f468a0d 198 BLEDevice::startAdvertising(void) {
Rohit Grover 41:7ae5c71cd44c 199 return transport->getGap().startAdvertising(advParams);
Rohit Grover 36:9ec94579bb78 200 }
Rohit Grover 36:9ec94579bb78 201
Rohit Grover 39:a57137537521 202 inline ble_error_t
Rohit Grover 39:a57137537521 203 BLEDevice::stopAdvertising(void) {
Rohit Grover 41:7ae5c71cd44c 204 return transport->getGap().stopAdvertising();
Rohit Grover 36:9ec94579bb78 205 }
Rohit Grover 36:9ec94579bb78 206
Rohit Grover 39:a57137537521 207 inline ble_error_t
Rohit Grover 39:a57137537521 208 BLEDevice::disconnect(void) {
Rohit Grover 41:7ae5c71cd44c 209 return transport->getGap().disconnect();
Rohit Grover 36:9ec94579bb78 210 }
Rohit Grover 36:9ec94579bb78 211
Rohit Grover 48:ec0c28e62abf 212 /*
Rohit Grover 48:ec0c28e62abf 213 * ALL OF THE FOLLOWING METHODS ARE DEPRECATED
Rohit Grover 48:ec0c28e62abf 214 */
Rohit Grover 48:ec0c28e62abf 215
Rohit Grover 48:ec0c28e62abf 216 inline ble_error_t
Rohit Grover 48:ec0c28e62abf 217 BLEDevice::setAdvertisingData(const GapAdvertisingData &ADStructures,
Rohit Grover 48:ec0c28e62abf 218 const GapAdvertisingData &scanResponse) {
Rohit Grover 48:ec0c28e62abf 219 return transport->getGap().setAdvertisingData(ADStructures, scanResponse);
Rohit Grover 48:ec0c28e62abf 220 }
Rohit Grover 48:ec0c28e62abf 221
Rohit Grover 48:ec0c28e62abf 222 inline ble_error_t
Rohit Grover 48:ec0c28e62abf 223 BLEDevice::setAdvertisingData(const GapAdvertisingData &ADStructures) {
Rohit Grover 48:ec0c28e62abf 224 GapAdvertisingData scanResponse;
Rohit Grover 48:ec0c28e62abf 225 return transport->getGap().setAdvertisingData(ADStructures, scanResponse);
Rohit Grover 48:ec0c28e62abf 226 }
Rohit Grover 48:ec0c28e62abf 227
Rohit Grover 46:33d87f468a0d 228 inline ble_error_t
Rohit Grover 46:33d87f468a0d 229 BLEDevice::startAdvertising(const GapAdvertisingParams &_advParams) {
Rohit Grover 46:33d87f468a0d 230 return transport->getGap().startAdvertising(_advParams);
Rohit Grover 46:33d87f468a0d 231 }
Rohit Grover 46:33d87f468a0d 232
Rohit Grover 34:da2ea8cd6216 233 #endif // ifndef __BLE_DEVICE_H__