Revision 936:a7bedf42bfb9, committed 2015-11-26

Comitter:

rgrover1

Date:

Thu Nov 26 12:52:06 2015 +0000

Parent:

935:e9b595e6b0ed

Child:

937:4932e700daf2

Commit message:

Synchronized with git rev 700850d1
Author: Irit Arkin
Minor edits

Changed in this revision

--- a/ble/services/DFUService.h	Thu Nov 26 12:52:06 2015 +0000
+++ b/ble/services/DFUService.h	Thu Nov 26 12:52:06 2015 +0000
@@ -37,20 +37,20 @@
 class DFUService {
 public:
     /**
-     * @brief Signature for the handover callback. The application may provide this
-     * callback when setting up the DFU service. The callback is then
+     * @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
      * 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 @@
                GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_WRITE_WITHOUT_RESPONSE),
         controlBytes(),
         packetBytes() {
-        static bool serviceAdded = false; /* We only add the DFU service once. */
+        static bool serviceAdded = false; /* We should only ever need to add the DFU service once. */
         if (serviceAdded) {
             return;
         }
 
-        /* Set an initial value for control bytes, so that the application's DFU service can
+        /* Set an initial value for control bytes so that the application's DFUService can
          * be distinguished from the real DFU service provided by the bootloader. */
         controlBytes[0] = 0xFF;
         controlBytes[1] = 0xFF;
@@ -80,7 +80,7 @@
     }
 
     /**
-    * @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 @@
 
     /**
      * @brief This callback allows the DFU service to receive the initial trigger to
-     * hand control over to the bootloader. First, the application is given a
+     * handover control to the bootloader; but first the application is given a
      * chance to clean up.
      *
      * @param[in] params
@@ -96,7 +96,7 @@
      */
     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:
     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<uint8_t, SIZEOF_CONTROL_BYTES> controlPoint;
 
-    /**< The packet characteristic in this service doesn't do anything meaningful;
-      *  it is only a placeholder to mimic the corresponding characteristic in the
+    /**< The packet characteristic in this service doesn't do anything meaningful, but
+      *  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, because service definitions change after
+      *  FOTA clients might get confused as 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__*/
\ No newline at end of file

