Lancaster University / BLE_API

Lancaster University's fork of the mbed BLE API. Lives on github, https://github.com/lancaster-university/BLE_API

Dependents:   microbit-dal microbit-dal microbit-ble-open microbit-dal ... more

Fork of BLE_API by Bluetooth Low Energy

ble/DiscoveredCharacteristic.h@716:11b41f651697, 2015-07-02 (annotated)

Committer:
rgrover1
Date:
Thu Jul 02 09:06:11 2015 +0100
Revision:
716:11b41f651697
Child:
720:ce8a760a4504
Synchronized with git rev d80fec88

Author: Rohit Grover

Release 0.4.0

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



This is a major release which introduces the GATT Client functionality. It

also aligns BLE_API with builds using our new package manager: yotta

(https://github.com/armmbed/yotta).



Many APIs have seen some redesign. We encourage our users to pay attention to

the changes and migrate appropriately over time. We've also taken care to

ensure that existing code continues to work the same way. There's more

documentation in the form of comment headers for APIs to explain proper usage;

in many cases comment headers suggest alternative use of APIs.



Enhancements

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



* Introduce GattClient. This includes functionality for service-discovery,

  connections, and attribute-reads and writes. You'll find a demo program for

  LEDBlinker on the mbed.org Bluetooth team page to use the new APIs. Some of

  the GATT client functionality hasn't been implemented yet, but the APIs have

  been added.



* Most APIs in the abstract base classes like Gap and GattServer return

  BLE_ERROR_NOT_IMPLEMENTED. Previously many APIs were pure-virtual, which did

  not permit partial ports to compile.



* We've added a new abstract base class for SecurityManager. All security

  related APIs have been moved into that.



* BLEDevice has been renamed as BLE. A deprecated alias for BLEDevice is

  available to support existing code.



* There has been a major cleanup of APIs under BLE. APIs have now been

  categorized as belonging to Gap, GattServer, GattClient, or SecurityManager.

  There are accessors to get references for Gap, GattServer, GattClient, and

  SecurityManager. A former call to ble.setAddress(...) is now expected to be

  achieved with ble.gap().setAddress(...).



* We've cleaned up our APIs, and this has resulted in dropping some APIs like

  BLE::reset().



* We've also dropped GattServer::initializeGattDatabase(). THis was added at

  some point to support controllers where a commit point was needed to

  indicate when the application had finished constructing the GATT database.

  This API would get called internally before Gap::startAdvertising(). We now

  expect the underlying port to do the equivalent of initializeGattDatabase()

  implicitly upon Gap::startAdvertising().



* The callback for BLE.onTimeout() now receives a TimeoutSource_t to indicate

  the cause of the timeout. This is perhaps the only breaking API change. We

  expect it to have very little disruptive effect.



* We've added a version of Gap::disconnect() which takes a connection handle.

  The previous API (which did not take a connection handle) has been

  deprecated; it will still work for situations where there's only a single

  active connection. We hold on to that API to allow existing code to migrate

  to the new API.



Bugfixes

~~~~~~~~



* None.

Who changed what in which revision?

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