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.

common/BLEDeviceInstanceBase.h → ble/BLEInstanceBase.h

@@ -17,36 +17,40 @@
 #ifndef __BLE_DEVICE_INSTANCE_BASE__
 #define __BLE_DEVICE_INSTANCE_BASE__
 
+#include "Gap.h"
+
+/* forward declarations */
+class GattServer;
+class GattClient;
+
 /**
  *  The interface for the transport object to be created by the target library's
- *  createBLEDeviceInstance().
+ *  createBLEInstance().
  */
-class BLEDeviceInstanceBase
+class BLEInstanceBase
 {
 public:
-    virtual const char *getVersion(void)           = 0;
-    virtual Gap&        getGap()                   = 0;
-    virtual GattServer& getGattServer()            = 0;
-    virtual ble_error_t init(void)                 = 0;
-    virtual ble_error_t shutdown(void)             = 0;
-    virtual ble_error_t reset(void)                = 0;
-    virtual ble_error_t initializeSecurity(bool                          enableBonding = true,
-                                           bool                          requireMITM   = true,
-                                           Gap::SecurityIOCapabilities_t iocaps        = Gap::IO_CAPS_NONE,
-                                           const Gap::Passkey_t          passkey       = NULL) = 0;
-    virtual ble_error_t setTxPower(int8_t txPower) = 0;
-    virtual void        getPermittedTxPowerValues(const int8_t **, size_t *) = 0;
+    virtual ble_error_t init(void)                  = 0;
+    virtual ble_error_t shutdown(void)              = 0;
+    virtual const char *getVersion(void)            = 0;
+    virtual Gap&        getGap()                    = 0;
+    virtual const Gap&  getGap() const              = 0;
+    virtual GattServer& getGattServer()             = 0;
+    virtual const GattServer& getGattServer() const = 0;
+    virtual GattClient& getGattClient()             = 0;
+    virtual SecurityManager& getSecurityManager()   = 0;
+    virtual const SecurityManager& getSecurityManager() const = 0;
     virtual void        waitForEvent(void)         = 0;
 };
 
 /**
- * BLEDevice uses composition to hide an interface object encapsulating the
+ * BLE uses composition to hide an interface object encapsulating the
  * backend transport.
  *
  * The following API is used to create the singleton interface object. An
  * implementation for this function must be provided by the device-specific
  * library, otherwise there will be a linker error.
  */
-extern BLEDeviceInstanceBase *createBLEDeviceInstance(void);
+extern BLEInstanceBase *createBLEInstance(void);
 
 #endif // ifndef __BLE_DEVICE_INSTANCE_BASE__

ble/DiscoveredCharacteristic.h

