Heart Rate Monitor example for the BLE API using nRF51822 native mode drivers

Dependencies:   BLE_API mbed nRF51822 X_NUCLEO_IDB0XA1

BLE_HeartRate implements the Heart Rate Service which enables a collector device (such as a smart phone) to connect and interact with a Heart Rate Sensor.

For the sake of simplicity and portability, the sensor in this case has been abstracted using a counter which counts up to a threshold and then recycles. The code can be easily extended to use the real heart rate sensor.

Apps on the collector device may expect auxiliary services to supplement the HRService. We've therefore also included the Device Information Service and the Battery Service.

BLE_API offers the building blocks to compose the needed GATT services out of Characteristics and Attributes, but that can be cumbersome. As a shortcut, it is possible to simply instantiate reference services offered by BLE_API, and we'll be taking that easier route. The user is encouraged to peek under the hood of these 'services' and be aware of the underlying mechanics. It is not necessary to use these ready-made services.

Like most non-trivial services, the heart-rate service is connection oriented. In the default state, the application configures the Bluetooth stack to advertise its presence and indicate connectability. A Central/Master device is expected to scan for advertisements from peripherals in the vicinity and then initiate a connection. Once connected, the peripheral stops advertising, and communicates periodically as a server using the Attribute Protocol.

Walkthrough of the code

Let's see how this magic is achieved. We'll be pulling out excerpts from main.cpp where most of the code resides.

You'll find that the entire system is event driven, with a single main thread idling most of its time in a while loop and being interrupted by events. An important startup activity for the application is to setup the event callback handlers appropriately.

The first thing to notice is the BLEDevice class, which encapsulates the Bluetooth low energy protocol stack.


#include "BLEDevice.h"

BLEDevice  ble;

void disconnectionCallback(Gap::Handle_t handle, Gap::DisconnectionReason_t reason)
    ble.startAdvertising(); // restart advertising

