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 
00025 extern const uint8_t  DFUServiceBaseUUID[];
00026 extern const uint16_t DFUServiceShortUUID;
00027 extern const uint16_t DFUServiceControlCharacteristicShortUUID;
00028 
00029 extern const uint8_t  DFUServiceUUID[];
00030 extern const uint8_t  DFUServiceControlCharacteristicUUID[];
00031 extern const uint8_t  DFUServicePacketCharacteristicUUID[];
00032 
00033 class DFUService {
00034 public:
00035     /**
00036      * Signature for the handover callback. The application may provide such a
00037      * callback when setting up the DFU service, in which case it will be
00038      * invoked before handing control over to the bootloader.
00039      */
00040     typedef void (*ResetPrepare_t)(void);
00041 
00042 public:
00043     DFUService(BLEDevice &_ble, ResetPrepare_t _handoverCallback = NULL) :
00044         ble(_ble),
00045         controlBytes(),
00046         packetBytes(),
00047         controlPoint(DFUServiceControlCharacteristicUUID, controlBytes, SIZEOF_CONTROL_BYTES, SIZEOF_CONTROL_BYTES,
00048                      GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_WRITE | GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_NOTIFY),
00049         packet(DFUServicePacketCharacteristicUUID, packetBytes, SIZEOF_PACKET_BYTES, SIZEOF_PACKET_BYTES,
00050                GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_WRITE_WITHOUT_RESPONSE) {
00051         static bool serviceAdded = false; /* We should only ever need to add the DFU service once. */
00052         if (serviceAdded) {
00053             return;
00054         }
00055 
00056         /* Set an initial value for control bytes so that the application's DFUService can
00057          * be distinguished from the real DFU service provided by the bootloader. */
00058         controlBytes[0] = 0xFF;
00059         controlBytes[1] = 0xFF;
00060 
00061         GattCharacteristic *dfuChars[] = {&controlPoint, &packet};
00062         GattService         dfuService(DFUServiceUUID, dfuChars, sizeof(dfuChars) / sizeof(GattCharacteristic *));
00063 
00064         ble.addService(dfuService);
00065         handoverCallback = _handoverCallback;
00066         serviceAdded = true;
00067 
00068         ble.onDataWritten(this, &DFUService::onDataWritten);
00069     }
00070 
00071     uint16_t getControlHandle(void) {
00072         return controlPoint.getValueAttribute().getHandle();
00073     }
00074 
00075     /**
00076      * This callback allows the DFU service to receive the initial trigger to
00077      * handover control to the bootloader; but first the application is given a
00078      * chance to clean up.
00079      */
00080     virtual void onDataWritten(const GattCharacteristicWriteCBParams *params) {
00081         if (params->charHandle == controlPoint.getValueAttribute().getHandle()) {
00082             /* At present, writing anything will do the trick--this needs to be improved. */
00083             if (handoverCallback) {
00084                 handoverCallback();
00085             }
00086 
00087             bootloader_start();
00088         }
00089     }
00090 
00091 private:
00092     static const unsigned SIZEOF_CONTROL_BYTES = 2;
00093     static const unsigned SIZEOF_PACKET_BYTES  = 20;
00094 
00095     static ResetPrepare_t handoverCallback;  /**< application specific handover callback. */
00096 
00097 private:
00098     BLEDevice          &ble;
00099     uint8_t             controlBytes[SIZEOF_CONTROL_BYTES];
00100     uint8_t             packetBytes[SIZEOF_PACKET_BYTES];
00101 
00102     /**< Writing to the control characteristic triggers the handover to dfu-
00103       *  bootloader. At present, writing anything will do the trick--this needs
00104       *  to be improved. */
00105     GattCharacteristic  controlPoint;
00106 
00107     /**< The packet characteristic in this service doesn't do anything meaningful, but
00108       *  is only a placeholder to mimic the corresponding characteristic in the
00109       *  actual DFU service implemented by the bootloader. Without this, some
00110       *  FOTA clients might get confused as service definitions change after
00111       *  handing control over to the bootloader. */
00112     GattCharacteristic  packet;
00113 };
00114 
00115 #endif /* #ifndef __BLE_DFU_SERVICE_H__*/