ARMmbed
/
mbed-os
mirror of https://github.com/ARMmbed/mbed-os.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge pull request #5475 from pan-/doc_heart_rate_service 

BLE: update heart rate service definition.
pull/5358/merge
Martin Kojtal 2017-11-16 16:16:37 +00:00 committed by GitHub
parent 01bc4340e8 a855251cba
commit bc92e40d1b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 156 additions and 119 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

275
features/FEATURE_BLE/ble/services/HeartRateService.h
View File

@ -14,181 +14,218 @@
* limitations under the License. * limitations under the License.
*/ */
#ifndef __BLE_HEART_RATE_SERVICE_H__ #ifndef MBED_BLE_HEART_RATE_SERVICE_H__
#define __BLE_HEART_RATE_SERVICE_H__ #define MBED_BLE_HEART_RATE_SERVICE_H__
#include "ble/BLE.h" #include "ble/BLE.h"
/** /**
* @class HeartRateService * BLE Heart Rate Service.
* @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 * @purpose
* 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 * Fitness applications use the heart rate service to expose the heart
*/ * beat per minute measured by a 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 a 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 { class HeartRateService {
public: public:
/** /**
* @enum SensorLocation * Intended location of the heart rate sensor.
* @brief Location of the heart rate sensor on body. */
*/ enum BodySensorLocation {
enum { /**
LOCATION_OTHER = 0, /*!< Other location. */ * Other location.
LOCATION_CHEST, /*!< Chest. */ */
LOCATION_WRIST, /*!< Wrist. */ LOCATION_OTHER = 0,
LOCATION_FINGER, /*!< Finger. */
LOCATION_HAND, /*!< Hand. */ /**
LOCATION_EAR_LOBE, /*!< Earlobe. */ * Chest.
LOCATION_FOOT, /*!< Foot. */ */
LOCATION_CHEST = 1,
/**
* Wrist.
*/
LOCATION_WRIST = 2,
/**
* Finger.
*/
LOCATION_FINGER,
/**
* Hand.
*/
LOCATION_HAND,
/**
* Earlobe.
*/
LOCATION_EAR_LOBE,
/**
* Foot.
*/
LOCATION_FOOT,
}; };
public: public:
/** /**
* @brief Constructor with 8-bit HRM Counter value. * Construct and initialize a heart rate service.
* *
* @param[ref] _ble * The construction process adds a GATT heart rate service in @p _ble
* Reference to the underlying BLE. * GattServer, sets the value of the heart rate measurement characteristic
* @param[in] hrmCounter (8-bit) * to @p hrmCounter and the value of the body sensor location characteristic
* Initial value for the HRM counter. * to @p location.
* @param[in] location *
* Sensor's location. * @param[in] _ble BLE device that hosts 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), ble(_ble),
valueBytes(hrmCounter), valueBytes(hrmCounter),
hrmRate(GattCharacteristic::UUID_HEART_RATE_MEASUREMENT_CHAR, valueBytes.getPointer(), hrmRate(
valueBytes.getNumValueBytes(), HeartRateValueBytes::MAX_VALUE_BYTES, GattCharacteristic::UUID_HEART_RATE_MEASUREMENT_CHAR,
GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_NOTIFY), valueBytes.getPointer(),
hrmLocation(GattCharacteristic::UUID_BODY_SENSOR_LOCATION_CHAR, &location), valueBytes.getNumValueBytes(),
controlPoint(GattCharacteristic::UUID_HEART_RATE_CONTROL_POINT_CHAR, &controlPointValue) { HeartRateValueBytes::MAX_VALUE_BYTES,
GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_NOTIFY
),
hrmLocation(
GattCharacteristic::UUID_BODY_SENSOR_LOCATION_CHAR,
reinterpret_cast<uint8_t*>(&location)
)
{
setupService(); setupService();
} }
/** /**
* @brief Constructor with a 16-bit HRM Counter value. * Update the heart rate that the service exposes.
* *
* @param[in] _ble * The server sends a notification of the new value to clients that have
* Reference to the underlying BLE. * subscribed to updates of the heart rate measurement characteristic; clients
* @param[in] hrmCounter (8-bit) * reading the heart rate measurement characteristic after the update obtain
* Initial value for the HRM counter. * the updated value.
* @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.
* *
* @param[in] hrmCounter * @param[in] hrmCounter Heart rate measured in BPM.
* 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 * @important This function must be called in the execution context of the
* Heart rate in BPM. * BLE stack.
*/ */
void updateHeartRate(uint16_t hrmCounter) { void updateHeartRate(uint16_t hrmCounter) {
valueBytes.updateHeartRate(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 * Construct and add to the GattServer the heart rate service.
* controlPoint characteristic.
*
* @param[in] params
* Information about the characteristic being updated.
*/ */
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) { void setupService(void) {
GattCharacteristic *charTable[] = {&hrmRate, &hrmLocation, &controlPoint}; GattCharacteristic *charTable[] = {
GattService hrmService(GattService::UUID_HEART_RATE_SERVICE, charTable, sizeof(charTable) / sizeof(GattCharacteristic *)); &hrmRate,
&hrmLocation
};
GattService hrmService(
GattService::UUID_HEART_RATE_SERVICE,
charTable,
sizeof(charTable) / sizeof(GattCharacteristic*)
);
ble.addService(hrmService); ble.gattServer().addService(hrmService);
ble.onDataWritten(this, &HeartRateService::onDataWritten);
} }
protected: protected:
/* Private internal representation for the bytes used to work with the value of the heart rate characteristic. */ /*
* Heart rate measurement value.
*/
struct HeartRateValueBytes { 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 FLAGS_BYTE_INDEX = 0;
static const unsigned VALUE_FORMAT_BITNUM = 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); updateHeartRate(hrmCounter);
} }
HeartRateValueBytes(uint16_t hrmCounter) : valueBytes() { void updateHeartRate(uint16_t hrmCounter)
updateHeartRate(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) { uint8_t *getPointer(void)
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) {
return valueBytes; return valueBytes;
} }
const uint8_t *getPointer(void) const { const uint8_t *getPointer(void) const
{
return valueBytes; return valueBytes;
} }
unsigned getNumValueBytes(void) const { unsigned getNumValueBytes(void) const
return 1 + ((valueBytes[FLAGS_BYTE_INDEX] & VALUE_FORMAT_FLAG) ? sizeof(uint16_t) : sizeof(uint8_t)); {
if (valueBytes[FLAGS_BYTE_INDEX] & VALUE_FORMAT_FLAG) {
return 1 + sizeof(uint16_t);
} else {
return 1 + sizeof(uint8_t);
}
} }
private: 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]; uint8_t valueBytes[MAX_VALUE_BYTES];
}; };
protected: protected:
BLE &ble; BLE &ble;
HeartRateValueBytes valueBytes;
HeartRateValueBytes valueBytes; GattCharacteristic hrmRate;
uint8_t controlPointValue; ReadOnlyGattCharacteristic<uint8_t> hrmLocation;
GattCharacteristic hrmRate;
ReadOnlyGattCharacteristic<uint8_t> hrmLocation;
WriteOnlyGattCharacteristic<uint8_t> controlPoint;
}; };
#endif /* #ifndef __BLE_HEART_RATE_SERVICE_H__*/ #endif /* #ifndef MBED_BLE_HEART_RATE_SERVICE_H__*/