DFUService.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2006-2013 ARM Limited
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 #ifdef TARGET_NRF51822 /* DFU only supported on nrf51 platforms */
00018 
00019 #ifndef __BLE_DFU_SERVICE_H__
00020 #define __BLE_DFU_SERVICE_H__
00021 
00022 #if BLE_FEATURE_GATT_SERVER
00023 
00024 #include "ble/BLE.h"
00025 #include "ble/UUID.h "
00026 
00027 extern "C" {
00028 #include "dfu_app_handler.h"
00029 }
00030 
00031 extern const uint8_t  DFUServiceBaseUUID[];
00032 extern const uint16_t DFUServiceShortUUID;
00033 extern const uint16_t DFUServiceControlCharacteristicShortUUID;
00034 
00035 extern const uint8_t  DFUServiceUUID[];
00036 extern const uint8_t  DFUServiceControlCharacteristicUUID[];
00037 extern const uint8_t  DFUServicePacketCharacteristicUUID[];
00038 
00039 /**
00040 * @class DFUService
00041 * @brief Device Firmware Update Service.
00042 */
00043 class DFUService {
00044 public:
00045     /**
00046      * @brief Signature for the handover callback. The application may provide this
00047      * callback when setting up the DFU service. The callback is then
00048      * invoked before handing control over to the bootloader.
00049      */
00050     typedef void (*ResetPrepare_t)(void);
00051 
00052 public:
00053     /**
00054     * @brief Adds Device Firmware Update Service to an existing BLE object.
00055     *
00056     * @param[ref] _ble
00057     *               BLE object for the underlying controller.
00058     * @param[in] _handoverCallback
00059     *                Application-specific handover callback.
00060     */
00061     DFUService(BLE &_ble, ResetPrepare_t _handoverCallback = NULL) :
00062         ble(_ble),
00063         controlPoint(DFUServiceControlCharacteristicUUID, controlBytes, GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_NOTIFY),
00064         packet(DFUServicePacketCharacteristicUUID, packetBytes, SIZEOF_PACKET_BYTES, SIZEOF_PACKET_BYTES,
00065                GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_WRITE_WITHOUT_RESPONSE),
00066         controlBytes(),
00067         packetBytes() {
00068         static bool serviceAdded = false; /* We only add the DFU service once. */
00069         if (serviceAdded) {
00070             return;
00071         }
00072 
00073         /* Set an initial value for control bytes, so that the application's DFU service can
00074          * be distinguished from the real DFU service provided by the bootloader. */
00075         controlBytes[0] = 0xFF;
00076         controlBytes[1] = 0xFF;
00077 
00078         GattCharacteristic *dfuChars[] = {&controlPoint, &packet};
00079         GattService         dfuService(DFUServiceUUID, dfuChars, sizeof(dfuChars) / sizeof(GattCharacteristic *));
00080 
00081         ble.addService(dfuService);
00082         handoverCallback = _handoverCallback;
00083         serviceAdded     = true;
00084 
00085         ble.onDataWritten(this, &DFUService::onDataWritten);
00086     }
00087 
00088     /**
00089     * @brief Get the handle for the value attribute of the control characteristic.
00090     */
00091     uint16_t getControlHandle(void) const {
00092         return controlPoint.getValueHandle();
00093     }
00094 
00095     /**
00096      * @brief This callback allows the DFU service to receive the initial trigger to
00097      * hand control over to the bootloader. First, the application is given a
00098      * chance to clean up.
00099      *
00100      * @param[in] params
00101      *     Information about the characteristic being updated.
00102      */
00103     virtual void onDataWritten(const GattWriteCallbackParams *params) {
00104         if (params->handle == controlPoint.getValueHandle()) {
00105             /* At present, writing anything will do the trick - this needs to be improved. */
00106             if (handoverCallback) {
00107                 handoverCallback();
00108             }
00109 
00110             // Call bootloader_start implicitly trough a event handler call
00111             // it is a work around for bootloader_start not being public in sdk 8.1
00112             ble_dfu_t p_dfu;
00113             ble_dfu_evt_t p_evt;
00114 
00115             p_dfu.conn_handle = params->connHandle;
00116             p_evt.ble_dfu_evt_type = BLE_DFU_START;
00117 
00118             dfu_app_on_dfu_evt(&p_dfu, &p_evt);
00119         }
00120     }
00121 
00122 protected:
00123     static const unsigned SIZEOF_CONTROL_BYTES = 2;
00124     static const unsigned SIZEOF_PACKET_BYTES  = 20;
00125 
00126 protected:
00127     BLE          &ble;
00128 
00129     /** Writing to the control characteristic triggers the handover to DFU
00130      *  bootloader. At present, writing anything will do the trick - this needs
00131      *  to be improved. */
00132     WriteOnlyArrayGattCharacteristic<uint8_t, SIZEOF_CONTROL_BYTES>  controlPoint;
00133 
00134     /** The packet characteristic in this service doesn't do anything meaningful;
00135      *  it is only a placeholder to mimic the corresponding characteristic in the
00136      *  actual DFU service implemented by the bootloader. Without this, some
00137      *  FOTA clients might get confused, because service definitions change after
00138      *  handing control over to the bootloader. */
00139     GattCharacteristic  packet;
00140 
00141     uint8_t             controlBytes[SIZEOF_CONTROL_BYTES];
00142     uint8_t             packetBytes[SIZEOF_PACKET_BYTES];
00143 
00144     static ResetPrepare_t handoverCallback;  /**< Application-specific handover callback. */
00145 };
00146 
00147 #endif // BLE_FEATURE_GATT_SERVER
00148 
00149 #endif /* #ifndef __BLE_DFU_SERVICE_H__*/
00150 #endif /* #ifdef TARGET_NRF51822 */