Bluetooth Low Energy / BLE_API

High level Bluetooth Low Energy API and radio abstraction layer

Dependents:   BLE_ANCS_SDAPI BLE_temperature BLE_HeartRate BLE_ANCS_SDAPI_IRC ... more

Overview

The BLE_API is a high level abstraction for using Bluetooth Low Energy on multiple platforms. For details and examples using the BLE_API please see the BLE_API Summary Page. Or click on the API Documentation tab above.

Supported Services

Supported services can be found in the BLE_API/services folder.

ble/DiscoveredCharacteristic.h@710:b2e1a2660ec2, 2015-06-19 (annotated)

Committer:
rgrover1
Date:
Fri Jun 19 15:53:28 2015 +0100
Revision:
710:b2e1a2660ec2
Parent:
public/DiscoveredCharacteristic.h@566:6681c6e0d7c0 
Synchronized with git rev 7e8977d8

Author: Rohit Grover

Release 0.3.8

=============



This is a minor set of enhancements before we yotta-ize BLE_API.



Enhancements

~~~~~~~~~~~~



* Minor rework for class UUID; added a default and copy constructor; and a != operator.



* Added copy constructor and accessors for GapAdvertisingParams.



* GapScanningParams:: remove unnecessary checks for SCAN_TIMEOUT_MAX.



* Add a comment header block to explain why BLEDevice::init() may not be safe

  to call from global static context.



* Introduce GattAttribute::INVALID_HANDLE.



* Replace some deprecated uses of Gap::address_t with Gap::Address_t.



Bugfixes

~~~~~~~~



