BLE: update heart rate service definition.

pan- · pan- · commit 93a4a2a87baa · 2017-11-10T15:38:39.000Z
This patch includes:
* Documentation update.
* Code simplification and correctness; the value overloads based on the
  size of the hrm counter has been removed in favor of runtime check which
  is more correct.
* The control point characteristic has been removed since HeartRate value
  byte does not support the accumulated energy expanded.
diff --git a/features/FEATURE_BLE/ble/services/HeartRateService.h b/features/FEATURE_BLE/ble/services/HeartRateService.h
@@ -14,181 +14,218 @@
  * limitations under the License.
  */
 
-#ifndef __BLE_HEART_RATE_SERVICE_H__
-#define __BLE_HEART_RATE_SERVICE_H__
+#ifndef MBED_BLE_HEART_RATE_SERVICE_H__
+#define MBED_BLE_HEART_RATE_SERVICE_H__
 
 #include "ble/BLE.h"
 
 /**
-* @class HeartRateService
-* @brief BLE Service for HeartRate. This BLE Service contains the location of the sensor and the heart rate in beats per minute.
-* Service:  https://developer.bluetooth.org/gatt/services/Pages/ServiceViewer.aspx?u=org.bluetooth.service.heart_rate.xml
-* HRM Char: https://developer.bluetooth.org/gatt/characteristics/Pages/CharacteristicViewer.aspx?u=org.bluetooth.characteristic.heart_rate_measurement.xml
-* Location: https://developer.bluetooth.org/gatt/characteristics/Pages/CharacteristicViewer.aspx?u=org.bluetooth.characteristic.body_sensor_location.xml
-*/
+ * BLE Heart Rate Service.
+ *
+ * @purpose
+ *
+ * The heart rate service is used by fitness applications to exposes the heart
+ * beat per minute measured by an heart rate sensor.
+ *
+ * Clients can read the intended location of the sensor and the last heart rate
+ * value measured. Additionally clients can subscribe to server initiated
+ * updates of the heart rate value measured by the sensor. The service delivers
+ * these updates to the subscribed client in a notification packet.
+ *
+ * The subscription mechanism is useful to save power; it avoids unecessary data
+ * traffic between the client and the server, which may be induced by polling the
+ * value of the heart rate measurement characteristic.
+ *
+ * @par usage
+ *
+ * When this class is instantiated, it adds an heart rate service in the GattServer.
+ * The service contains the location of the sensor and the initial value measured
+ * by the sensor.
+ *
+ * Application code can invoke updateHeartRate() when a new heart rate measurement
+ * is acquired; this function updates the value of the heart rate measurement
+ * characteristic and notifies the new value to subscribed clients.
+ *
+ * @note You can find specification of the heart rate service here:
+ * https://www.bluetooth.com/specifications/gatt
+ *
+ * @important The service does not expose information related to the sensor
+ * contact, the accumulated energy expanded or the interbeat intervals.
+ *
+ * @important The heart rate profile limits the number of instantiations of the
+ * heart rate services to one.
+ */
 class HeartRateService {
 public:
     /**
-    * @enum SensorLocation
-    * @brief Location of the heart rate sensor on body.
-    */
-    enum {
-        LOCATION_OTHER = 0, /*!< Other location. */
-        LOCATION_CHEST,     /*!< Chest. */
-        LOCATION_WRIST,     /*!< Wrist. */
-        LOCATION_FINGER,    /*!< Finger. */
-        LOCATION_HAND,      /*!< Hand. */
-        LOCATION_EAR_LOBE,  /*!< Earlobe. */
-        LOCATION_FOOT,      /*!< Foot. */
+     * Intended location of the heart rate sensor.
+     */
+    enum BodySensorLocation {
+        /**
+         * Other location.
+         */
+        LOCATION_OTHER = 0,
+
+        /**
+         * Chest.
+         */
+        LOCATION_CHEST = 1,
+
+        /**
+         * Wrist.
+         */
+        LOCATION_WRIST = 2,
+
+        /**
+         * Finger.
+         */
+        LOCATION_FINGER,
+
+        /**
+         * Hand.
+         */
+        LOCATION_HAND,
+
+        /**
+         * Earlobe.
+         */
+        LOCATION_EAR_LOBE,
+
+        /**
+         * Foot.
+         */
+        LOCATION_FOOT,
     };
 
 public:
     /**
-     * @brief Constructor with 8-bit HRM Counter value.
+     * Construct and initialize an heart rate service.
      *
-     * @param[ref] _ble
-     *               Reference to the underlying BLE.
-     * @param[in] hrmCounter (8-bit)
-     *               Initial value for the HRM counter.
-     * @param[in] location
-     *               Sensor's location.
-     */
-    HeartRateService(BLE &_ble, uint8_t hrmCounter, uint8_t location) :
-        ble(_ble),
-        valueBytes(hrmCounter),
-        hrmRate(GattCharacteristic::UUID_HEART_RATE_MEASUREMENT_CHAR, valueBytes.getPointer(),
-                valueBytes.getNumValueBytes(), HeartRateValueBytes::MAX_VALUE_BYTES,
-                GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_NOTIFY),
-        hrmLocation(GattCharacteristic::UUID_BODY_SENSOR_LOCATION_CHAR, &location),
-        controlPoint(GattCharacteristic::UUID_HEART_RATE_CONTROL_POINT_CHAR, &controlPointValue) {
-        setupService();
-    }
-
-    /**
-     * @brief Constructor with a 16-bit HRM Counter value.
+     * The construction process adds a GATT heart rate service in @p _ble
+     * GattServer, sets the value of the heart rate measurement characteristic
+     * to @p hrmCounter and the value of the body sensor location characteristic
+     * to @p location.
      *
-     * @param[in] _ble
-     *               Reference to the underlying BLE.
-     * @param[in] hrmCounter (8-bit)
-     *               Initial value for the HRM counter.
-     * @param[in] location
-     *               Sensor's location.
+     * @param[in] _ble BLE device which will host the heart rate service.
+     * @param[in] hrmCounter Heart beats per minute measured by the heart rate
+     * sensor.
+     * @param[in] location Intended location of the heart rate sensor.
      */
-    HeartRateService(BLE &_ble, uint16_t hrmCounter, uint8_t location) :
+    HeartRateService(BLE &_ble, uint16_t hrmCounter, BodySensorLocation location) :
         ble(_ble),
         valueBytes(hrmCounter),
-        hrmRate(GattCharacteristic::UUID_HEART_RATE_MEASUREMENT_CHAR, valueBytes.getPointer(),
-                valueBytes.getNumValueBytes(), HeartRateValueBytes::MAX_VALUE_BYTES,
-                GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_NOTIFY),
-        hrmLocation(GattCharacteristic::UUID_BODY_SENSOR_LOCATION_CHAR, &location),
-        controlPoint(GattCharacteristic::UUID_HEART_RATE_CONTROL_POINT_CHAR, &controlPointValue) {
+        hrmRate(
+            GattCharacteristic::UUID_HEART_RATE_MEASUREMENT_CHAR,
+            valueBytes.getPointer(),
+            valueBytes.getNumValueBytes(),
+            HeartRateValueBytes::MAX_VALUE_BYTES,
+            GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_NOTIFY
+        ),
+        hrmLocation(
+            GattCharacteristic::UUID_BODY_SENSOR_LOCATION_CHAR,
+            reinterpret_cast<uint8_t*>(&location)
+        )
+    {
         setupService();
     }
 
     /**
-     * @brief Set a new 8-bit value for the heart rate.
+     * Update the heart rate that the service exposes.
      *
-     * @param[in] hrmCounter
-     *                  Heart rate in BPM.
-     */
-    void updateHeartRate(uint8_t hrmCounter) {
-        valueBytes.updateHeartRate(hrmCounter);
-        ble.gattServer().write(hrmRate.getValueHandle(), valueBytes.getPointer(), valueBytes.getNumValueBytes());
-    }
-
-    /**
-     * Set a new 16-bit value for the heart rate.
+     * The server sends a notification of the new value to clients that have
+     * subscribed to updates of the heart rate measurement characteristic; clients
+     * reading the heart rate measurement characteristic after the update obtain
+     * the updated value.
+     *
+     * @param[in] hrmCounter Heart rate measured in BPM.
      *
-     * @param[in] hrmCounter
-     *                  Heart rate in BPM.
+     * @important This function must be called in the execution context of the
+     * BLE stack.
      */
     void updateHeartRate(uint16_t hrmCounter) {
         valueBytes.updateHeartRate(hrmCounter);
-        ble.gattServer().write(hrmRate.getValueHandle(), valueBytes.getPointer(), valueBytes.getNumValueBytes());
+        ble.gattServer().write(
+            hrmRate.getValueHandle(),
+            valueBytes.getPointer(),
+            valueBytes.getNumValueBytes()
+        );
     }
 
+protected:
     /**
-     * This callback allows the heart rate service to receive updates to the
-     * controlPoint characteristic.
-     *
-     * @param[in] params
-     *     Information about the characteristic being updated.
+     * Construct and add to the GattServer the heart rate service.
      */
-    virtual void onDataWritten(const GattWriteCallbackParams *params) {
-        if (params->handle == controlPoint.getValueAttribute().getHandle()) {
-            /* Do something here if the new value is 1; else you can override this method by
-             * extending this class.
-             * @NOTE: If you are extending this class, be sure to also call
-             * ble.onDataWritten(this, &ExtendedHRService::onDataWritten); in
-             * your constructor.
-             */
-        }
-    }
-
-protected:
     void setupService(void) {
-        GattCharacteristic *charTable[] = {&hrmRate, &hrmLocation, &controlPoint};
-        GattService         hrmService(GattService::UUID_HEART_RATE_SERVICE, charTable, sizeof(charTable) / sizeof(GattCharacteristic *));
-
-        ble.addService(hrmService);
-        ble.onDataWritten(this, &HeartRateService::onDataWritten);
+        GattCharacteristic *charTable[] = {
+            &hrmRate,
+            &hrmLocation
+        };
+        GattService hrmService(
+            GattService::UUID_HEART_RATE_SERVICE,
+            charTable,
+            sizeof(charTable) / sizeof(GattCharacteristic*)
+        );
+
+        ble.gattServer().addService(hrmService);
     }
 
 protected:
-    /* Private internal representation for the bytes used to work with the value of the heart rate characteristic. */
+    /*
+     * Heart rate measurement value.
+     */
     struct HeartRateValueBytes {
-        static const unsigned MAX_VALUE_BYTES  = 3; /* Flags, and up to two bytes for heart rate. */
+        /* 1 byte for the Flags, and up to two bytes for heart rate value. */
+        static const unsigned MAX_VALUE_BYTES = 3;
         static const unsigned FLAGS_BYTE_INDEX = 0;
 
         static const unsigned VALUE_FORMAT_BITNUM = 0;
-        static const uint8_t  VALUE_FORMAT_FLAG   = (1 << VALUE_FORMAT_BITNUM);
-
-        HeartRateValueBytes(uint8_t hrmCounter) : valueBytes() {
-            updateHeartRate(hrmCounter);
-        }
+        static const uint8_t  VALUE_FORMAT_FLAG = (1 << VALUE_FORMAT_BITNUM);
 
-        HeartRateValueBytes(uint16_t hrmCounter) : valueBytes() {
+        HeartRateValueBytes(uint16_t hrmCounter) : valueBytes()
+        {
             updateHeartRate(hrmCounter);
         }
 
-        void updateHeartRate(uint8_t hrmCounter) {
-            valueBytes[FLAGS_BYTE_INDEX]    &= ~VALUE_FORMAT_FLAG;
-            valueBytes[FLAGS_BYTE_INDEX + 1] = hrmCounter;
-        }
-
-        void updateHeartRate(uint16_t hrmCounter) {
-            valueBytes[FLAGS_BYTE_INDEX]    |= VALUE_FORMAT_FLAG;
-            valueBytes[FLAGS_BYTE_INDEX + 1] = (uint8_t)(hrmCounter & 0xFF);
-            valueBytes[FLAGS_BYTE_INDEX + 2] = (uint8_t)(hrmCounter >> 8);
+        void updateHeartRate(uint16_t hrmCounter)
+        {
+            if (hrmCounter <= 255) {
+                valueBytes[FLAGS_BYTE_INDEX] &= ~VALUE_FORMAT_FLAG;
+                valueBytes[FLAGS_BYTE_INDEX + 1] = hrmCounter;
+            } else {
+                valueBytes[FLAGS_BYTE_INDEX] |= VALUE_FORMAT_FLAG;
+                valueBytes[FLAGS_BYTE_INDEX + 1] = (uint8_t)(hrmCounter & 0xFF);
+                valueBytes[FLAGS_BYTE_INDEX + 2] = (uint8_t)(hrmCounter >> 8);
+            }
         }
 
-        uint8_t       *getPointer(void) {
+        uint8_t *getPointer(void)
+        {
             return valueBytes;
         }
 
-        const uint8_t *getPointer(void) const {
+        const uint8_t *getPointer(void) const
+        {
             return valueBytes;
         }
 
-        unsigned       getNumValueBytes(void) const {
-            return 1 + ((valueBytes[FLAGS_BYTE_INDEX] & VALUE_FORMAT_FLAG) ? sizeof(uint16_t) : sizeof(uint8_t));
+        unsigned getNumValueBytes(void) const
+        {
+            if (valueBytes[FLAGS_BYTE_INDEX] & VALUE_FORMAT_FLAG) {
+                return 1 + sizeof(uint16_t);
+            } else {
+                return 1 + sizeof(uint8_t);
+            }
         }
 
     private:
-        /* First byte: 8-bit values, no extra info. Second byte: uint8_t HRM value */
-        /* See https://developer.bluetooth.org/gatt/characteristics/Pages/CharacteristicViewer.aspx?u=org.bluetooth.characteristic.heart_rate_measurement.xml */
         uint8_t valueBytes[MAX_VALUE_BYTES];
     };
 
 protected:
-    BLE                 &ble;
-
-    HeartRateValueBytes  valueBytes;
-    uint8_t              controlPointValue;
-
-    GattCharacteristic                   hrmRate;
-    ReadOnlyGattCharacteristic<uint8_t>  hrmLocation;
-    WriteOnlyGattCharacteristic<uint8_t> controlPoint;
+    BLE &ble;
+    HeartRateValueBytes valueBytes;
+    GattCharacteristic hrmRate;
+    ReadOnlyGattCharacteristic<uint8_t> hrmLocation;
 };
 
-#endif /* #ifndef __BLE_HEART_RATE_SERVICE_H__*/
+#endif /* #ifndef MBED_BLE_HEART_RATE_SERVICE_H__*/
