vo dung / Mbed 2 deprecated ibeacon

project for nrf51822 qfab

Dependencies:   eddystone_URL mbed

Fork of eddystone_URL by vo dung

BLE_API/public/BLEDevice.h@0:76dfa9657d9d, 2014-11-12 (annotated)

Committer:
jksoft
Date:
Wed Nov 12 02:40:34 2014 +0000
Revision:
0:76dfa9657d9d
????????

Who changed what in which revision?

UserRevisionLine numberNew contents of line
jksoft 0:76dfa9657d9d 1 /* mbed Microcontroller Library
jksoft 0:76dfa9657d9d 2 * Copyright (c) 2006-2013 ARM Limited
jksoft 0:76dfa9657d9d 3 *
jksoft 0:76dfa9657d9d 4 * Licensed under the Apache License, Version 2.0 (the "License");
jksoft 0:76dfa9657d9d 5 * you may not use this file except in compliance with the License.
jksoft 0:76dfa9657d9d 6 * You may obtain a copy of the License at
jksoft 0:76dfa9657d9d 7 *
jksoft 0:76dfa9657d9d 8 * http://www.apache.org/licenses/LICENSE-2.0
jksoft 0:76dfa9657d9d 9 *
jksoft 0:76dfa9657d9d 10 * Unless required by applicable law or agreed to in writing, software
jksoft 0:76dfa9657d9d 11 * distributed under the License is distributed on an "AS IS" BASIS,
jksoft 0:76dfa9657d9d 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
jksoft 0:76dfa9657d9d 13 * See the License for the specific language governing permissions and
jksoft 0:76dfa9657d9d 14 * limitations under the License.
jksoft 0:76dfa9657d9d 15 */
jksoft 0:76dfa9657d9d 16
jksoft 0:76dfa9657d9d 17 #ifndef __BLE_DEVICE__
jksoft 0:76dfa9657d9d 18 #define __BLE_DEVICE__
jksoft 0:76dfa9657d9d 19
jksoft 0:76dfa9657d9d 20 #include "mbed.h"
jksoft 0:76dfa9657d9d 21 #include "blecommon.h"
jksoft 0:76dfa9657d9d 22 #include "Gap.h"
jksoft 0:76dfa9657d9d 23 #include "GattServer.h"
jksoft 0:76dfa9657d9d 24 #include "BLEDeviceInstanceBase.h"
jksoft 0:76dfa9657d9d 25
jksoft 0:76dfa9657d9d 26 /**
jksoft 0:76dfa9657d9d 27 * The base class used to abstract away BLE capable radio transceivers or SOCs,
jksoft 0:76dfa9657d9d 28 * to enable this BLE API to work with any radio transparently.
jksoft 0:76dfa9657d9d 29 */
jksoft 0:76dfa9657d9d 30 class BLEDevice
jksoft 0:76dfa9657d9d 31 {
jksoft 0:76dfa9657d9d 32 public:
jksoft 0:76dfa9657d9d 33 /**
jksoft 0:76dfa9657d9d 34 * Initialize the BLE controller. This should be called before using
jksoft 0:76dfa9657d9d 35 * anything else in the BLE_API.
jksoft 0:76dfa9657d9d 36 */
jksoft 0:76dfa9657d9d 37 ble_error_t init();
jksoft 0:76dfa9657d9d 38 ble_error_t reset(void);
jksoft 0:76dfa9657d9d 39
jksoft 0:76dfa9657d9d 40 /* GAP specific APIs */
jksoft 0:76dfa9657d9d 41 public:
jksoft 0:76dfa9657d9d 42 /**
jksoft 0:76dfa9657d9d 43 * Set the BTLE MAC address and type.
jksoft 0:76dfa9657d9d 44 * @return
jksoft 0:76dfa9657d9d 45 */
jksoft 0:76dfa9657d9d 46 ble_error_t setAddress(Gap::addr_type_t type, const uint8_t address[6]);
jksoft 0:76dfa9657d9d 47
jksoft 0:76dfa9657d9d 48 /**
jksoft 0:76dfa9657d9d 49 * @param[in] advType
jksoft 0:76dfa9657d9d 50 * The GAP advertising mode to use for this device. Valid
jksoft 0:76dfa9657d9d 51 * values are defined in AdvertisingType:
jksoft 0:76dfa9657d9d 52 *
jksoft 0:76dfa9657d9d 53 * \par ADV_NON_CONNECTABLE_UNDIRECTED
jksoft 0:76dfa9657d9d 54 * All connections to the peripheral device will be refused.
jksoft 0:76dfa9657d9d 55 *
jksoft 0:76dfa9657d9d 56 * \par ADV_CONNECTABLE_DIRECTED
jksoft 0:76dfa9657d9d 57 * Only connections from a pre-defined central device will be
jksoft 0:76dfa9657d9d 58 * accepted.
jksoft 0:76dfa9657d9d 59 *
jksoft 0:76dfa9657d9d 60 * \par ADV_CONNECTABLE_UNDIRECTED
jksoft 0:76dfa9657d9d 61 * Any central device can connect to this peripheral.
jksoft 0:76dfa9657d9d 62 *
jksoft 0:76dfa9657d9d 63 * \par ADV_SCANNABLE_UNDIRECTED
jksoft 0:76dfa9657d9d 64 * Any central device can connect to this peripheral, and
jksoft 0:76dfa9657d9d 65 * the secondary Scan Response payload will be included or
jksoft 0:76dfa9657d9d 66 * available to central devices.
jksoft 0:76dfa9657d9d 67 *
jksoft 0:76dfa9657d9d 68 * \par
jksoft 0:76dfa9657d9d 69 * See Bluetooth Core Specification 4.0 (Vol. 3), Part C,
jksoft 0:76dfa9657d9d 70 * Section 9.3 and Core Specification 4.0 (Vol. 6), Part B,
jksoft 0:76dfa9657d9d 71 * Section 2.3.1 for further information on GAP connection
jksoft 0:76dfa9657d9d 72 * modes
jksoft 0:76dfa9657d9d 73 */
jksoft 0:76dfa9657d9d 74 void setAdvertisingType(GapAdvertisingParams::AdvertisingType);
jksoft 0:76dfa9657d9d 75
jksoft 0:76dfa9657d9d 76 /**
jksoft 0:76dfa9657d9d 77 * @param[in] interval
jksoft 0:76dfa9657d9d 78 * Advertising interval between 0x0020 and 0x4000 in 0.625ms
jksoft 0:76dfa9657d9d 79 * units (20ms to 10.24s). If using non-connectable mode
jksoft 0:76dfa9657d9d 80 * (ADV_NON_CONNECTABLE_UNDIRECTED) this min value is
jksoft 0:76dfa9657d9d 81 * 0x00A0 (100ms). To reduce the likelihood of collisions, the
jksoft 0:76dfa9657d9d 82 * link layer perturbs this interval by a pseudo-random delay
jksoft 0:76dfa9657d9d 83 * with a range of 0 ms to 10 ms for each advertising event.
jksoft 0:76dfa9657d9d 84 *
jksoft 0:76dfa9657d9d 85 * \par
jksoft 0:76dfa9657d9d 86 * Decreasing this value will allow central devices to detect
jksoft 0:76dfa9657d9d 87 * your peripheral faster at the expense of more power being
jksoft 0:76dfa9657d9d 88 * used by the radio due to the higher data transmit rate.
jksoft 0:76dfa9657d9d 89 *
jksoft 0:76dfa9657d9d 90 * \par
jksoft 0:76dfa9657d9d 91 * This field must be set to 0 if connectionMode is equal
jksoft 0:76dfa9657d9d 92 * to ADV_CONNECTABLE_DIRECTED
jksoft 0:76dfa9657d9d 93 *
jksoft 0:76dfa9657d9d 94 * \par
jksoft 0:76dfa9657d9d 95 * See Bluetooth Core Specification, Vol 3., Part C,
jksoft 0:76dfa9657d9d 96 * Appendix A for suggested advertising intervals.
jksoft 0:76dfa9657d9d 97 */
jksoft 0:76dfa9657d9d 98 void setAdvertisingInterval(uint16_t interval);
jksoft 0:76dfa9657d9d 99
jksoft 0:76dfa9657d9d 100 /**
jksoft 0:76dfa9657d9d 101 * @param[in] timeout
jksoft 0:76dfa9657d9d 102 * Advertising timeout between 0x1 and 0x3FFF (1 and 16383)
jksoft 0:76dfa9657d9d 103 * in seconds. Enter 0 to disable the advertising timeout.
jksoft 0:76dfa9657d9d 104 */
jksoft 0:76dfa9657d9d 105 void setAdvertisingTimeout(uint16_t timeout);
jksoft 0:76dfa9657d9d 106
jksoft 0:76dfa9657d9d 107 /**
jksoft 0:76dfa9657d9d 108 * Please refer to the APIs above.
jksoft 0:76dfa9657d9d 109 */
jksoft 0:76dfa9657d9d 110 void setAdvertisingParams(const GapAdvertisingParams &advParams);
jksoft 0:76dfa9657d9d 111
jksoft 0:76dfa9657d9d 112 /**
jksoft 0:76dfa9657d9d 113 * This API is typically used as an internal helper to udpate the transport
jksoft 0:76dfa9657d9d 114 * backend with advertising data before starting to advertise. It may also
jksoft 0:76dfa9657d9d 115 * be explicity used to dynamically reset the accumulated advertising
jksoft 0:76dfa9657d9d 116 * payload and scanResponse; to do this, the application can clear and re-
jksoft 0:76dfa9657d9d 117 * accumulate a new advertising payload (and scanResponse) before using this
jksoft 0:76dfa9657d9d 118 * API.
jksoft 0:76dfa9657d9d 119 */
jksoft 0:76dfa9657d9d 120 ble_error_t setAdvertisingPayload(void);
jksoft 0:76dfa9657d9d 121
jksoft 0:76dfa9657d9d 122 /**
jksoft 0:76dfa9657d9d 123 * Reset any advertising payload prepared from prior calls to
jksoft 0:76dfa9657d9d 124 * accumulateAdvertisingPayload().
jksoft 0:76dfa9657d9d 125 */
jksoft 0:76dfa9657d9d 126 void clearAdvertisingPayload(void);
jksoft 0:76dfa9657d9d 127
jksoft 0:76dfa9657d9d 128 /**
jksoft 0:76dfa9657d9d 129 * Accumulate an AD structure in the advertising payload. Please note that
jksoft 0:76dfa9657d9d 130 * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
jksoft 0:76dfa9657d9d 131 * as an additional 31 bytes if the advertising payload proves to be too
jksoft 0:76dfa9657d9d 132 * small.
jksoft 0:76dfa9657d9d 133 *
jksoft 0:76dfa9657d9d 134 * @param flags
jksoft 0:76dfa9657d9d 135 * The flags to be added. Multiple flags may be specified in
jksoft 0:76dfa9657d9d 136 * combination.
jksoft 0:76dfa9657d9d 137 */
jksoft 0:76dfa9657d9d 138 ble_error_t accumulateAdvertisingPayload(uint8_t flags);
jksoft 0:76dfa9657d9d 139
jksoft 0:76dfa9657d9d 140 /**
jksoft 0:76dfa9657d9d 141 * Accumulate an AD structure in the advertising payload. Please note that
jksoft 0:76dfa9657d9d 142 * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
jksoft 0:76dfa9657d9d 143 * as an additional 31 bytes if the advertising payload proves to be too
jksoft 0:76dfa9657d9d 144 * small.
jksoft 0:76dfa9657d9d 145 *
jksoft 0:76dfa9657d9d 146 * @param app
jksoft 0:76dfa9657d9d 147 * The appearance of the peripheral.
jksoft 0:76dfa9657d9d 148 */
jksoft 0:76dfa9657d9d 149 ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::Appearance app);
jksoft 0:76dfa9657d9d 150
jksoft 0:76dfa9657d9d 151 /**
jksoft 0:76dfa9657d9d 152 * Accumulate an AD structure in the advertising payload. Please note that
jksoft 0:76dfa9657d9d 153 * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
jksoft 0:76dfa9657d9d 154 * as an additional 31 bytes if the advertising payload proves to be too
jksoft 0:76dfa9657d9d 155 * small.
jksoft 0:76dfa9657d9d 156 *
jksoft 0:76dfa9657d9d 157 * @param app
jksoft 0:76dfa9657d9d 158 * The max transmit power to be used by the controller. This is
jksoft 0:76dfa9657d9d 159 * only a hint.
jksoft 0:76dfa9657d9d 160 */
jksoft 0:76dfa9657d9d 161 ble_error_t accumulateAdvertisingPayloadTxPower(int8_t power);
jksoft 0:76dfa9657d9d 162
jksoft 0:76dfa9657d9d 163 /**
jksoft 0:76dfa9657d9d 164 * Accumulate a variable length byte-stream as an AD structure in the
jksoft 0:76dfa9657d9d 165 * advertising payload. Please note that the payload is limited to 31 bytes.
jksoft 0:76dfa9657d9d 166 * The SCAN_RESPONSE message may be used as an additional 31 bytes if the
jksoft 0:76dfa9657d9d 167 * advertising payload proves to be too small.
jksoft 0:76dfa9657d9d 168 *
jksoft 0:76dfa9657d9d 169 * @param type The type which describes the variable length data.
jksoft 0:76dfa9657d9d 170 * @param data data bytes.
jksoft 0:76dfa9657d9d 171 * @param len length of data.
jksoft 0:76dfa9657d9d 172 */
jksoft 0:76dfa9657d9d 173 ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len);
jksoft 0:76dfa9657d9d 174
jksoft 0:76dfa9657d9d 175 /**
jksoft 0:76dfa9657d9d 176 * Accumulate a variable length byte-stream as an AD structure in the
jksoft 0:76dfa9657d9d 177 * scanResponse payload.
jksoft 0:76dfa9657d9d 178 *
jksoft 0:76dfa9657d9d 179 * @param type The type which describes the variable length data.
jksoft 0:76dfa9657d9d 180 * @param data data bytes.
jksoft 0:76dfa9657d9d 181 * @param len length of data.
jksoft 0:76dfa9657d9d 182 */
jksoft 0:76dfa9657d9d 183 ble_error_t accumulateScanResponse(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len);
jksoft 0:76dfa9657d9d 184
jksoft 0:76dfa9657d9d 185 /**
jksoft 0:76dfa9657d9d 186 * Start advertising (GAP Discoverable, Connectable modes, Broadcast
jksoft 0:76dfa9657d9d 187 * Procedure).
jksoft 0:76dfa9657d9d 188 */
jksoft 0:76dfa9657d9d 189 ble_error_t startAdvertising(void);
jksoft 0:76dfa9657d9d 190
jksoft 0:76dfa9657d9d 191 /**
jksoft 0:76dfa9657d9d 192 * Stop advertising (GAP Discoverable, Connectable modes, Broadcast
jksoft 0:76dfa9657d9d 193 * Procedure).
jksoft 0:76dfa9657d9d 194 */
jksoft 0:76dfa9657d9d 195 ble_error_t stopAdvertising(void);
jksoft 0:76dfa9657d9d 196
jksoft 0:76dfa9657d9d 197 ble_error_t disconnect(Gap::DisconnectionReason_t reason);
jksoft 0:76dfa9657d9d 198
jksoft 0:76dfa9657d9d 199 /* APIs to set GAP callbacks. */
jksoft 0:76dfa9657d9d 200 void onTimeout(Gap::EventCallback_t timeoutCallback);
jksoft 0:76dfa9657d9d 201
jksoft 0:76dfa9657d9d 202 void onConnection(Gap::ConnectionEventCallback_t connectionCallback);
jksoft 0:76dfa9657d9d 203 /**
jksoft 0:76dfa9657d9d 204 * Used to setup a callback for GAP disconnection.
jksoft 0:76dfa9657d9d 205 */
jksoft 0:76dfa9657d9d 206 void onDisconnection(Gap::DisconnectionEventCallback_t disconnectionCallback);
jksoft 0:76dfa9657d9d 207
jksoft 0:76dfa9657d9d 208 /**
jksoft 0:76dfa9657d9d 209 * Setup a callback for the GATT event DATA_SENT.
jksoft 0:76dfa9657d9d 210 */
jksoft 0:76dfa9657d9d 211 void onDataSent(GattServer::ServerEventCallbackWithCount_t callback);
jksoft 0:76dfa9657d9d 212
jksoft 0:76dfa9657d9d 213 /**
jksoft 0:76dfa9657d9d 214 * Setup a callback for when a characteristic has its value updated by a
jksoft 0:76dfa9657d9d 215 * client.
jksoft 0:76dfa9657d9d 216 *
jksoft 0:76dfa9657d9d 217 * @Note: it is possible to chain together multiple onDataWritten callbacks
jksoft 0:76dfa9657d9d 218 * (potentially from different modules of an application) to receive updates
jksoft 0:76dfa9657d9d 219 * to characteristics. Many services, such as DFU and UART add their own
jksoft 0:76dfa9657d9d 220 * onDataWritten callbacks behind the scenes to trap interesting events.
jksoft 0:76dfa9657d9d 221 *
jksoft 0:76dfa9657d9d 222 * @Note: it is also possible to setup a callback into a member function of
jksoft 0:76dfa9657d9d 223 * some object.
jksoft 0:76dfa9657d9d 224 */
jksoft 0:76dfa9657d9d 225 void onDataWritten(void (*callback)(const GattCharacteristicWriteCBParams *eventDataP));
jksoft 0:76dfa9657d9d 226 template <typename T> void onDataWritten(T *objPtr, void (T::*memberPtr)(const GattCharacteristicWriteCBParams *context));
jksoft 0:76dfa9657d9d 227
jksoft 0:76dfa9657d9d 228 void onUpdatesEnabled(GattServer::EventCallback_t callback);
jksoft 0:76dfa9657d9d 229 void onUpdatesDisabled(GattServer::EventCallback_t callback);
jksoft 0:76dfa9657d9d 230 void onConfirmationReceived(GattServer::EventCallback_t callback);
jksoft 0:76dfa9657d9d 231
jksoft 0:76dfa9657d9d 232 /**
jksoft 0:76dfa9657d9d 233 * Add a service declaration to the local server ATT table. Also add the
jksoft 0:76dfa9657d9d 234 * characteristics contained within.
jksoft 0:76dfa9657d9d 235 */
jksoft 0:76dfa9657d9d 236 ble_error_t addService(GattService &service);
jksoft 0:76dfa9657d9d 237
jksoft 0:76dfa9657d9d 238 Gap::GapState_t getGapState(void) const;
jksoft 0:76dfa9657d9d 239
jksoft 0:76dfa9657d9d 240 /**
jksoft 0:76dfa9657d9d 241 * @param[in/out] lengthP
jksoft 0:76dfa9657d9d 242 * input: Length in bytes to be read,
jksoft 0:76dfa9657d9d 243 * output: Total length of attribute value upon successful return.
jksoft 0:76dfa9657d9d 244 */
jksoft 0:76dfa9657d9d 245 ble_error_t readCharacteristicValue(uint16_t handle, uint8_t *const buffer, uint16_t *const lengthP);
jksoft 0:76dfa9657d9d 246
jksoft 0:76dfa9657d9d 247 /**
jksoft 0:76dfa9657d9d 248 * @param localOnly
jksoft 0:76dfa9657d9d 249 * Only update the characteristic locally regardless of notify/indicate flags in the CCCD.
jksoft 0:76dfa9657d9d 250 */
jksoft 0:76dfa9657d9d 251 ble_error_t updateCharacteristicValue(uint16_t handle, const uint8_t* value, uint16_t size, bool localOnly = false);
jksoft 0:76dfa9657d9d 252
jksoft 0:76dfa9657d9d 253 /**
jksoft 0:76dfa9657d9d 254 * Yield control to the BLE stack or to other tasks waiting for events. This
jksoft 0:76dfa9657d9d 255 * is a sleep function which will return when there is an application
jksoft 0:76dfa9657d9d 256 * specific interrupt, but the MCU might wake up several times before
jksoft 0:76dfa9657d9d 257 * returning (to service the stack). This is not always interchangeable with
jksoft 0:76dfa9657d9d 258 * WFE().
jksoft 0:76dfa9657d9d 259 */
jksoft 0:76dfa9657d9d 260 void waitForEvent(void);
jksoft 0:76dfa9657d9d 261
jksoft 0:76dfa9657d9d 262 ble_error_t getPreferredConnectionParams(Gap::ConnectionParams_t *params);
jksoft 0:76dfa9657d9d 263 ble_error_t setPreferredConnectionParams(const Gap::ConnectionParams_t *params);
jksoft 0:76dfa9657d9d 264 ble_error_t updateConnectionParams(Gap::Handle_t handle, const Gap::ConnectionParams_t *params);
jksoft 0:76dfa9657d9d 265
jksoft 0:76dfa9657d9d 266 /**
jksoft 0:76dfa9657d9d 267 * This call allows the application to get the BLE stack version information.
jksoft 0:76dfa9657d9d 268 *
jksoft 0:76dfa9657d9d 269 * @return A pointer to a const string representing the version.
jksoft 0:76dfa9657d9d 270 * Note: The string is owned by the BLE_API.
jksoft 0:76dfa9657d9d 271 */
jksoft 0:76dfa9657d9d 272 const char *getVersion(void);
jksoft 0:76dfa9657d9d 273
jksoft 0:76dfa9657d9d 274 /**
jksoft 0:76dfa9657d9d 275 * Set the device name characteristic in the GAP service.
jksoft 0:76dfa9657d9d 276 * @param deviceName The new value for the device-name. This is a UTF-8 encoded, <b>NULL-terminated</b> string.
jksoft 0:76dfa9657d9d 277 */
jksoft 0:76dfa9657d9d 278 ble_error_t setDeviceName(const uint8_t *deviceName);
jksoft 0:76dfa9657d9d 279
jksoft 0:76dfa9657d9d 280 /**
jksoft 0:76dfa9657d9d 281 * Get the value of the device name characteristic in the GAP service.
jksoft 0:76dfa9657d9d 282 * @param[out] deviceName Pointer to an empty buffer where the UTF-8 *non NULL-
jksoft 0:76dfa9657d9d 283 * terminated* string will be placed. Set this
jksoft 0:76dfa9657d9d 284 * value to NULL in order to obtain the deviceName-length
jksoft 0:76dfa9657d9d 285 * from the 'length' parameter.
jksoft 0:76dfa9657d9d 286 *
jksoft 0:76dfa9657d9d 287 * @param[in/out] lengthP (on input) Length of the buffer pointed to by deviceName;
jksoft 0:76dfa9657d9d 288 * (on output) the complete device name length (without the
jksoft 0:76dfa9657d9d 289 * null terminator).
jksoft 0:76dfa9657d9d 290 *
jksoft 0:76dfa9657d9d 291 * @note If the device name is longer than the size of the supplied buffer,
jksoft 0:76dfa9657d9d 292 * length will return the complete device name length,
jksoft 0:76dfa9657d9d 293 * and not the number of bytes actually returned in deviceName.
jksoft 0:76dfa9657d9d 294 * The application may use this information to retry with a suitable buffer size.
jksoft 0:76dfa9657d9d 295 *
jksoft 0:76dfa9657d9d 296 * Sample use:
jksoft 0:76dfa9657d9d 297 * uint8_t deviceName[20];
jksoft 0:76dfa9657d9d 298 * unsigned length = sizeof(deviceName);
jksoft 0:76dfa9657d9d 299 * ble.getDeviceName(deviceName, &length);
jksoft 0:76dfa9657d9d 300 * if (length < sizeof(deviceName)) {
jksoft 0:76dfa9657d9d 301 * deviceName[length] = 0;
jksoft 0:76dfa9657d9d 302 * }
jksoft 0:76dfa9657d9d 303 * DEBUG("length: %u, deviceName: %s\r\n", length, deviceName);
jksoft 0:76dfa9657d9d 304 */
jksoft 0:76dfa9657d9d 305 ble_error_t getDeviceName(uint8_t *deviceName, unsigned *lengthP);
jksoft 0:76dfa9657d9d 306
jksoft 0:76dfa9657d9d 307 /**
jksoft 0:76dfa9657d9d 308 * Set the appearance characteristic in the GAP service.
jksoft 0:76dfa9657d9d 309 * @param[in] appearance The new value for the device-appearance.
jksoft 0:76dfa9657d9d 310 */
jksoft 0:76dfa9657d9d 311 ble_error_t setAppearance(uint16_t appearance);
jksoft 0:76dfa9657d9d 312
jksoft 0:76dfa9657d9d 313 /**
jksoft 0:76dfa9657d9d 314 * Set the appearance characteristic in the GAP service.
jksoft 0:76dfa9657d9d 315 * @param[out] appearance The new value for the device-appearance.
jksoft 0:76dfa9657d9d 316 */
jksoft 0:76dfa9657d9d 317 ble_error_t getAppearance(uint16_t *appearanceP);
jksoft 0:76dfa9657d9d 318
jksoft 0:76dfa9657d9d 319 /**
jksoft 0:76dfa9657d9d 320 * Set the radio's transmit power.
jksoft 0:76dfa9657d9d 321 * @param[in] txPower Radio transmit power in dBm.
jksoft 0:76dfa9657d9d 322 */
jksoft 0:76dfa9657d9d 323 ble_error_t setTxPower(int8_t txPower);
jksoft 0:76dfa9657d9d 324
jksoft 0:76dfa9657d9d 325 public:
jksoft 0:76dfa9657d9d 326 BLEDevice() : transport(createBLEDeviceInstance()), advParams(), advPayload(), scanResponse(), needToSetAdvPayload(true) {
jksoft 0:76dfa9657d9d 327 advPayload.clear();
jksoft 0:76dfa9657d9d 328 scanResponse.clear();
jksoft 0:76dfa9657d9d 329 }
jksoft 0:76dfa9657d9d 330
jksoft 0:76dfa9657d9d 331 private:
jksoft 0:76dfa9657d9d 332 BLEDeviceInstanceBase *const transport; /* the device specific backend */
jksoft 0:76dfa9657d9d 333
jksoft 0:76dfa9657d9d 334 GapAdvertisingParams advParams;
jksoft 0:76dfa9657d9d 335 GapAdvertisingData advPayload;
jksoft 0:76dfa9657d9d 336 GapAdvertisingData scanResponse;
jksoft 0:76dfa9657d9d 337
jksoft 0:76dfa9657d9d 338 /* Accumulation of AD structures in the advertisement payload should
jksoft 0:76dfa9657d9d 339 * eventually result in a call to the target's setAdvertisingData() before
jksoft 0:76dfa9657d9d 340 * the server begins advertising. This flag marks the status of the pending update.*/
jksoft 0:76dfa9657d9d 341 bool needToSetAdvPayload;
jksoft 0:76dfa9657d9d 342
jksoft 0:76dfa9657d9d 343 /**
jksoft 0:76dfa9657d9d 344 * DEPRECATED
jksoft 0:76dfa9657d9d 345 */
jksoft 0:76dfa9657d9d 346 public:
jksoft 0:76dfa9657d9d 347 ble_error_t setAdvertisingData(const GapAdvertisingData &ADStructures, const GapAdvertisingData &scanResponse);
jksoft 0:76dfa9657d9d 348 ble_error_t setAdvertisingData(const GapAdvertisingData &ADStructures);
jksoft 0:76dfa9657d9d 349
jksoft 0:76dfa9657d9d 350 ble_error_t startAdvertising(const GapAdvertisingParams &advParams);
jksoft 0:76dfa9657d9d 351 };
jksoft 0:76dfa9657d9d 352
jksoft 0:76dfa9657d9d 353 /* BLEDevice methods. Most of these simply forward the calls to the underlying
jksoft 0:76dfa9657d9d 354 * transport.*/
jksoft 0:76dfa9657d9d 355
jksoft 0:76dfa9657d9d 356 inline ble_error_t
jksoft 0:76dfa9657d9d 357 BLEDevice::reset(void)
jksoft 0:76dfa9657d9d 358 {
jksoft 0:76dfa9657d9d 359 return transport->reset();
jksoft 0:76dfa9657d9d 360 }
jksoft 0:76dfa9657d9d 361
jksoft 0:76dfa9657d9d 362 inline ble_error_t
jksoft 0:76dfa9657d9d 363 BLEDevice::setAddress(Gap::addr_type_t type, const uint8_t address[6])
jksoft 0:76dfa9657d9d 364 {
jksoft 0:76dfa9657d9d 365 return transport->getGap().setAddress(type, address);
jksoft 0:76dfa9657d9d 366 }
jksoft 0:76dfa9657d9d 367
jksoft 0:76dfa9657d9d 368 inline void
jksoft 0:76dfa9657d9d 369 BLEDevice::setAdvertisingType(GapAdvertisingParams::AdvertisingType advType)
jksoft 0:76dfa9657d9d 370 {
jksoft 0:76dfa9657d9d 371 advParams.setAdvertisingType(advType);
jksoft 0:76dfa9657d9d 372 }
jksoft 0:76dfa9657d9d 373
jksoft 0:76dfa9657d9d 374 inline void
jksoft 0:76dfa9657d9d 375 BLEDevice::setAdvertisingInterval(uint16_t interval)
jksoft 0:76dfa9657d9d 376 {
jksoft 0:76dfa9657d9d 377 advParams.setInterval(interval);
jksoft 0:76dfa9657d9d 378 }
jksoft 0:76dfa9657d9d 379
jksoft 0:76dfa9657d9d 380 inline void
jksoft 0:76dfa9657d9d 381 BLEDevice::setAdvertisingTimeout(uint16_t timeout)
jksoft 0:76dfa9657d9d 382 {
jksoft 0:76dfa9657d9d 383 advParams.setTimeout(timeout);
jksoft 0:76dfa9657d9d 384 }
jksoft 0:76dfa9657d9d 385
jksoft 0:76dfa9657d9d 386 inline void
jksoft 0:76dfa9657d9d 387 BLEDevice::setAdvertisingParams(const GapAdvertisingParams &newAdvParams)
jksoft 0:76dfa9657d9d 388 {
jksoft 0:76dfa9657d9d 389 advParams = newAdvParams;
jksoft 0:76dfa9657d9d 390 }
jksoft 0:76dfa9657d9d 391
jksoft 0:76dfa9657d9d 392 inline void
jksoft 0:76dfa9657d9d 393 BLEDevice::clearAdvertisingPayload(void)
jksoft 0:76dfa9657d9d 394 {
jksoft 0:76dfa9657d9d 395 needToSetAdvPayload = true;
jksoft 0:76dfa9657d9d 396 advPayload.clear();
jksoft 0:76dfa9657d9d 397 }
jksoft 0:76dfa9657d9d 398
jksoft 0:76dfa9657d9d 399 inline ble_error_t
jksoft 0:76dfa9657d9d 400 BLEDevice::accumulateAdvertisingPayload(uint8_t flags)
jksoft 0:76dfa9657d9d 401 {
jksoft 0:76dfa9657d9d 402 needToSetAdvPayload = true;
jksoft 0:76dfa9657d9d 403 return advPayload.addFlags(flags);
jksoft 0:76dfa9657d9d 404 }
jksoft 0:76dfa9657d9d 405
jksoft 0:76dfa9657d9d 406 inline ble_error_t
jksoft 0:76dfa9657d9d 407 BLEDevice::accumulateAdvertisingPayload(GapAdvertisingData::Appearance app)
jksoft 0:76dfa9657d9d 408 {
jksoft 0:76dfa9657d9d 409 needToSetAdvPayload = true;
jksoft 0:76dfa9657d9d 410 return advPayload.addAppearance(app);
jksoft 0:76dfa9657d9d 411 }
jksoft 0:76dfa9657d9d 412
jksoft 0:76dfa9657d9d 413 inline ble_error_t
jksoft 0:76dfa9657d9d 414 BLEDevice::accumulateAdvertisingPayloadTxPower(int8_t txPower)
jksoft 0:76dfa9657d9d 415 {
jksoft 0:76dfa9657d9d 416 needToSetAdvPayload = true;
jksoft 0:76dfa9657d9d 417 return advPayload.addTxPower(txPower);
jksoft 0:76dfa9657d9d 418 }
jksoft 0:76dfa9657d9d 419
jksoft 0:76dfa9657d9d 420 inline ble_error_t
jksoft 0:76dfa9657d9d 421 BLEDevice::accumulateAdvertisingPayload(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len)
jksoft 0:76dfa9657d9d 422 {
jksoft 0:76dfa9657d9d 423 needToSetAdvPayload = true;
jksoft 0:76dfa9657d9d 424 return advPayload.addData(type, data, len);
jksoft 0:76dfa9657d9d 425 }
jksoft 0:76dfa9657d9d 426
jksoft 0:76dfa9657d9d 427 inline ble_error_t
jksoft 0:76dfa9657d9d 428 BLEDevice::accumulateScanResponse(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len)
jksoft 0:76dfa9657d9d 429 {
jksoft 0:76dfa9657d9d 430 needToSetAdvPayload = true;
jksoft 0:76dfa9657d9d 431 return scanResponse.addData(type, data, len);
jksoft 0:76dfa9657d9d 432 }
jksoft 0:76dfa9657d9d 433
jksoft 0:76dfa9657d9d 434 inline ble_error_t
jksoft 0:76dfa9657d9d 435 BLEDevice::setAdvertisingPayload(void) {
jksoft 0:76dfa9657d9d 436 needToSetAdvPayload = false;
jksoft 0:76dfa9657d9d 437 return transport->getGap().setAdvertisingData(advPayload, scanResponse);
jksoft 0:76dfa9657d9d 438 }
jksoft 0:76dfa9657d9d 439
jksoft 0:76dfa9657d9d 440 inline ble_error_t
jksoft 0:76dfa9657d9d 441 BLEDevice::startAdvertising(void)
jksoft 0:76dfa9657d9d 442 {
jksoft 0:76dfa9657d9d 443 if (needToSetAdvPayload) {
jksoft 0:76dfa9657d9d 444 ble_error_t rc;
jksoft 0:76dfa9657d9d 445 if ((rc = setAdvertisingPayload()) != BLE_ERROR_NONE) {
jksoft 0:76dfa9657d9d 446 return rc;
jksoft 0:76dfa9657d9d 447 }
jksoft 0:76dfa9657d9d 448 }
jksoft 0:76dfa9657d9d 449
jksoft 0:76dfa9657d9d 450 return transport->getGap().startAdvertising(advParams);
jksoft 0:76dfa9657d9d 451 }
jksoft 0:76dfa9657d9d 452
jksoft 0:76dfa9657d9d 453 inline ble_error_t
jksoft 0:76dfa9657d9d 454 BLEDevice::stopAdvertising(void)
jksoft 0:76dfa9657d9d 455 {
jksoft 0:76dfa9657d9d 456 return transport->getGap().stopAdvertising();
jksoft 0:76dfa9657d9d 457 }
jksoft 0:76dfa9657d9d 458
jksoft 0:76dfa9657d9d 459 inline ble_error_t
jksoft 0:76dfa9657d9d 460 BLEDevice::disconnect(Gap::DisconnectionReason_t reason)
jksoft 0:76dfa9657d9d 461 {
jksoft 0:76dfa9657d9d 462 return transport->getGap().disconnect(reason);
jksoft 0:76dfa9657d9d 463 }
jksoft 0:76dfa9657d9d 464
jksoft 0:76dfa9657d9d 465 inline void
jksoft 0:76dfa9657d9d 466 BLEDevice::onTimeout(Gap::EventCallback_t timeoutCallback)
jksoft 0:76dfa9657d9d 467 {
jksoft 0:76dfa9657d9d 468 transport->getGap().setOnTimeout(timeoutCallback);
jksoft 0:76dfa9657d9d 469 }
jksoft 0:76dfa9657d9d 470
jksoft 0:76dfa9657d9d 471 inline void
jksoft 0:76dfa9657d9d 472 BLEDevice::onConnection(Gap::ConnectionEventCallback_t connectionCallback)
jksoft 0:76dfa9657d9d 473 {
jksoft 0:76dfa9657d9d 474 transport->getGap().setOnConnection(connectionCallback);
jksoft 0:76dfa9657d9d 475 }
jksoft 0:76dfa9657d9d 476
jksoft 0:76dfa9657d9d 477 inline void
jksoft 0:76dfa9657d9d 478 BLEDevice::onDisconnection(Gap::DisconnectionEventCallback_t disconnectionCallback)
jksoft 0:76dfa9657d9d 479 {
jksoft 0:76dfa9657d9d 480 transport->getGap().setOnDisconnection(disconnectionCallback);
jksoft 0:76dfa9657d9d 481 }
jksoft 0:76dfa9657d9d 482
jksoft 0:76dfa9657d9d 483 inline void
jksoft 0:76dfa9657d9d 484 BLEDevice::onDataSent(GattServer::ServerEventCallbackWithCount_t callback)
jksoft 0:76dfa9657d9d 485 {
jksoft 0:76dfa9657d9d 486 transport->getGattServer().setOnDataSent(callback);
jksoft 0:76dfa9657d9d 487 }
jksoft 0:76dfa9657d9d 488
jksoft 0:76dfa9657d9d 489 inline void
jksoft 0:76dfa9657d9d 490 BLEDevice::onDataWritten(void (*callback)(const GattCharacteristicWriteCBParams *eventDataP)) {
jksoft 0:76dfa9657d9d 491 transport->getGattServer().setOnDataWritten(callback);
jksoft 0:76dfa9657d9d 492 }
jksoft 0:76dfa9657d9d 493
jksoft 0:76dfa9657d9d 494 template <typename T> inline void
jksoft 0:76dfa9657d9d 495 BLEDevice::onDataWritten(T *objPtr, void (T::*memberPtr)(const GattCharacteristicWriteCBParams *context)) {
jksoft 0:76dfa9657d9d 496 transport->getGattServer().setOnDataWritten(objPtr, memberPtr);
jksoft 0:76dfa9657d9d 497 }
jksoft 0:76dfa9657d9d 498
jksoft 0:76dfa9657d9d 499
jksoft 0:76dfa9657d9d 500 inline void
jksoft 0:76dfa9657d9d 501 BLEDevice::onUpdatesEnabled(GattServer::EventCallback_t callback)
jksoft 0:76dfa9657d9d 502 {
jksoft 0:76dfa9657d9d 503 transport->getGattServer().setOnUpdatesEnabled(callback);
jksoft 0:76dfa9657d9d 504 }
jksoft 0:76dfa9657d9d 505
jksoft 0:76dfa9657d9d 506 inline void
jksoft 0:76dfa9657d9d 507 BLEDevice::onUpdatesDisabled(GattServer::EventCallback_t callback)
jksoft 0:76dfa9657d9d 508 {
jksoft 0:76dfa9657d9d 509 transport->getGattServer().setOnUpdatesDisabled(callback);
jksoft 0:76dfa9657d9d 510 }
jksoft 0:76dfa9657d9d 511
jksoft 0:76dfa9657d9d 512 inline void
jksoft 0:76dfa9657d9d 513 BLEDevice::onConfirmationReceived(GattServer::EventCallback_t callback)
jksoft 0:76dfa9657d9d 514 {
jksoft 0:76dfa9657d9d 515 transport->getGattServer().setOnConfirmationReceived(callback);
jksoft 0:76dfa9657d9d 516 }
jksoft 0:76dfa9657d9d 517
jksoft 0:76dfa9657d9d 518 inline ble_error_t
jksoft 0:76dfa9657d9d 519 BLEDevice::addService(GattService &service)
jksoft 0:76dfa9657d9d 520 {
jksoft 0:76dfa9657d9d 521 return transport->getGattServer().addService(service);
jksoft 0:76dfa9657d9d 522 }
jksoft 0:76dfa9657d9d 523
jksoft 0:76dfa9657d9d 524 inline Gap::GapState_t
jksoft 0:76dfa9657d9d 525 BLEDevice::getGapState(void) const
jksoft 0:76dfa9657d9d 526 {
jksoft 0:76dfa9657d9d 527 return transport->getGap().getState();
jksoft 0:76dfa9657d9d 528 }
jksoft 0:76dfa9657d9d 529
jksoft 0:76dfa9657d9d 530 inline ble_error_t BLEDevice::readCharacteristicValue(uint16_t handle, uint8_t *const buffer, uint16_t *const lengthP)
jksoft 0:76dfa9657d9d 531 {
jksoft 0:76dfa9657d9d 532 return transport->getGattServer().readValue(handle, buffer, lengthP);
jksoft 0:76dfa9657d9d 533 }
jksoft 0:76dfa9657d9d 534
jksoft 0:76dfa9657d9d 535 inline ble_error_t
jksoft 0:76dfa9657d9d 536 BLEDevice::updateCharacteristicValue(uint16_t handle, const uint8_t* value, uint16_t size, bool localOnly)
jksoft 0:76dfa9657d9d 537 {
jksoft 0:76dfa9657d9d 538 return transport->getGattServer().updateValue(handle, const_cast<uint8_t *>(value), size, localOnly);
jksoft 0:76dfa9657d9d 539 }
jksoft 0:76dfa9657d9d 540
jksoft 0:76dfa9657d9d 541 inline void
jksoft 0:76dfa9657d9d 542 BLEDevice::waitForEvent(void)
jksoft 0:76dfa9657d9d 543 {
jksoft 0:76dfa9657d9d 544 transport->waitForEvent();
jksoft 0:76dfa9657d9d 545 }
jksoft 0:76dfa9657d9d 546
jksoft 0:76dfa9657d9d 547 inline ble_error_t
jksoft 0:76dfa9657d9d 548 BLEDevice::getPreferredConnectionParams(Gap::ConnectionParams_t *params)
jksoft 0:76dfa9657d9d 549 {
jksoft 0:76dfa9657d9d 550 return transport->getGap().getPreferredConnectionParams(params);
jksoft 0:76dfa9657d9d 551 }
jksoft 0:76dfa9657d9d 552
jksoft 0:76dfa9657d9d 553 inline ble_error_t
jksoft 0:76dfa9657d9d 554 BLEDevice::setPreferredConnectionParams(const Gap::ConnectionParams_t *params)
jksoft 0:76dfa9657d9d 555 {
jksoft 0:76dfa9657d9d 556 return transport->getGap().setPreferredConnectionParams(params);
jksoft 0:76dfa9657d9d 557 }
jksoft 0:76dfa9657d9d 558
jksoft 0:76dfa9657d9d 559 inline ble_error_t
jksoft 0:76dfa9657d9d 560 BLEDevice::updateConnectionParams(Gap::Handle_t handle, const Gap::ConnectionParams_t *params) {
jksoft 0:76dfa9657d9d 561 return transport->getGap().updateConnectionParams(handle, params);
jksoft 0:76dfa9657d9d 562 }
jksoft 0:76dfa9657d9d 563
jksoft 0:76dfa9657d9d 564 inline const char *
jksoft 0:76dfa9657d9d 565 BLEDevice::getVersion(void)
jksoft 0:76dfa9657d9d 566 {
jksoft 0:76dfa9657d9d 567 return transport->getVersion();
jksoft 0:76dfa9657d9d 568 }
jksoft 0:76dfa9657d9d 569
jksoft 0:76dfa9657d9d 570 inline ble_error_t
jksoft 0:76dfa9657d9d 571 BLEDevice::setDeviceName(const uint8_t *deviceName)
jksoft 0:76dfa9657d9d 572 {
jksoft 0:76dfa9657d9d 573 return transport->getGap().setDeviceName(deviceName);
jksoft 0:76dfa9657d9d 574 }
jksoft 0:76dfa9657d9d 575
jksoft 0:76dfa9657d9d 576 inline ble_error_t
jksoft 0:76dfa9657d9d 577 BLEDevice::getDeviceName(uint8_t *deviceName, unsigned *lengthP)
jksoft 0:76dfa9657d9d 578 {
jksoft 0:76dfa9657d9d 579 return transport->getGap().getDeviceName(deviceName, lengthP);
jksoft 0:76dfa9657d9d 580 }
jksoft 0:76dfa9657d9d 581
jksoft 0:76dfa9657d9d 582 inline ble_error_t
jksoft 0:76dfa9657d9d 583 BLEDevice::setAppearance(uint16_t appearance)
jksoft 0:76dfa9657d9d 584 {
jksoft 0:76dfa9657d9d 585 return transport->getGap().setAppearance(appearance);
jksoft 0:76dfa9657d9d 586 }
jksoft 0:76dfa9657d9d 587
jksoft 0:76dfa9657d9d 588 inline ble_error_t
jksoft 0:76dfa9657d9d 589 BLEDevice::getAppearance(uint16_t *appearanceP)
jksoft 0:76dfa9657d9d 590 {
jksoft 0:76dfa9657d9d 591 return transport->getGap().getAppearance(appearanceP);
jksoft 0:76dfa9657d9d 592 }
jksoft 0:76dfa9657d9d 593
jksoft 0:76dfa9657d9d 594 inline ble_error_t
jksoft 0:76dfa9657d9d 595 BLEDevice::setTxPower(int8_t txPower)
jksoft 0:76dfa9657d9d 596 {
jksoft 0:76dfa9657d9d 597 return transport->setTxPower(txPower);
jksoft 0:76dfa9657d9d 598 }
jksoft 0:76dfa9657d9d 599
jksoft 0:76dfa9657d9d 600 /*
jksoft 0:76dfa9657d9d 601 * ALL OF THE FOLLOWING METHODS ARE DEPRECATED
jksoft 0:76dfa9657d9d 602 */
jksoft 0:76dfa9657d9d 603
jksoft 0:76dfa9657d9d 604 inline ble_error_t
jksoft 0:76dfa9657d9d 605 BLEDevice::setAdvertisingData(const GapAdvertisingData &ADStructures, const GapAdvertisingData &scanResponse)
jksoft 0:76dfa9657d9d 606 {
jksoft 0:76dfa9657d9d 607 needToSetAdvPayload = false;
jksoft 0:76dfa9657d9d 608 return transport->getGap().setAdvertisingData(ADStructures, scanResponse);
jksoft 0:76dfa9657d9d 609 }
jksoft 0:76dfa9657d9d 610
jksoft 0:76dfa9657d9d 611 inline ble_error_t
jksoft 0:76dfa9657d9d 612 BLEDevice::setAdvertisingData(const GapAdvertisingData &ADStructures)
jksoft 0:76dfa9657d9d 613 {
jksoft 0:76dfa9657d9d 614 GapAdvertisingData scanResponse;
jksoft 0:76dfa9657d9d 615
jksoft 0:76dfa9657d9d 616 needToSetAdvPayload = false;
jksoft 0:76dfa9657d9d 617 return transport->getGap().setAdvertisingData(ADStructures, scanResponse);
jksoft 0:76dfa9657d9d 618 }
jksoft 0:76dfa9657d9d 619
jksoft 0:76dfa9657d9d 620 inline ble_error_t
jksoft 0:76dfa9657d9d 621 BLEDevice::startAdvertising(const GapAdvertisingParams &_advParams)
jksoft 0:76dfa9657d9d 622 {
jksoft 0:76dfa9657d9d 623 return transport->getGap().startAdvertising(_advParams);
jksoft 0:76dfa9657d9d 624 }
jksoft 0:76dfa9657d9d 625
jksoft 0:76dfa9657d9d 626 #endif // ifndef __BLE_DEVICE__