YUFEI JIANG / BLE_API_Tiny_BLE

BLE_API_Tiny_BLE

Dependents:   CSSE4011_BLE_IMU

Fork of BLE_API by Bluetooth Low Energy

public/GattServer.h@118:620d28e7a1ba, 2014-09-22 (annotated)

Committer:
Rohit Grover
Date:
Mon Sep 22 10:59:09 2014 +0100
Revision:
118:620d28e7a1ba
Parent:
116:ca826083980e
Child:
126:fdebe4d5d62f
Release 0.2.0

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



Highlights:

  Introducing standard services to simplify applications.

  Add support for over-the-air firmware updates.



Features

~~~~~~~~



- This release introduces 'templates' for common services such as heart-rate,

  battery-level, device-info, UART, device-firmware-update etc. These services

  take the shape of class declarations within header files aggregated under a

  new folder called 'services/'. These service-classes provide a high-level

  API hopefully easing the burden of developing BLE applications. The

  underlying APIs to work with characteristics and services are still

  available to allow greater control if needed. We expect to grow the

  supported services to include all SIG defined BLE profiles.



- WriteCallbackParams now includes the characteristic's value-attribute

  handle; this changes the signature of onDataWritten().



- BLEDevice::onDataWritten() now allows chaining of callbacks--this means that

  it is possible to chain together multiple onDataWritten callbacks

  (potentially from different modules of an application) to receive updates to

  characteristics. Many services, such as DFU and UART add their own

  onDataWritten callbacks behind the scenes to trap interesting events. It is

  also possible to chain callbacks to functions within objects.



- Added the following expectation for GattCharacteristic: If valuePtr ==

  NULL, initialLength == 0, and properties == READ for the value attribute of

  a characteristic, then that particular characteristic may be considered

  optional and dropped while instantiating the service with the underlying BLE

  stack.



- Introducing the typedef GattAttribute::Handle_t to capture Attribute handles.



Bugfixes

~~~~~~~~



None.



Compatibility

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



The signature of onDataWritten() has seen a change; so application programs

using this new version of the BLE API will need minor modifications. Please

