Fix Jira 676 and Jira 685

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

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

@@ -8,16 +8,18 @@
 /*
    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.
+    This sketch will receive the Notifications and out put the received data in the serail monitor
 */
 
 #define MAX_IMU_RECORD 1
 
-ble_conn_param_t conn_param = {30.0,    //ms
-                               50.0,    //ms
-                               0, 
-                               4000     //ms
+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];
@@ -30,28 +32,24 @@ 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()
 {
-    Serial.begin(115200);    // initialize serial communication
+    // 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);
 
-    /* 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 */
+    // Setup callback whenever a Peripheral advertising data is found)
     bleCentral.setAdvertiseHandler(adv_found);
     bleCentral.setEventHandler(BLEConnected, ble_connected);
 
@@ -64,19 +62,24 @@ void setup()
 
 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();
@@ -103,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:

libraries/CurieBLE/examples/IMUBleNotification/IMUBleNotification.ino

@@ -19,6 +19,7 @@ typedef struct {
     unsigned int slot[3];
 } imuFrameType;
 
+// Buffer to hold IMU data
 imuFrameType imuBuf[MAX_IMU_RECORD];
 
 unsigned seqNum = 0;
@@ -40,20 +41,21 @@ void setup()
      The name can be changed but maybe be truncated based on space left in advertisement packet */
     blePeripheral.setLocalName("Imu");
     blePeripheral.setAdvertisedServiceUuid(bleImuService.uuid());  // add the service UUID
-    blePeripheral.addAttribute(bleImuService);   // Add the BLE Battery service
-    blePeripheral.addAttribute(bleImuChar); // add the battery level characteristic
+    blePeripheral.addAttribute(bleImuService);   // Add the Imu service
+    blePeripheral.addAttribute(bleImuChar); // add the Imu characteristic
 
     /* 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 */
     blePeripheral.begin();
-
+    // Start the IMU
     CurieIMU.begin();
 }
 
 void loop()
 {
     // listen for BLE peripherals to connect:
+    // Since we are a peripheral we need a central object to connect to
     BLECentralHelper central = blePeripheral.central();
 
     // if a central is connected to peripheral:
@@ -82,7 +84,7 @@ void loop()
                 sentTime = millis();
                 bleImuChar.setValue((unsigned char *)&(imuBuf[0]), sizeof(imuBuf));
             }
-        } // while
+        } // end of while loop
 
         // when the central disconnects, turn off the LED:
         digitalWrite(13, LOW);
@@ -91,6 +93,7 @@ void loop()
     }
 }
 
