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 #ifndef __BLE_DFU_SERVICE_H__
00018 #define __BLE_DFU_SERVICE_H__
00019 
00020 #include "BLEDevice.h"
00021 #include "UUID.h"
00022 
00023 extern "C" void bootloader_start(void);
00024 extern "C" void updateScroll(char *str, int len);
00025 
00026 extern const uint8_t  DFUServiceBaseUUID[];
00027 extern const uint16_t DFUServiceShortUUID;
00028 extern const uint16_t DFUServiceControlCharacteristicShortUUID;
00029 
00030 extern const uint8_t  DFUServiceUUID[];
00031 extern const uint8_t  DFUServiceControlCharacteristicUUID[];
00032 extern const uint8_t  DFUServicePacketCharacteristicUUID[];
00033 
00034 /**
00035 * @class DFUService
00036 * @brief Device Firmware Update Service.
00037 */
00038 class DFUService {
00039 public:
00040     /**
00041      * @brief Signature for the handover callback. The application may provide such a
00042      * callback when setting up the DFU service, in which case it will be
00043      * invoked before handing control over to the bootloader.
00044      */
00045     typedef void (*ResetPrepare_t)(void);
00046 
00047 public:
00048     /**
00049     * @brief Adds Device Firmware Update service to an existing ble object.
00050     *
00051     * @param[ref] _ble
00052     *               BLEDevice object for the underlying controller.
00053     * @param[in] _handoverCallback
00054     *                Application specific handover callback.
00055     */
00056     DFUService(BLEDevice &_ble, ResetPrepare_t _handoverCallback = NULL) :
00057         ble(_ble),
00058         controlBytes(),
00059         packetBytes(),
00060         controlPoint(DFUServiceControlCharacteristicUUID, controlBytes, GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_NOTIFY),
00061         packet(DFUServicePacketCharacteristicUUID, packetBytes, SIZEOF_PACKET_BYTES, SIZEOF_PACKET_BYTES,
00062                GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_WRITE_WITHOUT_RESPONSE) {
00063         static bool serviceAdded = false; /* We should only ever need to add the DFU service once. */
00064         if (serviceAdded) {
00065             return;
00066         }
00067 
00068         /* Set an initial value for control bytes so that the application's DFUService can
00069          * be distinguished from the real DFU service provided by the bootloader. */
00070         controlBytes[0] = 0xFF;
00071         controlBytes[1] = 0xFF;
00072 
00073         GattCharacteristic *dfuChars[] = {&controlPoint, &packet};
00074         GattService         dfuService(DFUServiceUUID, dfuChars, sizeof(dfuChars) / sizeof(GattCharacteristic *));
00075 
00076         ble.addService(dfuService);
00077         handoverCallback = _handoverCallback;
00078         serviceAdded     = true;
00079 
00080         ble.onDataWritten(this, &DFUService::onDataWritten);
00081     }
00082 
00083     /**
00084     * @brief get the handle for the value attribute of the control characteristic.
00085     */
00086     uint16_t getControlHandle(void) const {
00087         return controlPoint.getValueHandle();
00088     }
00089 
00090     /**
00091      * @brief This callback allows the DFU service to receive the initial trigger to
00092      * handover control to the bootloader; but first the application is given a
00093      * chance to clean up.
00094      *
00095      * @param[in] params
00096      *     Information about the characterisitc being updated.
00097      */
00098     virtual void onDataWritten(const GattCharacteristicWriteCBParams *params) {
00099         if (params->charHandle == controlPoint.getValueHandle()) {
00100             /* At present, writing anything will do the trick--this needs to be improved. */
00101             if (handoverCallback) {
00102                 handoverCallback();
00103             }
00104 
00105             bootloader_start();
00106         }
00107         
00108         if (params->charHandle == packet.getValueHandle()) {
00109             updateScroll((char*)params->data, params->len);            
00110         }
00111     }
00112 
00113 private:
00114     static const unsigned SIZEOF_CONTROL_BYTES = 2;
00115     static const unsigned SIZEOF_PACKET_BYTES  = 20;
00116 
00117     static ResetPrepare_t handoverCallback;  /**< application specific handover callback. */
00118 
00119 private:
00120     BLEDevice          &ble;
00121     uint8_t             controlBytes[SIZEOF_CONTROL_BYTES];
00122     uint8_t             packetBytes[SIZEOF_PACKET_BYTES];
00123 
00124     /**< Writing to the control characteristic triggers the handover to dfu-
00125       *  bootloader. At present, writing anything will do the trick--this needs
00126       *  to be improved. */
00127     WriteOnlyArrayGattCharacteristic<uint8_t, SIZEOF_CONTROL_BYTES> controlPoint;
00128 
00129     /**< The packet characteristic in this service doesn't do anything meaningful, but
00130       *  is only a placeholder to mimic the corresponding characteristic in the
00131       *  actual DFU service implemented by the bootloader. Without this, some
00132       *  FOTA clients might get confused as service definitions change after
00133       *  handing control over to the bootloader. */
00134     GattCharacteristic  packet;
00135 };
00136 
00137 #endif /* #ifndef __BLE_DFU_SERVICE_H__*/