refer to sample programs under BLE team page.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Rohit Grover 106:a20be740075d 1 /* mbed Microcontroller Library
Rohit Grover 106:a20be740075d 2 * Copyright (c) 2006-2013 ARM Limited
Rohit Grover 106:a20be740075d 3 *
Rohit Grover 106:a20be740075d 4 * Licensed under the Apache License, Version 2.0 (the "License");
Rohit Grover 106:a20be740075d 5 * you may not use this file except in compliance with the License.
Rohit Grover 106:a20be740075d 6 * You may obtain a copy of the License at
Rohit Grover 106:a20be740075d 7 *
Rohit Grover 106:a20be740075d 8 * http://www.apache.org/licenses/LICENSE-2.0
Rohit Grover 106:a20be740075d 9 *
Rohit Grover 106:a20be740075d 10 * Unless required by applicable law or agreed to in writing, software
Rohit Grover 106:a20be740075d 11 * distributed under the License is distributed on an "AS IS" BASIS,
Rohit Grover 106:a20be740075d 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
Rohit Grover 106:a20be740075d 13 * See the License for the specific language governing permissions and
Rohit Grover 106:a20be740075d 14 * limitations under the License.
Rohit Grover 106:a20be740075d 15 */
Rohit Grover 106:a20be740075d 16
Rohit Grover 106:a20be740075d 17 #ifndef __GATT_SERVER_H__
Rohit Grover 106:a20be740075d 18 #define __GATT_SERVER_H__
Rohit Grover 106:a20be740075d 19
Rohit Grover 106:a20be740075d 20 #include "mbed.h"
Rohit Grover 106:a20be740075d 21 #include "blecommon.h"
Rohit Grover 106:a20be740075d 22 #include "GattService.h"
Rohit Grover 106:a20be740075d 23 #include "GattServerEvents.h"
Rohit Grover 116:ca826083980e 24 #include "GattCharacteristicWriteCBParams.h"
Rohit Grover 118:620d28e7a1ba 25 #include "CallChainOfFunctionPointersWithContext.h"
Rohit Grover 106:a20be740075d 26
Rohit Grover 106:a20be740075d 27 /**************************************************************************/
Rohit Grover 106:a20be740075d 28 /*!
Rohit Grover 106:a20be740075d 29 \brief
Rohit Grover 106:a20be740075d 30 The base class used to abstract GATT Server functionality to a specific
Rohit Grover 106:a20be740075d 31 radio transceiver, SOC or BLE Stack.
Rohit Grover 106:a20be740075d 32 */
Rohit Grover 106:a20be740075d 33 /**************************************************************************/
Rohit Grover 106:a20be740075d 34 class GattServer
Rohit Grover 106:a20be740075d 35 {
Rohit Grover 106:a20be740075d 36 public:
Rohit Grover 106:a20be740075d 37 /* These functions must be defined in the sub-class */
Rohit Grover 106:a20be740075d 38 virtual ble_error_t addService(GattService &) = 0;
Rohit Grover 106:a20be740075d 39 virtual ble_error_t readValue(uint16_t handle, uint8_t buffer[], uint16_t *const lengthP) = 0;
Rohit Grover 106:a20be740075d 40 virtual ble_error_t updateValue(uint16_t, uint8_t[], uint16_t, bool localOnly = false) = 0;
Rohit Grover 106:a20be740075d 41
Rohit Grover 106:a20be740075d 42 // ToDo: For updateValue, check the CCCD to see if the value we are
Rohit Grover 106:a20be740075d 43 // updating has the notify or indicate bits sent, and if BOTH are set
Rohit Grover 106:a20be740075d 44 // be sure to call sd_ble_gatts_hvx() twice with notify then indicate!
Rohit Grover 106:a20be740075d 45 // Strange use case, but valid and must be covered!
Rohit Grover 106:a20be740075d 46
Rohit Grover 106:a20be740075d 47 /* Event callback handlers. */
Rohit Grover 106:a20be740075d 48 typedef void (*EventCallback_t)(uint16_t attributeHandle);
Rohit Grover 116:ca826083980e 49 typedef void (*ServerEventCallback_t)(void); /**< independent of any particular attribute */
Rohit Grover 116:ca826083980e 50 typedef void (*ServerEventCallbackWithCount_t)(unsigned count); /**< independent of any particular attribute */
Rohit Grover 116:ca826083980e 51 void setOnDataSent(ServerEventCallbackWithCount_t callback) {
Rohit Grover 106:a20be740075d 52 onDataSent = callback;
Rohit Grover 106:a20be740075d 53 }
Rohit Grover 118:620d28e7a1ba 54 void setOnDataWritten(void (*callback)(const GattCharacteristicWriteCBParams *eventDataP)) {
Rohit Grover 118:620d28e7a1ba 55 onDataWritten.add(callback);
Rohit Grover 118:620d28e7a1ba 56 }
Rohit Grover 118:620d28e7a1ba 57 template <typename T>
Rohit Grover 118:620d28e7a1ba 58 void setOnDataWritten(T *objPtr, void (T::*memberPtr)(const GattCharacteristicWriteCBParams *context)) {
Rohit Grover 118:620d28e7a1ba 59 onDataWritten.add(objPtr, memberPtr);
Rohit Grover 106:a20be740075d 60 }
Rohit Grover 106:a20be740075d 61 void setOnUpdatesEnabled(EventCallback_t callback) {
Rohit Grover 106:a20be740075d 62 onUpdatesEnabled = callback;
Rohit Grover 106:a20be740075d 63 }
Rohit Grover 106:a20be740075d 64 void setOnUpdatesDisabled(EventCallback_t callback) {
Rohit Grover 106:a20be740075d 65 onUpdatesDisabled = callback;
Rohit Grover 106:a20be740075d 66 }
Rohit Grover 106:a20be740075d 67 void setOnConfirmationReceived(EventCallback_t callback) {
Rohit Grover 106:a20be740075d 68 onConfirmationReceived = callback;
Rohit Grover 106:a20be740075d 69 }
Rohit Grover 106:a20be740075d 70
Rohit Grover 118:620d28e7a1ba 71 void handleDataWrittenEvent(const GattCharacteristicWriteCBParams *params) {
Rohit Grover 118:620d28e7a1ba 72 if (onDataWritten.hasCallbacksAttached()) {
Rohit Grover 118:620d28e7a1ba 73 onDataWritten.call(params);
Rohit Grover 116:ca826083980e 74 }
Rohit Grover 116:ca826083980e 75 }
Rohit Grover 116:ca826083980e 76
Rohit Grover 106:a20be740075d 77 void handleEvent(GattServerEvents::gattEvent_e type, uint16_t charHandle) {
Rohit Grover 106:a20be740075d 78 switch (type) {
Rohit Grover 106:a20be740075d 79 case GattServerEvents::GATT_EVENT_UPDATES_ENABLED:
Rohit Grover 106:a20be740075d 80 if (onUpdatesEnabled) {
Rohit Grover 106:a20be740075d 81 onUpdatesEnabled(charHandle);
Rohit Grover 106:a20be740075d 82 }
Rohit Grover 106:a20be740075d 83 break;
Rohit Grover 106:a20be740075d 84 case GattServerEvents::GATT_EVENT_UPDATES_DISABLED:
Rohit Grover 106:a20be740075d 85 if (onUpdatesDisabled) {
Rohit Grover 106:a20be740075d 86 onUpdatesDisabled(charHandle);
Rohit Grover 106:a20be740075d 87 }
Rohit Grover 106:a20be740075d 88 break;
Rohit Grover 106:a20be740075d 89 case GattServerEvents::GATT_EVENT_CONFIRMATION_RECEIVED:
Rohit Grover 106:a20be740075d 90 if (onConfirmationReceived) {
Rohit Grover 106:a20be740075d 91 onConfirmationReceived(charHandle);
Rohit Grover 106:a20be740075d 92 }
Rohit Grover 106:a20be740075d 93 break;
Rohit Grover 106:a20be740075d 94 }
Rohit Grover 106:a20be740075d 95 }
Rohit Grover 106:a20be740075d 96
Rohit Grover 116:ca826083980e 97 void handleDataSentEvent(unsigned count) {
Rohit Grover 116:ca826083980e 98 if (onDataSent) {
Rohit Grover 116:ca826083980e 99 onDataSent(count);
Rohit Grover 106:a20be740075d 100 }
Rohit Grover 106:a20be740075d 101 }
Rohit Grover 106:a20be740075d 102
Rohit Grover 106:a20be740075d 103 protected:
Rohit Grover 118:620d28e7a1ba 104 GattServer() : serviceCount(0), characteristicCount(0), onDataSent(NULL), onDataWritten(), onUpdatesEnabled(NULL), onUpdatesDisabled(NULL), onConfirmationReceived(NULL) {
Rohit Grover 106:a20be740075d 105 /* empty */
Rohit Grover 106:a20be740075d 106 }
Rohit Grover 106:a20be740075d 107
Rohit Grover 106:a20be740075d 108 protected:
Rohit Grover 106:a20be740075d 109 uint8_t serviceCount;
Rohit Grover 106:a20be740075d 110 uint8_t characteristicCount;
carlescufi 114:f1ede142a78f 111 uint8_t descriptorCount;
Rohit Grover 106:a20be740075d 112
Rohit Grover 106:a20be740075d 113 private:
Rohit Grover 116:ca826083980e 114 ServerEventCallbackWithCount_t onDataSent;
Rohit Grover 118:620d28e7a1ba 115 CallChainOfFunctionPointersWithContext<const GattCharacteristicWriteCBParams *> onDataWritten;
Rohit Grover 116:ca826083980e 116 EventCallback_t onUpdatesEnabled;
Rohit Grover 116:ca826083980e 117 EventCallback_t onUpdatesDisabled;
Rohit Grover 116:ca826083980e 118 EventCallback_t onConfirmationReceived;
Rohit Grover 106:a20be740075d 119 };
Rohit Grover 106:a20be740075d 120
Rohit Grover 106:a20be740075d 121 #endif // ifndef __GATT_SERVER_H__