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:
rgrover1
Date:
Fri Nov 28 14:15:43 2014 +0000
Revision:
53:06a74fd722b8
Parent:
52:6bbf62943106
Child:
55:3a7d497a3e03
Updating to 0.2.5 of BLE_API

Who changed what in which revision?

UserRevisionLine numberNew contents of line
ktownsend 0:87a7fc231fae 1 /* mbed Microcontroller Library
ktownsend 0:87a7fc231fae 2 * Copyright (c) 2006-2013 ARM Limited
ktownsend 0:87a7fc231fae 3 *
ktownsend 0:87a7fc231fae 4 * Licensed under the Apache License, Version 2.0 (the "License");
ktownsend 0:87a7fc231fae 5 * you may not use this file except in compliance with the License.
ktownsend 0:87a7fc231fae 6 * You may obtain a copy of the License at
ktownsend 0:87a7fc231fae 7 *
ktownsend 0:87a7fc231fae 8 * http://www.apache.org/licenses/LICENSE-2.0
ktownsend 0:87a7fc231fae 9 *
ktownsend 0:87a7fc231fae 10 * Unless required by applicable law or agreed to in writing, software
ktownsend 0:87a7fc231fae 11 * distributed under the License is distributed on an "AS IS" BASIS,
ktownsend 0:87a7fc231fae 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
ktownsend 0:87a7fc231fae 13 * See the License for the specific language governing permissions and
ktownsend 0:87a7fc231fae 14 * limitations under the License.
ktownsend 0:87a7fc231fae 15 */
ktownsend 0:87a7fc231fae 16
ktownsend 0:87a7fc231fae 17 #include "mbed.h"
Rohit Grover 10:2436164b692e 18 #include "BLEDevice.h"
rgrover1 39:6390604f904c 19 #include "HeartRateService.h"
rgrover1 42:06ebef2e0e44 20 #include "BatteryService.h"
rgrover1 42:06ebef2e0e44 21 #include "DeviceInformationService.h"
ktownsend 0:87a7fc231fae 22
rgrover1 52:6bbf62943106 23 /* Enable the following if you need to throttle the connection interval. This has
rgrover1 52:6bbf62943106 24 * the effect of reducing energy consumption after a connection is made;
rgrover1 52:6bbf62943106 25 * particularly for applications where the central may want a fast connection
rgrover1 52:6bbf62943106 26 * interval.*/
rgrover1 52:6bbf62943106 27 #define UPDATE_PARAMS_FOR_LONGER_CONNECTION_INTERVAL 0
rgrover1 52:6bbf62943106 28
Rohit Grover 10:2436164b692e 29 BLEDevice ble;
rgrover1 47:430545f41113 30 DigitalOut led1(LED1);
ktownsend 0:87a7fc231fae 31
rgrover1 45:98c5a34b07a4 32 const static char DEVICE_NAME[] = "Nordic_HRM";
rgrover1 42:06ebef2e0e44 33 static const uint16_t uuid16_list[] = {GattService::UUID_HEART_RATE_SERVICE,
rgrover1 42:06ebef2e0e44 34 GattService::UUID_BATTERY_SERVICE,
rgrover1 42:06ebef2e0e44 35 GattService::UUID_DEVICE_INFORMATION_SERVICE};
rgrover1 39:6390604f904c 36 static volatile bool triggerSensorPolling = false;
Rohit Grover 36:ea2a1b4f51c1 37
rgrover1 41:9cef0129da5f 38 void disconnectionCallback(Gap::Handle_t handle, Gap::DisconnectionReason_t reason)
ktownsend 0:87a7fc231fae 39 {
rgrover1 46:ee7c55907f36 40 ble.startAdvertising(); // restart advertising
rgrover1 7:daab8ba5139e 41 }
Rohit Grover 3:24e2b056d229 42
rgrover1 52:6bbf62943106 43 void onConnectionCallback(Gap::Handle_t handle, Gap::addr_type_t peerAddrType, const Gap::address_t peerAddr, const Gap::ConnectionParams_t *params)
rgrover1 52:6bbf62943106 44 {
rgrover1 52:6bbf62943106 45 #if UPDATE_PARAMS_FOR_LONGER_CONNECTION_INTERVAL
rgrover1 52:6bbf62943106 46 /* Updating connection parameters can be attempted only after a connection has been
rgrover1 52:6bbf62943106 47 * established. Please note that the ble-Central is still the final arbiter for
rgrover1 52:6bbf62943106 48 * the effective parameters; the peripheral can only hope that the request is
rgrover1 52:6bbf62943106 49 * honored. Please also be mindful of the constraints that might be enforced by
rgrover1 52:6bbf62943106 50 * the BLE stack on the underlying controller.*/
rgrover1 52:6bbf62943106 51 #define MIN_CONN_INTERVAL 250 /**< Minimum connection interval (250 ms) */
rgrover1 52:6bbf62943106 52 #define MAX_CONN_INTERVAL 350 /**< Maximum connection interval (350 ms). */
rgrover1 52:6bbf62943106 53 #define CONN_SUP_TIMEOUT 6000 /**< Connection supervisory timeout (6 seconds). */
rgrover1 52:6bbf62943106 54 #define SLAVE_LATENCY 4
rgrover1 52:6bbf62943106 55
rgrover1 52:6bbf62943106 56 Gap::ConnectionParams_t gap_conn_params;
rgrover1 52:6bbf62943106 57 gap_conn_params.minConnectionInterval = Gap::MSEC_TO_GAP_DURATION_UNITS(MIN_CONN_INTERVAL);
rgrover1 52:6bbf62943106 58 gap_conn_params.maxConnectionInterval = Gap::MSEC_TO_GAP_DURATION_UNITS(MAX_CONN_INTERVAL);
rgrover1 52:6bbf62943106 59 gap_conn_params.connectionSupervisionTimeout = Gap::MSEC_TO_GAP_DURATION_UNITS(CONN_SUP_TIMEOUT);
rgrover1 52:6bbf62943106 60 gap_conn_params.slaveLatency = SLAVE_LATENCY;
rgrover1 52:6bbf62943106 61 ble.updateConnectionParams(handle, &gap_conn_params);
rgrover1 52:6bbf62943106 62 #endif /* #if UPDATE_PARAMS_FOR_LONGER_CONNECTION_INTERVAL */
rgrover1 52:6bbf62943106 63 }
rgrover1 52:6bbf62943106 64
Rohit Grover 11:1d9aafee4984 65 void periodicCallback(void)
Rohit Grover 11:1d9aafee4984 66 {
rgrover1 47:430545f41113 67 led1 = !led1; /* Do blinky on LED1 while we're waiting for BLE events */
rgrover1 47:430545f41113 68
rgrover1 39:6390604f904c 69 /* Note that the periodicCallback() executes in interrupt context, so it is safer to do
rgrover1 39:6390604f904c 70 * heavy-weight sensor polling from the main thread. */
rgrover1 39:6390604f904c 71 triggerSensorPolling = true;
Rohit Grover 11:1d9aafee4984 72 }
Rohit Grover 11:1d9aafee4984 73
ktownsend 0:87a7fc231fae 74 int main(void)
ktownsend 0:87a7fc231fae 75 {
rgrover1 47:430545f41113 76 led1 = 1;
Rohit Grover 11:1d9aafee4984 77 Ticker ticker;
Rohit Grover 11:1d9aafee4984 78 ticker.attach(periodicCallback, 1);
ktownsend 0:87a7fc231fae 79
Rohit Grover 15:7ba28817e31e 80 ble.init();
rgrover1 7:daab8ba5139e 81 ble.onDisconnection(disconnectionCallback);
rgrover1 52:6bbf62943106 82 #if UPDATE_PARAMS_FOR_LONGER_CONNECTION_INTERVAL
rgrover1 52:6bbf62943106 83 ble.onConnection(onConnectionCallback);
rgrover1 52:6bbf62943106 84 #endif /* #if UPDATE_PARAMS_FOR_LONGER_CONNECTION_INTERVAL */
ktownsend 0:87a7fc231fae 85
rgrover1 45:98c5a34b07a4 86 /* Setup primary service. */
rgrover1 45:98c5a34b07a4 87 uint8_t hrmCounter = 100;
rgrover1 45:98c5a34b07a4 88 HeartRateService hrService(ble, hrmCounter, HeartRateService::LOCATION_FINGER);
rgrover1 45:98c5a34b07a4 89
rgrover1 45:98c5a34b07a4 90 /* Setup auxiliary services. */
rgrover1 45:98c5a34b07a4 91 BatteryService battery(ble);
rgrover1 45:98c5a34b07a4 92 DeviceInformationService deviceInfo(ble, "ARM", "Model1", "SN1", "hw-rev1", "fw-rev1", "soft-rev1");
rgrover1 45:98c5a34b07a4 93
rgrover1 45:98c5a34b07a4 94 /* Setup advertising. */
Rohit Grover 29:76d865c718a6 95 ble.accumulateAdvertisingPayload(GapAdvertisingData::BREDR_NOT_SUPPORTED | GapAdvertisingData::LE_GENERAL_DISCOVERABLE);
rgrover1 40:e73130c6f2bb 96 ble.accumulateAdvertisingPayload(GapAdvertisingData::COMPLETE_LIST_16BIT_SERVICE_IDS, (uint8_t *)uuid16_list, sizeof(uuid16_list));
rgrover1 42:06ebef2e0e44 97 ble.accumulateAdvertisingPayload(GapAdvertisingData::GENERIC_HEART_RATE_SENSOR);
Rohit Grover 29:76d865c718a6 98 ble.accumulateAdvertisingPayload(GapAdvertisingData::COMPLETE_LOCAL_NAME, (uint8_t *)DEVICE_NAME, sizeof(DEVICE_NAME));
rgrover1 7:daab8ba5139e 99 ble.setAdvertisingType(GapAdvertisingParams::ADV_CONNECTABLE_UNDIRECTED);
rgrover1 53:06a74fd722b8 100 ble.setAdvertisingInterval(Gap::MSEC_TO_ADVERTISEMENT_DURATION_UNITS(1000));
rgrover1 7:daab8ba5139e 101 ble.startAdvertising();
Rohit Grover 3:24e2b056d229 102
Rohit Grover 11:1d9aafee4984 103 while (true) {
rgrover1 50:477004d54431 104 if (triggerSensorPolling && ble.getGapState().connected) {
Rohit Grover 36:ea2a1b4f51c1 105 triggerSensorPolling = false;
Rohit Grover 36:ea2a1b4f51c1 106
Rohit Grover 36:ea2a1b4f51c1 107 /* Do blocking calls or whatever is necessary for sensor polling. */
Rohit Grover 36:ea2a1b4f51c1 108 /* In our case, we simply update the dummy HRM measurement. */
Rohit Grover 36:ea2a1b4f51c1 109 hrmCounter++;
Rohit Grover 36:ea2a1b4f51c1 110 if (hrmCounter == 175) {
Rohit Grover 36:ea2a1b4f51c1 111 hrmCounter = 100;
Rohit Grover 36:ea2a1b4f51c1 112 }
Rohit Grover 36:ea2a1b4f51c1 113
rgrover1 39:6390604f904c 114 hrService.updateHeartRate(hrmCounter);
Rohit Grover 36:ea2a1b4f51c1 115 } else {
Rohit Grover 36:ea2a1b4f51c1 116 ble.waitForEvent();
Rohit Grover 36:ea2a1b4f51c1 117 }
ktownsend 0:87a7fc231fae 118 }
ktownsend 0:87a7fc231fae 119 }