* None.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
rgrover1 524:6e97ab392e2a 1 /* mbed Microcontroller Library
rgrover1 524:6e97ab392e2a 2 * Copyright (c) 2006-2013 ARM Limited
rgrover1 524:6e97ab392e2a 3 *
rgrover1 524:6e97ab392e2a 4 * Licensed under the Apache License, Version 2.0 (the "License");
rgrover1 524:6e97ab392e2a 5 * you may not use this file except in compliance with the License.
rgrover1 524:6e97ab392e2a 6 * You may obtain a copy of the License at
rgrover1 524:6e97ab392e2a 7 *
rgrover1 524:6e97ab392e2a 8 * http://www.apache.org/licenses/LICENSE-2.0
rgrover1 524:6e97ab392e2a 9 *
rgrover1 524:6e97ab392e2a 10 * Unless required by applicable law or agreed to in writing, software
rgrover1 524:6e97ab392e2a 11 * distributed under the License is distributed on an "AS IS" BASIS,
rgrover1 524:6e97ab392e2a 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
rgrover1 524:6e97ab392e2a 13 * See the License for the specific language governing permissions and
rgrover1 524:6e97ab392e2a 14 * limitations under the License.
rgrover1 524:6e97ab392e2a 15 */
rgrover1 524:6e97ab392e2a 16
rgrover1 524:6e97ab392e2a 17 #ifndef __DISCOVERED_CHARACTERISTIC_H__
rgrover1 524:6e97ab392e2a 18 #define __DISCOVERED_CHARACTERISTIC_H__
rgrover1 524:6e97ab392e2a 19
rgrover1 524:6e97ab392e2a 20 #include "UUID.h"
rgrover1 524:6e97ab392e2a 21 #include "Gap.h"
rgrover1 524:6e97ab392e2a 22 #include "GattAttribute.h"
rgrover1 524:6e97ab392e2a 23 #include "GattClient.h"
rgrover1 524:6e97ab392e2a 24
rgrover1 524:6e97ab392e2a 25 /**
rgrover1 524:6e97ab392e2a 26 * Structure for holding information about the service and the characteristics
rgrover1 524:6e97ab392e2a 27 * found during the discovery process.
rgrover1 524:6e97ab392e2a 28 */
rgrover1 524:6e97ab392e2a 29 class DiscoveredCharacteristic {
rgrover1 524:6e97ab392e2a 30 public:
rgrover1 524:6e97ab392e2a 31 struct Properties_t {
rgrover1 524:6e97ab392e2a 32 uint8_t _broadcast :1; /**< Broadcasting of the value permitted. */
rgrover1 524:6e97ab392e2a 33 uint8_t _read :1; /**< Reading the value permitted. */
rgrover1 524:6e97ab392e2a 34 uint8_t _writeWoResp :1; /**< Writing the value with Write Command permitted. */
rgrover1 524:6e97ab392e2a 35 uint8_t _write :1; /**< Writing the value with Write Request permitted. */
rgrover1 524:6e97ab392e2a 36 uint8_t _notify :1; /**< Notications of the value permitted. */
rgrover1 524:6e97ab392e2a 37 uint8_t _indicate :1; /**< Indications of the value permitted. */
rgrover1 524:6e97ab392e2a 38 uint8_t _authSignedWrite :1; /**< Writing the value with Signed Write Command permitted. */
rgrover1 524:6e97ab392e2a 39
rgrover1 524:6e97ab392e2a 40 public:
rgrover1 524:6e97ab392e2a 41 bool broadcast(void) const {return _broadcast; }
rgrover1 524:6e97ab392e2a 42 bool read(void) const {return _read; }
rgrover1 524:6e97ab392e2a 43 bool writeWoResp(void) const {return _writeWoResp; }
rgrover1 524:6e97ab392e2a 44 bool write(void) const {return _write; }
rgrover1 524:6e97ab392e2a 45 bool notify(void) const {return _notify; }
rgrover1 524:6e97ab392e2a 46 bool indicate(void) const {return _indicate; }
rgrover1 524:6e97ab392e2a 47 bool authSignedWrite(void) const {return _authSignedWrite;}
rgrover1 524:6e97ab392e2a 48
rgrover1 524:6e97ab392e2a 49 private:
rgrover1 524:6e97ab392e2a 50 operator uint8_t() const; /* disallow implicit conversion into an integer */
rgrover1 524:6e97ab392e2a 51 operator unsigned() const; /* disallow implicit conversion into an integer */
rgrover1 524:6e97ab392e2a 52 };
rgrover1 524:6e97ab392e2a 53
rgrover1 524:6e97ab392e2a 54 /**
rgrover1 565:a3fb221c0813 55 * Structure for holding information about the service and the characteristics
rgrover1 565:a3fb221c0813 56 * found during the discovery process.
rgrover1 565:a3fb221c0813 57 */
rgrover1 565:a3fb221c0813 58 struct DiscoveredDescriptor {
rgrover1 565:a3fb221c0813 59 GattAttribute::Handle_t handle; /**< Descriptor Handle. */
rgrover1 565:a3fb221c0813 60 UUID uuid; /**< Descriptor UUID. */
rgrover1 565:a3fb221c0813 61 };
rgrover1 565:a3fb221c0813 62
rgrover1 565:a3fb221c0813 63 /**
rgrover1 565:a3fb221c0813 64 * Callback type for when a characteristic descriptor is found during descriptor-
rgrover1 565:a3fb221c0813 65 * discovery. The receiving function is passed in a pointer to a
rgrover1 565:a3fb221c0813 66 * DiscoveredDescriptor object which will remain valid for the lifetime
rgrover1 565:a3fb221c0813 67 * of the callback. Memory for this object is owned by the BLE_API eventing
rgrover1 565:a3fb221c0813 68 * framework. The application can safely make a persistent shallow-copy of
rgrover1 565:a3fb221c0813 69 * this object in order to work with the characteristic beyond the callback.
rgrover1 565:a3fb221c0813 70 */
rgrover1 565:a3fb221c0813 71 typedef void (*DescriptorCallback_t)(const DiscoveredDescriptor *);
rgrover1 565:a3fb221c0813 72
rgrover1 565:a3fb221c0813 73 /**
rgrover1 524:6e97ab392e2a 74 * Initiate (or continue) a read for the value attribute, optionally at a
rgrover1 524:6e97ab392e2a 75 * given offset. If the Characteristic or Descriptor to be read is longer
rgrover1 524:6e97ab392e2a 76 * than ATT_MTU - 1, this function must be called multiple times with
rgrover1 524:6e97ab392e2a 77 * appropriate offset to read the complete value.
rgrover1 524:6e97ab392e2a 78 *
rgrover1 524:6e97ab392e2a 79 * @return BLE_ERROR_NONE if a read has been initiated, else
rgrover1 524:6e97ab392e2a 80 * BLE_ERROR_INVALID_STATE if some internal state about the connection is invalid, or
rgrover1 524:6e97ab392e2a 81 * BLE_STACK_BUSY if some client procedure already in progress, or
rgrover1 524:6e97ab392e2a 82 * BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's properties.
rgrover1 524:6e97ab392e2a 83 */
rgrover1 524:6e97ab392e2a 84 ble_error_t read(uint16_t offset = 0) const;
rgrover1 524:6e97ab392e2a 85
rgrover1 524:6e97ab392e2a 86 /**
rgrover1 524:6e97ab392e2a 87 * Perform a write without response procedure.
rgrover1 524:6e97ab392e2a 88 *
rgrover1 524:6e97ab392e2a 89 * @param length
rgrover1 524:6e97ab392e2a 90 * The amount of data being written.
rgrover1 524:6e97ab392e2a 91 * @param value
rgrover1 524:6e97ab392e2a 92 * The bytes being written.
rgrover1 524:6e97ab392e2a 93 *
rgrover1 524:6e97ab392e2a 94 * @note It is important to note that a write without response will generate
rgrover1 524:6e97ab392e2a 95 * an onDataSent() callback when the packet has been transmitted. There
rgrover1 524:6e97ab392e2a 96 * will be a BLE-stack specific limit to the number of pending
rgrover1 524:6e97ab392e2a 97 * writeWoResponse operations; the user may want to use the onDataSent()
rgrover1 524:6e97ab392e2a 98 * callback for flow-control.
rgrover1 524:6e97ab392e2a 99 *
rgrover1 524:6e97ab392e2a 100 * @retval BLE_ERROR_NONE Successfully started the Write procedure, else
rgrover1 524:6e97ab392e2a 101 * BLE_ERROR_INVALID_STATE if some internal state about the connection is invalid, or
rgrover1 524:6e97ab392e2a 102 * BLE_STACK_BUSY if some client procedure already in progress, or
rgrover1 524:6e97ab392e2a 103 * BLE_ERROR_NO_MEM if there are no available buffers left to process the request, or
rgrover1 524:6e97ab392e2a 104 * BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's properties.
rgrover1 524:6e97ab392e2a 105 */
rgrover1 524:6e97ab392e2a 106 ble_error_t writeWoResponse(uint16_t length, const uint8_t *value) const;
rgrover1 524:6e97ab392e2a 107
rgrover1 524:6e97ab392e2a 108 /**
rgrover1 565:a3fb221c0813 109 * Initiate a GATT Characteristic Descriptor Discovery procedure for descriptors within this characteristic.
rgrover1 565:a3fb221c0813 110 *
rgrover1 565:a3fb221c0813 111 * @param callback
rgrover1 565:a3fb221c0813 112 * @param matchingUUID
rgrover1 565:a3fb221c0813 113 * filter for descriptors. Defaults to wildcard which will discover all descriptors.
rgrover1 565:a3fb221c0813 114 *
rgrover1 565:a3fb221c0813 115 * @return BLE_ERROR_NONE if descriptor discovery is launched successfully; else an appropriate error.
rgrover1 565:a3fb221c0813 116 */
rgrover1 565:a3fb221c0813 117 ble_error_t discoverDescriptors(DescriptorCallback_t callback, const UUID &matchingUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN)) const;
rgrover1 565:a3fb221c0813 118
rgrover1 565:a3fb221c0813 119 /**
rgrover1 524:6e97ab392e2a 120 * Perform a write procedure.
rgrover1 524:6e97ab392e2a 121 *
rgrover1 524:6e97ab392e2a 122 * @param length
rgrover1 524:6e97ab392e2a 123 * The amount of data being written.
rgrover1 524:6e97ab392e2a 124 * @param value
rgrover1 524:6e97ab392e2a 125 * The bytes being written.
rgrover1 524:6e97ab392e2a 126 *
rgrover1 524:6e97ab392e2a 127 * @note It is important to note that a write will generate
rgrover1 524:6e97ab392e2a 128 * an onDataWritten() callback when the peer acknowledges the request.
rgrover1 524:6e97ab392e2a 129 *
rgrover1 524:6e97ab392e2a 130 * @retval BLE_ERROR_NONE Successfully started the Write procedure, else
rgrover1 524:6e97ab392e2a 131 * BLE_ERROR_INVALID_STATE if some internal state about the connection is invalid, or
rgrover1 524:6e97ab392e2a 132 * BLE_STACK_BUSY if some client procedure already in progress, or
rgrover1 524:6e97ab392e2a 133 * BLE_ERROR_NO_MEM if there are no available buffers left to process the request, or
rgrover1 524:6e97ab392e2a 134 * BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's properties.
rgrover1 524:6e97ab392e2a 135 */
rgrover1 524:6e97ab392e2a 136 ble_error_t write(uint16_t length, const uint8_t *value) const;
rgrover1 524:6e97ab392e2a 137
rgrover1 524:6e97ab392e2a 138 static void setupOnDataRead(GattClient::ReadCallback_t callback) {
rgrover1 524:6e97ab392e2a 139 onDataReadCallback = callback;
rgrover1 524:6e97ab392e2a 140 }
rgrover1 524:6e97ab392e2a 141
rgrover1 524:6e97ab392e2a 142 static void setupOnDataWrite(GattClient::WriteCallback_t callback) {
rgrover1 524:6e97ab392e2a 143 onDataWriteCallback = callback;
rgrover1 524:6e97ab392e2a 144 }
rgrover1 524:6e97ab392e2a 145
rgrover1 524:6e97ab392e2a 146 void setupLongUUID(UUID::LongUUIDBytes_t longUUID) {
rgrover1 524:6e97ab392e2a 147 uuid.setupLong(longUUID);
rgrover1 524:6e97ab392e2a 148 }
rgrover1 524:6e97ab392e2a 149
rgrover1 524:6e97ab392e2a 150 public:
rgrover1 524:6e97ab392e2a 151 UUID::ShortUUIDBytes_t getShortUUID(void) const {
rgrover1 524:6e97ab392e2a 152 return uuid.getShortUUID();
rgrover1 524:6e97ab392e2a 153 }
rgrover1 524:6e97ab392e2a 154
rgrover1 524:6e97ab392e2a 155 const Properties_t& getProperties(void) const {
rgrover1 524:6e97ab392e2a 156 return props;
rgrover1 524:6e97ab392e2a 157 }
rgrover1 524:6e97ab392e2a 158
rgrover1 524:6e97ab392e2a 159 const GattAttribute::Handle_t& getDeclHandle(void) const {
rgrover1 524:6e97ab392e2a 160 return declHandle;
rgrover1 524:6e97ab392e2a 161 }
rgrover1 524:6e97ab392e2a 162 const GattAttribute::Handle_t& getValueHandle(void) const {
rgrover1 524:6e97ab392e2a 163 return valueHandle;
rgrover1 524:6e97ab392e2a 164 }
rgrover1 524:6e97ab392e2a 165
rgrover1 524:6e97ab392e2a 166 public:
rgrover1 524:6e97ab392e2a 167 DiscoveredCharacteristic() : gattc(NULL),
rgrover1 524:6e97ab392e2a 168 uuid(UUID::ShortUUIDBytes_t(0)),
rgrover1 524:6e97ab392e2a 169 props(),
rgrover1 524:6e97ab392e2a 170 declHandle(GattAttribute::INVALID_HANDLE),
rgrover1 524:6e97ab392e2a 171 valueHandle(GattAttribute::INVALID_HANDLE) {
rgrover1 524:6e97ab392e2a 172 /* empty */
rgrover1 524:6e97ab392e2a 173 }
rgrover1 524:6e97ab392e2a 174
rgrover1 524:6e97ab392e2a 175 protected:
rgrover1 566:6681c6e0d7c0 176 GattClient *gattc;
rgrover1 524:6e97ab392e2a 177
rgrover1 524:6e97ab392e2a 178 protected:
rgrover1 566:6681c6e0d7c0 179 UUID uuid;
rgrover1 566:6681c6e0d7c0 180 Properties_t props;
rgrover1 566:6681c6e0d7c0 181 GattAttribute::Handle_t declHandle;
rgrover1 566:6681c6e0d7c0 182 GattAttribute::Handle_t valueHandle;
rgrover1 524:6e97ab392e2a 183
rgrover1 566:6681c6e0d7c0 184 Gap::Handle_t connHandle;
rgrover1 524:6e97ab392e2a 185
rgrover1 524:6e97ab392e2a 186 public:
rgrover1 524:6e97ab392e2a 187 static GattClient::ReadCallback_t onDataReadCallback;
rgrover1 524:6e97ab392e2a 188 static GattClient::WriteCallback_t onDataWriteCallback;
rgrover1 524:6e97ab392e2a 189 };
rgrover1 524:6e97ab392e2a 190
rgrover1 524:6e97ab392e2a 191 #endif /*__DISCOVERED_CHARACTERISTIC_H__*/