High level Bluetooth Low Energy API and radio abstraction layer

Fork of BLE_API by Bluetooth Low Energy

Committer:
rgrover1
Date:
Thu Jul 02 09:06:11 2015 +0100
Revision:
716:11b41f651697
Child:
1035:d8ba3cb5a39a
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_SERVICE_H__
rgrover1 716:11b41f651697 18 #define __DISCOVERED_SERVICE_H__
rgrover1 716:11b41f651697 19
rgrover1 716:11b41f651697 20 #include "UUID.h"
rgrover1 716:11b41f651697 21 #include "GattAttribute.h"
rgrover1 716:11b41f651697 22
rgrover1 716:11b41f651697 23 /**@brief Type for holding information about the service and the characteristics found during
rgrover1 716:11b41f651697 24 * the discovery process.
rgrover1 716:11b41f651697 25 */
rgrover1 716:11b41f651697 26 class DiscoveredService {
rgrover1 716:11b41f651697 27 public:
rgrover1 716:11b41f651697 28 void setup(UUID uuidIn, GattAttribute::Handle_t startHandleIn, GattAttribute::Handle_t endHandleIn) {
rgrover1 716:11b41f651697 29 uuid = uuidIn;
rgrover1 716:11b41f651697 30 startHandle = startHandleIn;
rgrover1 716:11b41f651697 31 endHandle = endHandleIn;
rgrover1 716:11b41f651697 32 }
rgrover1 716:11b41f651697 33
rgrover1 716:11b41f651697 34 void setup(GattAttribute::Handle_t startHandleIn, GattAttribute::Handle_t endHandleIn) {
rgrover1 716:11b41f651697 35 startHandle = startHandleIn;
rgrover1 716:11b41f651697 36 endHandle = endHandleIn;
rgrover1 716:11b41f651697 37 }
rgrover1 716:11b41f651697 38
rgrover1 716:11b41f651697 39 void setupLongUUID(UUID::LongUUIDBytes_t longUUID) {
rgrover1 716:11b41f651697 40 uuid.setupLong(longUUID);
rgrover1 716:11b41f651697 41 }
rgrover1 716:11b41f651697 42
rgrover1 716:11b41f651697 43 public:
rgrover1 716:11b41f651697 44 const UUID &getUUID(void) const {
rgrover1 716:11b41f651697 45 return uuid;
rgrover1 716:11b41f651697 46 }
rgrover1 716:11b41f651697 47
rgrover1 716:11b41f651697 48 const GattAttribute::Handle_t& getStartHandle(void) const {
rgrover1 716:11b41f651697 49 return startHandle;
rgrover1 716:11b41f651697 50 }
rgrover1 716:11b41f651697 51 const GattAttribute::Handle_t& getEndHandle(void) const {
rgrover1 716:11b41f651697 52 return endHandle;
rgrover1 716:11b41f651697 53 }
rgrover1 716:11b41f651697 54
rgrover1 716:11b41f651697 55 public:
rgrover1 716:11b41f651697 56 DiscoveredService() : uuid(UUID::ShortUUIDBytes_t(0)),
rgrover1 716:11b41f651697 57 startHandle(GattAttribute::INVALID_HANDLE),
rgrover1 716:11b41f651697 58 endHandle(GattAttribute::INVALID_HANDLE) {
rgrover1 716:11b41f651697 59 /* empty */
rgrover1 716:11b41f651697 60 }
rgrover1 716:11b41f651697 61
rgrover1 716:11b41f651697 62 private:
rgrover1 716:11b41f651697 63 DiscoveredService(const DiscoveredService &);
rgrover1 716:11b41f651697 64
rgrover1 716:11b41f651697 65 private:
rgrover1 716:11b41f651697 66 UUID uuid; /**< UUID of the service. */
rgrover1 716:11b41f651697 67 GattAttribute::Handle_t startHandle; /**< Service Handle Range. */
rgrover1 716:11b41f651697 68 GattAttribute::Handle_t endHandle; /**< Service Handle Range. */
rgrover1 716:11b41f651697 69 };
rgrover1 716:11b41f651697 70
rgrover1 716:11b41f651697 71 #endif /*__DISCOVERED_SERVICE_H__*/