Jira Tickets and Bug fix

1. Jira 541 Peripheral Start fails on X Number of Attributes
    -Change the interface and add return value

2. Fix BLE Peripheral is not advertising
    -Add a delay after register the profile.

3. Modify some comments based on code review

4. Jira 544 BLE peripheral disconnect and end functions
    -The state not aligned and make disconnect failed. Update when connect and disconnect event received

5. Delete the duplicated code that base class has implemented

6. Fix Jira 665 BLECentral Preview -- compile issue when instantiating BLE descriptor
    -Fix the build error.
    Note:
      i  . The current code only support one descriptor on characteristic.
      ii . The central discover logic need more twist.
      iii. Now is so long and can't process CCCD and another characteristic.
      iv . The library will support one other descriptor except CCCD.

7. Improve the discover logic and support another descriptor
    i.  Improve the discover logic
    ii. Support another the descriptor and CCCD at same time.

8. Modify the comments and delete the unused API

9. Fix Jira 670 A compile error occurs with two BLE methods with the same name
    i.  Add method uuid_cstr in BLEAttribute class.
    ii. Remove the duplicate file.

10. Fix Jira 672 BLE documentation in code needs to specify units
    i.   Change the scan and connection interval's unit to ms.
    ii.  Unify the advertising interval unit as millisecond
    iii. Delete some unused code.

11. Fix Jria 671 Support update connection interval in central/peripheral
     i. Central can update the connection interval.
     ii. Unify the interval unit to ms at user API.

12. Adjust the example comments and functions
     i.  Fix Jira 675 - BLE callbacks should use passed arguments instead of global variables
     ii. Adjust the code struture to align with Arduino's requirement

13. Fix Jira 680 LED and LED Central sketches need some work
     -Add a delay to make sure profile register process success.
     -The UART send too fast may makes the profile registration failed.

14. Fix Jira 673 BLE Api should pass arguments that are typedef

15. Fix Jira 671 Support update connection interval in central/peripheral
     i. Add peripheral update the connection interval feature.
     ii. Update the library.

16. Fix Jira  687 Edit the keyword.txt of CurieBLE to reflect Library changes

17. Make example function ready. But need to resolve Jira 675

18. Fix Jira 676 Review Edit Update BLE User Manual with China Flex
19. Fix Jira 685 BLE Peripheral sketches shall state which associated Central sketch to use

20. Fix Jira 588 - BLE Corrupted Long Write
     i. Modify the BLECharacteristic to implement the Long write feature.

Author: sgbihu

libraries/CurieBLE/examples/BatteryMonitor/BatteryMonitor.ino

@@ -15,9 +15,9 @@ BLEPeripheral blePeripheral;       // BLE Peripheral Device (the board you're pr
 BLEService batteryService("180F"); // BLE Battery Service
 
 // BLE Battery Level Characteristic"