@@ -0,0 +1,191 @@
+/* mbed Microcontroller Library
+ * Copyright (c) 2006-2013 ARM Limited
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef __DISCOVERED_CHARACTERISTIC_H__
+#define __DISCOVERED_CHARACTERISTIC_H__
+
+#include "UUID.h"
+#include "Gap.h"
+#include "GattAttribute.h"
+#include "GattClient.h"
+
+/**
+ * Structure for holding information about the service and the characteristics
+ * found during the discovery process.
+ */
+class DiscoveredCharacteristic {
+public:
+    struct Properties_t {
+        uint8_t _broadcast       :1; /**< Broadcasting of the value permitted. */
+        uint8_t _read            :1; /**< Reading the value permitted. */
+        uint8_t _writeWoResp     :1; /**< Writing the value with Write Command permitted. */
+        uint8_t _write           :1; /**< Writing the value with Write Request permitted. */
+        uint8_t _notify          :1; /**< Notications of the value permitted. */
+        uint8_t _indicate        :1; /**< Indications of the value permitted. */
+        uint8_t _authSignedWrite :1; /**< Writing the value with Signed Write Command permitted. */
+
+    public:
+        bool broadcast(void)       const {return _broadcast;      }
+        bool read(void)            const {return _read;           }
+        bool writeWoResp(void)     const {return _writeWoResp;    }
+        bool write(void)           const {return _write;          }
+        bool notify(void)          const {return _notify;         }
+        bool indicate(void)        const {return _indicate;       }
+        bool authSignedWrite(void) const {return _authSignedWrite;}
+
+    private:
+        operator uint8_t()  const; /* disallow implicit conversion into an integer */
+        operator unsigned() const; /* disallow implicit conversion into an integer */
+    };
+
+    /**
+     * Structure for holding information about the service and the characteristics
+     * found during the discovery process.
+     */
+    struct DiscoveredDescriptor {
+        GattAttribute::Handle_t handle; /**< Descriptor Handle. */
+        UUID                    uuid;   /**< Descriptor UUID. */
+    };
+
+    /**
+     * Callback type for when a characteristic descriptor is found during descriptor-
+     * discovery. The receiving function is passed in a pointer to a
+     * DiscoveredDescriptor object which will remain valid for the lifetime
+     * of the callback. Memory for this object is owned by the BLE_API eventing
+     * framework. The application can safely make a persistent shallow-copy of
+     * this object in order to work with the characteristic beyond the callback.
+     */
+    typedef void (*DescriptorCallback_t)(const DiscoveredDescriptor *);
+
+    /**
+     * Initiate (or continue) a read for the value attribute, optionally at a
+     * given offset. If the Characteristic or Descriptor to be read is longer
+     * than ATT_MTU - 1, this function must be called multiple times with
+     * appropriate offset to read the complete value.
+     *
+     * @return BLE_ERROR_NONE if a read has been initiated, else
+     *         BLE_ERROR_INVALID_STATE if some internal state about the connection is invalid, or
+     *         BLE_STACK_BUSY if some client procedure already in progress, or
+     *         BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's properties.
+     */
+    ble_error_t read(uint16_t offset = 0) const;
+
+    /**
+     * Perform a write without response procedure.
+     *
+     * @param  length
+     *           The amount of data being written.
+     * @param  value
+     *           The bytes being written.
+     *
+     * @note   It is important to note that a write without response will generate
+     *         an onDataSent() callback when the packet has been transmitted. There
+     *         will be a BLE-stack specific limit to the number of pending
+     *         writeWoResponse operations; the user may want to use the onDataSent()
+     *         callback for flow-control.
+     *
+     * @retval BLE_ERROR_NONE Successfully started the Write procedure, else
+     *         BLE_ERROR_INVALID_STATE if some internal state about the connection is invalid, or
+     *         BLE_STACK_BUSY if some client procedure already in progress, or
+     *         BLE_ERROR_NO_MEM if there are no available buffers left to process the request, or
+     *         BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's properties.
+     */
+    ble_error_t writeWoResponse(uint16_t length, const uint8_t *value) const;
+
+    /**
+     * Initiate a GATT Characteristic Descriptor Discovery procedure for descriptors within this characteristic.
+     *
+     * @param  callback
+     * @param  matchingUUID
+     *           filter for descriptors. Defaults to wildcard which will discover all descriptors.
+     *
+     * @return  BLE_ERROR_NONE if descriptor discovery is launched successfully; else an appropriate error.
+     */
+    ble_error_t discoverDescriptors(DescriptorCallback_t callback, const UUID &matchingUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN)) const;
+
+    /**
+     * Perform a write procedure.
+     *
+     * @param  length
+     *           The amount of data being written.
+     * @param  value
+     *           The bytes being written.
+     *
+     * @note   It is important to note that a write will generate
+     *         an onDataWritten() callback when the peer acknowledges the request.
+     *
+     * @retval BLE_ERROR_NONE Successfully started the Write procedure, else
+     *         BLE_ERROR_INVALID_STATE if some internal state about the connection is invalid, or
+     *         BLE_STACK_BUSY if some client procedure already in progress, or
+     *         BLE_ERROR_NO_MEM if there are no available buffers left to process the request, or
+     *         BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's properties.
+     */
+    ble_error_t write(uint16_t length, const uint8_t *value) const;
+
+    static void setupOnDataRead(GattClient::ReadCallback_t callback) {
+        onDataReadCallback = callback;
+    }
+
+    static void setupOnDataWrite(GattClient::WriteCallback_t callback) {
+        onDataWriteCallback = callback;
+    }
+
+    void setupLongUUID(UUID::LongUUIDBytes_t longUUID) {
+        uuid.setupLong(longUUID);
+    }
+
+public:
+    UUID::ShortUUIDBytes_t getShortUUID(void) const {
+        return uuid.getShortUUID();
+    }
+
+    const Properties_t& getProperties(void) const {
+        return props;
+    }
+
+    const GattAttribute::Handle_t& getDeclHandle(void) const {
+        return declHandle;
+    }
+    const GattAttribute::Handle_t& getValueHandle(void) const {
+        return valueHandle;
+    }
+
+public:
+    DiscoveredCharacteristic() : gattc(NULL),
+                                 uuid(UUID::ShortUUIDBytes_t(0)),
+                                 props(),
+                                 declHandle(GattAttribute::INVALID_HANDLE),
+                                 valueHandle(GattAttribute::INVALID_HANDLE) {
+        /* empty */
+    }
+
+protected:
+    GattClient              *gattc;
+
+protected:
+    UUID                     uuid;
+    Properties_t             props;
+    GattAttribute::Handle_t  declHandle;
+    GattAttribute::Handle_t  valueHandle;
+
+    Gap::Handle_t            connHandle;
+
+public:
+    static GattClient::ReadCallback_t  onDataReadCallback;
+    static GattClient::WriteCallback_t onDataWriteCallback;
+};
+
+#endif /*__DISCOVERED_CHARACTERISTIC_H__*/

