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/GattService.h@716:11b41f651697, 2015-07-02 (annotated)

Committer:
rgrover1
Date:
Thu Jul 02 09:06:11 2015 +0100
Revision:
716:11b41f651697
Parent:
public/GattService.h@714:a6130aaa0fd9
Child:
745:922b059aca6a
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 __GATT_SERVICE_H__
rgrover1 710:b2e1a2660ec2 18 #define __GATT_SERVICE_H__
rgrover1 710:b2e1a2660ec2 19
rgrover1 710:b2e1a2660ec2 20 #include "UUID.h"
rgrover1 710:b2e1a2660ec2 21 #include "GattCharacteristic.h"
rgrover1 710:b2e1a2660ec2 22
rgrover1 710:b2e1a2660ec2 23 class GattService {
rgrover1 710:b2e1a2660ec2 24 public:
rgrover1 710:b2e1a2660ec2 25 enum {
rgrover1 710:b2e1a2660ec2 26 UUID_ALERT_NOTIFICATION_SERVICE = 0x1811,
rgrover1 710:b2e1a2660ec2 27 UUID_BATTERY_SERVICE = 0x180F,
rgrover1 710:b2e1a2660ec2 28 UUID_BLOOD_PRESSURE_SERVICE = 0x1810,
rgrover1 710:b2e1a2660ec2 29 UUID_CURRENT_TIME_SERVICE = 0x1805,
rgrover1 710:b2e1a2660ec2 30 UUID_CYCLING_SPEED_AND_CADENCE = 0x1816,
rgrover1 710:b2e1a2660ec2 31 UUID_DEVICE_INFORMATION_SERVICE = 0x180A,
rgrover1 710:b2e1a2660ec2 32 UUID_GLUCOSE_SERVICE = 0x1808,
rgrover1 710:b2e1a2660ec2 33 UUID_HEALTH_THERMOMETER_SERVICE = 0x1809,
rgrover1 710:b2e1a2660ec2 34 UUID_HEART_RATE_SERVICE = 0x180D,
rgrover1 710:b2e1a2660ec2 35 UUID_HUMAN_INTERFACE_DEVICE_SERVICE = 0x1812,
rgrover1 710:b2e1a2660ec2 36 UUID_IMMEDIATE_ALERT_SERVICE = 0x1802,
rgrover1 710:b2e1a2660ec2 37 UUID_LINK_LOSS_SERVICE = 0x1803,
rgrover1 710:b2e1a2660ec2 38 UUID_NEXT_DST_CHANGE_SERVICE = 0x1807,
rgrover1 710:b2e1a2660ec2 39 UUID_PHONE_ALERT_STATUS_SERVICE = 0x180E,
rgrover1 710:b2e1a2660ec2 40 UUID_REFERENCE_TIME_UPDATE_SERVICE = 0x1806,
rgrover1 710:b2e1a2660ec2 41 UUID_RUNNING_SPEED_AND_CADENCE = 0x1814,
rgrover1 710:b2e1a2660ec2 42 UUID_SCAN_PARAMETERS_SERVICE = 0x1813,
rgrover1 710:b2e1a2660ec2 43 UUID_TX_POWER_SERVICE = 0x1804
rgrover1 710:b2e1a2660ec2 44 };
rgrover1 710:b2e1a2660ec2 45
rgrover1 710:b2e1a2660ec2 46 public:
rgrover1 710:b2e1a2660ec2 47 /**
rgrover1 710:b2e1a2660ec2 48 * @brief Creates a new GattCharacteristic using the specified 16-bit
rgrover1 710:b2e1a2660ec2 49 * UUID, value length, and properties
rgrover1 710:b2e1a2660ec2 50 *
rgrover1 710:b2e1a2660ec2 51 * @note The UUID value must be unique in the service and is normally >1
rgrover1 710:b2e1a2660ec2 52 *
rgrover1 710:b2e1a2660ec2 53 * @param[in] uuid
rgrover1 710:b2e1a2660ec2 54 * The UUID to use for this characteristic
rgrover1 710:b2e1a2660ec2 55 * @param[in] characteristics
rgrover1 710:b2e1a2660ec2 56 * A pointer to an array of characteristics to be included within this service
rgrover1 710:b2e1a2660ec2 57 * @param[in] numCharacteristics
rgrover1 710:b2e1a2660ec2 58 * The number of characteristics
rgrover1 710:b2e1a2660ec2 59 */
rgrover1 710:b2e1a2660ec2 60 GattService(const UUID &uuid, GattCharacteristic *characteristics[], unsigned numCharacteristics) :
rgrover1 710:b2e1a2660ec2 61 _primaryServiceID(uuid), _characteristicCount(numCharacteristics), _characteristics(characteristics), _handle(0) {
rgrover1 710:b2e1a2660ec2 62 /* empty */
rgrover1 710:b2e1a2660ec2 63 }
rgrover1 710:b2e1a2660ec2 64
rgrover1 710:b2e1a2660ec2 65 const UUID &getUUID(void) const {return _primaryServiceID; }
rgrover1 710:b2e1a2660ec2 66 uint16_t getHandle(void) const {return _handle; }
rgrover1 710:b2e1a2660ec2 67 uint8_t getCharacteristicCount(void) const {return _characteristicCount;}
rgrover1 710:b2e1a2660ec2 68 void setHandle(uint16_t handle) {_handle = handle;}
rgrover1 710:b2e1a2660ec2 69
rgrover1 710:b2e1a2660ec2 70 GattCharacteristic *getCharacteristic(uint8_t index) {
rgrover1 710:b2e1a2660ec2 71 if (index >= _characteristicCount) {
rgrover1 710:b2e1a2660ec2 72 return NULL;
rgrover1 710:b2e1a2660ec2 73 }
rgrover1 710:b2e1a2660ec2 74
rgrover1 710:b2e1a2660ec2 75 return _characteristics[index];
rgrover1 710:b2e1a2660ec2 76 }
rgrover1 710:b2e1a2660ec2 77
rgrover1 710:b2e1a2660ec2 78 private:
rgrover1 710:b2e1a2660ec2 79 UUID _primaryServiceID;
rgrover1 710:b2e1a2660ec2 80 uint8_t _characteristicCount;
rgrover1 710:b2e1a2660ec2 81 GattCharacteristic **_characteristics;
rgrover1 710:b2e1a2660ec2 82 uint16_t _handle;
rgrover1 710:b2e1a2660ec2 83 };
rgrover1 710:b2e1a2660ec2 84
rgrover1 710:b2e1a2660ec2 85 #endif // ifndef __GATT_SERVICE_H__