+// This function records the IMU data that we send to the central 
 void recordImuData(int index)
 {
     /* Read IMU data.
@@ -100,7 +103,8 @@ void recordImuData(int index)
 
     imuBuf[index].index = seqNum++;
     CurieIMU.readMotionSensor(ax, ay, az, gx, gy, gz);
-
+    
+    // Encode the data into the buffer
     imuBuf[index].slot[0] = (unsigned int)((ax << 16) | (ay & 0x0FFFF));
     imuBuf[index].slot[1] = (unsigned int)((az << 16) | (gx & 0x0FFFF));
     imuBuf[index].slot[2] = (unsigned int)((gy << 16) | (gz & 0x0FFFF));

libraries/CurieBLE/examples/LED/LED.ino

@@ -2,7 +2,17 @@
  * 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 is similar to CallbackLED example in functionality
+// It does not use callbacks. In the loop it interogates the connection state with central
+// Checks if the characteristic is wriiten and turns of the LED accordingly
+ // 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>
 
 BLEPeripheral blePeripheral;  // BLE Peripheral Device (the board you're programming)

libraries/CurieBLE/examples/LEDCentral/LEDCentral.ino

@@ -6,23 +6,28 @@
 #include <CurieBLE.h>
 
 /* 
-   This example can work with CallbackLED 
-    to show the profile read/write operation in central
+   This example can work with CallbackLED  and LED
+    to show how a central device can do charcteristic read and write operations.
+	A third party serial terminal is recommended to see outputs from central and peripheral device
 */
 
-ble_conn_param_t conn_param = {30.0,    //ms
-                               50.0,    //ms
-                               0, 
-                               4000     //ms
+// set up connection params
+
+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
                                };
 
 const int ledPin = 13; // set ledPin to use on-board LED
 BLECentral bleCentral; // create central instance
 BLEPeripheralHelper *blePeripheral1 = NULL;
 
-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
 BLECharCharacteristic switchChar("19B10001-E8F2-537E-4F6C-D104768A1214", BLERead | BLEWrite);// create switch characteristic and allow remote device to read and write
 
+// 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,

libraries/CurieBLE/examples/MIDIBLE/MIDIBLE.ino

@@ -25,6 +25,9 @@
   Towards the bottom of advanced, you will see 'Bluetooth MIDI devices'.
   You should see your Arduino 101 advertising in the list. Connect to
   your device and it should be available to all other iOS MIDI apps you have.
+  
+  If you do not have iOS, you can still use a BLE app on Android and just subscribe 
+  to the midiChar charcteristic and see the updates.
 
   To send data, you use the following line: char.setValue(d, n); where char is
   the BLE characteristic (in our case, midiCha), d is the data, and n is the
@@ -98,6 +101,21 @@ void setup() {
   Serial.println(("Bluetooth device active, waiting for connections..."));
 }
 
+void loop() {
+
+  /*Simple randome note player to test MIDI output
+     Plays random note every 400ms
+  */
+  int note = random(0, 127);
+  //readMIDI();
+  noteOn(0, note, 127); //loads up midiData buffer
+  midiChar.setValue(midiData, 5);//midiData); //posts 5 bytes
+  delay(200);
+  noteOff(0, note);
+  midiChar.setValue(midiData, 5);//midiData); //posts 5 bytes
+  delay(200);
+}
+
 void BLESetup()
 {
   // set the local name peripheral advertises
@@ -124,22 +142,6 @@ void BLESetup()
   midiDevice.begin();
 }
 
-void loop() {
-
-  /*Simple randome note player to test MIDI output
-     Plays random note every 400ms
-  */
-  int note = random(0, 127);
-  //readMIDI();
-  noteOn(0, note, 127); //loads up midiData buffer
-  midiChar.setValue(midiData, 5);//midiData); //posts 5 bytes
-  delay(200);
-  noteOff(0, note);
-  midiChar.setValue(midiData, 5);//midiData); //posts 5 bytes
-  delay(200);
-}
-
-
 void midiDeviceConnectHandler(BLEHelper& central) {
   // central connected event handler
   Serial.print("Connected event, central: ");

libraries/CurieBLE/examples/Scanning/Scanning.ino

@@ -11,14 +11,15 @@
      The list will refresh every 3s
 */
 
-#define BLE_SCANING_DEVICE_MAX_CNT  5
+
+const int bleScanMaxCnt = 5;
 
 typedef struct{
     char macaddr[32];       // BLE MAC address.
     char loacalname[22];    // Device's name
 }ble_device_info_t;
 
-ble_device_info_t device_list[BLE_SCANING_DEVICE_MAX_CNT];
+ble_device_info_t device_list[bleScanMaxCnt];
 uint8_t list_index = 0;
 
 BLECentral bleCentral;       // BLE Central Device (the board you're programming)
@@ -64,9 +65,10 @@ void loop()
     adv_list_clear();
 }
 
+// Add the scanned BLE device into the global variables.
 bool adv_list_add(ble_device_info_t &device)
 {
-    if (list_index >= BLE_SCANING_DEVICE_MAX_CNT)
+    if (list_index >= bleScanMaxCnt)
     {
         return false;
     }
@@ -115,7 +117,7 @@ bool adv_found(uint8_t type,
     ble_device_info_t device;
     bt_addr_le_to_str (addr, device.macaddr, sizeof (device.macaddr));
     memcpy(device.loacalname, " -NA-", sizeof(" -NA-"));
-    
+    // Please see https://www.bluetooth.org/en-us/specification/assigned-numbers/generic-access-profile
     switch (type) {
         case BT_DATA_NAME_SHORTENED:
         case BT_DATA_NAME_COMPLETE: