Wang Xinglu / BLE_API

High level Bluetooth Low Energy API and radio abstraction layer

Dependencies:   nRF51822

Dependents:   LinkNode_LIS3DH

Fork of BLE_API by Bluetooth Low Energy

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

Committer:
rgrover1
Date:
Thu Jul 02 09:06:11 2015 +0100
Revision:
716:11b41f651697
Parent:
710:b2e1a2660ec2
Child:
844:96aedb87cdd4
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 710:b2e1a2660ec2 1 /* mbed Microcontroller Library
rgrover1 710:b2e1a2660ec2 2 * Copyright (c) 2006-2013 ARM Limited
rgrover1 710:b2e1a2660ec2 3 *
rgrover1 710:b2e1a2660ec2 4 * Licensed under the Apache License, Version 2.0 (the "License");
rgrover1 710:b2e1a2660ec2 5 * you may not use this file except in compliance with the License.
rgrover1 710:b2e1a2660ec2 6 * You may obtain a copy of the License at
rgrover1 710:b2e1a2660ec2 7 *
rgrover1 710:b2e1a2660ec2 8 * http://www.apache.org/licenses/LICENSE-2.0
rgrover1 710:b2e1a2660ec2 9 *
rgrover1 710:b2e1a2660ec2 10 * Unless required by applicable law or agreed to in writing, software
rgrover1 710:b2e1a2660ec2 11 * distributed under the License is distributed on an "AS IS" BASIS,
rgrover1 710:b2e1a2660ec2 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
rgrover1 710:b2e1a2660ec2 13 * See the License for the specific language governing permissions and
rgrover1 710:b2e1a2660ec2 14 * limitations under the License.
rgrover1 710:b2e1a2660ec2 15 */
rgrover1 710:b2e1a2660ec2 16
rgrover1 710:b2e1a2660ec2 17 #ifndef __UUID_H__
rgrover1 710:b2e1a2660ec2 18 #define __UUID_H__
rgrover1 710:b2e1a2660ec2 19
rgrover1 710:b2e1a2660ec2 20 #include <stdint.h>
rgrover1 710:b2e1a2660ec2 21 #include <string.h>
rgrover1 710:b2e1a2660ec2 22
rgrover1 710:b2e1a2660ec2 23 #include "blecommon.h"
rgrover1 710:b2e1a2660ec2 24
rgrover1 710:b2e1a2660ec2 25 class UUID {
rgrover1 710:b2e1a2660ec2 26 public:
rgrover1 710:b2e1a2660ec2 27 enum UUID_Type_t {
rgrover1 710:b2e1a2660ec2 28 UUID_TYPE_SHORT = 0, // Short BLE UUID
rgrover1 710:b2e1a2660ec2 29 UUID_TYPE_LONG = 1 // Full 128-bit UUID
rgrover1 710:b2e1a2660ec2 30 };
rgrover1 710:b2e1a2660ec2 31
rgrover1 710:b2e1a2660ec2 32 typedef uint16_t ShortUUIDBytes_t;
rgrover1 710:b2e1a2660ec2 33
rgrover1 710:b2e1a2660ec2 34 static const unsigned LENGTH_OF_LONG_UUID = 16;
rgrover1 710:b2e1a2660ec2 35 typedef uint8_t LongUUIDBytes_t[LENGTH_OF_LONG_UUID];
rgrover1 710:b2e1a2660ec2 36
rgrover1 710:b2e1a2660ec2 37 public:
rgrover1 710:b2e1a2660ec2 38 /**
rgrover1 710:b2e1a2660ec2 39 * Creates a new 128-bit UUID
rgrover1 710:b2e1a2660ec2 40 *
rgrover1 710:b2e1a2660ec2 41 * @note The UUID is a unique 128-bit (16 byte) ID used to identify
rgrover1 710:b2e1a2660ec2 42 * different service or characteristics on the BLE device.
rgrover1 710:b2e1a2660ec2 43 *
rgrover1 710:b2e1a2660ec2 44 * @param longUUID
rgrover1 710:b2e1a2660ec2 45 * The 128-bit (16-byte) UUID value, MSB first (big-endian).
rgrover1 710:b2e1a2660ec2 46 */
rgrover1 710:b2e1a2660ec2 47 UUID(const LongUUIDBytes_t longUUID) : type(UUID_TYPE_LONG), baseUUID(), shortUUID(0) {
rgrover1 710:b2e1a2660ec2 48 setupLong(longUUID);
rgrover1 710:b2e1a2660ec2 49 }
rgrover1 710:b2e1a2660ec2 50
rgrover1 710:b2e1a2660ec2 51 /**
rgrover1 710:b2e1a2660ec2 52 * Creates a new 16-bit UUID
rgrover1 710:b2e1a2660ec2 53 *
rgrover1 710:b2e1a2660ec2 54 * @note The UUID is a unique 16-bit (2 byte) ID used to identify
rgrover1 710:b2e1a2660ec2 55 * different service or characteristics on the BLE device.
rgrover1 710:b2e1a2660ec2 56 *
rgrover1 710:b2e1a2660ec2 57 * For efficiency, and because 16 bytes would take a large chunk of the
rgrover1 710:b2e1a2660ec2 58 * 27-byte data payload length of the Link Layer, the BLE specification adds
rgrover1 710:b2e1a2660ec2 59 * two additional UUID formats: 16-bit and 32-bit UUIDs. These shortened
rgrover1 710:b2e1a2660ec2 60 * formats can be used only with UUIDs that are defined in the Bluetooth
rgrover1 710:b2e1a2660ec2 61 * specification (i.e., that are listed by the Bluetooth SIG as standard
rgrover1 710:b2e1a2660ec2 62 * Bluetooth UUIDs).
rgrover1 710:b2e1a2660ec2 63 *
rgrover1 710:b2e1a2660ec2 64 * To reconstruct the full 128-bit UUID from the shortened version, insert
rgrover1 710:b2e1a2660ec2 65 * the 16-bit short value (indicated by xxxx, including leading zeros) into
rgrover1 710:b2e1a2660ec2 66 * the Bluetooth Base UUID:
rgrover1 710:b2e1a2660ec2 67 *
rgrover1 710:b2e1a2660ec2 68 * 0000xxxx-0000-1000-8000-00805F9B34FB
rgrover1 710:b2e1a2660ec2 69 *
rgrover1 710:b2e1a2660ec2 70 * @note Shortening is not available for UUIDs that are not derived from the
rgrover1 710:b2e1a2660ec2 71 * Bluetooth Base UUID. Such non-standard UUIDs are commonly called
rgrover1 710:b2e1a2660ec2 72 * vendor-specific UUIDs. In these cases, you’ll need to use the full
rgrover1 710:b2e1a2660ec2 73 * 128-bit UUID value at all times.
rgrover1 710:b2e1a2660ec2 74 *
rgrover1 710:b2e1a2660ec2 75 * @note we don't yet support 32-bit shortened UUIDs.
rgrover1 710:b2e1a2660ec2 76 */
rgrover1 710:b2e1a2660ec2 77 UUID(ShortUUIDBytes_t shortUUID) : type(UUID_TYPE_SHORT), baseUUID(), shortUUID(shortUUID) {
rgrover1 710:b2e1a2660ec2 78 /* empty */
rgrover1 710:b2e1a2660ec2 79 }
rgrover1 710:b2e1a2660ec2 80
rgrover1 710:b2e1a2660ec2 81 UUID(const UUID &source) {
rgrover1 710:b2e1a2660ec2 82 type = source.type;
rgrover1 710:b2e1a2660ec2 83 shortUUID = source.shortUUID;
rgrover1 710:b2e1a2660ec2 84 memcpy(baseUUID, source.baseUUID, LENGTH_OF_LONG_UUID);
rgrover1 710:b2e1a2660ec2 85 }
rgrover1 710:b2e1a2660ec2 86
rgrover1 710:b2e1a2660ec2 87 UUID(void) : type(UUID_TYPE_SHORT), shortUUID(BLE_UUID_UNKNOWN) {
rgrover1 710:b2e1a2660ec2 88 /* empty */
rgrover1 710:b2e1a2660ec2 89 }
rgrover1 710:b2e1a2660ec2 90
rgrover1 710:b2e1a2660ec2 91 /**
rgrover1 710:b2e1a2660ec2 92 * Fill in a 128-bit UUID; this is useful when UUID isn't known at the time of object construction.
rgrover1 710:b2e1a2660ec2 93 */
rgrover1 710:b2e1a2660ec2 94 void setupLong(const LongUUIDBytes_t longUUID) {
rgrover1 710:b2e1a2660ec2 95 type = UUID_TYPE_LONG;
rgrover1 710:b2e1a2660ec2 96 memcpy(baseUUID, longUUID, LENGTH_OF_LONG_UUID);
rgrover1 710:b2e1a2660ec2 97 shortUUID = (uint16_t)((longUUID[2] << 8) | (longUUID[3]));
rgrover1 710:b2e1a2660ec2 98 }
rgrover1 710:b2e1a2660ec2 99
rgrover1 710:b2e1a2660ec2 100 public:
rgrover1 710:b2e1a2660ec2 101 UUID_Type_t shortOrLong(void) const {return type; }
rgrover1 710:b2e1a2660ec2 102 const uint8_t *getBaseUUID(void) const {
rgrover1 710:b2e1a2660ec2 103 if (type == UUID_TYPE_SHORT) {
rgrover1 710:b2e1a2660ec2 104 return (const uint8_t*)&shortUUID;
rgrover1 710:b2e1a2660ec2 105 } else {
rgrover1 710:b2e1a2660ec2 106 return baseUUID;
rgrover1 710:b2e1a2660ec2 107 }
rgrover1 710:b2e1a2660ec2 108 }
rgrover1 710:b2e1a2660ec2 109
rgrover1 710:b2e1a2660ec2 110 ShortUUIDBytes_t getShortUUID(void) const {return shortUUID;}
rgrover1 710:b2e1a2660ec2 111 uint8_t getLen(void) const {
rgrover1 710:b2e1a2660ec2 112 return ((type == UUID_TYPE_SHORT) ? sizeof(ShortUUIDBytes_t) : LENGTH_OF_LONG_UUID);
rgrover1 710:b2e1a2660ec2 113 }
rgrover1 710:b2e1a2660ec2 114
rgrover1 710:b2e1a2660ec2 115 bool operator== (const UUID &other) const {
rgrover1 710:b2e1a2660ec2 116 if ((this->type == UUID_TYPE_SHORT) && (other.type == UUID_TYPE_SHORT) &&
rgrover1 710:b2e1a2660ec2 117 (this->shortUUID == other.shortUUID)) {
rgrover1 710:b2e1a2660ec2 118 return true;
rgrover1 710:b2e1a2660ec2 119 }
rgrover1 710:b2e1a2660ec2 120
rgrover1 710:b2e1a2660ec2 121 if ((this->type == UUID_TYPE_LONG) && (other.type == UUID_TYPE_LONG) &&
rgrover1 710:b2e1a2660ec2 122 (memcmp(this->baseUUID, other.baseUUID, LENGTH_OF_LONG_UUID) == 0)) {
rgrover1 710:b2e1a2660ec2 123 return true;
rgrover1 710:b2e1a2660ec2 124 }
rgrover1 710:b2e1a2660ec2 125
rgrover1 710:b2e1a2660ec2 126 return false;
rgrover1 710:b2e1a2660ec2 127 }
rgrover1 710:b2e1a2660ec2 128
rgrover1 710:b2e1a2660ec2 129 bool operator!= (const UUID &other) const {
rgrover1 710:b2e1a2660ec2 130 return !(*this == other);
rgrover1 710:b2e1a2660ec2 131 }
rgrover1 710:b2e1a2660ec2 132
rgrover1 710:b2e1a2660ec2 133 private:
rgrover1 710:b2e1a2660ec2 134 UUID_Type_t type; // UUID_TYPE_SHORT or UUID_TYPE_LONG
rgrover1 710:b2e1a2660ec2 135 LongUUIDBytes_t baseUUID; /* the base of the long UUID (if
rgrover1 710:b2e1a2660ec2 136 * used). Note: bytes 12 and 13 (counting from LSB)
rgrover1 710:b2e1a2660ec2 137 * are zeroed out to allow comparison with other long
rgrover1 710:b2e1a2660ec2 138 * UUIDs which differ only in the 16-bit relative
rgrover1 710:b2e1a2660ec2 139 * part.*/
rgrover1 710:b2e1a2660ec2 140 ShortUUIDBytes_t shortUUID; // 16 bit uuid (byte 2-3 using with base)
rgrover1 710:b2e1a2660ec2 141 };
rgrover1 710:b2e1a2660ec2 142
rgrover1 710:b2e1a2660ec2 143 #endif // ifndef __UUID_H__