Revision 999:6ee4c335819b, committed 2015-12-02

Comitter:

rgrover1

Date:

Wed Dec 02 10:29:45 2015 +0000

Parent:

998:18188b7e2aec

Child:

1000:409fdc9db5f8

Commit message:

Synchronized with git rev 1af35b64
Author: Irit Arkin
Edit

Changed in this revision

--- a/ble/services/UARTService.h	Wed Dec 02 10:29:45 2015 +0000
+++ b/ble/services/UARTService.h	Wed Dec 02 10:29:45 2015 +0000
@@ -40,12 +40,12 @@
 extern const uint8_t  UARTServiceRXCharacteristicUUID[UUID::LENGTH_OF_LONG_UUID];
 
 /**
-* @class UARTService
-* @brief BLE Service to enable UART over BLE
+* @class UARTService.
+* @brief BLE Service to enable UART over BLE.
 */
 class UARTService {
 public:
-    /**< Maximum length of data (in bytes) that can be transmitted by the UART service module to the peer. */
+    /**< Maximum length of data (in bytes) that the UART service module can transmit to the peer. */
     static const unsigned BLE_UART_SERVICE_MAX_DATA_LEN = (BLE_GATT_MTU_SIZE_DEFAULT - 3);
 
 public:
@@ -87,20 +87,20 @@
 
     /**
      * We attempt to collect bytes before pushing them to the UART RX
-     * characteristic--writing to the RX characteristic will then generate
+     * characteristic; writing to the RX characteristic then generates
      * notifications for the client. Updates made in quick succession to a
-     * notification-generating characteristic will result in data being buffered
-     * in the bluetooth stack as notifications are sent out. The stack will have
-     * its limits for this buffering; typically a small number under 10.
+     * notification-generating characteristic result in data being buffered
+     * in the Bluetooth stack as notifications are sent out. The stack has
+     * its limits for this buffering - typically a small number under 10.
      * Collecting data into the sendBuffer buffer helps mitigate the rate of
      * updates. But we shouldn't buffer a large amount of data before updating
-     * the characteristic otherwise the client will need to turn around and make
+     * the characteristic, otherwise the client needs to turn around and make
      * a long read request; this is because notifications include only the first
      * 20 bytes of the updated data.
      *
-     * @param  buffer The received update
-     * @param  length Amount of characters to be appended.
-     * @return        Amount of characters appended to the rxCharacteristic.
+     * @param  buffer The received update.
+     * @param  length Number of characters to be appended.
+     * @return        Number of characters appended to the rxCharacteristic.
      */
     size_t write(const void *_buffer, size_t length) {
         size_t         origLength = length;
@@ -112,13 +112,13 @@
                 unsigned bytesRemainingInSendBuffer = BLE_UART_SERVICE_MAX_DATA_LEN - sendBufferIndex;
                 unsigned bytesToCopy                = (length < bytesRemainingInSendBuffer) ? length : bytesRemainingInSendBuffer;
 
-                /* copy bytes into sendBuffer */
+                /* Copy bytes into sendBuffer. */
                 memcpy(&sendBuffer[sendBufferIndex], &buffer[bufferIndex], bytesToCopy);
                 length          -= bytesToCopy;
                 sendBufferIndex += bytesToCopy;
                 bufferIndex     += bytesToCopy;
 
-                /* have we collected enough? */
+                /* Have we collected enough? */
                 if ((sendBufferIndex == BLE_UART_SERVICE_MAX_DATA_LEN) ||
                     // (sendBuffer[sendBufferIndex - 1] == '\r')          ||
                     (sendBuffer[sendBufferIndex - 1] == '\n')) {
@@ -134,14 +134,14 @@
     /**
      * Helper function to write out strings.
      * @param  str The received string.
-     * @return     Amount of characters appended to the rxCharacteristic.
+     * @return     Number of characters appended to the rxCharacteristic.
      */
     size_t writeString(const char *str) {
         return write(str, strlen(str));
     }
 
     /**
-     * Override for Stream::_putc()
+     * Override for Stream::_putc().
      * @param  c
      *         This function writes the character c, cast to an unsigned char, to stream.
      * @return
@@ -152,7 +152,7 @@
     }
 
     /**
-     * Override for Stream::_getc()
+     * Override for Stream::_getc().
      * @return
      *     The character read.
      */
@@ -168,7 +168,7 @@
     /**
      * This callback allows the UART service to receive updates to the
      * txCharacteristic. The application should forward the call to this
-     * function from the global onDataWritten() callback handler; or if that's
+     * function from the global onDataWritten() callback handler; if that's
      * not used, this method can be used as a callback directly.
      */
     void onDataWritten(const GattWriteCallbackParams *params) {

--- a/ble/services/URIBeaconConfigService.h	Wed Dec 02 10:29:45 2015 +0000
+++ b/ble/services/URIBeaconConfigService.h	Wed Dec 02 10:29:45 2015 +0000
@@ -47,18 +47,18 @@
 class URIBeaconConfigService {
   public:
     /**
-     * @brief Transmission power modes for UriBeacon.
+     * @brief Transmission Power Modes for UriBeacon
      */
-    static const uint8_t TX_POWER_MODE_LOWEST = 0; /*!< Lowest TX power mode. */
-    static const uint8_t TX_POWER_MODE_LOW    = 1; /*!< Low TX power mode. */
-    static const uint8_t TX_POWER_MODE_MEDIUM = 2; /*!< Medium TX power mode. */
-    static const uint8_t TX_POWER_MODE_HIGH   = 3; /*!< High TX power mode. */
-    static const unsigned NUM_POWER_MODES     = 4; /*!< Number of power modes defined. */
+    static const uint8_t TX_POWER_MODE_LOWEST = 0; /*!< Lowest TX power mode */
+    static const uint8_t TX_POWER_MODE_LOW    = 1; /*!< Low TX power mode */
+    static const uint8_t TX_POWER_MODE_MEDIUM = 2; /*!< Medium TX power mode */
+    static const uint8_t TX_POWER_MODE_HIGH   = 3; /*!< High TX power mode */
+    static const unsigned NUM_POWER_MODES     = 4; /*!< Number of Power Modes defined */
 
     static const int ADVERTISING_INTERVAL_MSEC = 1000;  // Advertising interval for config service.
-    static const int SERVICE_DATA_MAX = 31;             // Maximum size of service data in ADV packets.
+    static const int SERVICE_DATA_MAX = 31;             // Maximum size of service data in ADV packets
 
-    typedef uint8_t Lock_t[16];               /* 128 bits. */
+    typedef uint8_t Lock_t[16];               /* 128 bits */
     typedef int8_t PowerLevels_t[NUM_POWER_MODES];
 
     static const int URI_DATA_MAX = 18;
@@ -69,8 +69,8 @@
         uint8_t       uriDataLength;
         UriData_t     uriData;
         uint8_t       flags;
-        PowerLevels_t advPowerLevels; // Current value of AdvertisedPowerLevels.
-        uint8_t       txPowerMode;    // Firmware power levels used with setTxPower().
+        PowerLevels_t advPowerLevels; // Current value of AdvertisedPowerLevels
+        uint8_t       txPowerMode;    // Firmware power levels used with setTxPower()
         uint16_t      beaconPeriod;
     };
 
@@ -86,9 +86,9 @@
      *                    un-initialized, and default values should be used
      *                    instead. Otherwise, paramsIn overrides the defaults.
      * @param[in]     defaultUriDataIn
-     *                    Default un-encoded URI. Applies only if the resetToDefaultsFlag is true.
+     *                    Default un-encoded URI; applies only if the resetToDefaultsFlag is true.
      * @param[in]     defaultAdvPowerLevelsIn
-     *                    Default power-levels array. Applies only if the resetToDefaultsFlag is true.
+     *                    Default power-levels array; applies only if the resetToDefaultsFlag is true.
      */
     URIBeaconConfigService(BLE          &bleIn,
                            Params_t      &paramsIn,
@@ -148,7 +148,7 @@
         ble.addService(configService);
         ble.onDataWritten(this, &URIBeaconConfigService::onDataWrittenCallback);
 
-        setupURIBeaconConfigAdvertisements(); /* Set up advertising for the config service. */
+        setupURIBeaconConfigAdvertisements(); /* Setup advertising for the configService. */
 
         initSucceeded = true;
     }
@@ -157,9 +157,9 @@
         return initSucceeded;
     }
 
-    /* Start out by advertising the config service for a limited time after
-     * startup. Then switch to the normal non-connectible beacon functionality.
-     */
+    /* Start out by advertising the configService for a limited time after
+     * startup; and switch to the normal non-connectible beacon functionality
+     * afterwards. */
     void setupURIBeaconConfigAdvertisements()
     {
         const char DEVICE_NAME[] = "mUriBeacon Config";
@@ -186,14 +186,14 @@
         ble.gap().setAdvertisingInterval(GapAdvertisingParams::MSEC_TO_ADVERTISEMENT_DURATION_UNITS(ADVERTISING_INTERVAL_MSEC));
     }
 
-    /* Helper function to switch to the non-connectible normal mode for UriBeacon. This gets called after a timeout. */
+    /* Helper function to switch to the non-connectible normal mode for URIBeacon. This gets called after a timeout. */
     void setupURIBeaconAdvertisements()
     {
         /* Reinitialize the BLE stack. This will clear away the existing services and advertising state. */
         ble.shutdown();
         ble.init();
 
-        // Fields from the service.
+        // Fields from the Service
         unsigned beaconPeriod                                 = params.beaconPeriod;
         unsigned txPowerMode                                  = params.txPowerMode;
         unsigned uriDataLength                                = params.uriDataLength;
@@ -201,7 +201,7 @@
         URIBeaconConfigService::PowerLevels_t &advPowerLevels = params.advPowerLevels;
         uint8_t flags                                         = params.flags;
 
-        extern void saveURIBeaconConfigParams(const Params_t *paramsP); /* Forward declaration; necessary to avoid a circular dependency. */
+        extern void saveURIBeaconConfigParams(const Params_t *paramsP); /* forward declaration; necessary to avoid a circular dependency. */
         saveURIBeaconConfigParams(&params);
 
         ble.gap().clearAdvertisingPayload();
@@ -224,7 +224,7 @@
     }
 
   private:
-    // True if the lock bits are non-zero.
+    // True if the lock bits are non-zero
     bool isLocked() {
         Lock_t testLock;
         memset(testLock, 0, sizeof(Lock_t));
@@ -233,19 +233,19 @@
 
     /*
      * This callback is invoked when a GATT client attempts to modify any of the
-     * characteristics of this service. These attempts are also applied to
+     * characteristics of this service. Attempts to do so are also applied to
      * the internal state of this service object.
      */
     void onDataWrittenCallback(const GattWriteCallbackParams *writeParams) {
         uint16_t handle = writeParams->handle;
 
         if (handle == lockChar.getValueHandle()) {
-            // Validated earlier,
+            // Validated earlier
             memcpy(params.lock, writeParams->data, sizeof(Lock_t));
-            // Use isLocked() in case bits are being set to all zeros.
+            // use isLocked() in case bits are being set to all 0's
             lockedState = isLocked();
         } else if (handle == unlockChar.getValueHandle()) {
-            // Validated earlier.
+            // Validated earlier
             memset(params.lock, 0, sizeof(Lock_t));
             lockedState = false;
         } else if (handle == uriDataChar.getValueHandle()) {
@@ -260,7 +260,7 @@
         } else if (handle == beaconPeriodChar.getValueHandle()) {
             params.beaconPeriod = *((uint16_t *)(writeParams->data));
 
-            /* Remap beaconPeriod to within permissible bounds if necessary. */
+            /* Re-map beaconPeriod to within permissible bounds if necessary. */
             if (params.beaconPeriod != 0) {
                 bool paramsUpdated = false;
                 if (params.beaconPeriod < ble.gap().getMinAdvertisingInterval()) {
@@ -378,9 +378,9 @@
     BLE           &ble;
     Params_t      &params;
 
-    size_t        defaultUriDataLength;   // Default value that is restored on reset.
-    UriData_t     defaultUriData;         // Default value that is restored on reset.
-    PowerLevels_t &defaultAdvPowerLevels; // Default value that is restored on reset.
+    size_t        defaultUriDataLength;   // Default value that is restored on reset
+    UriData_t     defaultUriData;         // Default value that is restored on reset
+    PowerLevels_t &defaultAdvPowerLevels; // Default value that is restored on reset
 
     uint8_t       lockedState;
     bool          initSucceeded;
@@ -398,7 +398,7 @@
 
 public:
     /*
-     *  Encode a human-readable URI into the binary format defined by the UriBeacon spec (https://github.com/google/uribeacon/tree/master/specification).
+     *  Encode a human-readable URI into the binary format defined by URIBeacon spec (https://github.com/google/uribeacon/tree/master/specification).
      */
     static void encodeURI(const char *uriDataIn, UriData_t uriDataOut, size_t &sizeofURIDataOut) {
         const char *prefixes[] = {
@@ -447,7 +447,7 @@
         }
 
         /*
-         * Handle suffixes.
+         * handle suffixes
          */
         while (*uriDataIn && (sizeofURIDataOut < URI_DATA_MAX)) {
             /* check for suffix match */
@@ -457,10 +457,10 @@
                 if (strncmp(uriDataIn, suffixes[i], suffixLen) == 0) {
                     uriDataOut[sizeofURIDataOut++]  = i;
                     uriDataIn                      += suffixLen;
-                    break; /* From the for loop for checking against suffixes. */
+                    break; /* from the for loop for checking against suffixes */
                 }
             }
-            /* This is the default case where we've got an ordinary character that doesn't match a suffix. */
+            /* This is the default case where we've got an ordinary character which doesn't match a suffix. */
             if (i == NUM_SUFFIXES) {
                 uriDataOut[sizeofURIDataOut++] = *uriDataIn;
                 ++uriDataIn;