int main(void)

    while (true) {

There is an init() method that must be called before using the BLEDevice object. The startAdvertising() method is called to advertise the device's presence allowing other devices to connect to it.

onDisconnect() is a typical example of setting up of an event handler. With onDisconnect(), a callback function is setup to restart advertising when the connection is terminated.

The waitForEvent() method should be called whenever the main thread is 'done' doing any work; it hands the control over to the protocol and lets you save power. So when will waitForEvent() return? Basically whenever you have an application interrupt, and most typically that results in some event callback being invoked. In this example there is a Ticker object that is setup to call a function every second. Whenever the ticker 'ticks' the periodicCallback() is invoked, and then waitForEvent() returns, resuming the execution in main.

Interrupt to trigger periodic actions

void periodicCallback(void)
    led1 = !led1; /* Do blinky on LED1 while we're waiting for BLE events */

    /* Note that the periodicCallback() executes in interrupt context, so it is safer to do
     * heavy-weight sensor polling from the main thread. */
    triggerSensorPolling = true;

int main(void)
    led1 = 1;
    Ticker ticker;
    ticker.attach(periodicCallback, 1);

It is worth emphasizing that the periodicCallback() (or any other event handler) is called in interrupt context; and should not engage in any heavy-weight tasks to avoid the system from becoming unresponsive. A typical workaround is to mark some activity as pending to be handled in the main thread; as done through 'triggerSensorPolling'.

BLEDevice offers APIs to setup GAP (for connectability) and GATT (for services). As has been mentioned already, GATT services may be composed by defining Characteristics and Attributes separately (which is cumbersome), or in some cases by simply instantiating reference services offered by BLE_API. The following illustrates how straightforward this can be. You are encouraged to peek under the hood of these implementations and study the mechanics.

Service setup

    /* Setup primary service. */
    uint8_t hrmCounter = 100;
    HeartRateService hrService(ble, hrmCounter, HeartRateService::LOCATION_FINGER);

    /* Setup auxiliary services. */
    BatteryService           battery(ble);
    DeviceInformationService deviceInfo(ble, "ARM", "Model1", "SN1", "hw-rev1", "fw-rev1", "soft-rev1");

Setting up GAP mostly has to do with configuring connectability and the payload contained in the advertisement packets.

Advertiser setup

    ble.accumulateAdvertisingPayload(GapAdvertisingData::BREDR_NOT_SUPPORTED | GapAdvertisingData::LE_GENERAL_DISCOVERABLE);
    ble.accumulateAdvertisingPayload(GapAdvertisingData::COMPLETE_LIST_16BIT_SERVICE_IDS, (uint8_t *)uuid16_list, sizeof(uuid16_list));
    ble.accumulateAdvertisingPayload(GapAdvertisingData::COMPLETE_LOCAL_NAME, (uint8_t *)DEVICE_NAME, sizeof(DEVICE_NAME));
    ble.setAdvertisingInterval(1600); /* 1000ms; in multiples of 0.625ms. */

The first line (above) is mandatory for Bluetooth Smart, and says that this device only supports Bluetooth low energy. The 'general discoverable' is the typical value to set when you want your device to be seen by other devices on order to connect. Next comes the ID for the heart rate sensor service and the name of the device.

After the payload is set the code sets the advertising type and the advertising interval. In Bluetooth Smart timing values are typically multiples of 625 us.

If you are new to Bluetooth Smart there are probably a lot of terms that are new to you. There is a lot of information about this on the Internet.

Revisions of main.cpp

Revision Date Message Actions
75:8128a06c0a21 2015-11-03 fix waiting condition for ble initialization process File  Diff  Annotate
74:c9d58e7847c4 2015-11-03 update to the latest of underlying ilbraries. File  Diff  Annotate
73:49b6090478e2 2015-11-02 make use of BLE::hasInitialized() before entering the main loop. File  Diff  Annotate
72:99c283dfe28d 2015-11-02 update to v2.0.0 of BLE_API. Add bleInitComplete() to main.c File  Diff  Annotate
71:469dbde1a238 2015-09-29 updating call to onDisconnection() due to updates to underlying libraries. File  Diff  Annotate
67:b2d2dee347c0 2015-07-01 update path for header includes. File  Diff  Annotate
66:c09ddf226b9c 2015-06-20 switch to newer APIs; rename BLEDevice to BLE File  Diff  Annotate
65:cb76569f74f6 2015-06-20 make use of the gap() accessor for ble File  Diff  Annotate
56:83623419d5e4 2015-03-24 updating underlying libraries File  Diff  Annotate
55:3a7d497a3e03 2015-02-09 removed unncessary Battery Service from HearRate demo code File  Diff  Annotate
53:06a74fd722b8 2014-11-28 Updating to 0.2.5 of BLE_API File  Diff  Annotate
52:6bbf62943106 2014-11-21 add some code to configure slower connection interval File  Diff  Annotate
50:477004d54431 2014-11-17 add a check for gap-connectedness before polling for sensor data. File  Diff  Annotate
47:430545f41113 2014-09-30 updating the underlying libraries. File  Diff  Annotate
46:ee7c55907f36 2014-09-30 DFUService is now added automatically for DFU platforms. File  Diff  Annotate
45:98c5a34b07a4 2014-09-29 move service initialization before starting advertisements. File  Diff  Annotate
43:dbb025ed4a55 2014-09-23 minor update to advertising payload; and fleshing out Device Information Service. File  Diff  Annotate
42:06ebef2e0e44 2014-09-22 updating to 0.2.0 of the BLE_API File  Diff  Annotate
41:9cef0129da5f 2014-09-02 updated underlying libraries File  Diff  Annotate
40:e73130c6f2bb 2014-08-22 white space diffs File  Diff  Annotate
39:6390604f904c 2014-08-22 Extract HeartRateService as a template to simplify the main application. File  Diff  Annotate
37:d310a72115c7 2014-07-11 updated heart-rate demo to use the new connectionParams APIs File  Diff  Annotate
36:ea2a1b4f51c1 2014-07-11 change hrm demo to do sensor polling from the main thread File  Diff  Annotate
35:ba3e3174331a 2014-07-11 disconnectionCallback now takes a handle File  Diff  Annotate
34:44dc6efc0b50 2014-07-08 use a declared constant for the Heart-Rate Location characteristic File  Diff  Annotate
33:e63df636d3b2 2014-07-08 Remove a const attribute for a global variable used to initialize the location characteristic. File  Diff  Annotate
30:3dc9e6f2bc8c 2014-07-04 remove the battery-level and device-information services File  Diff  Annotate
29:76d865c718a6 2014-07-04 HRM demo now works with the nordic Android App (nRFToolBox) File  Diff  Annotate
28:bdfc8cc53f0b 2014-07-04 add the battery level server to the HRM demo File  Diff  Annotate
27:97adf2b76b9c 2014-07-03 add 16-bit UUIDs to the advertising payload; this is cosmetic File  Diff  Annotate
26:e6ad33b227c6 2014-07-03 add deviceInformationService to the basic HRM demo File  Diff  Annotate
22:299658c5fa3c 2014-06-12 simplify demo to only contain the heart-rate service File  Diff  Annotate
20:58bff62d0f7a 2014-06-11 remove un-necessary callbacks from the demo File  Diff  Annotate
19:1713b11694ea 2014-06-11 make use of the new GattService constructor which takes in an array of pointers to Characteristics File  Diff  Annotate
18:8a2e313f49cb 2014-06-11 GattServer::addService() automatically sets initial value for characteristics File  Diff  Annotate
17:583b765af55f 2014-06-11 remove an un-used global variable File  Diff  Annotate
16:f3361e20642d 2014-06-11 minor white-space diffs having to do with coding style File  Diff  Annotate
15:7ba28817e31e 2014-06-10 move ble_init() to the beginning of main() File  Diff  Annotate
13:3ca2045597e7 2014-06-10 minor updates to comment headers File  Diff  Annotate
11:1d9aafee4984 2014-06-10 use a ticker to schedule a periodicCallback() instead of a busy-wait loop File  Diff  Annotate
10:2436164b692e 2014-06-10 reverting to BLEDevice (from BLEPeripheral) File  Diff  Annotate
9:5d693381e883 2014-06-10 make console output optional File  Diff  Annotate
8:49d8ee0aac11 2014-06-10 remove ticker; consumes un-necessary power; also added a satic const File  Diff  Annotate
7:daab8ba5139e 2014-06-10 Update to using the latest versions of the underlying APIs and waitForEvent() to reduce power consumption. File  Diff  Annotate
5:b0baff4a124f 2014-05-29 use accessor methods to get handle for characteristics File  Diff  Annotate
4:12890f3c62eb 2014-05-21 removing un-necessary nordic-specific hardware initialization from the demo File  Diff  Annotate
3:24e2b056d229 2014-05-21 white space diffs; using uncrustify File  Diff  Annotate
0:87a7fc231fae 2014-03-31 First commit of HRM example for the BLE API (using nRF51822 native mode drivers) File  Diff  Annotate