Oscar Ariza / BLE_API

BLE

Fork of BLE_API by Bluetooth Low Energy

public/BLE.h@531:00800f9ffbfb, 2015-06-19 (annotated)

Committer:
rgrover1
Date:
Fri Jun 19 15:52:07 2015 +0100
Revision:
531:00800f9ffbfb
Parent:
530:ccfae9d8e56e
Child:
532:bdcd44b03974
Synchronized with git rev 756e86da

Author: Rohit Grover

BLE: move scanningParams to a better location

Who changed what in which revision?

UserRevisionLine numberNew contents of line
rgrover1 529:8d21604fe31d 1 /* mbed Microcontroller Library
rgrover1 529:8d21604fe31d 2 * Copyright (c) 2006-2013 ARM Limited
rgrover1 529:8d21604fe31d 3 *
rgrover1 529:8d21604fe31d 4 * Licensed under the Apache License, Version 2.0 (the "License");
rgrover1 529:8d21604fe31d 5 * you may not use this file except in compliance with the License.
rgrover1 529:8d21604fe31d 6 * You may obtain a copy of the License at
rgrover1 529:8d21604fe31d 7 *
rgrover1 529:8d21604fe31d 8 * http://www.apache.org/licenses/LICENSE-2.0
rgrover1 529:8d21604fe31d 9 *
rgrover1 529:8d21604fe31d 10 * Unless required by applicable law or agreed to in writing, software
rgrover1 529:8d21604fe31d 11 * distributed under the License is distributed on an "AS IS" BASIS,
rgrover1 529:8d21604fe31d 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
rgrover1 529:8d21604fe31d 13 * See the License for the specific language governing permissions and
rgrover1 529:8d21604fe31d 14 * limitations under the License.
rgrover1 529:8d21604fe31d 15 */
rgrover1 529:8d21604fe31d 16
rgrover1 529:8d21604fe31d 17 #ifndef __BLE_H__
rgrover1 529:8d21604fe31d 18 #define __BLE_H__
rgrover1 529:8d21604fe31d 19
rgrover1 529:8d21604fe31d 20 #include "blecommon.h"
rgrover1 529:8d21604fe31d 21 #include "Gap.h"
rgrover1 529:8d21604fe31d 22 #include "GattServer.h"
rgrover1 529:8d21604fe31d 23 #include "GattClient.h"
rgrover1 529:8d21604fe31d 24 #include "BLEInstanceBase.h"
rgrover1 529:8d21604fe31d 25
rgrover1 529:8d21604fe31d 26 #include "GapAdvertisingData.h"
rgrover1 529:8d21604fe31d 27 #include "GapAdvertisingParams.h"
rgrover1 529:8d21604fe31d 28 #include "GapScanningParams.h"
rgrover1 529:8d21604fe31d 29
rgrover1 529:8d21604fe31d 30
rgrover1 529:8d21604fe31d 31 /**
rgrover1 529:8d21604fe31d 32 * The base class used to abstract away BLE capable radio transceivers or SOCs,
rgrover1 529:8d21604fe31d 33 * to enable this BLE API to work with any radio transparently.
rgrover1 529:8d21604fe31d 34 */
rgrover1 529:8d21604fe31d 35 class BLE
rgrover1 529:8d21604fe31d 36 {
rgrover1 529:8d21604fe31d 37 public:
rgrover1 529:8d21604fe31d 38 /**
rgrover1 529:8d21604fe31d 39 * Initialize the BLE controller. This should be called before using
rgrover1 529:8d21604fe31d 40 * anything else in the BLE_API.
rgrover1 529:8d21604fe31d 41 *
rgrover1 529:8d21604fe31d 42 * init() hands control to the underlying BLE module to accomplish
rgrover1 529:8d21604fe31d 43 * initialization. This initialization may tacitly depend on other hardware
rgrover1 529:8d21604fe31d 44 * setup (such as clocks or power-modes) which happens early on during
rgrover1 529:8d21604fe31d 45 * system startup. It may not be safe to call init() from global static
rgrover1 529:8d21604fe31d 46 * context where ordering is compiler specific and can't be guaranteed--it
rgrover1 529:8d21604fe31d 47 * is safe to call BLE::init() from within main().
rgrover1 529:8d21604fe31d 48 */
rgrover1 529:8d21604fe31d 49 ble_error_t init();
rgrover1 529:8d21604fe31d 50
rgrover1 529:8d21604fe31d 51 ble_error_t reset(void);
rgrover1 529:8d21604fe31d 52
rgrover1 529:8d21604fe31d 53 /**
rgrover1 529:8d21604fe31d 54 * Purge the BLE stack of GATT and GAP state. init() must be called afterwards to re-instate services and GAP state.
rgrover1 529:8d21604fe31d 55 */
rgrover1 529:8d21604fe31d 56 ble_error_t shutdown(void);
rgrover1 529:8d21604fe31d 57
rgrover1 530:ccfae9d8e56e 58 const Gap &gap() const {
rgrover1 530:ccfae9d8e56e 59 return transport->getGap();
rgrover1 530:ccfae9d8e56e 60 }
rgrover1 530:ccfae9d8e56e 61 Gap &gap() {
rgrover1 530:ccfae9d8e56e 62 return transport->getGap();
rgrover1 530:ccfae9d8e56e 63 }
rgrover1 530:ccfae9d8e56e 64
rgrover1 529:8d21604fe31d 65 /* GAP specific APIs */
rgrover1 529:8d21604fe31d 66 public:
rgrover1 529:8d21604fe31d 67 /**
rgrover1 529:8d21604fe31d 68 * Set the BTLE MAC address and type.
rgrover1 529:8d21604fe31d 69 * @return BLE_ERROR_NONE on success.
rgrover1 529:8d21604fe31d 70 */
rgrover1 529:8d21604fe31d 71 ble_error_t setAddress(Gap::AddressType_t type, const Gap::Address_t address);
rgrover1 529:8d21604fe31d 72
rgrover1 529:8d21604fe31d 73 /**
rgrover1 529:8d21604fe31d 74 * Fetch the BTLE MAC address and type.
rgrover1 529:8d21604fe31d 75 * @return BLE_ERROR_NONE on success.
rgrover1 529:8d21604fe31d 76 */
rgrover1 529:8d21604fe31d 77 ble_error_t getAddress(Gap::AddressType_t *typeP, Gap::Address_t address);
rgrover1 529:8d21604fe31d 78
rgrover1 529:8d21604fe31d 79 /**
rgrover1 529:8d21604fe31d 80 * @param[in] advType
rgrover1 529:8d21604fe31d 81 * The GAP advertising mode to use for this device. Valid
rgrover1 529:8d21604fe31d 82 * values are defined in AdvertisingType:
rgrover1 529:8d21604fe31d 83 *
rgrover1 529:8d21604fe31d 84 * \par ADV_NON_CONNECTABLE_UNDIRECTED
rgrover1 529:8d21604fe31d 85 * All connections to the peripheral device will be refused.
rgrover1 529:8d21604fe31d 86 *
rgrover1 529:8d21604fe31d 87 * \par ADV_CONNECTABLE_DIRECTED
rgrover1 529:8d21604fe31d 88 * Only connections from a pre-defined central device will be
rgrover1 529:8d21604fe31d 89 * accepted.
rgrover1 529:8d21604fe31d 90 *
rgrover1 529:8d21604fe31d 91 * \par ADV_CONNECTABLE_UNDIRECTED
rgrover1 529:8d21604fe31d 92 * Any central device can connect to this peripheral.
rgrover1 529:8d21604fe31d 93 *
rgrover1 529:8d21604fe31d 94 * \par ADV_SCANNABLE_UNDIRECTED
rgrover1 529:8d21604fe31d 95 * Include support for Scan Response payloads.
rgrover1 529:8d21604fe31d 96 *
rgrover1 529:8d21604fe31d 97 * \par
rgrover1 529:8d21604fe31d 98 * See Bluetooth Core Specification 4.0 (Vol. 3), Part C,
rgrover1 529:8d21604fe31d 99 * Section 9.3 and Core Specification 4.0 (Vol. 6), Part B,
rgrover1 529:8d21604fe31d 100 * Section 2.3.1 for further information on GAP connection
rgrover1 529:8d21604fe31d 101 * modes
rgrover1 529:8d21604fe31d 102 */
rgrover1 529:8d21604fe31d 103 void setAdvertisingType(GapAdvertisingParams::AdvertisingType);
rgrover1 529:8d21604fe31d 104
rgrover1 529:8d21604fe31d 105 /**
rgrover1 529:8d21604fe31d 106 * @param[in] interval
rgrover1 529:8d21604fe31d 107 * Advertising interval in units of milliseconds. Advertising
rgrover1 529:8d21604fe31d 108 * is disabled if interval is 0. If interval is smaller than
rgrover1 529:8d21604fe31d 109 * the minimum supported value, then the minimum supported
rgrover1 529:8d21604fe31d 110 * value is used instead.
rgrover1 529:8d21604fe31d 111 *
rgrover1 529:8d21604fe31d 112 * \par
rgrover1 529:8d21604fe31d 113 * Decreasing this value will allow central devices to detect
rgrover1 529:8d21604fe31d 114 * your peripheral faster at the expense of more power being
rgrover1 529:8d21604fe31d 115 * used by the radio due to the higher data transmit rate.
rgrover1 529:8d21604fe31d 116 *
rgrover1 529:8d21604fe31d 117 * \par
rgrover1 529:8d21604fe31d 118 * This field must be set to 0 if connectionMode is equal
rgrover1 529:8d21604fe31d 119 * to ADV_CONNECTABLE_DIRECTED
rgrover1 529:8d21604fe31d 120 *
rgrover1 529:8d21604fe31d 121 * \par
rgrover1 529:8d21604fe31d 122 * See Bluetooth Core Specification, Vol 3., Part C,
rgrover1 529:8d21604fe31d 123 * Appendix A for suggested advertising intervals.
rgrover1 529:8d21604fe31d 124 *
rgrover1 529:8d21604fe31d 125 * @Note: [WARNING] This API previously used 0.625ms as the unit for its
rgrover1 529:8d21604fe31d 126 * 'interval' argument. That required an explicit conversion from
rgrover1 529:8d21604fe31d 127 * milliseconds using Gap::MSEC_TO_GAP_DURATION_UNITS(). This conversion is
rgrover1 529:8d21604fe31d 128 * no longer required as the new units are milliseconds. Any application
rgrover1 529:8d21604fe31d 129 * code depending on the old semantics would need to be updated accordingly.
rgrover1 529:8d21604fe31d 130 */
rgrover1 529:8d21604fe31d 131 void setAdvertisingInterval(uint16_t interval);
rgrover1 529:8d21604fe31d 132
rgrover1 529:8d21604fe31d 133 /**
rgrover1 529:8d21604fe31d 134 * @return Minimum Advertising interval in milliseconds.
rgrover1 529:8d21604fe31d 135 */
rgrover1 529:8d21604fe31d 136 uint16_t getMinAdvertisingInterval(void) const;
rgrover1 529:8d21604fe31d 137 /**
rgrover1 529:8d21604fe31d 138 * @return Minimum Advertising interval in milliseconds for non connectible mode.
rgrover1 529:8d21604fe31d 139 */
rgrover1 529:8d21604fe31d 140 uint16_t getMinNonConnectableAdvertisingInterval(void) const;
rgrover1 529:8d21604fe31d 141 /**
rgrover1 529:8d21604fe31d 142 * @return Maximum Advertising interval in milliseconds.
rgrover1 529:8d21604fe31d 143 */
rgrover1 529:8d21604fe31d 144 uint16_t getMaxAdvertisingInterval(void) const;
rgrover1 529:8d21604fe31d 145
rgrover1 529:8d21604fe31d 146 /**
rgrover1 529:8d21604fe31d 147 * @param[in] timeout
rgrover1 529:8d21604fe31d 148 * Advertising timeout between 0x1 and 0x3FFF (1 and 16383)
rgrover1 529:8d21604fe31d 149 * in seconds. Enter 0 to disable the advertising timeout.
rgrover1 529:8d21604fe31d 150 */
rgrover1 529:8d21604fe31d 151 void setAdvertisingTimeout(uint16_t timeout);
rgrover1 529:8d21604fe31d 152
rgrover1 529:8d21604fe31d 153 /**
rgrover1 529:8d21604fe31d 154 * Please refer to the APIs above.
rgrover1 529:8d21604fe31d 155 */
rgrover1 529:8d21604fe31d 156 void setAdvertisingParams(const GapAdvertisingParams &advParams);
rgrover1 529:8d21604fe31d 157
rgrover1 529:8d21604fe31d 158 /**
rgrover1 529:8d21604fe31d 159 * @return Read back advertising parameters. Useful for storing and
rgrover1 529:8d21604fe31d 160 * restoring parameters rapidly.
rgrover1 529:8d21604fe31d 161 */
rgrover1 529:8d21604fe31d 162 const GapAdvertisingParams &getAdvertisingParams(void) const;
rgrover1 529:8d21604fe31d 163
rgrover1 529:8d21604fe31d 164 /**
rgrover1 529:8d21604fe31d 165 * This API is typically used as an internal helper to udpate the transport
rgrover1 529:8d21604fe31d 166 * backend with advertising data before starting to advertise. It may also
rgrover1 529:8d21604fe31d 167 * be explicity used to dynamically reset the accumulated advertising
rgrover1 529:8d21604fe31d 168 * payload and scanResponse; to do this, the application can clear and re-
rgrover1 529:8d21604fe31d 169 * accumulate a new advertising payload (and scanResponse) before using this
rgrover1 529:8d21604fe31d 170 * API.
rgrover1 529:8d21604fe31d 171 */
rgrover1 529:8d21604fe31d 172 ble_error_t setAdvertisingPayload(void);
rgrover1 529:8d21604fe31d 173
rgrover1 529:8d21604fe31d 174 /**
rgrover1 529:8d21604fe31d 175 * Set advertising data using object.
rgrover1 529:8d21604fe31d 176 */
rgrover1 529:8d21604fe31d 177 ble_error_t setAdvertisingData(const GapAdvertisingData &advData);
rgrover1 529:8d21604fe31d 178
rgrover1 529:8d21604fe31d 179 /**
rgrover1 529:8d21604fe31d 180 * @return Read back advertising data. Useful for storing and
rgrover1 529:8d21604fe31d 181 * restoring payload.
rgrover1 529:8d21604fe31d 182 */
rgrover1 529:8d21604fe31d 183 const GapAdvertisingData &getAdvertisingData(void) const;
rgrover1 529:8d21604fe31d 184
rgrover1 529:8d21604fe31d 185 /**
rgrover1 529:8d21604fe31d 186 * Reset any advertising payload prepared from prior calls to
rgrover1 529:8d21604fe31d 187 * accumulateAdvertisingPayload().
rgrover1 529:8d21604fe31d 188 *
rgrover1 529:8d21604fe31d 189 * Note: This should be followed by a call to setAdvertisingPayload() or
rgrover1 529:8d21604fe31d 190 * startAdvertising() before the update takes effect.
rgrover1 529:8d21604fe31d 191 */
rgrover1 529:8d21604fe31d 192 void clearAdvertisingPayload(void);
rgrover1 529:8d21604fe31d 193
rgrover1 529:8d21604fe31d 194 /**
rgrover1 529:8d21604fe31d 195 * Accumulate an AD structure in the advertising payload. Please note that
rgrover1 529:8d21604fe31d 196 * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
rgrover1 529:8d21604fe31d 197 * as an additional 31 bytes if the advertising payload proves to be too
rgrover1 529:8d21604fe31d 198 * small.
rgrover1 529:8d21604fe31d 199 *
rgrover1 529:8d21604fe31d 200 * @param flags
rgrover1 529:8d21604fe31d 201 * The flags to be added. Multiple flags may be specified in
rgrover1 529:8d21604fe31d 202 * combination.
rgrover1 529:8d21604fe31d 203 */
rgrover1 529:8d21604fe31d 204 ble_error_t accumulateAdvertisingPayload(uint8_t flags);
rgrover1 529:8d21604fe31d 205
rgrover1 529:8d21604fe31d 206 /**
rgrover1 529:8d21604fe31d 207 * Accumulate an AD structure in the advertising payload. Please note that
rgrover1 529:8d21604fe31d 208 * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
rgrover1 529:8d21604fe31d 209 * as an additional 31 bytes if the advertising payload proves to be too
rgrover1 529:8d21604fe31d 210 * small.
rgrover1 529:8d21604fe31d 211 *
rgrover1 529:8d21604fe31d 212 * @param app
rgrover1 529:8d21604fe31d 213 * The appearance of the peripheral.
rgrover1 529:8d21604fe31d 214 */
rgrover1 529:8d21604fe31d 215 ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::Appearance app);
rgrover1 529:8d21604fe31d 216
rgrover1 529:8d21604fe31d 217 /**
rgrover1 529:8d21604fe31d 218 * Accumulate an AD structure in the advertising payload. Please note that
rgrover1 529:8d21604fe31d 219 * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
rgrover1 529:8d21604fe31d 220 * as an additional 31 bytes if the advertising payload proves to be too
rgrover1 529:8d21604fe31d 221 * small.
rgrover1 529:8d21604fe31d 222 *
rgrover1 529:8d21604fe31d 223 * @param app
rgrover1 529:8d21604fe31d 224 * The max transmit power to be used by the controller. This is
rgrover1 529:8d21604fe31d 225 * only a hint.
rgrover1 529:8d21604fe31d 226 */
rgrover1 529:8d21604fe31d 227 ble_error_t accumulateAdvertisingPayloadTxPower(int8_t power);
rgrover1 529:8d21604fe31d 228
rgrover1 529:8d21604fe31d 229 /**
rgrover1 529:8d21604fe31d 230 * Accumulate a variable length byte-stream as an AD structure in the
rgrover1 529:8d21604fe31d 231 * advertising payload. Please note that the payload is limited to 31 bytes.
rgrover1 529:8d21604fe31d 232 * The SCAN_RESPONSE message may be used as an additional 31 bytes if the
rgrover1 529:8d21604fe31d 233 * advertising payload proves to be too small.
rgrover1 529:8d21604fe31d 234 *
rgrover1 529:8d21604fe31d 235 * @param type The type which describes the variable length data.
rgrover1 529:8d21604fe31d 236 * @param data data bytes.
rgrover1 529:8d21604fe31d 237 * @param len length of data.
rgrover1 529:8d21604fe31d 238 */
rgrover1 529:8d21604fe31d 239 ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len);
rgrover1 529:8d21604fe31d 240
rgrover1 529:8d21604fe31d 241 /**
rgrover1 529:8d21604fe31d 242 * Accumulate a variable length byte-stream as an AD structure in the
rgrover1 529:8d21604fe31d 243 * scanResponse payload.
rgrover1 529:8d21604fe31d 244 *
rgrover1 529:8d21604fe31d 245 * @param type The type which describes the variable length data.
rgrover1 529:8d21604fe31d 246 * @param data data bytes.
rgrover1 529:8d21604fe31d 247 * @param len length of data.
rgrover1 529:8d21604fe31d 248 */
rgrover1 529:8d21604fe31d 249 ble_error_t accumulateScanResponse(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len);
rgrover1 529:8d21604fe31d 250
rgrover1 529:8d21604fe31d 251 /**
rgrover1 529:8d21604fe31d 252 * Reset any scan response prepared from prior calls to
rgrover1 529:8d21604fe31d 253 * accumulateScanResponse().
rgrover1 529:8d21604fe31d 254 *
rgrover1 529:8d21604fe31d 255 * Note: This should be followed by a call to setAdvertisingPayload() or
rgrover1 529:8d21604fe31d 256 * startAdvertising() before the update takes effect.
rgrover1 529:8d21604fe31d 257 */
rgrover1 529:8d21604fe31d 258 void clearScanResponse(void);
rgrover1 529:8d21604fe31d 259
rgrover1 529:8d21604fe31d 260 /**
rgrover1 529:8d21604fe31d 261 * Start advertising (GAP Discoverable, Connectable modes, Broadcast
rgrover1 529:8d21604fe31d 262 * Procedure).
rgrover1 529:8d21604fe31d 263 */
rgrover1 529:8d21604fe31d 264 ble_error_t startAdvertising(void);
rgrover1 529:8d21604fe31d 265
rgrover1 529:8d21604fe31d 266 /**
rgrover1 529:8d21604fe31d 267 * Stop advertising (GAP Discoverable, Connectable modes, Broadcast
rgrover1 529:8d21604fe31d 268 * Procedure).
rgrover1 529:8d21604fe31d 269 */
rgrover1 529:8d21604fe31d 270 ble_error_t stopAdvertising(void);
rgrover1 529:8d21604fe31d 271
rgrover1 529:8d21604fe31d 272 /**
rgrover1 529:8d21604fe31d 273 * Setup parameters for GAP scanning--i.e. observer mode.
rgrover1 529:8d21604fe31d 274 * @param interval Scan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s].
rgrover1 529:8d21604fe31d 275 * @param window Scan Window (in milliseconds) [valid values lie between 2.5ms and 10.24s].
rgrover1 529:8d21604fe31d 276 * @param timeout Scan timeout (in seconds) between 0x0001 and 0xFFFF, 0x0000 disables timeout.
rgrover1 529:8d21604fe31d 277 * @param activeScanning Set to True if active-scanning is required. This is used to fetch the
rgrover1 529:8d21604fe31d 278 * scan response from a peer if possible.
rgrover1 529:8d21604fe31d 279 *
rgrover1 529:8d21604fe31d 280 * The scanning window divided by the interval determines the duty cycle for
rgrover1 529:8d21604fe31d 281 * scanning. For example, if the interval is 100ms and the window is 10ms,
rgrover1 529:8d21604fe31d 282 * then the controller will scan for 10 percent of the time. It is possible
rgrover1 529:8d21604fe31d 283 * to have the interval and window set to the same value. In this case,
rgrover1 529:8d21604fe31d 284 * scanning is continuous, with a change of scanning frequency once every
rgrover1 529:8d21604fe31d 285 * interval.
rgrover1 529:8d21604fe31d 286 *
rgrover1 529:8d21604fe31d 287 * Once the scanning parameters have been configured, scanning can be
rgrover1 529:8d21604fe31d 288 * enabled by using startScan().
rgrover1 529:8d21604fe31d 289 *
rgrover1 529:8d21604fe31d 290 * @Note: The scan interval and window are recommendations to the BLE stack.
rgrover1 529:8d21604fe31d 291 */
rgrover1 529:8d21604fe31d 292 ble_error_t setScanParams(uint16_t interval = GapScanningParams::SCAN_INTERVAL_MAX,
rgrover1 529:8d21604fe31d 293 uint16_t window = GapScanningParams::SCAN_WINDOW_MAX,
rgrover1 529:8d21604fe31d 294 uint16_t timeout = 0,
rgrover1 529:8d21604fe31d 295 bool activeScanning = false);
rgrover1 529:8d21604fe31d 296 ble_error_t setScanInterval(uint16_t interval);
rgrover1 529:8d21604fe31d 297 ble_error_t setScanWindow (uint16_t window);
rgrover1 529:8d21604fe31d 298 ble_error_t setScanTimeout (uint16_t timeout);
rgrover1 529:8d21604fe31d 299 void setActiveScan (bool activeScanning);
rgrover1 529:8d21604fe31d 300
rgrover1 529:8d21604fe31d 301 /**
rgrover1 529:8d21604fe31d 302 * Start scanning (Observer Procedure) based on the scan-params currently
rgrover1 529:8d21604fe31d 303 * in effect.
rgrover1 529:8d21604fe31d 304 *
rgrover1 529:8d21604fe31d 305 * @param callback The application callback to be invoked upon receiving
rgrover1 529:8d21604fe31d 306 * every advertisement report. Can be passed in as NULL, in which case
rgrover1 529:8d21604fe31d 307 * scanning may not be enabled at all.
rgrover1 529:8d21604fe31d 308 */
rgrover1 529:8d21604fe31d 309 ble_error_t startScan(void (*callback)(const Gap::AdvertisementCallbackParams_t *params));
rgrover1 529:8d21604fe31d 310
rgrover1 529:8d21604fe31d 311 /**
rgrover1 529:8d21604fe31d 312 * Start scanning (Observer Procedure) based on the scan-params currently
rgrover1 529:8d21604fe31d 313 * in effect.
rgrover1 529:8d21604fe31d 314 *
rgrover1 529:8d21604fe31d 315 * @param[in] object
rgrover1 529:8d21604fe31d 316 * @param[in] callbackMember
rgrover1 529:8d21604fe31d 317 * The above pair of parameters define the callback object
rgrover1 529:8d21604fe31d 318 * and member function to receive the advertisement params.
rgrover1 529:8d21604fe31d 319 */
rgrover1 529:8d21604fe31d 320 template<typename T>
rgrover1 529:8d21604fe31d 321 ble_error_t startScan(T *object, void (T::*memberCallback)(const Gap::AdvertisementCallbackParams_t *params));
rgrover1 529:8d21604fe31d 322
rgrover1 529:8d21604fe31d 323 /**
rgrover1 529:8d21604fe31d 324 * Stop scanning. The current scanning parameters remain in effect.
rgrover1 529:8d21604fe31d 325 *
rgrover1 529:8d21604fe31d 326 * @retval BLE_ERROR_NONE if successfully stopped scanning procedure.
rgrover1 529:8d21604fe31d 327 */
rgrover1 529:8d21604fe31d 328 ble_error_t stopScan(void);
rgrover1 529:8d21604fe31d 329
rgrover1 529:8d21604fe31d 330 /**
rgrover1 529:8d21604fe31d 331 * Create a connection (GAP Link Establishment).
rgrover1 529:8d21604fe31d 332 * @param peerAddr
rgrover1 529:8d21604fe31d 333 * 48-bit address, LSB format.
rgrover1 529:8d21604fe31d 334 * @param peerAddrType
rgrover1 529:8d21604fe31d 335 * Address type of the peer.
rgrover1 529:8d21604fe31d 336 * @param connectionParams
rgrover1 529:8d21604fe31d 337 * Connection parameters.
rgrover1 529:8d21604fe31d 338 * @param scanParams
rgrover1 529:8d21604fe31d 339 * Paramters to be used while scanning for the peer.
rgrover1 529:8d21604fe31d 340 * @return BLE_ERROR_NONE if connection establishment procedure is started
rgrover1 529:8d21604fe31d 341 * successfully. The onConnection callback (if set) will be invoked upon
rgrover1 529:8d21604fe31d 342 * a connection event.
rgrover1 529:8d21604fe31d 343 */
rgrover1 529:8d21604fe31d 344 ble_error_t connect(const Gap::Address_t peerAddr,
rgrover1 529:8d21604fe31d 345 Gap::AddressType_t peerAddrType = Gap::ADDR_TYPE_RANDOM_STATIC,
rgrover1 529:8d21604fe31d 346 const Gap::ConnectionParams_t *connectionParams = NULL,
rgrover1 529:8d21604fe31d 347 const GapScanningParams *scanParams = NULL);
rgrover1 529:8d21604fe31d 348
rgrover1 529:8d21604fe31d 349 /**
rgrover1 529:8d21604fe31d 350 * This call initiates the disconnection procedure, and its completion will
rgrover1 529:8d21604fe31d 351 * be communicated to the application with an invocation of the
rgrover1 529:8d21604fe31d 352 * onDisconnection callback.
rgrover1 529:8d21604fe31d 353 *
rgrover1 529:8d21604fe31d 354 * @param reason
rgrover1 529:8d21604fe31d 355 * The reason for disconnection to be sent back to the peer.
rgrover1 529:8d21604fe31d 356 */
rgrover1 529:8d21604fe31d 357 ble_error_t disconnect(Gap::DisconnectionReason_t reason);
rgrover1 529:8d21604fe31d 358
rgrover1 529:8d21604fe31d 359 /* APIs to set GAP callbacks. */
rgrover1 529:8d21604fe31d 360 void onTimeout(Gap::EventCallback_t timeoutCallback);
rgrover1 529:8d21604fe31d 361
rgrover1 529:8d21604fe31d 362 void onConnection(Gap::ConnectionEventCallback_t connectionCallback);
rgrover1 529:8d21604fe31d 363 /**
rgrover1 529:8d21604fe31d 364 * Used to setup a callback for GAP disconnection.
rgrover1 529:8d21604fe31d 365 */
rgrover1 529:8d21604fe31d 366 void onDisconnection(Gap::DisconnectionEventCallback_t disconnectionCallback);
rgrover1 529:8d21604fe31d 367
rgrover1 529:8d21604fe31d 368 /**
rgrover1 529:8d21604fe31d 369 * Append to a chain of callbacks to be invoked upon disconnection; these
rgrover1 529:8d21604fe31d 370 * callbacks receive no context and are therefore different from the
rgrover1 529:8d21604fe31d 371 * onDisconnection callback.
rgrover1 529:8d21604fe31d 372 */
rgrover1 529:8d21604fe31d 373 template<typename T>
rgrover1 529:8d21604fe31d 374 void addToDisconnectionCallChain(T *tptr, void (T::*mptr)(void));
rgrover1 529:8d21604fe31d 375
rgrover1 529:8d21604fe31d 376 /**
rgrover1 529:8d21604fe31d 377 * Add a callback for the GATT event DATA_SENT (which is triggered when
rgrover1 529:8d21604fe31d 378 * updates are sent out by GATT in the form of notifications).
rgrover1 529:8d21604fe31d 379 *
rgrover1 529:8d21604fe31d 380 * @Note: it is possible to chain together multiple onDataSent callbacks
rgrover1 529:8d21604fe31d 381 * (potentially from different modules of an application) to receive updates
rgrover1 529:8d21604fe31d 382 * to characteristics.
rgrover1 529:8d21604fe31d 383 *
rgrover1 529:8d21604fe31d 384 * @Note: it is also possible to setup a callback into a member function of
rgrover1 529:8d21604fe31d 385 * some object.
rgrover1 529:8d21604fe31d 386 */
rgrover1 529:8d21604fe31d 387 void onDataSent(void (*callback)(unsigned count));
rgrover1 529:8d21604fe31d 388 template <typename T> void onDataSent(T * objPtr, void (T::*memberPtr)(unsigned count));
rgrover1 529:8d21604fe31d 389
rgrover1 529:8d21604fe31d 390 /**
rgrover1 529:8d21604fe31d 391 * Setup a callback for when a characteristic has its value updated by a
rgrover1 529:8d21604fe31d 392 * client.
rgrover1 529:8d21604fe31d 393 *
rgrover1 529:8d21604fe31d 394 * @Note: it is possible to chain together multiple onDataWritten callbacks
rgrover1 529:8d21604fe31d 395 * (potentially from different modules of an application) to receive updates
rgrover1 529:8d21604fe31d 396 * to characteristics. Many services, such as DFU and UART add their own
rgrover1 529:8d21604fe31d 397 * onDataWritten callbacks behind the scenes to trap interesting events.
rgrover1 529:8d21604fe31d 398 *
rgrover1 529:8d21604fe31d 399 * @Note: it is also possible to setup a callback into a member function of
rgrover1 529:8d21604fe31d 400 * some object.
rgrover1 529:8d21604fe31d 401 */
rgrover1 529:8d21604fe31d 402 void onDataWritten(void (*callback)(const GattWriteCallbackParams *eventDataP));
rgrover1 529:8d21604fe31d 403 template <typename T> void onDataWritten(T * objPtr, void (T::*memberPtr)(const GattWriteCallbackParams *context));
rgrover1 529:8d21604fe31d 404
rgrover1 529:8d21604fe31d 405 /**
rgrover1 529:8d21604fe31d 406 * Setup a callback for when a characteristic is being read by a client.
rgrover1 529:8d21604fe31d 407 *
rgrover1 529:8d21604fe31d 408 * @Note: this functionality may not be available on all underlying stacks.
rgrover1 529:8d21604fe31d 409 * You could use GattCharacteristic::setReadAuthorizationCallback() as an
rgrover1 529:8d21604fe31d 410 * alternative.
rgrover1 529:8d21604fe31d 411 *
rgrover1 529:8d21604fe31d 412 * @Note: it is possible to chain together multiple onDataRead callbacks
rgrover1 529:8d21604fe31d 413 * (potentially from different modules of an application) to receive updates
rgrover1 529:8d21604fe31d 414 * to characteristics. Services may add their own onDataRead callbacks
rgrover1 529:8d21604fe31d 415 * behind the scenes to trap interesting events.
rgrover1 529:8d21604fe31d 416 *
rgrover1 529:8d21604fe31d 417 * @Note: it is also possible to setup a callback into a member function of
rgrover1 529:8d21604fe31d 418 * some object.
rgrover1 529:8d21604fe31d 419 *
rgrover1 529:8d21604fe31d 420 * @return BLE_ERROR_NOT_IMPLEMENTED if this functionality isn't available;
rgrover1 529:8d21604fe31d 421 * else BLE_ERROR_NONE.
rgrover1 529:8d21604fe31d 422 */
rgrover1 529:8d21604fe31d 423 ble_error_t onDataRead(void (*callback)(const GattReadCallbackParams *eventDataP));
rgrover1 529:8d21604fe31d 424 template <typename T> ble_error_t onDataRead(T * objPtr, void (T::*memberPtr)(const GattReadCallbackParams *context));
rgrover1 529:8d21604fe31d 425
rgrover1 529:8d21604fe31d 426 void onUpdatesEnabled(GattServer::EventCallback_t callback);
rgrover1 529:8d21604fe31d 427 void onUpdatesDisabled(GattServer::EventCallback_t callback);
rgrover1 529:8d21604fe31d 428 void onConfirmationReceived(GattServer::EventCallback_t callback);
rgrover1 529:8d21604fe31d 429
rgrover1 529:8d21604fe31d 430 /**
rgrover1 529:8d21604fe31d 431 * Radio Notification is a feature that enables ACTIVE and INACTIVE
rgrover1 529:8d21604fe31d 432 * (nACTIVE) signals from the stack that notify the application when the
rgrover1 529:8d21604fe31d 433 * radio is in use. The signal is sent using software interrupt.
rgrover1 529:8d21604fe31d 434 *
rgrover1 529:8d21604fe31d 435 * The ACTIVE signal is sent before the Radio Event starts. The nACTIVE
rgrover1 529:8d21604fe31d 436 * signal is sent at the end of the Radio Event. These signals can be used
rgrover1 529:8d21604fe31d 437 * by the application programmer to synchronize application logic with radio
rgrover1 529:8d21604fe31d 438 * activity. For example, the ACTIVE signal can be used to shut off external
rgrover1 529:8d21604fe31d 439 * devices to manage peak current drawn during periods when the radio is on,
rgrover1 529:8d21604fe31d 440 * or to trigger sensor data collection for transmission in the Radio Event.
rgrover1 529:8d21604fe31d 441 *
rgrover1 529:8d21604fe31d 442 * @param callback
rgrover1 529:8d21604fe31d 443 * The application handler to be invoked in response to a radio
rgrover1 529:8d21604fe31d 444 * ACTIVE/INACTIVE event.
rgrover1 529:8d21604fe31d 445 */
rgrover1 529:8d21604fe31d 446 void onRadioNotification(Gap::RadioNotificationEventCallback_t callback);
rgrover1 529:8d21604fe31d 447
rgrover1 529:8d21604fe31d 448 /**
rgrover1 529:8d21604fe31d 449 * Add a service declaration to the local server ATT table. Also add the
rgrover1 529:8d21604fe31d 450 * characteristics contained within.
rgrover1 529:8d21604fe31d 451 */
rgrover1 529:8d21604fe31d 452 ble_error_t addService(GattService &service);
rgrover1 529:8d21604fe31d 453
rgrover1 529:8d21604fe31d 454 /**
rgrover1 529:8d21604fe31d 455 * Returns the current GAP state of the device using a bitmask which
rgrover1 529:8d21604fe31d 456 * describes whether the device is advertising and/or connected.
rgrover1 529:8d21604fe31d 457 */
rgrover1 529:8d21604fe31d 458 Gap::GapState_t getGapState(void) const;
rgrover1 529:8d21604fe31d 459
rgrover1 529:8d21604fe31d 460 /**
rgrover1 529:8d21604fe31d 461 * @param[in/out] lengthP
rgrover1 529:8d21604fe31d 462 * input: Length in bytes to be read,
rgrover1 529:8d21604fe31d 463 * output: Total length of attribute value upon successful return.
rgrover1 529:8d21604fe31d 464 */
rgrover1 529:8d21604fe31d 465 ble_error_t readCharacteristicValue(GattAttribute::Handle_t attributeHandle, uint8_t *buffer, uint16_t *lengthP);
rgrover1 529:8d21604fe31d 466 /**
rgrover1 529:8d21604fe31d 467 * A version of the same as above with connection handle parameter to allow fetches for connection-specific multivalued attribtues (such as the CCCDs).
rgrover1 529:8d21604fe31d 468 */
rgrover1 529:8d21604fe31d 469 ble_error_t readCharacteristicValue(Gap::Handle_t connectionHandle, GattAttribute::Handle_t attributeHandle, uint8_t *buffer, uint16_t *lengthP);
rgrover1 529:8d21604fe31d 470
rgrover1 529:8d21604fe31d 471 /**
rgrover1 529:8d21604fe31d 472 * @param localOnly
rgrover1 529:8d21604fe31d 473 * Only update the characteristic locally regardless of notify/indicate flags in the CCCD.
rgrover1 529:8d21604fe31d 474 */
rgrover1 529:8d21604fe31d 475 ble_error_t updateCharacteristicValue(GattAttribute::Handle_t attributeHandle, const uint8_t *value, uint16_t size, bool localOnly = false);
rgrover1 529:8d21604fe31d 476 /**
rgrover1 529:8d21604fe31d 477 * A version of the same as above with connection handle parameter to allow updates for connection-specific multivalued attribtues (such as the CCCDs).
rgrover1 529:8d21604fe31d 478 */
rgrover1 529:8d21604fe31d 479 ble_error_t updateCharacteristicValue(Gap::Handle_t connectionHandle,
rgrover1 529:8d21604fe31d 480 GattAttribute::Handle_t attributeHandle,
rgrover1 529:8d21604fe31d 481 const uint8_t *value,
rgrover1 529:8d21604fe31d 482 uint16_t size,
rgrover1 529:8d21604fe31d 483 bool localOnly = false);
rgrover1 529:8d21604fe31d 484
rgrover1 529:8d21604fe31d 485 /**
rgrover1 529:8d21604fe31d 486 * Yield control to the BLE stack or to other tasks waiting for events. This
rgrover1 529:8d21604fe31d 487 * is a sleep function which will return when there is an application
rgrover1 529:8d21604fe31d 488 * specific interrupt, but the MCU might wake up several times before
rgrover1 529:8d21604fe31d 489 * returning (to service the stack). This is not always interchangeable with
rgrover1 529:8d21604fe31d 490 * WFE().
rgrover1 529:8d21604fe31d 491 */
rgrover1 529:8d21604fe31d 492 void waitForEvent(void);
rgrover1 529:8d21604fe31d 493
rgrover1 529:8d21604fe31d 494 ble_error_t getPreferredConnectionParams(Gap::ConnectionParams_t *params);
rgrover1 529:8d21604fe31d 495 ble_error_t setPreferredConnectionParams(const Gap::ConnectionParams_t *params);
rgrover1 529:8d21604fe31d 496 ble_error_t updateConnectionParams(Gap::Handle_t handle, const Gap::ConnectionParams_t *params);
rgrover1 529:8d21604fe31d 497
rgrover1 529:8d21604fe31d 498 /**
rgrover1 529:8d21604fe31d 499 * This call allows the application to get the BLE stack version information.
rgrover1 529:8d21604fe31d 500 *
rgrover1 529:8d21604fe31d 501 * @return A pointer to a const string representing the version.
rgrover1 529:8d21604fe31d 502 * Note: The string is owned by the BLE_API.
rgrover1 529:8d21604fe31d 503 */
rgrover1 529:8d21604fe31d 504 const char *getVersion(void);
rgrover1 529:8d21604fe31d 505
rgrover1 529:8d21604fe31d 506 /**
rgrover1 529:8d21604fe31d 507 * Set the device name characteristic in the GAP service.
rgrover1 529:8d21604fe31d 508 * @param deviceName The new value for the device-name. This is a UTF-8 encoded, <b>NULL-terminated</b> string.
rgrover1 529:8d21604fe31d 509 */
rgrover1 529:8d21604fe31d 510 ble_error_t setDeviceName(const uint8_t *deviceName);
rgrover1 529:8d21604fe31d 511
rgrover1 529:8d21604fe31d 512 /**
rgrover1 529:8d21604fe31d 513 * Get the value of the device name characteristic in the GAP service.
rgrover1 529:8d21604fe31d 514 * @param[out] deviceName Pointer to an empty buffer where the UTF-8 *non NULL-
rgrover1 529:8d21604fe31d 515 * terminated* string will be placed. Set this
rgrover1 529:8d21604fe31d 516 * value to NULL in order to obtain the deviceName-length
rgrover1 529:8d21604fe31d 517 * from the 'length' parameter.
rgrover1 529:8d21604fe31d 518 *
rgrover1 529:8d21604fe31d 519 * @param[in/out] lengthP (on input) Length of the buffer pointed to by deviceName;
rgrover1 529:8d21604fe31d 520 * (on output) the complete device name length (without the
rgrover1 529:8d21604fe31d 521 * null terminator).
rgrover1 529:8d21604fe31d 522 *
rgrover1 529:8d21604fe31d 523 * @note If the device name is longer than the size of the supplied buffer,
rgrover1 529:8d21604fe31d 524 * length will return the complete device name length,
rgrover1 529:8d21604fe31d 525 * and not the number of bytes actually returned in deviceName.
rgrover1 529:8d21604fe31d 526 * The application may use this information to retry with a suitable buffer size.
rgrover1 529:8d21604fe31d 527 *
rgrover1 529:8d21604fe31d 528 * Sample use:
rgrover1 529:8d21604fe31d 529 * uint8_t deviceName[20];
rgrover1 529:8d21604fe31d 530 * unsigned length = sizeof(deviceName);
rgrover1 529:8d21604fe31d 531 * ble.getDeviceName(deviceName, &length);
rgrover1 529:8d21604fe31d 532 * if (length < sizeof(deviceName)) {
rgrover1 529:8d21604fe31d 533 * deviceName[length] = 0;
rgrover1 529:8d21604fe31d 534 * }
rgrover1 529:8d21604fe31d 535 * DEBUG("length: %u, deviceName: %s\r\n", length, deviceName);
rgrover1 529:8d21604fe31d 536 */
rgrover1 529:8d21604fe31d 537 ble_error_t getDeviceName(uint8_t *deviceName, unsigned *lengthP);
rgrover1 529:8d21604fe31d 538
rgrover1 529:8d21604fe31d 539 /**
rgrover1 529:8d21604fe31d 540 * Set the appearance characteristic in the GAP service.
rgrover1 529:8d21604fe31d 541 * @param[in] appearance The new value for the device-appearance.
rgrover1 529:8d21604fe31d 542 */
rgrover1 529:8d21604fe31d 543 ble_error_t setAppearance(uint16_t appearance);
rgrover1 529:8d21604fe31d 544
rgrover1 529:8d21604fe31d 545 /**
rgrover1 529:8d21604fe31d 546 * Set the appearance characteristic in the GAP service.
rgrover1 529:8d21604fe31d 547 * @param[out] appearance The new value for the device-appearance.
rgrover1 529:8d21604fe31d 548 */
rgrover1 529:8d21604fe31d 549 ble_error_t getAppearance(uint16_t *appearanceP);
rgrover1 529:8d21604fe31d 550
rgrover1 529:8d21604fe31d 551 /**
rgrover1 529:8d21604fe31d 552 * Set the radio's transmit power.
rgrover1 529:8d21604fe31d 553 * @param[in] txPower Radio transmit power in dBm.
rgrover1 529:8d21604fe31d 554 */
rgrover1 529:8d21604fe31d 555 ble_error_t setTxPower(int8_t txPower);
rgrover1 529:8d21604fe31d 556
rgrover1 529:8d21604fe31d 557 /**
rgrover1 529:8d21604fe31d 558 * Query the underlying stack for permitted arguments for setTxPower().
rgrover1 529:8d21604fe31d 559 *
rgrover1 529:8d21604fe31d 560 * @param[out] valueArrayPP
rgrover1 529:8d21604fe31d 561 * Out parameter to receive the immutable array of Tx values.
rgrover1 529:8d21604fe31d 562 * @param[out] countP
rgrover1 529:8d21604fe31d 563 * Out parameter to receive the array's size.
rgrover1 529:8d21604fe31d 564 */
rgrover1 529:8d21604fe31d 565 void getPermittedTxPowerValues(const int8_t **valueArrayPP, size_t *countP);
rgrover1 529:8d21604fe31d 566
rgrover1 529:8d21604fe31d 567 /**
rgrover1 529:8d21604fe31d 568 * Enable the BLE stack's Security Manager. The Security Manager implements
rgrover1 529:8d21604fe31d 569 * the actual cryptographic algorithms and protocol exchanges that allow two
rgrover1 529:8d21604fe31d 570 * devices to securely exchange data and privately detect each other.
rgrover1 529:8d21604fe31d 571 * Calling this API is a prerequisite for encryption and pairing (bonding).
rgrover1 529:8d21604fe31d 572 *
rgrover1 529:8d21604fe31d 573 * @param[in] enableBonding Allow for bonding.
rgrover1 529:8d21604fe31d 574 * @param[in] requireMITM Require protection for man-in-the-middle attacks.
rgrover1 529:8d21604fe31d 575 * @param[in] iocaps To specify IO capabilities of this peripheral,
rgrover1 529:8d21604fe31d 576 * such as availability of a display or keyboard to
rgrover1 529:8d21604fe31d 577 * support out-of-band exchanges of security data.
rgrover1 529:8d21604fe31d 578 * @param[in] passkey To specify a static passkey.
rgrover1 529:8d21604fe31d 579 *
rgrover1 529:8d21604fe31d 580 * @return BLE_ERROR_NONE on success.
rgrover1 529:8d21604fe31d 581 */
rgrover1 529:8d21604fe31d 582 ble_error_t initializeSecurity(bool enableBonding = true,
rgrover1 529:8d21604fe31d 583 bool requireMITM = true,
rgrover1 529:8d21604fe31d 584 Gap::SecurityIOCapabilities_t iocaps = Gap::IO_CAPS_NONE,
rgrover1 529:8d21604fe31d 585 const Gap::Passkey_t passkey = NULL);
rgrover1 529:8d21604fe31d 586
rgrover1 529:8d21604fe31d 587 /**
rgrover1 529:8d21604fe31d 588 * Setup a callback for when the security setup procedure (key generation
rgrover1 529:8d21604fe31d 589 * and exchange) for a link has started. This will be skipped for bonded
rgrover1 529:8d21604fe31d 590 * devices. The callback is passed in parameters received from the peer's
rgrover1 529:8d21604fe31d 591 * security request: bool allowBonding, bool requireMITM, and
rgrover1 529:8d21604fe31d 592 * SecurityIOCapabilities_t.
rgrover1 529:8d21604fe31d 593 */
rgrover1 529:8d21604fe31d 594 void onSecuritySetupInitiated(Gap::SecuritySetupInitiatedCallback_t callback);
rgrover1 529:8d21604fe31d 595
rgrover1 529:8d21604fe31d 596 /**
rgrover1 529:8d21604fe31d 597 * Setup a callback for when the security setup procedure (key generation
rgrover1 529:8d21604fe31d 598 * and exchange) for a link has completed. This will be skipped for bonded
rgrover1 529:8d21604fe31d 599 * devices. The callback is passed in the success/failure status of the
rgrover1 529:8d21604fe31d 600 * security setup procedure.
rgrover1 529:8d21604fe31d 601 */
rgrover1 529:8d21604fe31d 602 void onSecuritySetupCompleted(Gap::SecuritySetupCompletedCallback_t callback);
rgrover1 529:8d21604fe31d 603
rgrover1 529:8d21604fe31d 604 /**
rgrover1 529:8d21604fe31d 605 * Setup a callback for when a link with the peer is secured. For bonded
rgrover1 529:8d21604fe31d 606 * devices, subsequent reconnections with bonded peer will result only in
rgrover1 529:8d21604fe31d 607 * this callback when the link is secured and setup procedures will not
rgrover1 529:8d21604fe31d 608 * occur unless the bonding information is either lost or deleted on either
rgrover1 529:8d21604fe31d 609 * or both sides. The callback is passed in a Gap::SecurityMode_t according
rgrover1 529:8d21604fe31d 610 * to the level of security in effect for the secured link.
rgrover1 529:8d21604fe31d 611 */
rgrover1 529:8d21604fe31d 612 void onLinkSecured(Gap::LinkSecuredCallback_t callback);
rgrover1 529:8d21604fe31d 613
rgrover1 529:8d21604fe31d 614 /**
rgrover1 529:8d21604fe31d 615 * Setup a callback for successful bonding; i.e. that link-specific security
rgrover1 529:8d21604fe31d 616 * context is stored persistently for a peer device.
rgrover1 529:8d21604fe31d 617 */
rgrover1 529:8d21604fe31d 618 void onSecurityContextStored(Gap::HandleSpecificEvent_t callback);
rgrover1 529:8d21604fe31d 619
rgrover1 529:8d21604fe31d 620 /**
rgrover1 529:8d21604fe31d 621 * Setup a callback for when the passkey needs to be displayed on a
rgrover1 529:8d21604fe31d 622 * peripheral with DISPLAY capability. This happens when security is
rgrover1 529:8d21604fe31d 623 * configured to prevent Man-In-The-Middle attacks, and a PIN (or passkey)
rgrover1 529:8d21604fe31d 624 * needs to be exchanged between the peers to authenticate the connection
rgrover1 529:8d21604fe31d 625 * attempt.
rgrover1 529:8d21604fe31d 626 */
rgrover1 529:8d21604fe31d 627 void onPasskeyDisplay(Gap::PasskeyDisplayCallback_t callback);
rgrover1 529:8d21604fe31d 628
rgrover1 529:8d21604fe31d 629 /**
rgrover1 529:8d21604fe31d 630 * Get the security status of a connection.
rgrover1 529:8d21604fe31d 631 *
rgrover1 529:8d21604fe31d 632 * @param[in] connectionHandle Handle to identify the connection.
rgrover1 529:8d21604fe31d 633 * @param[out] securityStatusP security status.
rgrover1 529:8d21604fe31d 634 *
rgrover1 529:8d21604fe31d 635 * @return BLE_SUCCESS Or appropriate error code indicating reason for failure.
rgrover1 529:8d21604fe31d 636 */
rgrover1 529:8d21604fe31d 637 ble_error_t getLinkSecurity(Gap::Handle_t connectionHandle, Gap::LinkSecurityStatus_t *securityStatusP);
rgrover1 529:8d21604fe31d 638
rgrover1 529:8d21604fe31d 639 /**
rgrover1 529:8d21604fe31d 640 * Delete all peer device context and all related bonding information from
rgrover1 529:8d21604fe31d 641 * the database within the security manager.
rgrover1 529:8d21604fe31d 642 *
rgrover1 529:8d21604fe31d 643 * @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure.
rgrover1 529:8d21604fe31d 644 * @retval BLE_ERROR_INVALID_STATE If the API is called without module initialization and/or
rgrover1 529:8d21604fe31d 645 * application registration.
rgrover1 529:8d21604fe31d 646 */
rgrover1 529:8d21604fe31d 647 ble_error_t purgeAllBondingState(void);
rgrover1 529:8d21604fe31d 648
rgrover1 529:8d21604fe31d 649 /**
rgrover1 529:8d21604fe31d 650 * Launch service discovery. Once launched, service discovery will remain
rgrover1 529:8d21604fe31d 651 * active with callbacks being issued back into the application for matching
rgrover1 529:8d21604fe31d 652 * services/characteristics. isServiceDiscoveryActive() can be used to
rgrover1 529:8d21604fe31d 653 * determine status; and a termination callback (if setup) will be invoked
rgrover1 529:8d21604fe31d 654 * at the end. Service discovery can be terminated prematurely if needed
rgrover1 529:8d21604fe31d 655 * using terminateServiceDiscovery().
rgrover1 529:8d21604fe31d 656 *
rgrover1 529:8d21604fe31d 657 * @param connectionHandle
rgrover1 529:8d21604fe31d 658 * Handle for the connection with the peer.
rgrover1 529:8d21604fe31d 659 * @param sc
rgrover1 529:8d21604fe31d 660 * This is the application callback for matching service. Taken as
rgrover1 529:8d21604fe31d 661 * NULL by default. Note: service discovery may still be active
rgrover1 529:8d21604fe31d 662 * when this callback is issued; calling asynchronous BLE-stack
rgrover1 529:8d21604fe31d 663 * APIs from within this application callback might cause the
rgrover1 529:8d21604fe31d 664 * stack to abort service discovery. If this becomes an issue, it
rgrover1 529:8d21604fe31d 665 * may be better to make local copy of the discoveredService and
rgrover1 529:8d21604fe31d 666 * wait for service discovery to terminate before operating on the
rgrover1 529:8d21604fe31d 667 * service.
rgrover1 529:8d21604fe31d 668 * @param cc
rgrover1 529:8d21604fe31d 669 * This is the application callback for matching characteristic.
rgrover1 529:8d21604fe31d 670 * Taken as NULL by default. Note: service discovery may still be
rgrover1 529:8d21604fe31d 671 * active when this callback is issued; calling asynchronous
rgrover1 529:8d21604fe31d 672 * BLE-stack APIs from within this application callback might cause
rgrover1 529:8d21604fe31d 673 * the stack to abort service discovery. If this becomes an issue,
rgrover1 529:8d21604fe31d 674 * it may be better to make local copy of the discoveredCharacteristic
rgrover1 529:8d21604fe31d 675 * and wait for service discovery to terminate before operating on the
rgrover1 529:8d21604fe31d 676 * characteristic.
rgrover1 529:8d21604fe31d 677 * @param matchingServiceUUID
rgrover1 529:8d21604fe31d 678 * UUID based filter for specifying a service in which the application is
rgrover1 529:8d21604fe31d 679 * interested. By default it is set as the wildcard UUID_UNKNOWN,
rgrover1 529:8d21604fe31d 680 * in which case it matches all services. If characteristic-UUID
rgrover1 529:8d21604fe31d 681 * filter (below) is set to the wildcard value, then a service
rgrover1 529:8d21604fe31d 682 * callback will be invoked for the matching service (or for every
rgrover1 529:8d21604fe31d 683 * service if the service filter is a wildcard).
rgrover1 529:8d21604fe31d 684 * @param matchingCharacteristicUUIDIn
rgrover1 529:8d21604fe31d 685 * UUID based filter for specifying characteristic in which the application
rgrover1 529:8d21604fe31d 686 * is interested. By default it is set as the wildcard UUID_UKNOWN
rgrover1 529:8d21604fe31d 687 * to match against any characteristic. If both service-UUID
rgrover1 529:8d21604fe31d 688 * filter and characteristic-UUID filter are used with non- wildcard
rgrover1 529:8d21604fe31d 689 * values, then only a single characteristic callback is
rgrover1 529:8d21604fe31d 690 * invoked for the matching characteristic.
rgrover1 529:8d21604fe31d 691 *
rgrover1 529:8d21604fe31d 692 * @Note Using wildcard values for both service-UUID and characteristic-
rgrover1 529:8d21604fe31d 693 * UUID will result in complete service discovery--callbacks being
rgrover1 529:8d21604fe31d 694 * called for every service and characteristic.
rgrover1 529:8d21604fe31d 695 *
rgrover1 529:8d21604fe31d 696 * @return
rgrover1 529:8d21604fe31d 697 * BLE_ERROR_NONE if service discovery is launched successfully; else an appropriate error.
rgrover1 529:8d21604fe31d 698 */
rgrover1 529:8d21604fe31d 699 ble_error_t launchServiceDiscovery(Gap::Handle_t connectionHandle,
rgrover1 529:8d21604fe31d 700 ServiceDiscovery::ServiceCallback_t sc = NULL,
rgrover1 529:8d21604fe31d 701 ServiceDiscovery::CharacteristicCallback_t cc = NULL,
rgrover1 529:8d21604fe31d 702 const UUID &matchingServiceUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN),
rgrover1 529:8d21604fe31d 703 const UUID &matchingCharacteristicUUIDIn = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN));
rgrover1 529:8d21604fe31d 704
rgrover1 529:8d21604fe31d 705 /**
rgrover1 529:8d21604fe31d 706 * Setup callback for when serviceDiscovery terminates.
rgrover1 529:8d21604fe31d 707 */
rgrover1 529:8d21604fe31d 708 void onServiceDiscoveryTermination(ServiceDiscovery::TerminationCallback_t callback);
rgrover1 529:8d21604fe31d 709
rgrover1 529:8d21604fe31d 710 /**
rgrover1 529:8d21604fe31d 711 * Is service-discovery currently active?
rgrover1 529:8d21604fe31d 712 */
rgrover1 529:8d21604fe31d 713 bool isServiceDiscoveryActive(void);
rgrover1 529:8d21604fe31d 714
rgrover1 529:8d21604fe31d 715 /**
rgrover1 529:8d21604fe31d 716 * Terminate an ongoing service-discovery. This should result in an
rgrover1 529:8d21604fe31d 717 * invocation of the TerminationCallback if service-discovery is active.
rgrover1 529:8d21604fe31d 718 */
rgrover1 529:8d21604fe31d 719 void terminateServiceDiscovery(void);
rgrover1 529:8d21604fe31d 720
rgrover1 529:8d21604fe31d 721 public:
rgrover1 531:00800f9ffbfb 722 BLE() : transport(createBLEInstance()), advParams(), advPayload(), scanningParams(), scanResponse(), needToSetAdvPayload(true) {
rgrover1 529:8d21604fe31d 723 advPayload.clear();
rgrover1 529:8d21604fe31d 724 scanResponse.clear();
rgrover1 529:8d21604fe31d 725 }
rgrover1 529:8d21604fe31d 726
rgrover1 529:8d21604fe31d 727 private:
rgrover1 529:8d21604fe31d 728 BLEInstanceBase *const transport; /* the device specific backend */
rgrover1 529:8d21604fe31d 729
rgrover1 529:8d21604fe31d 730 GapAdvertisingParams advParams;
rgrover1 529:8d21604fe31d 731 GapAdvertisingData advPayload;
rgrover1 531:00800f9ffbfb 732 GapScanningParams scanningParams;
rgrover1 529:8d21604fe31d 733 GapAdvertisingData scanResponse;
rgrover1 529:8d21604fe31d 734
rgrover1 529:8d21604fe31d 735 /* Accumulation of AD structures in the advertisement payload should
rgrover1 529:8d21604fe31d 736 * eventually result in a call to the target's setAdvertisingData() before
rgrover1 529:8d21604fe31d 737 * the server begins advertising. This flag marks the status of the pending update.*/
rgrover1 529:8d21604fe31d 738 bool needToSetAdvPayload;
rgrover1 529:8d21604fe31d 739 };
rgrover1 529:8d21604fe31d 740
rgrover1 529:8d21604fe31d 741 typedef BLE BLEDevice; /* DEPRECATED. This type alias is retained for the sake of compatibilty with older
rgrover1 529:8d21604fe31d 742 * code. Will be dropped at some point soon.*/
rgrover1 529:8d21604fe31d 743
rgrover1 529:8d21604fe31d 744 /* BLE methods. Most of these simply forward the calls to the underlying
rgrover1 529:8d21604fe31d 745 * transport.*/
rgrover1 529:8d21604fe31d 746
rgrover1 529:8d21604fe31d 747 inline ble_error_t
rgrover1 529:8d21604fe31d 748 BLE::reset(void)
rgrover1 529:8d21604fe31d 749 {
rgrover1 529:8d21604fe31d 750 return transport->reset();
rgrover1 529:8d21604fe31d 751 }
rgrover1 529:8d21604fe31d 752
rgrover1 529:8d21604fe31d 753 inline ble_error_t
rgrover1 529:8d21604fe31d 754 BLE::shutdown(void)
rgrover1 529:8d21604fe31d 755 {
rgrover1 529:8d21604fe31d 756 clearAdvertisingPayload();
rgrover1 529:8d21604fe31d 757 return transport->shutdown();
rgrover1 529:8d21604fe31d 758 }
rgrover1 529:8d21604fe31d 759
rgrover1 529:8d21604fe31d 760 inline ble_error_t
rgrover1 529:8d21604fe31d 761 BLE::setAddress(Gap::AddressType_t type, const Gap::Address_t address)
rgrover1 529:8d21604fe31d 762 {
rgrover1 529:8d21604fe31d 763 return transport->getGap().setAddress(type, address);
rgrover1 529:8d21604fe31d 764 }
rgrover1 529:8d21604fe31d 765
rgrover1 529:8d21604fe31d 766 inline ble_error_t
rgrover1 529:8d21604fe31d 767 BLE::getAddress(Gap::AddressType_t *typeP, Gap::Address_t address)
rgrover1 529:8d21604fe31d 768 {
rgrover1 529:8d21604fe31d 769 return transport->getGap().getAddress(typeP, address);
rgrover1 529:8d21604fe31d 770 }
rgrover1 529:8d21604fe31d 771
rgrover1 529:8d21604fe31d 772 inline void
rgrover1 529:8d21604fe31d 773 BLE::setAdvertisingType(GapAdvertisingParams::AdvertisingType advType)
rgrover1 529:8d21604fe31d 774 {
rgrover1 529:8d21604fe31d 775 advParams.setAdvertisingType(advType);
rgrover1 529:8d21604fe31d 776 }
rgrover1 529:8d21604fe31d 777
rgrover1 529:8d21604fe31d 778 inline void
rgrover1 529:8d21604fe31d 779 BLE::setAdvertisingInterval(uint16_t interval)
rgrover1 529:8d21604fe31d 780 {
rgrover1 529:8d21604fe31d 781 if (interval == 0) {
rgrover1 529:8d21604fe31d 782 stopAdvertising();
rgrover1 529:8d21604fe31d 783 } else if (interval < getMinAdvertisingInterval()) {
rgrover1 529:8d21604fe31d 784 interval = getMinAdvertisingInterval();
rgrover1 529:8d21604fe31d 785 }
rgrover1 529:8d21604fe31d 786 advParams.setInterval(Gap::MSEC_TO_ADVERTISEMENT_DURATION_UNITS(interval));
rgrover1 529:8d21604fe31d 787 }
rgrover1 529:8d21604fe31d 788
rgrover1 529:8d21604fe31d 789 inline uint16_t
rgrover1 529:8d21604fe31d 790 BLE::getMinAdvertisingInterval(void) const {
rgrover1 529:8d21604fe31d 791 return transport->getGap().getMinAdvertisingInterval();
rgrover1 529:8d21604fe31d 792 }
rgrover1 529:8d21604fe31d 793
rgrover1 529:8d21604fe31d 794 inline uint16_t
rgrover1 529:8d21604fe31d 795 BLE::getMinNonConnectableAdvertisingInterval(void) const {
rgrover1 529:8d21604fe31d 796 return transport->getGap().getMinNonConnectableAdvertisingInterval();
rgrover1 529:8d21604fe31d 797 }
rgrover1 529:8d21604fe31d 798
rgrover1 529:8d21604fe31d 799 inline uint16_t
rgrover1 529:8d21604fe31d 800 BLE::getMaxAdvertisingInterval(void) const {
rgrover1 529:8d21604fe31d 801 return transport->getGap().getMaxAdvertisingInterval();
rgrover1 529:8d21604fe31d 802 }
rgrover1 529:8d21604fe31d 803
rgrover1 529:8d21604fe31d 804 inline void
rgrover1 529:8d21604fe31d 805 BLE::setAdvertisingTimeout(uint16_t timeout)
rgrover1 529:8d21604fe31d 806 {
rgrover1 529:8d21604fe31d 807 advParams.setTimeout(timeout);
rgrover1 529:8d21604fe31d 808 }
rgrover1 529:8d21604fe31d 809
rgrover1 529:8d21604fe31d 810 inline void
rgrover1 529:8d21604fe31d 811 BLE::setAdvertisingParams(const GapAdvertisingParams &newAdvParams)
rgrover1 529:8d21604fe31d 812 {
rgrover1 529:8d21604fe31d 813 advParams = newAdvParams;
rgrover1 529:8d21604fe31d 814 }
rgrover1 529:8d21604fe31d 815
rgrover1 529:8d21604fe31d 816 inline const GapAdvertisingParams &
rgrover1 529:8d21604fe31d 817 BLE::getAdvertisingParams(void) const
rgrover1 529:8d21604fe31d 818 {
rgrover1 529:8d21604fe31d 819 return advParams;
rgrover1 529:8d21604fe31d 820 }
rgrover1 529:8d21604fe31d 821
rgrover1 529:8d21604fe31d 822 inline void
rgrover1 529:8d21604fe31d 823 BLE::clearAdvertisingPayload(void)
rgrover1 529:8d21604fe31d 824 {
rgrover1 529:8d21604fe31d 825 needToSetAdvPayload = true;
rgrover1 529:8d21604fe31d 826 advPayload.clear();
rgrover1 529:8d21604fe31d 827 }
rgrover1 529:8d21604fe31d 828
rgrover1 529:8d21604fe31d 829 inline ble_error_t
rgrover1 529:8d21604fe31d 830 BLE::accumulateAdvertisingPayload(uint8_t flags)
rgrover1 529:8d21604fe31d 831 {
rgrover1 529:8d21604fe31d 832 needToSetAdvPayload = true;
rgrover1 529:8d21604fe31d 833 return advPayload.addFlags(flags);
rgrover1 529:8d21604fe31d 834 }
rgrover1 529:8d21604fe31d 835
rgrover1 529:8d21604fe31d 836 inline ble_error_t
rgrover1 529:8d21604fe31d 837 BLE::accumulateAdvertisingPayload(GapAdvertisingData::Appearance app)
rgrover1 529:8d21604fe31d 838 {
rgrover1 529:8d21604fe31d 839 needToSetAdvPayload = true;
rgrover1 529:8d21604fe31d 840 transport->getGap().setAppearance(app);
rgrover1 529:8d21604fe31d 841 return advPayload.addAppearance(app);
rgrover1 529:8d21604fe31d 842 }
rgrover1 529:8d21604fe31d 843
rgrover1 529:8d21604fe31d 844 inline ble_error_t
rgrover1 529:8d21604fe31d 845 BLE::accumulateAdvertisingPayloadTxPower(int8_t txPower)
rgrover1 529:8d21604fe31d 846 {
rgrover1 529:8d21604fe31d 847 needToSetAdvPayload = true;
rgrover1 529:8d21604fe31d 848 return advPayload.addTxPower(txPower);
rgrover1 529:8d21604fe31d 849 }
rgrover1 529:8d21604fe31d 850
rgrover1 529:8d21604fe31d 851 inline ble_error_t
rgrover1 529:8d21604fe31d 852 BLE::accumulateAdvertisingPayload(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len)
rgrover1 529:8d21604fe31d 853 {
rgrover1 529:8d21604fe31d 854 needToSetAdvPayload = true;
rgrover1 529:8d21604fe31d 855 if (type == GapAdvertisingData::COMPLETE_LOCAL_NAME) {
rgrover1 529:8d21604fe31d 856 transport->getGap().setDeviceName(data);
rgrover1 529:8d21604fe31d 857 }
rgrover1 529:8d21604fe31d 858 return advPayload.addData(type, data, len);
rgrover1 529:8d21604fe31d 859 }
rgrover1 529:8d21604fe31d 860
rgrover1 529:8d21604fe31d 861 inline ble_error_t
rgrover1 529:8d21604fe31d 862 BLE::accumulateScanResponse(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len)
rgrover1 529:8d21604fe31d 863 {
rgrover1 529:8d21604fe31d 864 needToSetAdvPayload = true;
rgrover1 529:8d21604fe31d 865 return scanResponse.addData(type, data, len);
rgrover1 529:8d21604fe31d 866 }
rgrover1 529:8d21604fe31d 867
rgrover1 529:8d21604fe31d 868 inline void
rgrover1 529:8d21604fe31d 869 BLE::clearScanResponse(void)
rgrover1 529:8d21604fe31d 870 {
rgrover1 529:8d21604fe31d 871 needToSetAdvPayload = true;
rgrover1 529:8d21604fe31d 872 scanResponse.clear();
rgrover1 529:8d21604fe31d 873 }
rgrover1 529:8d21604fe31d 874
rgrover1 529:8d21604fe31d 875 inline ble_error_t
rgrover1 529:8d21604fe31d 876 BLE::setAdvertisingPayload(void) {
rgrover1 529:8d21604fe31d 877 needToSetAdvPayload = false;
rgrover1 529:8d21604fe31d 878 return transport->getGap().setAdvertisingData(advPayload, scanResponse);
rgrover1 529:8d21604fe31d 879 }
rgrover1 529:8d21604fe31d 880
rgrover1 529:8d21604fe31d 881 inline ble_error_t
rgrover1 529:8d21604fe31d 882 BLE::setAdvertisingData(const GapAdvertisingData& newPayload)
rgrover1 529:8d21604fe31d 883 {
rgrover1 529:8d21604fe31d 884 advPayload = newPayload;
rgrover1 529:8d21604fe31d 885
rgrover1 529:8d21604fe31d 886 return setAdvertisingPayload();
rgrover1 529:8d21604fe31d 887 }
rgrover1 529:8d21604fe31d 888
rgrover1 529:8d21604fe31d 889 inline const GapAdvertisingData &
rgrover1 529:8d21604fe31d 890 BLE::getAdvertisingData(void) const {
rgrover1 529:8d21604fe31d 891 return advPayload;
rgrover1 529:8d21604fe31d 892 }
rgrover1 529:8d21604fe31d 893
rgrover1 529:8d21604fe31d 894 inline ble_error_t
rgrover1 529:8d21604fe31d 895 BLE::startAdvertising(void)
rgrover1 529:8d21604fe31d 896 {
rgrover1 529:8d21604fe31d 897 ble_error_t rc;
rgrover1 529:8d21604fe31d 898 if ((rc = transport->getGattServer().initializeGATTDatabase()) != BLE_ERROR_NONE) {
rgrover1 529:8d21604fe31d 899 return rc;
rgrover1 529:8d21604fe31d 900 }
rgrover1 529:8d21604fe31d 901 if (needToSetAdvPayload) {
rgrover1 529:8d21604fe31d 902 if ((rc = setAdvertisingPayload()) != BLE_ERROR_NONE) {
rgrover1 529:8d21604fe31d 903 return rc;
rgrover1 529:8d21604fe31d 904 }
rgrover1 529:8d21604fe31d 905 }
rgrover1 529:8d21604fe31d 906
rgrover1 529:8d21604fe31d 907 return transport->getGap().startAdvertising(advParams);
rgrover1 529:8d21604fe31d 908 }
rgrover1 529:8d21604fe31d 909
rgrover1 529:8d21604fe31d 910 inline ble_error_t
rgrover1 529:8d21604fe31d 911 BLE::stopAdvertising(void)
rgrover1 529:8d21604fe31d 912 {
rgrover1 529:8d21604fe31d 913 return transport->getGap().stopAdvertising();
rgrover1 529:8d21604fe31d 914 }
rgrover1 529:8d21604fe31d 915
rgrover1 529:8d21604fe31d 916 inline ble_error_t
rgrover1 529:8d21604fe31d 917 BLE::setScanParams(uint16_t interval, uint16_t window, uint16_t timeout, bool activeScanning) {
rgrover1 529:8d21604fe31d 918 ble_error_t rc;
rgrover1 529:8d21604fe31d 919 if (((rc = scanningParams.setInterval(interval)) == BLE_ERROR_NONE) &&
rgrover1 529:8d21604fe31d 920 ((rc = scanningParams.setWindow(window)) == BLE_ERROR_NONE) &&
rgrover1 529:8d21604fe31d 921 ((rc = scanningParams.setTimeout(timeout)) == BLE_ERROR_NONE)) {
rgrover1 529:8d21604fe31d 922 scanningParams.setActiveScanning(activeScanning);
rgrover1 529:8d21604fe31d 923 return BLE_ERROR_NONE;
rgrover1 529:8d21604fe31d 924 }
rgrover1 529:8d21604fe31d 925
rgrover1 529:8d21604fe31d 926 return rc;
rgrover1 529:8d21604fe31d 927 }
rgrover1 529:8d21604fe31d 928
rgrover1 529:8d21604fe31d 929 inline ble_error_t
rgrover1 529:8d21604fe31d 930 BLE::setScanInterval(uint16_t interval) {
rgrover1 529:8d21604fe31d 931 return scanningParams.setInterval(interval);
rgrover1 529:8d21604fe31d 932 }
rgrover1 529:8d21604fe31d 933
rgrover1 529:8d21604fe31d 934 inline ble_error_t
rgrover1 529:8d21604fe31d 935 BLE::setScanWindow(uint16_t window) {
rgrover1 529:8d21604fe31d 936 return scanningParams.setWindow(window);
rgrover1 529:8d21604fe31d 937 }
rgrover1 529:8d21604fe31d 938
rgrover1 529:8d21604fe31d 939 inline ble_error_t
rgrover1 529:8d21604fe31d 940 BLE::setScanTimeout(uint16_t timeout) {
rgrover1 529:8d21604fe31d 941 return scanningParams.setTimeout(timeout);
rgrover1 529:8d21604fe31d 942 }
rgrover1 529:8d21604fe31d 943
rgrover1 529:8d21604fe31d 944 inline void
rgrover1 529:8d21604fe31d 945 BLE::setActiveScan(bool activeScanning) {
rgrover1 529:8d21604fe31d 946 return scanningParams.setActiveScanning(activeScanning);
rgrover1 529:8d21604fe31d 947 }
rgrover1 529:8d21604fe31d 948
rgrover1 529:8d21604fe31d 949 inline ble_error_t
rgrover1 529:8d21604fe31d 950 BLE::startScan(void (*callback)(const Gap::AdvertisementCallbackParams_t *params)) {
rgrover1 529:8d21604fe31d 951 return transport->getGap().startScan(scanningParams, callback);
rgrover1 529:8d21604fe31d 952 }
rgrover1 529:8d21604fe31d 953
rgrover1 529:8d21604fe31d 954 template<typename T>
rgrover1 529:8d21604fe31d 955 inline ble_error_t
rgrover1 529:8d21604fe31d 956 BLE::startScan(T *object, void (T::*memberCallback)(const Gap::AdvertisementCallbackParams_t *params)) {
rgrover1 529:8d21604fe31d 957 return transport->getGap().startScan(scanningParams, object, memberCallback);
rgrover1 529:8d21604fe31d 958 }
rgrover1 529:8d21604fe31d 959
rgrover1 529:8d21604fe31d 960 inline ble_error_t
rgrover1 529:8d21604fe31d 961 BLE::stopScan(void) {
rgrover1 529:8d21604fe31d 962 return transport->getGap().stopScan();
rgrover1 529:8d21604fe31d 963 }
rgrover1 529:8d21604fe31d 964
rgrover1 529:8d21604fe31d 965 inline ble_error_t
rgrover1 529:8d21604fe31d 966 BLE::connect(const Gap::Address_t peerAddr,
rgrover1 529:8d21604fe31d 967 Gap::AddressType_t peerAddrType,
rgrover1 529:8d21604fe31d 968 const Gap::ConnectionParams_t *connectionParams,
rgrover1 529:8d21604fe31d 969 const GapScanningParams *scanParams) {
rgrover1 529:8d21604fe31d 970 return transport->getGap().connect(peerAddr, peerAddrType, connectionParams, scanParams);
rgrover1 529:8d21604fe31d 971 }
rgrover1 529:8d21604fe31d 972
rgrover1 529:8d21604fe31d 973 inline ble_error_t
rgrover1 529:8d21604fe31d 974 BLE::disconnect(Gap::DisconnectionReason_t reason)
rgrover1 529:8d21604fe31d 975 {
rgrover1 529:8d21604fe31d 976 return transport->getGap().disconnect(reason);
rgrover1 529:8d21604fe31d 977 }
rgrover1 529:8d21604fe31d 978
rgrover1 529:8d21604fe31d 979 inline void
rgrover1 529:8d21604fe31d 980 BLE::onTimeout(Gap::EventCallback_t timeoutCallback)
rgrover1 529:8d21604fe31d 981 {
rgrover1 529:8d21604fe31d 982 transport->getGap().setOnTimeout(timeoutCallback);
rgrover1 529:8d21604fe31d 983 }
rgrover1 529:8d21604fe31d 984
rgrover1 529:8d21604fe31d 985 inline void
rgrover1 529:8d21604fe31d 986 BLE::onConnection(Gap::ConnectionEventCallback_t connectionCallback)
rgrover1 529:8d21604fe31d 987 {
rgrover1 529:8d21604fe31d 988 transport->getGap().setOnConnection(connectionCallback);
rgrover1 529:8d21604fe31d 989 }
rgrover1 529:8d21604fe31d 990
rgrover1 529:8d21604fe31d 991 inline void
rgrover1 529:8d21604fe31d 992 BLE::onDisconnection(Gap::DisconnectionEventCallback_t disconnectionCallback)
rgrover1 529:8d21604fe31d 993 {
rgrover1 529:8d21604fe31d 994 transport->getGap().setOnDisconnection(disconnectionCallback);
rgrover1 529:8d21604fe31d 995 }
rgrover1 529:8d21604fe31d 996
rgrover1 529:8d21604fe31d 997 template<typename T>
rgrover1 529:8d21604fe31d 998 inline void
rgrover1 529:8d21604fe31d 999 BLE::addToDisconnectionCallChain(T *tptr, void (T::*mptr)(void)) {
rgrover1 529:8d21604fe31d 1000 transport->getGap().addToDisconnectionCallChain(tptr, mptr);
rgrover1 529:8d21604fe31d 1001 }
rgrover1 529:8d21604fe31d 1002
rgrover1 529:8d21604fe31d 1003 inline void
rgrover1 529:8d21604fe31d 1004 BLE::onDataSent(void (*callback)(unsigned count)) {
rgrover1 529:8d21604fe31d 1005 transport->getGattServer().setOnDataSent(callback);
rgrover1 529:8d21604fe31d 1006 }
rgrover1 529:8d21604fe31d 1007
rgrover1 529:8d21604fe31d 1008 template <typename T> inline void
rgrover1 529:8d21604fe31d 1009 BLE::onDataSent(T *objPtr, void (T::*memberPtr)(unsigned count)) {
rgrover1 529:8d21604fe31d 1010 transport->getGattServer().setOnDataSent(objPtr, memberPtr);
rgrover1 529:8d21604fe31d 1011 }
rgrover1 529:8d21604fe31d 1012
rgrover1 529:8d21604fe31d 1013 inline void
rgrover1 529:8d21604fe31d 1014 BLE::onDataWritten(void (*callback)(const GattWriteCallbackParams *eventDataP)) {
rgrover1 529:8d21604fe31d 1015 transport->getGattServer().setOnDataWritten(callback);
rgrover1 529:8d21604fe31d 1016 }
rgrover1 529:8d21604fe31d 1017
rgrover1 529:8d21604fe31d 1018 template <typename T> inline void
rgrover1 529:8d21604fe31d 1019 BLE::onDataWritten(T *objPtr, void (T::*memberPtr)(const GattWriteCallbackParams *context)) {
rgrover1 529:8d21604fe31d 1020 transport->getGattServer().setOnDataWritten(objPtr, memberPtr);
rgrover1 529:8d21604fe31d 1021 }
rgrover1 529:8d21604fe31d 1022
rgrover1 529:8d21604fe31d 1023 inline ble_error_t
rgrover1 529:8d21604fe31d 1024 BLE::onDataRead(void (*callback)(const GattReadCallbackParams *eventDataP)) {
rgrover1 529:8d21604fe31d 1025 return transport->getGattServer().setOnDataRead(callback);
rgrover1 529:8d21604fe31d 1026 }
rgrover1 529:8d21604fe31d 1027
rgrover1 529:8d21604fe31d 1028 template <typename T> inline ble_error_t
rgrover1 529:8d21604fe31d 1029 BLE::onDataRead(T *objPtr, void (T::*memberPtr)(const GattReadCallbackParams *context)) {
rgrover1 529:8d21604fe31d 1030 return transport->getGattServer().setOnDataRead(objPtr, memberPtr);
rgrover1 529:8d21604fe31d 1031 }
rgrover1 529:8d21604fe31d 1032
rgrover1 529:8d21604fe31d 1033 inline void
rgrover1 529:8d21604fe31d 1034 BLE::onUpdatesEnabled(GattServer::EventCallback_t callback)
rgrover1 529:8d21604fe31d 1035 {
rgrover1 529:8d21604fe31d 1036 transport->getGattServer().setOnUpdatesEnabled(callback);
rgrover1 529:8d21604fe31d 1037 }
rgrover1 529:8d21604fe31d 1038
rgrover1 529:8d21604fe31d 1039 inline void
rgrover1 529:8d21604fe31d 1040 BLE::onUpdatesDisabled(GattServer::EventCallback_t callback)
rgrover1 529:8d21604fe31d 1041 {
rgrover1 529:8d21604fe31d 1042 transport->getGattServer().setOnUpdatesDisabled(callback);
rgrover1 529:8d21604fe31d 1043 }
rgrover1 529:8d21604fe31d 1044
rgrover1 529:8d21604fe31d 1045 inline void
rgrover1 529:8d21604fe31d 1046 BLE::onConfirmationReceived(GattServer::EventCallback_t callback)
rgrover1 529:8d21604fe31d 1047 {
rgrover1 529:8d21604fe31d 1048 transport->getGattServer().setOnConfirmationReceived(callback);
rgrover1 529:8d21604fe31d 1049 }
rgrover1 529:8d21604fe31d 1050
rgrover1 529:8d21604fe31d 1051 inline void
rgrover1 529:8d21604fe31d 1052 BLE::onRadioNotification(Gap::RadioNotificationEventCallback_t callback)
rgrover1 529:8d21604fe31d 1053 {
rgrover1 529:8d21604fe31d 1054 transport->getGap().setOnRadioNotification(callback);
rgrover1 529:8d21604fe31d 1055 }
rgrover1 529:8d21604fe31d 1056
rgrover1 529:8d21604fe31d 1057 inline ble_error_t
rgrover1 529:8d21604fe31d 1058 BLE::addService(GattService &service)
rgrover1 529:8d21604fe31d 1059 {
rgrover1 529:8d21604fe31d 1060 return transport->getGattServer().addService(service);
rgrover1 529:8d21604fe31d 1061 }
rgrover1 529:8d21604fe31d 1062
rgrover1 529:8d21604fe31d 1063 inline Gap::GapState_t
rgrover1 529:8d21604fe31d 1064 BLE::getGapState(void) const
rgrover1 529:8d21604fe31d 1065 {
rgrover1 529:8d21604fe31d 1066 return transport->getGap().getState();
rgrover1 529:8d21604fe31d 1067 }
rgrover1 529:8d21604fe31d 1068
rgrover1 529:8d21604fe31d 1069 inline ble_error_t
rgrover1 529:8d21604fe31d 1070 BLE::readCharacteristicValue(GattAttribute::Handle_t attributeHandle, uint8_t *buffer, uint16_t *lengthP)
rgrover1 529:8d21604fe31d 1071 {
rgrover1 529:8d21604fe31d 1072 return transport->getGattServer().readValue(attributeHandle, buffer, lengthP);
rgrover1 529:8d21604fe31d 1073 }
rgrover1 529:8d21604fe31d 1074
rgrover1 529:8d21604fe31d 1075 inline ble_error_t
rgrover1 529:8d21604fe31d 1076 BLE::readCharacteristicValue(Gap::Handle_t connectionHandle,
rgrover1 529:8d21604fe31d 1077 GattAttribute::Handle_t attributeHandle,
rgrover1 529:8d21604fe31d 1078 uint8_t *buffer,
rgrover1 529:8d21604fe31d 1079 uint16_t *lengthP)
rgrover1 529:8d21604fe31d 1080 {
rgrover1 529:8d21604fe31d 1081 return transport->getGattServer().readValue(connectionHandle, attributeHandle, buffer, lengthP);
rgrover1 529:8d21604fe31d 1082 }
rgrover1 529:8d21604fe31d 1083
rgrover1 529:8d21604fe31d 1084 inline ble_error_t
rgrover1 529:8d21604fe31d 1085 BLE::updateCharacteristicValue(GattAttribute::Handle_t attributeHandle, const uint8_t *value, uint16_t size, bool localOnly)
rgrover1 529:8d21604fe31d 1086 {
rgrover1 529:8d21604fe31d 1087 return transport->getGattServer().updateValue(attributeHandle, const_cast<uint8_t *>(value), size, localOnly);
rgrover1 529:8d21604fe31d 1088 }
rgrover1 529:8d21604fe31d 1089
rgrover1 529:8d21604fe31d 1090 inline ble_error_t
rgrover1 529:8d21604fe31d 1091 BLE::updateCharacteristicValue(Gap::Handle_t connectionHandle,
rgrover1 529:8d21604fe31d 1092 GattAttribute::Handle_t attributeHandle,
rgrover1 529:8d21604fe31d 1093 const uint8_t *value,
rgrover1 529:8d21604fe31d 1094 uint16_t size,
rgrover1 529:8d21604fe31d 1095 bool localOnly)
rgrover1 529:8d21604fe31d 1096 {
rgrover1 529:8d21604fe31d 1097 return transport->getGattServer().updateValue(connectionHandle, attributeHandle, const_cast<uint8_t *>(value), size, localOnly);
rgrover1 529:8d21604fe31d 1098 }
rgrover1 529:8d21604fe31d 1099
rgrover1 529:8d21604fe31d 1100 inline void
rgrover1 529:8d21604fe31d 1101 BLE::waitForEvent(void)
rgrover1 529:8d21604fe31d 1102 {
rgrover1 529:8d21604fe31d 1103 transport->waitForEvent();
rgrover1 529:8d21604fe31d 1104 }
rgrover1 529:8d21604fe31d 1105
rgrover1 529:8d21604fe31d 1106 inline ble_error_t
rgrover1 529:8d21604fe31d 1107 BLE::getPreferredConnectionParams(Gap::ConnectionParams_t *params)
rgrover1 529:8d21604fe31d 1108 {
rgrover1 529:8d21604fe31d 1109 return transport->getGap().getPreferredConnectionParams(params);
rgrover1 529:8d21604fe31d 1110 }
rgrover1 529:8d21604fe31d 1111
rgrover1 529:8d21604fe31d 1112 inline ble_error_t
rgrover1 529:8d21604fe31d 1113 BLE::setPreferredConnectionParams(const Gap::ConnectionParams_t *params)
rgrover1 529:8d21604fe31d 1114 {
rgrover1 529:8d21604fe31d 1115 return transport->getGap().setPreferredConnectionParams(params);
rgrover1 529:8d21604fe31d 1116 }
rgrover1 529:8d21604fe31d 1117
rgrover1 529:8d21604fe31d 1118 inline ble_error_t
rgrover1 529:8d21604fe31d 1119 BLE::updateConnectionParams(Gap::Handle_t handle, const Gap::ConnectionParams_t *params) {
rgrover1 529:8d21604fe31d 1120 return transport->getGap().updateConnectionParams(handle, params);
rgrover1 529:8d21604fe31d 1121 }
rgrover1 529:8d21604fe31d 1122
rgrover1 529:8d21604fe31d 1123 inline const char *
rgrover1 529:8d21604fe31d 1124 BLE::getVersion(void)
rgrover1 529:8d21604fe31d 1125 {
rgrover1 529:8d21604fe31d 1126 return transport->getVersion();
rgrover1 529:8d21604fe31d 1127 }
rgrover1 529:8d21604fe31d 1128
rgrover1 529:8d21604fe31d 1129 inline ble_error_t
rgrover1 529:8d21604fe31d 1130 BLE::setDeviceName(const uint8_t *deviceName)
rgrover1 529:8d21604fe31d 1131 {
rgrover1 529:8d21604fe31d 1132 return transport->getGap().setDeviceName(deviceName);
rgrover1 529:8d21604fe31d 1133 }
rgrover1 529:8d21604fe31d 1134
rgrover1 529:8d21604fe31d 1135 inline ble_error_t
rgrover1 529:8d21604fe31d 1136 BLE::getDeviceName(uint8_t *deviceName, unsigned *lengthP)
rgrover1 529:8d21604fe31d 1137 {
rgrover1 529:8d21604fe31d 1138 return transport->getGap().getDeviceName(deviceName, lengthP);
rgrover1 529:8d21604fe31d 1139 }
rgrover1 529:8d21604fe31d 1140
rgrover1 529:8d21604fe31d 1141 inline ble_error_t
rgrover1 529:8d21604fe31d 1142 BLE::setAppearance(uint16_t appearance)
rgrover1 529:8d21604fe31d 1143 {
rgrover1 529:8d21604fe31d 1144 return transport->getGap().setAppearance(appearance);
rgrover1 529:8d21604fe31d 1145 }
rgrover1 529:8d21604fe31d 1146
rgrover1 529:8d21604fe31d 1147 inline ble_error_t
rgrover1 529:8d21604fe31d 1148 BLE::getAppearance(uint16_t *appearanceP)
rgrover1 529:8d21604fe31d 1149 {
rgrover1 529:8d21604fe31d 1150 return transport->getGap().getAppearance(appearanceP);
rgrover1 529:8d21604fe31d 1151 }
rgrover1 529:8d21604fe31d 1152
rgrover1 529:8d21604fe31d 1153 inline ble_error_t
rgrover1 529:8d21604fe31d 1154 BLE::setTxPower(int8_t txPower)
rgrover1 529:8d21604fe31d 1155 {
rgrover1 529:8d21604fe31d 1156 return transport->getGap().setTxPower(txPower);
rgrover1 529:8d21604fe31d 1157 }
rgrover1 529:8d21604fe31d 1158
rgrover1 529:8d21604fe31d 1159 inline void
rgrover1 529:8d21604fe31d 1160 BLE::getPermittedTxPowerValues(const int8_t **valueArrayPP, size_t *countP)
rgrover1 529:8d21604fe31d 1161 {
rgrover1 529:8d21604fe31d 1162 transport->getGap().getPermittedTxPowerValues(valueArrayPP, countP);
rgrover1 529:8d21604fe31d 1163 }
rgrover1 529:8d21604fe31d 1164
rgrover1 529:8d21604fe31d 1165 inline ble_error_t
rgrover1 529:8d21604fe31d 1166 BLE::initializeSecurity(bool enableBonding,
rgrover1 529:8d21604fe31d 1167 bool requireMITM,
rgrover1 529:8d21604fe31d 1168 Gap::SecurityIOCapabilities_t iocaps,
rgrover1 529:8d21604fe31d 1169 const Gap::Passkey_t passkey)
rgrover1 529:8d21604fe31d 1170 {
rgrover1 529:8d21604fe31d 1171 return transport->initializeSecurity(enableBonding, requireMITM, iocaps, passkey);
rgrover1 529:8d21604fe31d 1172 }
rgrover1 529:8d21604fe31d 1173
rgrover1 529:8d21604fe31d 1174 inline void
rgrover1 529:8d21604fe31d 1175 BLE::onSecuritySetupInitiated(Gap::SecuritySetupInitiatedCallback_t callback)
rgrover1 529:8d21604fe31d 1176 {
rgrover1 529:8d21604fe31d 1177 transport->getGap().setOnSecuritySetupInitiated(callback);
rgrover1 529:8d21604fe31d 1178 }
rgrover1 529:8d21604fe31d 1179
rgrover1 529:8d21604fe31d 1180 inline void
rgrover1 529:8d21604fe31d 1181 BLE::onSecuritySetupCompleted(Gap::SecuritySetupCompletedCallback_t callback)
rgrover1 529:8d21604fe31d 1182 {
rgrover1 529:8d21604fe31d 1183 transport->getGap().setOnSecuritySetupCompleted(callback);
rgrover1 529:8d21604fe31d 1184 }
rgrover1 529:8d21604fe31d 1185
rgrover1 529:8d21604fe31d 1186 inline void
rgrover1 529:8d21604fe31d 1187 BLE::onLinkSecured(Gap::LinkSecuredCallback_t callback)
rgrover1 529:8d21604fe31d 1188 {
rgrover1 529:8d21604fe31d 1189 transport->getGap().setOnLinkSecured(callback);
rgrover1 529:8d21604fe31d 1190 }
rgrover1 529:8d21604fe31d 1191
rgrover1 529:8d21604fe31d 1192 inline void
rgrover1 529:8d21604fe31d 1193 BLE::onSecurityContextStored(Gap::HandleSpecificEvent_t callback)
rgrover1 529:8d21604fe31d 1194 {
rgrover1 529:8d21604fe31d 1195 transport->getGap().setOnSecurityContextStored(callback);
rgrover1 529:8d21604fe31d 1196 }
rgrover1 529:8d21604fe31d 1197
rgrover1 529:8d21604fe31d 1198 inline void
rgrover1 529:8d21604fe31d 1199 BLE::onPasskeyDisplay(Gap::PasskeyDisplayCallback_t callback)
rgrover1 529:8d21604fe31d 1200 {
rgrover1 529:8d21604fe31d 1201 return transport->getGap().setOnPasskeyDisplay(callback);
rgrover1 529:8d21604fe31d 1202 }
rgrover1 529:8d21604fe31d 1203
rgrover1 529:8d21604fe31d 1204 inline ble_error_t
rgrover1 529:8d21604fe31d 1205 BLE::getLinkSecurity(Gap::Handle_t connectionHandle, Gap::LinkSecurityStatus_t *securityStatusP)
rgrover1 529:8d21604fe31d 1206 {
rgrover1 529:8d21604fe31d 1207 return transport->getGap().getLinkSecurity(connectionHandle, securityStatusP);
rgrover1 529:8d21604fe31d 1208 }
rgrover1 529:8d21604fe31d 1209
rgrover1 529:8d21604fe31d 1210 inline ble_error_t
rgrover1 529:8d21604fe31d 1211 BLE::purgeAllBondingState(void)
rgrover1 529:8d21604fe31d 1212 {
rgrover1 529:8d21604fe31d 1213 return transport->getGap().purgeAllBondingState();
rgrover1 529:8d21604fe31d 1214 }
rgrover1 529:8d21604fe31d 1215
rgrover1 529:8d21604fe31d 1216 inline ble_error_t
rgrover1 529:8d21604fe31d 1217 BLE::launchServiceDiscovery(Gap::Handle_t connectionHandle,
rgrover1 529:8d21604fe31d 1218 ServiceDiscovery::ServiceCallback_t sc,
rgrover1 529:8d21604fe31d 1219 ServiceDiscovery::CharacteristicCallback_t cc,
rgrover1 529:8d21604fe31d 1220 const UUID &matchingServiceUUID,
rgrover1 529:8d21604fe31d 1221 const UUID &matchingCharacteristicUUID)
rgrover1 529:8d21604fe31d 1222 {
rgrover1 529:8d21604fe31d 1223 return transport->getGattClient().launchServiceDiscovery(connectionHandle, sc, cc, matchingServiceUUID, matchingCharacteristicUUID);
rgrover1 529:8d21604fe31d 1224 }
rgrover1 529:8d21604fe31d 1225
rgrover1 529:8d21604fe31d 1226 inline void
rgrover1 529:8d21604fe31d 1227 BLE::onServiceDiscoveryTermination(ServiceDiscovery::TerminationCallback_t callback)
rgrover1 529:8d21604fe31d 1228 {
rgrover1 529:8d21604fe31d 1229 transport->getGattClient().onServiceDiscoveryTermination(callback);
rgrover1 529:8d21604fe31d 1230 }
rgrover1 529:8d21604fe31d 1231
rgrover1 529:8d21604fe31d 1232 /**
rgrover1 529:8d21604fe31d 1233 * Is service-discovery currently active?
rgrover1 529:8d21604fe31d 1234 */
rgrover1 529:8d21604fe31d 1235 inline bool
rgrover1 529:8d21604fe31d 1236 BLE::isServiceDiscoveryActive(void)
rgrover1 529:8d21604fe31d 1237 {
rgrover1 529:8d21604fe31d 1238 return transport->getGattClient().isServiceDiscoveryActive();
rgrover1 529:8d21604fe31d 1239 }
rgrover1 529:8d21604fe31d 1240
rgrover1 529:8d21604fe31d 1241 /**
rgrover1 529:8d21604fe31d 1242 * Terminate an ongoing service-discovery. This should result in an
rgrover1 529:8d21604fe31d 1243 * invocation of the TerminationCallback if service-discovery is active.
rgrover1 529:8d21604fe31d 1244 */
rgrover1 529:8d21604fe31d 1245 inline void
rgrover1 529:8d21604fe31d 1246 BLE::terminateServiceDiscovery(void)
rgrover1 529:8d21604fe31d 1247 {
rgrover1 529:8d21604fe31d 1248 transport->getGattClient().terminateServiceDiscovery();
rgrover1 529:8d21604fe31d 1249 }
rgrover1 529:8d21604fe31d 1250
rgrover1 529:8d21604fe31d 1251 #endif // ifndef __BLE_H__