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.

21. Fix Jira 683 Typecasting and Pointers should be avoided in sketch
     i.   Add write in Characteristic template
     ii.  Add method in BLE Role class to avoid typecaste
     iii. Modify the advertise address parameter and related example sketches

22. Fix Jira 704 Type Characteristic should be documented
23. Fix Jira 684 Documentation about the central/peripheral

Author: sgbihu

libraries/CurieBLE/examples/BatteryMonitor/BatteryMonitor.ino

@@ -6,7 +6,10 @@
 #include <CurieBLE.h>
 
 /*
-   This sketch example partially implements the standard Bluetooth Low-Energy Battery service.
+   This sketch can work with UpdateConnectionInterval. 
+   You can also use an android or IOS app that supports notifications   
+   This sketch example partially implements the standard Bluetooth Low-Energy Battery service
+   and connection interval paramater update.
    For more information: https://developer.bluetooth.org/gatt/services/Pages/ServicesHome.aspx
 */
 
@@ -15,9 +18,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

@@ -3,19 +3,28 @@
  * See the bottom of this file for the license terms.
  */
 
+ /*  This examples needs a button connected similarly as described here
+     https://www.arduino.cc/en/Tutorial/Button
+	 The only difference is that instead of connecting to pin 2 connect to pin 4
+	 After the sketch starts connect to a BLE app on a phone and set notification to the Characteristic and you should see it update
+	 whenever the button is pressed. This sketch is not written to pair with any of the central examples. 
+ */	 
+ 
 #include <CurieBLE.h>
 
 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 +41,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 +69,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,24 @@
  * Copyright (c) 2016 Intel Corporation.  All rights reserved.
  * See the bottom of this file for the license terms.
  */
+ 
+ // This example can work with LEDCentral
+ // You should see the LED blink on and off
+ // This example demonstrates the use of Callback or event Handlers responding to events
+ // BLECoonected, BLEDisconnected and BLEWritten are events.
+ // To test interactively use a Phone app like 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 such 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
+BLECentralHelper *bleCentral1 = NULL; // peer central device 
 
-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,10 +56,14 @@ 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
+  bleCentral1 = blePeripheral.getPeerCentralBLE(central);
   Serial.print("Connected event, central: ");
-  Serial.println(central.address());
+  Serial.println(bleCentral1->address());
 }
 
 void blePeripheralDisconnectHandler(BLEHelper& central) {
@@ -57,6 +72,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,28 @@
 /*
-   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 serial monitor
+	It also illustrates using a non typed characteristic
+	Set the baud rate to 115200 on the serial monitor to accomodate the  speed of constant data updates from IMU subsystem
+	
 */
 
 #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,19 +35,64 @@ 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
+																		// We have a third parameter which is the size of imyBuffer. This is because it is a non-typed characteristic
+																		// If we are only writing to this characteristic we can set this buffer to 512 bytes
+																		// But because of the limitation of the Nordic FW, please do not set this to more than 128 if you intend to read it.
+																		// MAX_IMU_RECORD value is 1 so we are safe
+// function prototype for function that determines if the advertising data is found
+bool adv_found(uint8_t type,
+               const uint8_t *dataPtr,
+               uint8_t data_len,
+               const bt_addr_le_t *addrPtr);
+
+void setup()
+{
+    // This is set to higher baud rate because accelerometer 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 events.
+    
+    delay(2000);
+}
 
 void ble_connected(BLEHelper &role)
 {
-    BLEPeripheralHelper&peripheral = *(BLEPeripheralHelper*)(&role);
+    // since we are a central device we create a BLEPeripheralHelper peripheral
+    BLEPeripheralHelper *peripheral = bleCentral.getPeerPeripheralBLE(role);
     Serial.println("Connected");
 
     // Start discovery the profiles in peripheral device
-    peripheral.discover();
+    peripheral->discover();
 }
 
-void bleImuCharacteristicWritten(BLEHelper& central, BLECharacteristic& characteristic)
+void bleImuCharacteristicWritten(BLEHelper& peripheral, BLECharacteristic& characteristic)
 {
     // Peripheral wrote new value to characteristic by Notification/Indication
+    // We have to use pointers because we are NOT using a type characteristic
+    // In other examples our charcteristics are typed so we not have to use pointers and can access the value directly
+    // The parent non typde characteristic class, the value method gives a pointer to the  characteristic value 
+	
     const unsigned char *cvalue = characteristic.value();
     const imuFrameType *value = (const imuFrameType *)cvalue;
     Serial.print("\r\nCharacteristic event, written: ");
@@ -64,32 +106,32 @@ void bleImuCharacteristicWritten(BLEHelper& central, BLECharacteristic& characte
 }
 
 bool adv_found(uint8_t type, 
-               const uint8_t *data, 
+               const uint8_t *dataPtr, 
                uint8_t data_len,
-               void *user_data)
+               const bt_addr_le_t *addrPtr)
 {
-    bt_addr_le_t *addr = (bt_addr_le_t *)user_data;
     int i;
 
     Serial.print("[AD]:");
     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:
         case BT_DATA_UUID128_ALL:
         {
-            if (data_len % MAX_UUID_SIZE != 0) 
+            if (data_len % UUID_SIZE_128 != 0) 
             {
                 Serial.println("AD malformed");
                 return true;
             }
-            struct bt_uuid * serviceuuid = bleImuService.uuid();
-            for (i = 0; i < data_len; i += MAX_UUID_SIZE)
+            for (i = 0; i < data_len; i += UUID_SIZE_128)
             {
-                if (memcmp (((struct bt_uuid_128*)serviceuuid)->val, &data[i], MAX_UUID_SIZE) != 0) 
+                if (bleImuService.uuidCompare(dataPtr + i, UUID_SIZE_128) == false)
                 {
                     continue;
                 }
@@ -102,7 +144,7 @@ bool adv_found(uint8_t type,
                 }
                 Serial.println("Connecting");
                 // Connect to peripheral
-                bleCentral.connect(addr, &conn_param);
+                bleCentral.connect(addrPtr, &conn_param);
                 return false;
             }
         }
@@ -111,33 +153,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
+*/