-BLEUnsignedCharCharacteristic batteryLevelChar("2A19",  // standard 16-bit characteristic UUID
+BLEUnsignedCharCharacteristic batteryLevelChar("2A19",  // standard 16-bit characteristic UUID  defined in the URL above
     BLERead | BLENotify);     // remote clients will be able to
-// get notifications if this characteristic changes
+                              // get notifications if this characteristic changes
 
 int oldBatteryLevel = 0;  // last battery level reading from analog input
 long previousMillis = 0;  // last time the battery level was checked, in ms

libraries/CurieBLE/examples/ButtonLED/ButtonLED.ino

@@ -9,13 +9,15 @@ const int ledPin = 13; // set ledPin to on-board LED
 const int buttonPin = 4; // set buttonPin to digital pin 4
 
 BLEPeripheral blePeripheral; // create peripheral instance
-BLEService ledService("19B10010-E8F2-537E-4F6C-D104768A1214"); // create service
+BLEService ledService("19B10010-E8F2-537E-4F6C-D104768A1214"); // create service with a 128-bit UUID (32 characters exclusive of dashes).
+                                                               // Long UUID denote custom user created UUID
 
 
 // create switch characteristic and allow remote device to read and write
 BLECharCharacteristic ledCharacteristic("19B10011-E8F2-537E-4F6C-D104768A1214", BLERead | BLEWrite);
 // create button characteristic and allow remote device to get notifications
 BLECharCharacteristic buttonCharacteristic("19B10012-E8F2-537E-4F6C-D104768A1214", BLERead | BLENotify); // allows remote device to get notifications
+// Note use of Typed Characteristics. These previous 2  characeristics are of the type char
 
 void setup() {
   Serial.begin(9600);
@@ -32,6 +34,7 @@ void setup() {
   blePeripheral.addAttribute(ledCharacteristic);
   blePeripheral.addAttribute(buttonCharacteristic);
 
+  // set initial values for led and button characteristic
   ledCharacteristic.setValue(0);
   buttonCharacteristic.setValue(0);
 
@@ -59,10 +62,13 @@ void loop() {
 
   if (ledCharacteristic.written() || buttonChanged) {
     // update LED, either central has written to characteristic or button state has changed
+	// if you are using a phone or a BLE  central device that is aware of this characteristic, writing a value of 0x40 for example
+	// Will be interpreted as written
     if (ledCharacteristic.value()) {
       Serial.println("LED on");
       digitalWrite(ledPin, HIGH);
     } else {
+	// If central writes a 0 value then it is interpreted as no value and turns off the LED
       Serial.println("LED off");
       digitalWrite(ledPin, LOW);
     }

libraries/CurieBLE/examples/CallbackLED/CallbackLED.ino

@@ -2,13 +2,23 @@
  * Copyright (c) 2016 Intel Corporation.  All rights reserved.
  * See the bottom of this file for the license terms.
  */
+ 
+ // This example can work with LEDCentral
+ // 
+ // This example demonstartes the use of Callback or event Handlers responding to events
+ // BLECoonected, BLEDisconnected and BLEWritten are events.
+ // To Test use a Phone app lie nrf Controller (Android) or Light Blue (iOS)
+ // Connect to BLE device named LEDCB and explore characteristic with UUID 19B10001-E8F2-537E-4F6C-D104768A1214
+ // Writing a byte value suck as 0x40 should turn on the LED
+ // Writng a byte value of 0x00 should turn off the LED
 
 #include <CurieBLE.h>
 
 const int ledPin = 13; // set ledPin to use on-board LED
 BLEPeripheral blePeripheral; // create peripheral instance
 
-BLEService ledService("19B10000-E8F2-537E-4F6C-D104768A1214"); // create service
+BLEService ledService("19B10000-E8F2-537E-4F6C-D104768A1214"); // create service with a 128-bit UUID (32 characters exclusive of dashes).
+                                                               // Long UUID denote custom user created UUID
 
 // create switch characteristic and allow remote device to read and write
 BLECharCharacteristic switchChar("19B10001-E8F2-537E-4F6C-D104768A1214", BLERead | BLEWrite);
@@ -45,6 +55,9 @@ void loop() {
   blePeripheral.poll();
 }
 
+// The function parameter (BLEHelper& central) is for peripheral devices
+// This enable us to have access to the central's data like its bluetooth address
+
 void blePeripheralConnectHandler(BLEHelper& central) {
   // central connected event handler
   Serial.print("Connected event, central: ");
@@ -57,6 +70,8 @@ void blePeripheralDisconnectHandler(BLEHelper& central) {
   Serial.println(central.address());
 }
 
+// In addtion to the BLECentral& central parameter, we also have to have to BLECharacteristic& characteristic parameter
+
 void switchCharacteristicWritten(BLEHelper& central, BLECharacteristic& characteristic) {
   // central wrote new value to characteristic, update LED
   Serial.print("Characteristic event, written: ");

libraries/CurieBLE/examples/IMUBleCentral/IMUBleCentral.ino

@@ -1,31 +1,25 @@
 /*
-   Copyright (c) 2016 Intel Corporation.  All rights reserved.
-
-   This library is free software; you can redistribute it and/or
-   modify it under the terms of the GNU Lesser General Public
-   License as published by the Free Software Foundation; either
-   version 2.1 of the License, or (at your option) any later version.
-
-   This library is distributed in the hope that it will be useful,
-   but WITHOUT ANY WARRANTY; without even the implied warranty of
-   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-   Lesser General Public License for more details.
-
-   You should have received a copy of the GNU Lesser General Public
-   License along with this library; if not, write to the Free Software
-   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
-*/
+ * Copyright (c) 2016 Intel Corporation.  All rights reserved.
+ * See the bottom of this file for the license terms.
+ */
 
 #include <CurieBLE.h>
 
 /*
-   This sketch example partially implements the standard Bluetooth Low-Energy Battery service.
-   For more information: https://developer.bluetooth.org/gatt/services/Pages/ServicesHome.aspx
+   This sketch example works with IMUBleNotification.ino
+    IMUBleNotification.ino will send Notification to this sketch.
+    This sketch will receive the Notifications and out put the received data in the serail monitor
 */
 
 #define MAX_IMU_RECORD 1
 
-struct bt_le_conn_param conn_param = {0x18, 0x28, 0, 400};
+ble_conn_param_t conn_param = {30.0,    // minimum interval in ms 7.5 - 4000
+                               50.0,    // maximum interval in ms 7.5 -
+                               0,       // latency 
+                               4000     // timeout in ms 100 - 32000ms
+                               };
+// define a structure that will serve as buffer for holding IMU data
+
 typedef struct {
     int index;
     unsigned int slot[3];
@@ -38,17 +32,54 @@ BLEService bleImuService("F7580001-153E-D4F6-F26D-43D8D98EEB13");
 BLECharacteristic bleImuChar("F7580003-153E-D4F6-F26D-43D8D98EEB13",    // standard 128-bit characteristic UUID
                              BLERead | BLENotify, sizeof(imuBuf));      // remote clients will be able to
                                                                         // get notifications if this characteristic changes
+// function prototype for function that determines if the advertising data is found
+bool adv_found(uint8_t type,
+               const uint8_t *data,
+               uint8_t data_len,
+               void *user_data);
+
+void setup()
+{
+    // This is set to higher baud rate because accelrometer data changes very quickly
+	Serial.begin(115200);    // initialize serial communication
+    pinMode(13, OUTPUT);   // initialize the LED on pin 13 to indicate when a central is connected
+    // set the event handeler function for the bleImuChar characteristic
+    bleImuChar.setEventHandler(BLEWritten, bleImuCharacteristicWritten);
+    
+    bleCentral.addAttribute(bleImuService); // Add the BLE IMU service
+    bleCentral.addAttribute(bleImuChar);    // Add the BLE IMU characteristic
+
+    // Setup callback whenever a Peripheral advertising data is found)
+    bleCentral.setAdvertiseHandler(adv_found);
+    bleCentral.setEventHandler(BLEConnected, ble_connected);
+    
+    /* Now activate the BLE device.  It will start continuously transmitting BLE
+     advertising packets and will be visible to remote BLE central devices
+     until it receives a new connection */
+    bleCentral.begin();
+}
+
+
+void loop()
+{
+    // we put a  2 second delay
+    // Even though this looks empty, since we setup 2 callbacks  by setting the advertising handler adv_found
+    // and event handler for BLEConnected, we basically are lsitening for advertising data and connected event.
+    
+    delay(2000);
+}
 
 void ble_connected(BLEHelper &role)
 {
+    // since we are a central device we create a BLEPeripheralHelper peripheral
     BLEPeripheralHelper&peripheral = *(BLEPeripheralHelper*)(&role);
     Serial.println("Connected");
 
     // Start discovery the profiles in peripheral device
     peripheral.discover();
 }
 
-void bleImuCharacteristicWritten(BLEHelper& central, BLECharacteristic& characteristic)
+void bleImuCharacteristicWritten(BLEHelper& peripheral, BLECharacteristic& characteristic)
 {
     // Peripheral wrote new value to characteristic by Notification/Indication
     const unsigned char *cvalue = characteristic.value();
@@ -75,7 +106,9 @@ bool adv_found(uint8_t type,
     Serial.print(type);
     Serial.print(" data_len ");
     Serial.println(data_len);
-
+    // Please see https://www.bluetooth.org/en-us/specification/assigned-numbers/generic-access-profile
+    //  To decode the data the central device cares.
+    //  This example use UUID as identity.
     switch (type)
     {
         case BT_DATA_UUID128_SOME:
@@ -86,10 +119,10 @@ bool adv_found(uint8_t type,
                 Serial.println("AD malformed");
                 return true;
             }
-            struct bt_uuid * serviceuuid = bleImuService.uuid();
+            bt_uuid_t* serviceuuid = bleImuService.uuid();
             for (i = 0; i < data_len; i += MAX_UUID_SIZE)
             {
-                if (memcmp (((struct bt_uuid_128*)serviceuuid)->val, &data[i], MAX_UUID_SIZE) != 0) 
+                if (memcmp (((bt_uuid_128_t*)serviceuuid)->val, &data[i], MAX_UUID_SIZE) != 0) 
                 {
                     continue;
                 }
@@ -111,33 +144,20 @@ bool adv_found(uint8_t type,
     return true;
 }
 
-void setup() {    
-    Serial.begin(115200);    // initialize serial communication
-    pinMode(13, OUTPUT);   // initialize the LED on pin 13 to indicate when a central is connected
-
-    bleImuChar.setEventHandler(BLEWritten, bleImuCharacteristicWritten);
-    
-    /* Set a local name for the BLE device
-     This name will appear in advertising packets
-     and can be used by remote devices to identify this BLE device
-     The name can be changed but maybe be truncated based on space 
-     left in advertisement packet */
-    bleCentral.addAttribute(bleImuService); // Add the BLE IMU service
-    bleCentral.addAttribute(bleImuChar);    // Add the BLE IMU characteristic
-
-    /* Setup callback */
-    bleCentral.setAdvertiseHandler(adv_found);
-    bleCentral.setEventHandler(BLEConnected, ble_connected);
-    
-    /* Now activate the BLE device.  It will start continuously transmitting BLE
-     advertising packets and will be visible to remote BLE central devices
-     until it receives a new connection */
-    bleCentral.begin();
-}
+/*
+   Copyright (c) 2016 Intel Corporation.  All rights reserved.
 
+   This library is free software; you can redistribute it and/or
+   modify it under the terms of the GNU Lesser General Public
+   License as published by the Free Software Foundation; either
+   version 2.1 of the License, or (at your option) any later version.
 
-void loop()
-{
-    delay(2000);
-}
+   This library is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+   Lesser General Public License for more details.
 
+   You should have received a copy of the GNU Lesser General Public
+   License along with this library; if not, write to the Free Software
+   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+*/