ble: address code review comments from Manoel Ramon

- Added checks in example sketches for API return values
- Applying Public MAC address if present in factory data
- Applying default device name if user doesn't provide one
- Only issuing notifications/indications if enabled by peer
- Re-sync'd with latest BLE code from Thunderdome
- Added basic DTM support for use in sketch (for internal testing)
- Other minor updates, corrections and clarifications

Signed-off-by: Dan O'Donovan <dan@emutex.com>

Author: Dan-Lightsource

libraries/CurieBle/examples/AutomationIO/AutomationIO.ino

@@ -23,10 +23,13 @@
 
 /*
  * This sketch partially implements the standard Bluetooth Low-Energy "Automation IO" service.
+ * It is a relatively complex example which demonstrates use of BLE descriptors and
+ * multi-instance characteristics for data input and data output.
+ *
  * For more information: https://developer.bluetooth.org/gatt/services/Pages/ServicesHome.aspx
  */
 
-/* Device name: Appears in advertising packets. Should not exceed 13 characters in length */
+/* Device name: Appears in advertising packets. Must not exceed 16 characters in length */
 #define DEVICE_NAME               "AE_IO"
 /* UUID for Automation I/O service */
 #define SERVICE_UUID_AUTOMATIONIO (0x1815)
@@ -41,19 +44,28 @@
  * This helps us to build lists of pins below to allow
  * flexible pin assignments to different modes of operation
  */
