Austin Blackstone / BLE_API

Fixes to BLE_API for mbedOS Alpha1 release. Mostly relating to doxygen fixes.

Fork of BLE_API by Bluetooth Low Energy

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

Committer:
Rohit Grover
Date:
Mon Sep 22 10:59:09 2014 +0100
Revision:
118:620d28e7a1ba
Child:
119:18684018b83e
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 118:620d28e7a1ba 1 /* mbed Microcontroller Library
Rohit Grover 118:620d28e7a1ba 2 * Copyright (c) 2006-2013 ARM Limited
Rohit Grover 118:620d28e7a1ba 3 *
Rohit Grover 118:620d28e7a1ba 4 * Licensed under the Apache License, Version 2.0 (the "License");
Rohit Grover 118:620d28e7a1ba 5 * you may not use this file except in compliance with the License.
Rohit Grover 118:620d28e7a1ba 6 * You may obtain a copy of the License at
Rohit Grover 118:620d28e7a1ba 7 *
Rohit Grover 118:620d28e7a1ba 8 * http://www.apache.org/licenses/LICENSE-2.0
Rohit Grover 118:620d28e7a1ba 9 *
Rohit Grover 118:620d28e7a1ba 10 * Unless required by applicable law or agreed to in writing, software
Rohit Grover 118:620d28e7a1ba 11 * distributed under the License is distributed on an "AS IS" BASIS,
Rohit Grover 118:620d28e7a1ba 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
Rohit Grover 118:620d28e7a1ba 13 * See the License for the specific language governing permissions and
Rohit Grover 118:620d28e7a1ba 14 * limitations under the License.
Rohit Grover 118:620d28e7a1ba 15 */
Rohit Grover 118:620d28e7a1ba 16
Rohit Grover 118:620d28e7a1ba 17 #ifndef __BLE_DFU_SERVICE_H__
Rohit Grover 118:620d28e7a1ba 18 #define __BLE_DFU_SERVICE_H__
Rohit Grover 118:620d28e7a1ba 19
Rohit Grover 118:620d28e7a1ba 20 #include "BLEDevice.h"
Rohit Grover 118:620d28e7a1ba 21 #include "UUID.h"
Rohit Grover 118:620d28e7a1ba 22
Rohit Grover 118:620d28e7a1ba 23 extern "C" void bootloader_start(void);
Rohit Grover 118:620d28e7a1ba 24
Rohit Grover 118:620d28e7a1ba 25 extern const uint8_t DFUServiceBaseUUID[];
Rohit Grover 118:620d28e7a1ba 26 extern const uint16_t DFUServiceShortUUID;
Rohit Grover 118:620d28e7a1ba 27 extern const uint16_t DFUServiceControlCharacteristicShortUUID;
Rohit Grover 118:620d28e7a1ba 28
Rohit Grover 118:620d28e7a1ba 29 extern const uint8_t DFUServiceUUID[];
Rohit Grover 118:620d28e7a1ba 30 extern const uint8_t DFUServiceControlCharacteristicUUID[];
Rohit Grover 118:620d28e7a1ba 31
Rohit Grover 118:620d28e7a1ba 32 class DFUService {
Rohit Grover 118:620d28e7a1ba 33 public:
Rohit Grover 118:620d28e7a1ba 34 /**
Rohit Grover 118:620d28e7a1ba 35 * Signature for the handover callback. The application may provide such a
Rohit Grover 118:620d28e7a1ba 36 * callback when setting up the DFU service, in which case it will be
Rohit Grover 118:620d28e7a1ba 37 * invoked before handing control over to the Bootloader.
Rohit Grover 118:620d28e7a1ba 38 */
Rohit Grover 118:620d28e7a1ba 39 typedef void (*ResetPrepare_t)(void);
Rohit Grover 118:620d28e7a1ba 40
Rohit Grover 118:620d28e7a1ba 41 public:
Rohit Grover 118:620d28e7a1ba 42 DFUService(BLEDevice &_ble, ResetPrepare_t _handoverCallback = NULL) :
Rohit Grover 118:620d28e7a1ba 43 ble(_ble),
Rohit Grover 118:620d28e7a1ba 44 controlBytes(),
Rohit Grover 118:620d28e7a1ba 45 controlPoint(DFUServiceControlCharacteristicUUID, controlBytes, SIZEOF_CONTROL_BYTES, SIZEOF_CONTROL_BYTES,
Rohit Grover 118:620d28e7a1ba 46 GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_WRITE | GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_NOTIFY) {
Rohit Grover 118:620d28e7a1ba 47 static bool serviceAdded = false; /* We should only ever need to add the DFU service once. */
Rohit Grover 118:620d28e7a1ba 48 if (serviceAdded) {
Rohit Grover 118:620d28e7a1ba 49 return;
Rohit Grover 118:620d28e7a1ba 50 }
Rohit Grover 118:620d28e7a1ba 51
Rohit Grover 118:620d28e7a1ba 52 GattCharacteristic *dfuChars[] = {&controlPoint};
Rohit Grover 118:620d28e7a1ba 53 GattService dfuService(DFUServiceUUID, dfuChars, sizeof(dfuChars) / sizeof(GattCharacteristic *));
Rohit Grover 118:620d28e7a1ba 54
Rohit Grover 118:620d28e7a1ba 55 ble.addService(dfuService);
Rohit Grover 118:620d28e7a1ba 56 handoverCallback = _handoverCallback;
Rohit Grover 118:620d28e7a1ba 57 serviceAdded = true;
Rohit Grover 118:620d28e7a1ba 58
Rohit Grover 118:620d28e7a1ba 59 ble.onDataWritten(this, &DFUService::onDataWritten);
Rohit Grover 118:620d28e7a1ba 60 }
Rohit Grover 118:620d28e7a1ba 61
Rohit Grover 118:620d28e7a1ba 62 uint16_t getControlHandle(void) {
Rohit Grover 118:620d28e7a1ba 63 return controlPoint.getValueAttribute().getHandle();
Rohit Grover 118:620d28e7a1ba 64 }
Rohit Grover 118:620d28e7a1ba 65
Rohit Grover 118:620d28e7a1ba 66 /**
Rohit Grover 118:620d28e7a1ba 67 * This callback allows the DFU service to receive the initial trigger to
Rohit Grover 118:620d28e7a1ba 68 * handover control to the bootloader; but first the application is given a
Rohit Grover 118:620d28e7a1ba 69 * chance to clean up.
Rohit Grover 118:620d28e7a1ba 70 */
Rohit Grover 118:620d28e7a1ba 71 virtual void onDataWritten(const GattCharacteristicWriteCBParams *params) {
Rohit Grover 118:620d28e7a1ba 72 if (params->charHandle == controlPoint.getValueAttribute().getHandle()) {
Rohit Grover 118:620d28e7a1ba 73 if (handoverCallback) {
Rohit Grover 118:620d28e7a1ba 74 handoverCallback();
Rohit Grover 118:620d28e7a1ba 75 }
Rohit Grover 118:620d28e7a1ba 76
Rohit Grover 118:620d28e7a1ba 77 bootloader_start();
Rohit Grover 118:620d28e7a1ba 78 }
Rohit Grover 118:620d28e7a1ba 79 }
Rohit Grover 118:620d28e7a1ba 80
Rohit Grover 118:620d28e7a1ba 81 private:
Rohit Grover 118:620d28e7a1ba 82 static const unsigned SIZEOF_CONTROL_BYTES = 2;
Rohit Grover 118:620d28e7a1ba 83
Rohit Grover 118:620d28e7a1ba 84 static ResetPrepare_t handoverCallback; /**< application specific handover callback. */
Rohit Grover 118:620d28e7a1ba 85
Rohit Grover 118:620d28e7a1ba 86 private:
Rohit Grover 118:620d28e7a1ba 87 BLEDevice &ble;
Rohit Grover 118:620d28e7a1ba 88 uint8_t controlBytes[SIZEOF_CONTROL_BYTES];
Rohit Grover 118:620d28e7a1ba 89 GattCharacteristic controlPoint;
Rohit Grover 118:620d28e7a1ba 90 };
Rohit Grover 118:620d28e7a1ba 91
Rohit Grover 118:620d28e7a1ba 92 #endif /* #ifndef __BLE_DFU_SERVICE_H__*/