diff --git a/ble/services/DFUService.h b/ble/services/DFUService.h index 253890e..032489a 100644 --- a/ble/services/DFUService.h +++ b/ble/services/DFUService.h @@ -37,20 +37,20 @@ extern const uint8_t DFUServicePacketCharacteristicUUID[]; class DFUService { public: /** - * @brief Signature for the handover callback. The application may provide such a - * callback when setting up the DFU service, in which case it will be + * @brief Signature for the handover callback. The application may provide this + * callback when setting up the DFU service. The callback is then * invoked before handing control over to the bootloader. */ typedef void (*ResetPrepare_t)(void); public: /** - * @brief Adds Device Firmware Update service to an existing ble object. + * @brief Adds Device Firmware Update Service to an existing BLE object. * * @param[ref] _ble * BLE object for the underlying controller. * @param[in] _handoverCallback - * Application specific handover callback. + * Application-specific handover callback. */ DFUService(BLE &_ble, ResetPrepare_t _handoverCallback = NULL) : ble(_ble), @@ -59,12 +59,12 @@ public: GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_WRITE_WITHOUT_RESPONSE), controlBytes(), packetBytes() { - static bool serviceAdded = false; /* We should only ever need to add the DFU service once. */ + static bool serviceAdded = false; /* We only add the DFU service once. */ if (serviceAdded) { return; } - /* Set an initial value for control bytes so that the application's DFUService can + /* Set an initial value for control bytes, so that the application's DFU service can * be distinguished from the real DFU service provided by the bootloader. */ controlBytes[0] = 0xFF; controlBytes[1] = 0xFF; @@ -80,7 +80,7 @@ public: } /** - * @brief get the handle for the value attribute of the control characteristic. + * @brief Get the handle for the value attribute of the control characteristic. */ uint16_t getControlHandle(void) const { return controlPoint.getValueHandle(); @@ -88,7 +88,7 @@ public: /** * @brief This callback allows the DFU service to receive the initial trigger to - * handover control to the bootloader; but first the application is given a + * hand control over to the bootloader. First, the application is given a * chance to clean up. * * @param[in] params @@ -96,7 +96,7 @@ public: */ virtual void onDataWritten(const GattWriteCallbackParams *params) { if (params->handle == controlPoint.getValueHandle()) { - /* At present, writing anything will do the trick--this needs to be improved. */ + /* At present, writing anything will do the trick - this needs to be improved. */ if (handoverCallback) { handoverCallback(); } @@ -112,22 +112,22 @@ protected: protected: BLE &ble; - /**< Writing to the control characteristic triggers the handover to dfu- - * bootloader. At present, writing anything will do the trick--this needs + /**< Writing to the control characteristic triggers the handover to DFU + * bootloader. At present, writing anything will do the trick - this needs * to be improved. */ WriteOnlyArrayGattCharacteristic controlPoint; - /**< The packet characteristic in this service doesn't do anything meaningful, but - * is only a placeholder to mimic the corresponding characteristic in the + /**< The packet characteristic in this service doesn't do anything meaningful; + * it is only a placeholder to mimic the corresponding characteristic in the * actual DFU service implemented by the bootloader. Without this, some - * FOTA clients might get confused as service definitions change after + * FOTA clients might get confused, because service definitions change after * handing control over to the bootloader. */ GattCharacteristic packet; uint8_t controlBytes[SIZEOF_CONTROL_BYTES]; uint8_t packetBytes[SIZEOF_PACKET_BYTES]; - static ResetPrepare_t handoverCallback; /**< application specific handover callback. */ + static ResetPrepare_t handoverCallback; /**< Application-specific handover callback. */ }; #endif /* #ifndef __BLE_DFU_SERVICE_H__*/