added central_custom_hrm

add BLECLientCharacteristic isValid() and read 8,16, 32 bit

Author: hathach

changelog.md

@@ -31,6 +31,8 @@
 - Added experimental (work in progress) BLE Homekit
 - Enhanced bleuart to work with larger MTU
 - Partially support data length extension
+- Added BLECLientCharacteristic isValid() and read 8,16, 32 bit
+- Added cental_custom_hrm example for how to use client service and characteristic
 
 ## Bug Fixs
 

libraries/Bluefruit52Lib/examples/Central/central_custom_hrm/central_custom_hrm.ino

@@ -0,0 +1,200 @@
+/*********************************************************************
+ This is an example for our nRF52 based Bluefruit LE modules
+
+ Pick one up today in the adafruit shop!
+
+ Adafruit invests time and resources providing this open source code,
+ please support Adafruit and open-source hardware by purchasing
+ products from Adafruit!
+
+ MIT license, check LICENSE for more information
+ All text above, and the splash screen below must be included in
+ any redistribution
+*********************************************************************/
+
+/* This sketch show how to use BLEClientService and BLEClientCharacteristic
+ * to implement a custom client that is used to talk with Gatt server on
+ * peripheral.
+ *
+ * Note: you will need another feather52 running peripheral/custom_HRM sketch
+ * to test with.
+ */
+
+#include <bluefruit.h>
+
+/* HRM Service Definitions
+ * Heart Rate Monitor Service:  0x180D
+ * Heart Rate Measurement Char: 0x2A37 (Mandatory)
+ * Body Sensor Location Char:   0x2A38 (Optional)
+ */
+
+BLEClientService        clientHRM(UUID16_SVC_HEART_RATE);
+BLEClientCharacteristic clientMeasurement   (UUID16_CHR_HEART_RATE_MEASUREMENT);
+BLEClientCharacteristic clientSensorLocation(UUID16_CHR_BODY_SENSOR_LOCATION);
+
+void setup()
+{
+  Serial.begin(115200);
+
+  Serial.println("Bluefruit52 Central Custom HRM Example");
+  Serial.println("--------------------------------------\n");
+
+  // Initialize Bluefruit with maximum connections as Peripheral = 0, Central = 1
+  // SRAM usage required by SoftDevice will increase dramatically with number of connections
+  Bluefruit.begin(0, 1);
+
+  Bluefruit.setName("Bluefruit52 Central");
+
+  // Initialize HRM client
+  clientHRM.begin();
+
+  // Initialize client characteristics of HRM.
+  // Note: Client Char will be added to the most recent Service that is initialized.
+  clientSensorLocation.begin();
+
+  clientMeasurement.begin();
+  clientMeasurement.setNotifyCallback(hrm_notify_callback); // set up callback for receiving measurement
+
+  // Increase Blink rate to different from PrPh advertising mode
+  Bluefruit.setConnLedInterval(250);
+
+  // Callbacks for Central
+  Bluefruit.Central.setConnectCallback(connect_callback);
+  Bluefruit.Central.setDisconnectCallback(disconnect_callback);
+
+  /* Start Central Scanning
+   * - Enable auto scan if disconnected
+   * - Interval = 100 ms, window = 80 ms
+   * - Don't use active scan
+   * - Filter only accept HRM service
+   * - Start(timeout) with timeout = 0 will scan forever (until connected)
+   */
+  Bluefruit.Scanner.setRxCallback(scan_callback);
+  Bluefruit.Scanner.restartOnDisconnect(true);
+  Bluefruit.Scanner.setInterval(160, 80); // in unit of 0.625 ms
+  Bluefruit.Scanner.filterUuid(clientHRM.uuid);
+  Bluefruit.Scanner.useActiveScan(false);
+  Bluefruit.Scanner.start(0);                   // // 0 = Don't stop scanning after n seconds
+}
+
+void loop()
+{
+  // do nothing
+}
+
+/**
+ * Callback invoked when scanner pick up an advertising data
+ * @param report Structural advertising data
+ */
+void scan_callback(ble_gap_evt_adv_report_t* report)
+{
+  // Connect to device with HRM service in advertising
+  Bluefruit.Central.connect(report);
+}
+
+/**
+ * Callback invoked when an connection is established
+ * @param conn_handle
+ */
+void connect_callback(uint16_t conn_handle)
+{
+  Serial.println("Connected");
+  Serial.print("Discovering HRM Service ... ");
+
+  // If HRM is not found, disconnect and return
+  if ( !clientHRM.discover(conn_handle) )
+  {
+    Serial.println("Found NONE");
+
+    // disconect since we couldn't find HRM service
+    Bluefruit.Central.disconnect(conn_handle);
+
+    return;
+  }
+
+  // HRM is found
+  Serial.println("Found it");
+  Serial.println("Discovering Measurement and Body location characteristic ... ");
+
+  uint8_t num_found_chr = Bluefruit.Discovery.discoverCharacteristic(conn_handle, clientMeasurement, clientSensorLocation);
+
+  Serial.print("Found ");
+  Serial.print(num_found_chr);
+  Serial.println("Characteristics");
+
+  // Measurement chr is mandatory, if it is not found (valid), then disconnect
+  if ( !clientMeasurement.isValid() )
+  {
+    Serial.println("Measurement characteristic not found");
+    Bluefruit.Central.disconnect(conn_handle);
+
+    return;
+  }
+
+  // https://www.bluetooth.com/specifications/gatt/viewer?attributeXmlFile=org.bluetooth.characteristic.body_sensor_location.xml
+  // Body Sensor Location is optional, print its location (in text) if present
+  if ( clientSensorLocation.isValid() )
+  {
+    // Body sensor location value is 8 bit
+    const char* body_str[] = { "Other", "Chest", "Wrist", "Finger", "Hand", "Ear Lobe", "Foot" };
+
+    uint8_t loc_value = 0;
+    if ( clientSensorLocation.read(&loc_value) )
+    {
+      Serial.print("Body Location Sensor: ");
+      Serial.println(body_str[loc_value]);
+    }
+  }
+
+  // Reaching here means we are ready to go, let's enable notification on measurement chr
+  if ( clientMeasurement.enableNotify() )
+  {
+    Serial.println("Ready to receive HRM Measurement value");
+  }else
+  {
+    Serial.println("Couldn't enable notify for HRM Measurement. Increase DEBUG LEVEL for troubleshooting");
+  }
+}
+
+/**
+ * Callback invoked when a connection is dropped
+ * @param conn_handle
+ * @param reason
+ */
+void disconnect_callback(uint16_t conn_handle, uint8_t reason)
+{
+  (void) conn_handle;
+  (void) reason;
+
+  Serial.println("Disconnected");
+}
+
+
+/**
+ * Hooked callback that triggered when a measurement value is sent from peripheral
+ * @param chr   Reference to client characteristic that even occurred,
+ *              in this example it should be clientMeasurement
+ * @param data  Pointer to received data
+ * @param len   Length of received data
+ */
+void hrm_notify_callback(BLEClientCharacteristic& chr, uint8_t* data, uint16_t len)
+{
+  // https://www.bluetooth.com/specifications/gatt/viewer?attributeXmlFile=org.bluetooth.characteristic.heart_rate_measurement.xml
+  // Measurement contains of control byte0 and measurement (8 or 16 bit) + optional field
+  // if byte0's bit0 is 0 --> measurement is 8 bit, otherwise 16 bit.
+
+  Serial.print("HRM Measurement: ");
+
+
+  if ( data[0] & bit(0) )
+  {
+    uint16_t value;
+    memcpy(&value, data+1, 2);
+
+    Serial.println(value);
+  }
+  else
+  {
+    Serial.println(data[1]);
+  }
+}