--- a/ble/services/DeviceInformationService.h	Thu Nov 26 12:52:06 2015 +0000
+++ b/ble/services/DeviceInformationService.h	Thu Nov 26 12:52:06 2015 +0000
@@ -21,41 +21,30 @@
 
 /**
 * @class DeviceInformationService
-* @brief BLE Device Information Service <br>
-* Service: https://developer.bluetooth.org/gatt/services/Pages/ServiceViewer.aspx?u=org.bluetooth.service.device_information.xml <br>
+* @brief BLE Device Information Service
+* Service: https://developer.bluetooth.org/gatt/services/Pages/ServiceViewer.aspx?u=org.bluetooth.service.device_information.xml
 * Manufacturer Name String Char: https://developer.bluetooth.org/gatt/characteristics/Pages/CharacteristicViewer.aspx?u=org.bluetooth.characteristic.manufacturer_name_string.xml
 */
 class DeviceInformationService {
 public:
     /**
-     * @brief Device Information Service Constructor.
+     * @brief Device Information Service Constructor: copies device-specific information 
+     * into the BLE stack.
      *
      * @param[ref] _ble
      *                BLE object for the underlying controller.
      * @param[in] manufacturersName
-     *                This characteristic represents the name of the
-     *                manufacturer of the device. The name is copied into the
-     *                BLE stack during this constructor.
+     *                The name of the manufacturer of the device.
      * @param[in] modelNumber
-     *                This characteristic represents the model number that is
-     *                assigned by the device vendor. The value is copied into
-     *                the BLE stack during this constructor.
+     *                The model number that is assigned by the device vendor.
      * @param[in] serialNumber
-     *                This characteristic represents the serial number for a
-     *                particular instance of the device.  The value is copied
-     *                into the BLE stack during this constructor.
+     *                The serial number for a particular instance of the device. 
      * @param[in] hardwareRevision
-     *                This characteristic represents the hardware revision for
-     *                the hardware within the device. The value is copied
-     *                into the BLE stack during this constructor.
+     *                The hardware revision for the hardware within the device.
      * @param[in] firmwareRevision
-     *                This characteristic represents the firmware revision for
-     *                the firmware within the device. The value is copied
-     *                into the BLE stack during this constructor.
+     *                The device's firmware version. 
      * @param[in] softwareRevision
-     *                This characteristic represents the software revision for
-     *                the software within the device. The value is copied
-     *                into the BLE stack during this constructor.
+     *                The device's software version.
      */
     DeviceInformationService(BLE        &_ble,
                              const char *manufacturersName = NULL,
@@ -67,36 +56,36 @@
         ble(_ble),
         manufacturersNameStringCharacteristic(GattCharacteristic::UUID_MANUFACTURER_NAME_STRING_CHAR,
                                               (uint8_t *)manufacturersName,
-                                              (manufacturersName != NULL) ? strlen(manufacturersName) : 0, /* minLength */
-                                              (manufacturersName != NULL) ? strlen(manufacturersName) : 0, /* maxLength */
+                                              (manufacturersName != NULL) ? strlen(manufacturersName) : 0, /* Min length */
+                                              (manufacturersName != NULL) ? strlen(manufacturersName) : 0, /* Max length */
                                               GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_READ),
         modelNumberStringCharacteristic(GattCharacteristic::UUID_MODEL_NUMBER_STRING_CHAR,
                                         (uint8_t *)modelNumber,
-                                        (modelNumber != NULL) ? strlen(modelNumber) : 0, /* minLength */
-                                        (modelNumber != NULL) ? strlen(modelNumber) : 0, /* maxLength */
+                                        (modelNumber != NULL) ? strlen(modelNumber) : 0, /* Min length */
+                                        (modelNumber != NULL) ? strlen(modelNumber) : 0, /* Max length */
                                         GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_READ),
         serialNumberStringCharacteristic(GattCharacteristic::UUID_SERIAL_NUMBER_STRING_CHAR,
                                          (uint8_t *)serialNumber,
-                                         (serialNumber != NULL) ? strlen(serialNumber) : 0, /* minLength */
-                                         (serialNumber != NULL) ? strlen(serialNumber) : 0, /* maxLength */
+                                         (serialNumber != NULL) ? strlen(serialNumber) : 0, /* Min length */
+                                         (serialNumber != NULL) ? strlen(serialNumber) : 0, /* Max length */
                                          GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_READ),
         hardwareRevisionStringCharacteristic(GattCharacteristic::UUID_HARDWARE_REVISION_STRING_CHAR,
                                              (uint8_t *)hardwareRevision,
-                                             (hardwareRevision != NULL) ? strlen(hardwareRevision) : 0, /* minLength */
-                                             (hardwareRevision != NULL) ? strlen(hardwareRevision) : 0, /* maxLength */
+                                             (hardwareRevision != NULL) ? strlen(hardwareRevision) : 0, /* Min length */
+                                             (hardwareRevision != NULL) ? strlen(hardwareRevision) : 0, /* Max length */
                                              GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_READ),
         firmwareRevisionStringCharacteristic(GattCharacteristic::UUID_FIRMWARE_REVISION_STRING_CHAR,
                                              (uint8_t *)firmwareRevision,
-                                             (firmwareRevision != NULL) ? strlen(firmwareRevision) : 0, /* minLength */
-                                             (firmwareRevision != NULL) ? strlen(firmwareRevision) : 0, /* maxLength */
+                                             (firmwareRevision != NULL) ? strlen(firmwareRevision) : 0, /* Min length */
+                                             (firmwareRevision != NULL) ? strlen(firmwareRevision) : 0, /* Max length */
                                              GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_READ),
         softwareRevisionStringCharacteristic(GattCharacteristic::UUID_SOFTWARE_REVISION_STRING_CHAR,
                                              (uint8_t *)softwareRevision,
-                                             (softwareRevision != NULL) ? strlen(softwareRevision) : 0, /* minLength */
-                                             (softwareRevision != NULL) ? strlen(softwareRevision) : 0, /* maxLength */
+                                             (softwareRevision != NULL) ? strlen(softwareRevision) : 0, /* Min length */
+                                             (softwareRevision != NULL) ? strlen(softwareRevision) : 0, /* Max length */
                                              GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_READ)
     {
-        static bool serviceAdded = false; /* We should only ever need to add the information service once. */
+        static bool serviceAdded = false; /* We only add the information service once. */
         if (serviceAdded) {
             return;
         }