-struct PinConfig {
+struct DigitalPinConfig {
+  unsigned          pin;
+  const char        *name;
+  BleCharacteristic characteristic;
+  BleDescriptor     numDigitalsDesc;
+  uint8_t           val;
+};
+
+struct AnalogPinConfig {
   unsigned          pin;
   const char        *name;
   BleCharacteristic characteristic;
+  uint16_t          val;
 };
 
 /* Macros to simplify the definition of a new PinConfig struct for a given pin number
  * Note that input pins are only readable by the remote device, while output pins are
  * only writable.  Different characteristic UUIDs are used for digital and analog pins */
 #define DIGITAL_INPUT_PINCONFIG(pin) \
-  { (pin), #pin, {CHAR_UUID_DIGITAL, sizeof(uint8_t), BLE_CLIENT_ACCESS_READ_ONLY, BLE_CLIENT_NOTIFY_ENABLED} }
+  { (pin), #pin, {CHAR_UUID_DIGITAL, sizeof(uint8_t), BLE_CLIENT_ACCESS_READ_ONLY, BLE_CLIENT_NOTIFY_ENABLED}, {DESC_UUID_NUMDIGITALS, sizeof(uint8_t), BLE_CLIENT_ACCESS_READ_ONLY} }
 #define DIGITAL_OUTPUT_PINCONFIG(pin) \
-  { (pin), #pin, {CHAR_UUID_DIGITAL, sizeof(uint8_t), BLE_CLIENT_ACCESS_WRITE_ONLY, BLE_CLIENT_NOTIFY_DISABLED} }
+  { (pin), #pin, {CHAR_UUID_DIGITAL, sizeof(uint8_t), BLE_CLIENT_ACCESS_WRITE_ONLY, BLE_CLIENT_NOTIFY_DISABLED}, {DESC_UUID_NUMDIGITALS, sizeof(uint8_t), BLE_CLIENT_ACCESS_READ_ONLY} }
 #define ANALOG_INPUT_PINCONFIG(pin) \
   { (pin), #pin, {CHAR_UUID_ANALOG, sizeof(uint16_t), BLE_CLIENT_ACCESS_READ_ONLY, BLE_CLIENT_NOTIFY_ENABLED} }
 #define ANALOG_OUTPUT_PINCONFIG(pin) \
@@ -68,39 +80,38 @@ struct PinConfig {
  *   - pins 0-19 are valid for digital input/output
  *   - pins 14-19 are valid for analog input
  *   - pins 3,5,6,9 are valid for analog output
+ * - a maximum of 16 pins are currently supported (limited by number of characteristics)
  */
-struct PinConfig digitalInputPins[] = {
+struct DigitalPinConfig digitalInputPins[] = {
   DIGITAL_INPUT_PINCONFIG(2),
   DIGITAL_INPUT_PINCONFIG(4),
   DIGITAL_INPUT_PINCONFIG(7),
 };
 
-struct PinConfig digitalOutputPins[] = {
+struct DigitalPinConfig digitalOutputPins[] = {
   DIGITAL_OUTPUT_PINCONFIG(8),
   DIGITAL_OUTPUT_PINCONFIG(10),
   DIGITAL_OUTPUT_PINCONFIG(11),
   DIGITAL_OUTPUT_PINCONFIG(12),
   DIGITAL_OUTPUT_PINCONFIG(13),
 };
 
-struct PinConfig analogInputPins[] = {
+struct AnalogPinConfig analogInputPins[] = {
   ANALOG_INPUT_PINCONFIG(14),
   ANALOG_INPUT_PINCONFIG(15),
   ANALOG_INPUT_PINCONFIG(16),
   ANALOG_INPUT_PINCONFIG(17),
-  ANALOG_INPUT_PINCONFIG(18),
-  ANALOG_INPUT_PINCONFIG(19),
 };
 
-struct PinConfig analogOutputPins[] = {
+struct AnalogPinConfig analogOutputPins[] = {
   ANALOG_OUTPUT_PINCONFIG(3),
   ANALOG_OUTPUT_PINCONFIG(5),
   ANALOG_OUTPUT_PINCONFIG(6),
   ANALOG_OUTPUT_PINCONFIG(9),
 };
 
 /* BLE Peripheral Device (this Intel Curie device) */
-BlePeripheral bleDevice(DEVICE_NAME);
+BlePeripheral bleDevice;
 
 /* BLE Automation I/O Service */
 BleService ioService(SERVICE_UUID_AUTOMATIONIO);
@@ -115,16 +126,33 @@ BleService ioService(SERVICE_UUID_AUTOMATIONIO);
 
 #define ARRAY_SIZE(x) (sizeof(x)/sizeof(x)[0])
 
+/* Serial port to use for printing informational messages to the user */
+#define LOG_SERIAL Serial
+
+/* For convenience, this macro will invoke a specified function call and will
+ * check the status value returned to ensure it is successful.  If not, it will
+ * print an error message to the serial port and will return from the current function
+ */
+#define CHECK_STATUS(op)                               \
+  do {                                                 \
+    BleStatus status = op;                             \
+    if (BLE_STATUS_SUCCESS != status) {                \
+      LOG_SERIAL.print(#op" returned error status: "); \
+      LOG_SERIAL.println(status);                      \
+      return;                                          \
+    }                                                  \
+  } while(0)
+
 /* This function will be called when a BLE GAP event is detected by the
  * Intel Curie BLE device */
 void blePeripheralEventCb(BlePeripheral &peripheral, BlePeripheralEvent event, void *arg)
 {
   if (BLE_PERIPH_EVENT_CONNECTED == event) {
-    Serial.println("Got CONNECTED event");
+    LOG_SERIAL.println("Got CONNECTED event");
   } else if (BLE_PERIPH_EVENT_DISCONNECTED == event) {
-    Serial.println("Got DISCONNECTED event");
+    LOG_SERIAL.println("Got DISCONNECTED event");
   } else {
-    Serial.println("Got UNKNOWN peripheral event");
+    LOG_SERIAL.println("Got UNKNOWN peripheral event");
   }
 }
 
@@ -140,7 +168,7 @@ void digitalOutputCharEventCb(BleCharacteristic &characteristic, BleCharacterist
     /* Update the state of the pin to reflect the new value */
     digitalWrite(pin, VAL_TO_DIGITAL_PIN_STATE(pin, val));
   } else
-    Serial.println("Got UNKNOWN characteristic event");
+    LOG_SERIAL.println("Got UNKNOWN characteristic event");
 }
 
 /* This function will be called when a connected remote peer sets a new value for an analog output characteristic */
@@ -156,110 +184,145 @@ void analogOutputCharEventCb(BleCharacteristic &characteristic, BleCharacteristi
     analogWrite(pin, val);
   }
   else
-    Serial.println("Got UNKNOWN characteristic event");
+    LOG_SERIAL.println("Got UNKNOWN characteristic event");
 }
 
 void setup() {
-  Serial.begin(115200);
+  LOG_SERIAL.begin(115200);
+
+  /* Set a name for the BLE device */
+  CHECK_STATUS(bleDevice.setName(DEVICE_NAME));
 
   /* First, initialise the BLE device */
-  bleDevice.init();
+  CHECK_STATUS(bleDevice.init());
 
   /* Set a function to be called whenever a BLE GAP event occurs */
   bleDevice.setEventCallback(blePeripheralEventCb);
 
   /* Add the Automation I/O Service, and include the UUID in BLE advertising data */
-  bleDevice.addPrimaryService(ioService, true);
+  CHECK_STATUS(bleDevice.addPrimaryService(ioService, true));
 
   /* Add characteristics for the Digital Inputs */
   for (unsigned i = 0; i < ARRAY_SIZE(digitalInputPins); i++) {
-    PinConfig *pin = &digitalInputPins[i];
+    DigitalPinConfig *pin = &digitalInputPins[i];
 
     /* Configure this pin as an input */
     pinMode(pin->pin, INPUT);
 
     /* Add the User-Description for this pin */
-    pin->characteristic.addUserDescription(pin->name);
-    /* Add the Presentation-Format for this pin */
-    pin->characteristic.addPresentationFormat(0x2, 0, 0x2700, 0x1, pin->pin + 1);
+    CHECK_STATUS(pin->characteristic.addUserDescription(pin->name));
+    /* Add the Presentation-Format for this pin
+     *   format:      0x2    (unsigned 2-bit integer)
+     *   exponent:    0      (Not Applicable)
+     *   unit:        0x2700 (BLE GATT Unit UUID: unitless)
+     *   nameSpace:   0x1    (Bluetooth standard namespace)
+     *   description: pin+1  (Instance number of this characteristic)
+     */
+    CHECK_STATUS(pin->characteristic.addPresentationFormat(0x2, 0, 0x2700, 0x1, pin->pin + 1));
     /* Add the characteristic for this pin */
-    ioService.addCharacteristic(pin->characteristic);
+    CHECK_STATUS(ioService.addCharacteristic(pin->characteristic));
     /* Set an initial value for this characteristic; refreshed later in the loop() function */
-    pin->characteristic.setValue(DIGITAL_PIN_STATE_TO_VAL(pin->pin, digitalRead(pin->pin)));
+    pin->val = digitalRead(pin->pin);
+    CHECK_STATUS(pin->characteristic.setValue(DIGITAL_PIN_STATE_TO_VAL(pin->pin, pin->val)));
     /* Add a number_of_digitals descriptor for this characteristic */
-    BleDescriptor numDigitalsDesc(DESC_UUID_NUMDIGITALS, sizeof(uint8_t), BLE_CLIENT_ACCESS_READ_ONLY);
-    pin->characteristic.addDescriptor(numDigitalsDesc);
-    numDigitalsDesc.setValue((uint8_t) 1);
-}
+    CHECK_STATUS(pin->characteristic.addDescriptor(pin->numDigitalsDesc));
+    CHECK_STATUS(pin->numDigitalsDesc.setValue((uint8_t) 1));
+  }
 
   /* Add characteristics for the Digital Outputs */
   for (unsigned i = 0; i < ARRAY_SIZE(digitalOutputPins); i++) {
-    PinConfig *pin = &digitalOutputPins[i];
+    DigitalPinConfig *pin = &digitalOutputPins[i];
 
     /* Configure this pin as an output */
     pinMode(pin->pin, OUTPUT);
 
     /* Add the User-Description for this pin */
-    pin->characteristic.addUserDescription(pin->name);
-    /* Add the Presentation-Format for this pin */
-    pin->characteristic.addPresentationFormat(0x2, 0, 0x2700, 0x1, pin->pin + 1);
+    CHECK_STATUS(pin->characteristic.addUserDescription(pin->name));
+    /* Add the Presentation-Format for this pin
+     *   format:      0x2    (unsigned 2-bit integer)
+     *   exponent:    0      (Not Applicable)
+     *   unit:        0x2700 (BLE GATT Unit UUID: unitless)
+     *   nameSpace:   0x1    (Bluetooth standard namespace)
+     *   description: pin+1  (Instance number of this characteristic)
+     */
+    CHECK_STATUS(pin->characteristic.addPresentationFormat(0x2, 0, 0x2700, 0x1, pin->pin + 1));
     /* Add the characteristic for this pin */
-    ioService.addCharacteristic(pin->characteristic);
+    CHECK_STATUS(ioService.addCharacteristic(pin->characteristic));
     /* Add a callback to be triggered if the remote device updates the value for this pin */
     pin->characteristic.setEventCallback(digitalOutputCharEventCb, (void*)pin->pin);
     /* Add a number_of_digitals descriptor for this characteristic */
-    BleDescriptor numDigitalsDesc(DESC_UUID_NUMDIGITALS, sizeof(uint8_t), BLE_CLIENT_ACCESS_READ_ONLY);
-    pin->characteristic.addDescriptor(numDigitalsDesc);
-    numDigitalsDesc.setValue((uint8_t) 1);
+    CHECK_STATUS(pin->characteristic.addDescriptor(pin->numDigitalsDesc));
+    CHECK_STATUS(pin->numDigitalsDesc.setValue((uint8_t) 1));
   }
 
   /* Add characteristics for the Analog Inputs */
   for (unsigned i = 0; i < ARRAY_SIZE(analogInputPins); i++) {
-    PinConfig *pin = &analogInputPins[i];
+    AnalogPinConfig *pin = &analogInputPins[i];
 
     /* Add the User-Description for this pin */
-    pin->characteristic.addUserDescription(pin->name);
-    /* Add the Presentation-Format for this pin */
-    pin->characteristic.addPresentationFormat(0x6, 0, 0x2700, 0x1, pin->pin + 1);
+    CHECK_STATUS(pin->characteristic.addUserDescription(pin->name));
+    /* Add the Presentation-Format for this pin
+     *   format:      0x6    (unsigned 16-bit integer)
+     *   exponent:    0      (Not Applicable)
+     *   unit:        0x2700 (BLE GATT Unit UUID: unitless)
+     *   nameSpace:   0x1    (Bluetooth standard namespace)
+     *   description: pin+1  (Instance number of this characteristic)
+     */
+    CHECK_STATUS(pin->characteristic.addPresentationFormat(0x6, 0, 0x2700, 0x1, pin->pin + 1));
     /* Add the characteristic for this pin */
-    ioService.addCharacteristic(pin->characteristic);
+    CHECK_STATUS(ioService.addCharacteristic(pin->characteristic));
     /* Set an initial value for this characteristic; refreshed later in the loop() function */
-    pin->characteristic.setValue((uint16_t)analogRead(pin->pin));
+    pin->val = analogRead(pin->pin);
+    CHECK_STATUS(pin->characteristic.setValue(pin->val));
   }
 
   /* Add characteristics for the Analog Outputs */
   for (unsigned i = 0; i < ARRAY_SIZE(analogOutputPins); i++) {
-    PinConfig *pin = &analogOutputPins[i];
+    AnalogPinConfig *pin = &analogOutputPins[i];
 
     /* Add the User-Description for this pin */
-    pin->characteristic.addUserDescription(pin->name);
-    /* Add the Presentation-Format for this pin */
-    pin->characteristic.addPresentationFormat(0x6, 0, 0x2700, 0x1, pin->pin + 1);
+    CHECK_STATUS(pin->characteristic.addUserDescription(pin->name));
+    /* Add the Presentation-Format for this pin
+     *   format:      0x6    (unsigned 16-bit integer)
+     *   exponent:    0      (Not Applicable)
+     *   unit:        0x2700 (BLE GATT Unit UUID: unitless)
+     *   nameSpace:   0x1    (Bluetooth standard namespace)
+     *   description: pin+1  (Instance number of this characteristic)
+     */
+    CHECK_STATUS(pin->characteristic.addPresentationFormat(0x6, 0, 0x2700, 0x1, pin->pin + 1));
     /* Add the characteristic for this pin */
-    ioService.addCharacteristic(pin->characteristic);
+    CHECK_STATUS(ioService.addCharacteristic(pin->characteristic));
     /* Add a callback to be triggered if the remote device updates the value for this pin */
     pin->characteristic.setEventCallback(analogOutputCharEventCb, (void*)pin->pin);
   }
 
   /* Now activate the BLE device.  It will start continuously transmitting BLE
    * advertising packets and thus become visible to remote BLE central devices
    * (e.g smartphones) until it receives a new connection */
-  if (BLE_STATUS_SUCCESS == bleDevice.start())
-    Serial.println("Bluetooth device active, waiting for connections...");
+  CHECK_STATUS(bleDevice.start());
+  LOG_SERIAL.println("Bluetooth device active, waiting for connections...");
 }
 
 void loop() {
   /* Update the digital input characteristics based on current pin reading */
   for (unsigned i = 0; i < ARRAY_SIZE(digitalInputPins); i++) {
-    PinConfig *pin = &digitalInputPins[i];
-    pin->characteristic.setValue(DIGITAL_PIN_STATE_TO_VAL(pin->pin, digitalRead(pin->pin)));
+    DigitalPinConfig *pin = &digitalInputPins[i];
+    uint8_t newVal = digitalRead(pin->pin);
+    if (newVal != pin->val) {
+      CHECK_STATUS(pin->characteristic.setValue(DIGITAL_PIN_STATE_TO_VAL(pin->pin, newVal)));
+      pin->val = newVal;
+    }
   }
   /* Update the analog input characteristics based on current pin reading*/
   for (unsigned i = 0; i < ARRAY_SIZE(analogInputPins); i++) {
-      PinConfig *pin = &analogInputPins[i];
-      pin->characteristic.setValue((uint16_t)analogRead(pin->pin));
+    AnalogPinConfig *pin = &analogInputPins[i];
+    uint16_t newVal = analogRead(pin->pin);
+    if (newVal != pin->val) {
+      CHECK_STATUS(pin->characteristic.setValue(newVal));
+      pin->val = newVal;
+    }
   }
 
-  /* Repeat the loop every 200ms - can be changed if desired */
-  delay(200);
+  /* Repeat the loop every 500ms - can be changed if desired */
+  delay(500);
 }