libraries/Bluefruit52Lib/keywords.txt

@@ -171,6 +171,7 @@ parentService	KEYWORD2
 assign	KEYWORD2
 discoverDescriptor	KEYWORD2
 valueHandle	KEYWORD2
+isValid	KEYWORD2
 
 read	KEYWORD2
 write	KEYWORD2

libraries/Bluefruit52Lib/src/BLEClientCharacteristic.cpp

@@ -106,6 +106,11 @@ uint16_t BLEClientCharacteristic::valueHandle(void)
   return _chr.handle_value;
 }
 
+bool BLEClientCharacteristic::isValid(void)
+{
+  return _chr.handle_value != BLE_GATT_HANDLE_INVALID;
+}
+
 uint8_t BLEClientCharacteristic::properties(void)
 {
   uint8_t u8;
@@ -159,6 +164,21 @@ uint16_t BLEClientCharacteristic::read(void* buffer, uint16_t bufsize)
   return (rxlen < 0) ? 0 : rxlen;
 }
 
+uint16_t BLEClientCharacteristic::read(uint32_t* num)
+{
+  return read(num, 4);
+}
+
+uint16_t BLEClientCharacteristic::read(uint16_t* num)
+{
+  return read(num, 2);
+}
+
+uint16_t BLEClientCharacteristic::read(uint8_t*  num)
+{
+  return read(num, 1);
+}
+
 /*------------------------------------------------------------------*/
 /* WRITE
  *------------------------------------------------------------------*/

libraries/Bluefruit52Lib/src/BLEClientCharacteristic.h

@@ -59,35 +59,41 @@ class BLEClientCharacteristic
     // Destructor
     virtual ~BLEClientCharacteristic();
 
-    void assign(ble_gattc_char_t* gattc_chr);
-    bool discoverDescriptor(uint16_t conn_handle, ble_gattc_handle_range_t hdl_range);
+    void     assign(ble_gattc_char_t* gattc_chr);
+    bool     discoverDescriptor(uint16_t conn_handle, ble_gattc_handle_range_t hdl_range);
 
-    void begin(BLEClientService* parent_svc = NULL);
+    void     begin(BLEClientService* parent_svc = NULL);
 
     uint16_t connHandle(void);
     uint16_t valueHandle(void);
+    bool     isValid(void);
     uint8_t  properties(void);
+
+
     BLEClientService& parentService(void);
 
     /*------------- Read -------------*/
     uint16_t read(void* buffer, uint16_t bufsize);
+    uint16_t read(uint32_t* num);
+    uint16_t read(uint16_t* num);
+    uint16_t read(uint8_t*  num);
 
     /*------------- Write -------------*/
     uint16_t write     (const void* data, uint16_t len);
     uint16_t write_resp(const void* data, uint16_t len);
 
     /*------------- Notify -------------*/
-    bool writeCCCD       (uint16_t value);
+    bool     writeCCCD       (uint16_t value);
 
-    bool enableNotify    (void);
-    bool disableNotify   (void);
+    bool     enableNotify    (void);
+    bool     disableNotify   (void);
 
-    bool enableIndicate  (void);
-    bool disableIndicate (void);
+    bool     enableIndicate  (void);
+    bool     disableIndicate (void);
 
     /*------------- Callbacks -------------*/
-    void setNotifyCallback(notify_cb_t fp);
-    void useAdaCallback(bool enabled);
+    void     setNotifyCallback(notify_cb_t fp);
+    void     useAdaCallback(bool enabled);
 
   private:
     ble_gattc_char_t   _chr;