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/services/DFUService.h@1053:ec4a5b9b254e, 2016-01-11 (annotated)

Committer:
vcoubard
Date:
Mon Jan 11 08:51:32 2016 +0000
Revision:
1053:ec4a5b9b254e
Parent:
1052:b55e1ad3e1b3 
Synchronized with git rev 13bf70b6

Author: Rohit Grover

Release 2.1.5

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



A minor release to separate the concept of minlen and len in

GattCharacteristic. Also contains some improvements to documentation.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
rgrover1 712:b04b5db36865 1 /* mbed Microcontroller Library
rgrover1 712:b04b5db36865 2 * Copyright (c) 2006-2013 ARM Limited
rgrover1 712:b04b5db36865 3 *
rgrover1 712:b04b5db36865 4 * Licensed under the Apache License, Version 2.0 (the "License");
rgrover1 712:b04b5db36865 5 * you may not use this file except in compliance with the License.
rgrover1 712:b04b5db36865 6 * You may obtain a copy of the License at
rgrover1 712:b04b5db36865 7 *
rgrover1 712:b04b5db36865 8 * http://www.apache.org/licenses/LICENSE-2.0
rgrover1 712:b04b5db36865 9 *
rgrover1 712:b04b5db36865 10 * Unless required by applicable law or agreed to in writing, software
rgrover1 712:b04b5db36865 11 * distributed under the License is distributed on an "AS IS" BASIS,
rgrover1 712:b04b5db36865 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
rgrover1 712:b04b5db36865 13 * See the License for the specific language governing permissions and
rgrover1 712:b04b5db36865 14 * limitations under the License.
rgrover1 712:b04b5db36865 15 */
rgrover1 712:b04b5db36865 16
vcoubard 1053:ec4a5b9b254e 17 #ifdef TARGET_NRF51822 /* DFU only supported on nrf51 platforms */
vcoubard 1053:ec4a5b9b254e 18
rgrover1 712:b04b5db36865 19 #ifndef __BLE_DFU_SERVICE_H__
rgrover1 712:b04b5db36865 20 #define __BLE_DFU_SERVICE_H__
rgrover1 712:b04b5db36865 21
rgrover1 712:b04b5db36865 22 #include "ble/BLE.h"
rgrover1 712:b04b5db36865 23 #include "ble/UUID.h"
rgrover1 712:b04b5db36865 24
vcoubard 1053:ec4a5b9b254e 25 extern "C" {
vcoubard 1053:ec4a5b9b254e 26 #include "dfu_app_handler.h"
vcoubard 1053:ec4a5b9b254e 27 }
rgrover1 712:b04b5db36865 28
rgrover1 712:b04b5db36865 29 extern const uint8_t DFUServiceBaseUUID[];
rgrover1 712:b04b5db36865 30 extern const uint16_t DFUServiceShortUUID;
rgrover1 712:b04b5db36865 31 extern const uint16_t DFUServiceControlCharacteristicShortUUID;
rgrover1 712:b04b5db36865 32
rgrover1 712:b04b5db36865 33 extern const uint8_t DFUServiceUUID[];
rgrover1 712:b04b5db36865 34 extern const uint8_t DFUServiceControlCharacteristicUUID[];
rgrover1 712:b04b5db36865 35 extern const uint8_t DFUServicePacketCharacteristicUUID[];
rgrover1 712:b04b5db36865 36
rgrover1 712:b04b5db36865 37 /**
rgrover1 712:b04b5db36865 38 * @class DFUService
rgrover1 712:b04b5db36865 39 * @brief Device Firmware Update Service.
rgrover1 712:b04b5db36865 40 */
rgrover1 712:b04b5db36865 41 class DFUService {
rgrover1 712:b04b5db36865 42 public:
rgrover1 712:b04b5db36865 43 /**
vcoubard 1052:b55e1ad3e1b3 44 * @brief Signature for the handover callback. The application may provide this
vcoubard 1052:b55e1ad3e1b3 45 * callback when setting up the DFU service. The callback is then
rgrover1 712:b04b5db36865 46 * invoked before handing control over to the bootloader.
rgrover1 712:b04b5db36865 47 */
rgrover1 712:b04b5db36865 48 typedef void (*ResetPrepare_t)(void);
rgrover1 712:b04b5db36865 49
rgrover1 712:b04b5db36865 50 public:
rgrover1 712:b04b5db36865 51 /**
vcoubard 1052:b55e1ad3e1b3 52 * @brief Adds Device Firmware Update Service to an existing BLE object.
rgrover1 712:b04b5db36865 53 *
rgrover1 712:b04b5db36865 54 * @param[ref] _ble
rgrover1 712:b04b5db36865 55 * BLE object for the underlying controller.
rgrover1 712:b04b5db36865 56 * @param[in] _handoverCallback
vcoubard 1052:b55e1ad3e1b3 57 * Application-specific handover callback.
rgrover1 712:b04b5db36865 58 */
rgrover1 712:b04b5db36865 59 DFUService(BLE &_ble, ResetPrepare_t _handoverCallback = NULL) :
rgrover1 712:b04b5db36865 60 ble(_ble),
rgrover1 712:b04b5db36865 61 controlPoint(DFUServiceControlCharacteristicUUID, controlBytes, GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_NOTIFY),
rgrover1 712:b04b5db36865 62 packet(DFUServicePacketCharacteristicUUID, packetBytes, SIZEOF_PACKET_BYTES, SIZEOF_PACKET_BYTES,
rgrover1 712:b04b5db36865 63 GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_WRITE_WITHOUT_RESPONSE),
rgrover1 712:b04b5db36865 64 controlBytes(),
rgrover1 712:b04b5db36865 65 packetBytes() {
vcoubard 1052:b55e1ad3e1b3 66 static bool serviceAdded = false; /* We only add the DFU service once. */
rgrover1 712:b04b5db36865 67 if (serviceAdded) {
rgrover1 712:b04b5db36865 68 return;
rgrover1 712:b04b5db36865 69 }
rgrover1 712:b04b5db36865 70
vcoubard 1052:b55e1ad3e1b3 71 /* Set an initial value for control bytes, so that the application's DFU service can
rgrover1 712:b04b5db36865 72 * be distinguished from the real DFU service provided by the bootloader. */
rgrover1 712:b04b5db36865 73 controlBytes[0] = 0xFF;
rgrover1 712:b04b5db36865 74 controlBytes[1] = 0xFF;
rgrover1 712:b04b5db36865 75
rgrover1 712:b04b5db36865 76 GattCharacteristic *dfuChars[] = {&controlPoint, &packet};
rgrover1 712:b04b5db36865 77 GattService dfuService(DFUServiceUUID, dfuChars, sizeof(dfuChars) / sizeof(GattCharacteristic *));
rgrover1 712:b04b5db36865 78
rgrover1 712:b04b5db36865 79 ble.addService(dfuService);
rgrover1 712:b04b5db36865 80 handoverCallback = _handoverCallback;
rgrover1 712:b04b5db36865 81 serviceAdded = true;
rgrover1 712:b04b5db36865 82
rgrover1 712:b04b5db36865 83 ble.onDataWritten(this, &DFUService::onDataWritten);
rgrover1 712:b04b5db36865 84 }
rgrover1 712:b04b5db36865 85
rgrover1 712:b04b5db36865 86 /**
vcoubard 1052:b55e1ad3e1b3 87 * @brief Get the handle for the value attribute of the control characteristic.
rgrover1 712:b04b5db36865 88 */
rgrover1 712:b04b5db36865 89 uint16_t getControlHandle(void) const {
rgrover1 712:b04b5db36865 90 return controlPoint.getValueHandle();
rgrover1 712:b04b5db36865 91 }
rgrover1 712:b04b5db36865 92
rgrover1 712:b04b5db36865 93 /**
rgrover1 712:b04b5db36865 94 * @brief This callback allows the DFU service to receive the initial trigger to
vcoubard 1052:b55e1ad3e1b3 95 * hand control over to the bootloader. First, the application is given a
rgrover1 712:b04b5db36865 96 * chance to clean up.
rgrover1 712:b04b5db36865 97 *
rgrover1 712:b04b5db36865 98 * @param[in] params
rgrover1 712:b04b5db36865 99 * Information about the characterisitc being updated.
rgrover1 712:b04b5db36865 100 */
rgrover1 712:b04b5db36865 101 virtual void onDataWritten(const GattWriteCallbackParams *params) {
rgrover1 712:b04b5db36865 102 if (params->handle == controlPoint.getValueHandle()) {
vcoubard 1052:b55e1ad3e1b3 103 /* At present, writing anything will do the trick - this needs to be improved. */
rgrover1 712:b04b5db36865 104 if (handoverCallback) {
rgrover1 712:b04b5db36865 105 handoverCallback();
rgrover1 712:b04b5db36865 106 }
rgrover1 712:b04b5db36865 107
vcoubard 1053:ec4a5b9b254e 108 // Call bootloader_start implicitly trough a event handler call
vcoubard 1053:ec4a5b9b254e 109 // it is a work around for bootloader_start not being public in sdk 8.1
vcoubard 1053:ec4a5b9b254e 110 ble_dfu_t p_dfu;
vcoubard 1053:ec4a5b9b254e 111 ble_dfu_evt_t p_evt;
vcoubard 1053:ec4a5b9b254e 112
vcoubard 1053:ec4a5b9b254e 113 p_dfu.conn_handle = params->connHandle;
vcoubard 1053:ec4a5b9b254e 114 p_evt.ble_dfu_evt_type = BLE_DFU_START;
vcoubard 1053:ec4a5b9b254e 115
vcoubard 1053:ec4a5b9b254e 116 dfu_app_on_dfu_evt(&p_dfu, &p_evt);
rgrover1 712:b04b5db36865 117 }
rgrover1 712:b04b5db36865 118 }
rgrover1 712:b04b5db36865 119
rgrover1 712:b04b5db36865 120 protected:
rgrover1 712:b04b5db36865 121 static const unsigned SIZEOF_CONTROL_BYTES = 2;
rgrover1 712:b04b5db36865 122 static const unsigned SIZEOF_PACKET_BYTES = 20;
rgrover1 712:b04b5db36865 123
rgrover1 712:b04b5db36865 124 protected:
rgrover1 712:b04b5db36865 125 BLE &ble;
rgrover1 712:b04b5db36865 126
vcoubard 1052:b55e1ad3e1b3 127 /**< Writing to the control characteristic triggers the handover to DFU
vcoubard 1052:b55e1ad3e1b3 128 * bootloader. At present, writing anything will do the trick - this needs
rgrover1 712:b04b5db36865 129 * to be improved. */
rgrover1 712:b04b5db36865 130 WriteOnlyArrayGattCharacteristic<uint8_t, SIZEOF_CONTROL_BYTES> controlPoint;
rgrover1 712:b04b5db36865 131
vcoubard 1052:b55e1ad3e1b3 132 /**< The packet characteristic in this service doesn't do anything meaningful;
vcoubard 1052:b55e1ad3e1b3 133 * it is only a placeholder to mimic the corresponding characteristic in the
rgrover1 712:b04b5db36865 134 * actual DFU service implemented by the bootloader. Without this, some
vcoubard 1052:b55e1ad3e1b3 135 * FOTA clients might get confused, because service definitions change after
rgrover1 712:b04b5db36865 136 * handing control over to the bootloader. */
rgrover1 712:b04b5db36865 137 GattCharacteristic packet;
rgrover1 712:b04b5db36865 138
rgrover1 712:b04b5db36865 139 uint8_t controlBytes[SIZEOF_CONTROL_BYTES];
rgrover1 712:b04b5db36865 140 uint8_t packetBytes[SIZEOF_PACKET_BYTES];
rgrover1 712:b04b5db36865 141
vcoubard 1052:b55e1ad3e1b3 142 static ResetPrepare_t handoverCallback; /**< Application-specific handover callback. */
rgrover1 712:b04b5db36865 143 };
rgrover1 712:b04b5db36865 144
vcoubard 1053:ec4a5b9b254e 145 #endif /* #ifndef __BLE_DFU_SERVICE_H__*/
vcoubard 1053:ec4a5b9b254e 146 #endif /* #ifdef TARGET_NRF51822 */