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.

BLEDevice

#include "BLEDevice.h"

BLEDevice  ble;

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

int main(void)
{
    ble.init();
    ble.onDisconnection(disconnectionCallback);
 ...
    ble.startAdvertising();

    while (true) {
...
            ble.waitForEvent();
...
    }
}

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::GENERIC_HEART_RATE_SENSOR);
    ble.accumulateAdvertisingPayload(GapAdvertisingData::COMPLETE_LOCAL_NAME, (uint8_t *)DEVICE_NAME, sizeof(DEVICE_NAME));
    ble.setAdvertisingType(GapAdvertisingParams::ADV_CONNECTABLE_UNDIRECTED);
    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.

Committer:
Vincent Coubard
Date:
Tue Sep 20 12:36:16 2016 +0100
Revision:
79:8b7c8c240540
Parent:
74:c9d58e7847c4
Update libraries.
Add support of ST shield.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
ktownsend0:87a7fc231fae 1/* mbed Microcontroller Library
rgrover167:b2d2dee347c0 2 * Copyright (c) 2006-2015 ARM Limited
ktownsend0:87a7fc231fae 3 *
ktownsend0:87a7fc231fae 4 * Licensed under the Apache License, Version 2.0 (the "License");
ktownsend0:87a7fc231fae 5 * you may not use this file except in compliance with the License.
ktownsend0:87a7fc231fae 6 * You may obtain a copy of the License at
ktownsend0:87a7fc231fae 7 *
ktownsend0:87a7fc231fae 8 * http://www.apache.org/licenses/LICENSE-2.0
ktownsend0:87a7fc231fae 9 *
ktownsend0:87a7fc231fae 10 * Unless required by applicable law or agreed to in writing, software
ktownsend0:87a7fc231fae 11 * distributed under the License is distributed on an "AS IS" BASIS,
ktownsend0:87a7fc231fae 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
ktownsend0:87a7fc231fae 13 * See the License for the specific language governing permissions and
ktownsend0:87a7fc231fae 14 * limitations under the License.
ktownsend0:87a7fc231fae 15 */
ktownsend0:87a7fc231fae 16
ktownsend0:87a7fc231fae 17#include "mbed.h"
rgrover167:b2d2dee347c0 18#include "ble/BLE.h"
rgrover167:b2d2dee347c0 19#include "ble/services/HeartRateService.h"
rgrover167:b2d2dee347c0 20#include "ble/services/BatteryService.h"
rgrover167:b2d2dee347c0 21#include "ble/services/DeviceInformationService.h"
ktownsend0:87a7fc231fae 22
rgrover147:430545f41113 23DigitalOut led1(LED1);
ktownsend0:87a7fc231fae 24
mbedAustin55:3a7d497a3e03 25const static char DEVICE_NAME[] = "HRM1";
rgrover142:06ebef2e0e44 26static const uint16_t uuid16_list[] = {GattService::UUID_HEART_RATE_SERVICE,
rgrover142:06ebef2e0e44 27 GattService::UUID_DEVICE_INFORMATION_SERVICE};
rgrover139:6390604f904c 28static volatile bool triggerSensorPolling = false;
Rohit Grover 36:ea2a1b4f51c1 29
rgrover172:99c283dfe28d 30uint8_t hrmCounter = 100; // init HRM to 100bps
rgrover172:99c283dfe28d 31
rgrover172:99c283dfe28d 32HeartRateService *hrService;
rgrover172:99c283dfe28d 33DeviceInformationService *deviceInfo;
rgrover172:99c283dfe28d 34
rgrover171:469dbde1a238 35void disconnectionCallback(const Gap::DisconnectionCallbackParams_t *params)
rgrover17:daab8ba5139e 36{
rgrover173:49b6090478e2 37 BLE::Instance(BLE::DEFAULT_INSTANCE).gap().startAdvertising(); // restart advertising
rgrover17:daab8ba5139e 38}
rgrover17:daab8ba5139e 39
Rohit Grover 11:1d9aafee4984 40void periodicCallback(void)
Rohit Grover 11:1d9aafee4984 41{
rgrover147:430545f41113 42 led1 = !led1; /* Do blinky on LED1 while we're waiting for BLE events */
rgrover147:430545f41113 43
rgrover139:6390604f904c 44 /* Note that the periodicCallback() executes in interrupt context, so it is safer to do
rgrover139:6390604f904c 45 * heavy-weight sensor polling from the main thread. */
rgrover139:6390604f904c 46 triggerSensorPolling = true;
Rohit Grover 11:1d9aafee4984 47}
Rohit Grover 11:1d9aafee4984 48
rgrover174:c9d58e7847c4 49void bleInitComplete(BLE::InitializationCompleteCallbackContext *params)
ktownsend0:87a7fc231fae 50{
rgrover174:c9d58e7847c4 51 BLE &ble = params->ble;
rgrover174:c9d58e7847c4 52 ble_error_t error = params->error;
rgrover174:c9d58e7847c4 53
rgrover172:99c283dfe28d 54 if (error != BLE_ERROR_NONE) {
rgrover172:99c283dfe28d 55 return;
rgrover172:99c283dfe28d 56 }
ktownsend0:87a7fc231fae 57
rgrover165:cb76569f74f6 58 ble.gap().onDisconnection(disconnectionCallback);
ktownsend0:87a7fc231fae 59
rgrover145:98c5a34b07a4 60 /* Setup primary service. */
rgrover172:99c283dfe28d 61 hrService = new HeartRateService(ble, hrmCounter, HeartRateService::LOCATION_FINGER);
rgrover145:98c5a34b07a4 62
mbedAustin55:3a7d497a3e03 63 /* Setup auxiliary service. */
rgrover172:99c283dfe28d 64 deviceInfo = new DeviceInformationService(ble, "ARM", "Model1", "SN1", "hw-rev1", "fw-rev1", "soft-rev1");
rgrover145:98c5a34b07a4 65
rgrover145:98c5a34b07a4 66 /* Setup advertising. */
rgrover165:cb76569f74f6 67 ble.gap().accumulateAdvertisingPayload(GapAdvertisingData::BREDR_NOT_SUPPORTED | GapAdvertisingData::LE_GENERAL_DISCOVERABLE);
rgrover165:cb76569f74f6 68 ble.gap().accumulateAdvertisingPayload(GapAdvertisingData::COMPLETE_LIST_16BIT_SERVICE_IDS, (uint8_t *)uuid16_list, sizeof(uuid16_list));
rgrover165:cb76569f74f6 69 ble.gap().accumulateAdvertisingPayload(GapAdvertisingData::GENERIC_HEART_RATE_SENSOR);
rgrover165:cb76569f74f6 70 ble.gap().accumulateAdvertisingPayload(GapAdvertisingData::COMPLETE_LOCAL_NAME, (uint8_t *)DEVICE_NAME, sizeof(DEVICE_NAME));
rgrover165:cb76569f74f6 71 ble.gap().setAdvertisingType(GapAdvertisingParams::ADV_CONNECTABLE_UNDIRECTED);
rgrover167:b2d2dee347c0 72 ble.gap().setAdvertisingInterval(1000); /* 1000ms */
rgrover165:cb76569f74f6 73 ble.gap().startAdvertising();
rgrover172:99c283dfe28d 74}
rgrover172:99c283dfe28d 75
rgrover172:99c283dfe28d 76int main(void)
rgrover172:99c283dfe28d 77{
rgrover172:99c283dfe28d 78 led1 = 1;
rgrover172:99c283dfe28d 79 Ticker ticker;
rgrover172:99c283dfe28d 80 ticker.attach(periodicCallback, 1); // blink LED every second
rgrover172:99c283dfe28d 81
rgrover173:49b6090478e2 82 BLE& ble = BLE::Instance(BLE::DEFAULT_INSTANCE);
rgrover172:99c283dfe28d 83 ble.init(bleInitComplete);
ktownsend0:87a7fc231fae 84
rgrover173:49b6090478e2 85 /* SpinWait for initialization to complete. This is necessary because the
rgrover173:49b6090478e2 86 * BLE object is used in the main loop below. */
vcoubard75:8128a06c0a21 87 while (ble.hasInitialized() == false) { /* spin loop */ }
rgrover173:49b6090478e2 88
mbedAustin55:3a7d497a3e03 89 // infinite loop
mbedAustin55:3a7d497a3e03 90 while (1) {
mbedAustin55:3a7d497a3e03 91 // check for trigger from periodicCallback()
rgrover150:477004d54431 92 if (triggerSensorPolling && ble.getGapState().connected) {
Rohit Grover 36:ea2a1b4f51c1 93 triggerSensorPolling = false;
Rohit Grover 36:ea2a1b4f51c1 94
mbedAustin55:3a7d497a3e03 95 // Do blocking calls or whatever is necessary for sensor polling.
rgrover167:b2d2dee347c0 96 // In our case, we simply update the HRM measurement.
Rohit Grover 36:ea2a1b4f51c1 97 hrmCounter++;
rgrover172:99c283dfe28d 98 if (hrmCounter == 175) { // 100 <= HRM bps <=175
Rohit Grover 36:ea2a1b4f51c1 99 hrmCounter = 100;
Rohit Grover 36:ea2a1b4f51c1 100 }
rgrover167:b2d2dee347c0 101
rgrover172:99c283dfe28d 102 hrService->updateHeartRate(hrmCounter);
Rohit Grover 36:ea2a1b4f51c1 103 } else {
mbedAustin55:3a7d497a3e03 104 ble.waitForEvent(); // low power wait for event
Rohit Grover 36:ea2a1b4f51c1 105 }
ktownsend0:87a7fc231fae 106 }
ktownsend0:87a7fc231fae 107}