ble/DiscoveredService.h

@@ -0,0 +1,71 @@
+/* mbed Microcontroller Library
+ * Copyright (c) 2006-2013 ARM Limited
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef __DISCOVERED_SERVICE_H__
+#define __DISCOVERED_SERVICE_H__
+
+#include "UUID.h"
+#include "GattAttribute.h"
+
+/**@brief Type for holding information about the service and the characteristics found during
+ *        the discovery process.
+ */
+class DiscoveredService {
+public:
+     void setup(UUID uuidIn, GattAttribute::Handle_t startHandleIn, GattAttribute::Handle_t endHandleIn) {
+         uuid        = uuidIn;
+         startHandle = startHandleIn;
+         endHandle   = endHandleIn;
+     }
+
+     void setup(GattAttribute::Handle_t startHandleIn, GattAttribute::Handle_t endHandleIn) {
+         startHandle = startHandleIn;
+         endHandle   = endHandleIn;
+     }
+
+    void setupLongUUID(UUID::LongUUIDBytes_t longUUID) {
+         uuid.setupLong(longUUID);
+    }
+
+public:
+    const UUID &getUUID(void) const {
+        return uuid;
+    }
+
+    const GattAttribute::Handle_t& getStartHandle(void) const {
+        return startHandle;
+    }
+    const GattAttribute::Handle_t& getEndHandle(void) const {
+        return endHandle;
+    }
+
+public:
+    DiscoveredService() : uuid(UUID::ShortUUIDBytes_t(0)),
+                          startHandle(GattAttribute::INVALID_HANDLE),
+                          endHandle(GattAttribute::INVALID_HANDLE) {
+        /* empty */
+    }
+
+private:
+    DiscoveredService(const DiscoveredService &);
+
+private:
+    UUID                    uuid;        /**< UUID of the service.  */
+    GattAttribute::Handle_t startHandle; /**< Service Handle Range. */
+    GattAttribute::Handle_t endHandle;   /**< Service Handle Range. */
+};
+
+#endif /*__DISCOVERED_SERVICE_H__*/