mirror of https://github.com/ARMmbed/mbed-os.git
BLE: update heart rate service definition.
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.pull/5475/head
Vincent Coubard
parent
47bae16a5c
commit
93a4a2a87b
|
|
@ -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.
|
||||
* 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 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, uint8_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 Constructor with a 16-bit HRM Counter value.
|
||||
* Update the heart rate that the service exposes.
|
||||
*
|
||||
* @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.
|
||||
*/
|
||||
HeartRateService(BLE &_ble, uint16_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 Set a new 8-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 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.
|
||||
* @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 *));
|
||||
GattCharacteristic *charTable[] = {
|
||||
&hrmRate,
|
||||
&hrmLocation
|
||||
};
|
||||
GattService hrmService(
|
||||
GattService::UUID_HEART_RATE_SERVICE,
|
||||
charTable,
|
||||
sizeof(charTable) / sizeof(GattCharacteristic*)
|
||||
);
|
||||
|
||||
ble.addService(hrmService);
|
||||
ble.onDataWritten(this, &HeartRateService::onDataWritten);
|
||||
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);
|
||||
static const uint8_t VALUE_FORMAT_FLAG = (1 << VALUE_FORMAT_BITNUM);
|
||||
|
||||
HeartRateValueBytes(uint8_t hrmCounter) : valueBytes() {
|
||||
HeartRateValueBytes(uint16_t hrmCounter) : valueBytes()
|
||||
{
|
||||
updateHeartRate(hrmCounter);
|
||||
}
|
||||
|
||||
HeartRateValueBytes(uint16_t hrmCounter) : valueBytes() {
|
||||
updateHeartRate(hrmCounter);
|
||||
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);
|
||||
}
|
||||
}
|
||||
|
||||
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);
|
||||
}
|
||||
|
||||
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__*/
|
||||
|
|
|
|||
Loading…
Reference in New Issue