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.
main.cpp@26:e6ad33b227c6, 2014-07-03 (annotated)
- Committer:
- Rohit Grover
- Date:
- Thu Jul 03 11:44:59 2014 +0100
- Revision:
- 26:e6ad33b227c6
- Parent:
- 22:299658c5fa3c
- Child:
- 27:97adf2b76b9c
add deviceInformationService to the basic HRM demo
Who changed what in which revision?
User | Revision | Line number | New 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" |
ktownsend | 0:87a7fc231fae | 19 | |
Rohit Grover |
10:2436164b692e | 20 | BLEDevice ble; |
Rohit Grover |
3:24e2b056d229 | 21 | DigitalOut led1(LED1); |
Rohit Grover |
9:5d693381e883 | 22 | |
Rohit Grover |
9:5d693381e883 | 23 | #define NEED_CONSOLE_OUTPUT 0 /* Set this if you need debug messages on the console; |
Rohit Grover |
22:299658c5fa3c | 24 | * it will have an impact on code-size and power consumption. */ |
Rohit Grover |
9:5d693381e883 | 25 | |
Rohit Grover |
9:5d693381e883 | 26 | #if NEED_CONSOLE_OUTPUT |
Rohit Grover |
9:5d693381e883 | 27 | Serial pc(USBTX, USBRX); |
Rohit Grover |
9:5d693381e883 | 28 | #define DEBUG(...) { pc.printf(__VA_ARGS__); } |
Rohit Grover |
9:5d693381e883 | 29 | #else |
Rohit Grover |
9:5d693381e883 | 30 | #define DEBUG(...) /* nothing */ |
Rohit Grover |
9:5d693381e883 | 31 | #endif /* #if NEED_CONSOLE_OUTPUT */ |
ktownsend | 0:87a7fc231fae | 32 | |
Rohit Grover |
26:e6ad33b227c6 | 33 | /* Device Information service */ |
Rohit Grover |
26:e6ad33b227c6 | 34 | const char deviceName[] = { 'm', 'b', 'e', 'd' }; |
Rohit Grover |
26:e6ad33b227c6 | 35 | GattCharacteristic deviceManufacturer(GattCharacteristic::UUID_MANUFACTURER_NAME_STRING_CHAR, (uint8_t *)deviceName, sizeof(deviceName), sizeof(deviceName), |
Rohit Grover |
26:e6ad33b227c6 | 36 | GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_READ); |
Rohit Grover |
26:e6ad33b227c6 | 37 | GattCharacteristic *deviceInformationChars[] = {&deviceManufacturer}; |
Rohit Grover |
26:e6ad33b227c6 | 38 | GattService deviceInformationService(GattService::UUID_DEVICE_INFORMATION_SERVICE, deviceInformationChars, |
Rohit Grover |
26:e6ad33b227c6 | 39 | sizeof(deviceInformationChars) / sizeof(GattCharacteristic *)); |
Rohit Grover |
26:e6ad33b227c6 | 40 | |
ktownsend | 0:87a7fc231fae | 41 | /* Heart Rate Service */ |
ktownsend | 0:87a7fc231fae | 42 | /* Service: https://developer.bluetooth.org/gatt/services/Pages/ServiceViewer.aspx?u=org.bluetooth.service.heart_rate.xml */ |
ktownsend | 0:87a7fc231fae | 43 | /* HRM Char: https://developer.bluetooth.org/gatt/characteristics/Pages/CharacteristicViewer.aspx?u=org.bluetooth.characteristic.heart_rate_measurement.xml */ |
ktownsend | 0:87a7fc231fae | 44 | /* Location: https://developer.bluetooth.org/gatt/characteristics/Pages/CharacteristicViewer.aspx?u=org.bluetooth.characteristic.body_sensor_location.xml */ |
Rohit Grover |
18:8a2e313f49cb | 45 | static uint8_t hrmCounter = 100; |
Rohit Grover |
18:8a2e313f49cb | 46 | static uint8_t bpm[2] = {0x00, hrmCounter}; |
Rohit Grover |
20:58bff62d0f7a | 47 | GattCharacteristic hrmRate(GattCharacteristic::UUID_HEART_RATE_MEASUREMENT_CHAR, bpm, sizeof(bpm), sizeof(bpm), |
Rohit Grover |
20:58bff62d0f7a | 48 | GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_NOTIFY); |
Rohit Grover |
18:8a2e313f49cb | 49 | static const uint8_t location = 0x03; /* Finger */ |
Rohit Grover |
18:8a2e313f49cb | 50 | GattCharacteristic hrmLocation(GattCharacteristic::UUID_BODY_SENSOR_LOCATION_CHAR, |
Rohit Grover |
18:8a2e313f49cb | 51 | (uint8_t *)&location, sizeof(location), sizeof(location), |
Rohit Grover |
18:8a2e313f49cb | 52 | GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_READ); |
Rohit Grover |
22:299658c5fa3c | 53 | GattCharacteristic *hrmChars[] = {&hrmRate, &hrmLocation, }; |
Rohit Grover |
19:1713b11694ea | 54 | GattService hrmService(GattService::UUID_HEART_RATE_SERVICE, hrmChars, sizeof(hrmChars) / sizeof(GattCharacteristic *)); |
ktownsend | 0:87a7fc231fae | 55 | |
rgrover1 | 7:daab8ba5139e | 56 | void disconnectionCallback(void) |
ktownsend | 0:87a7fc231fae | 57 | { |
Rohit Grover |
9:5d693381e883 | 58 | DEBUG("Disconnected!\n\r"); |
Rohit Grover |
9:5d693381e883 | 59 | DEBUG("Restarting the advertising process\n\r"); |
rgrover1 | 7:daab8ba5139e | 60 | ble.startAdvertising(); |
rgrover1 | 7:daab8ba5139e | 61 | } |
Rohit Grover |
3:24e2b056d229 | 62 | |
Rohit Grover |
13:3ca2045597e7 | 63 | /** |
Rohit Grover |
22:299658c5fa3c | 64 | * Triggered periodically by the 'ticker' interrupt; updates hrmCounter. |
Rohit Grover |
13:3ca2045597e7 | 65 | */ |
Rohit Grover |
11:1d9aafee4984 | 66 | void periodicCallback(void) |
Rohit Grover |
11:1d9aafee4984 | 67 | { |
Rohit Grover |
11:1d9aafee4984 | 68 | led1 = !led1; /* Do blinky on LED1 while we're waiting for BLE events */ |
Rohit Grover |
11:1d9aafee4984 | 69 | |
Rohit Grover |
11:1d9aafee4984 | 70 | if (ble.getGapState().connected) { |
Rohit Grover |
11:1d9aafee4984 | 71 | /* Update the HRM measurement */ |
Rohit Grover |
11:1d9aafee4984 | 72 | /* First byte = 8-bit values, no extra info, Second byte = uint8_t HRM value */ |
Rohit Grover |
11:1d9aafee4984 | 73 | /* See --> https://developer.bluetooth.org/gatt/characteristics/Pages/CharacteristicViewer.aspx?u=org.bluetooth.characteristic.heart_rate_measurement.xml */ |
Rohit Grover |
11:1d9aafee4984 | 74 | hrmCounter++; |
Rohit Grover |
11:1d9aafee4984 | 75 | if (hrmCounter == 175) { |
Rohit Grover |
11:1d9aafee4984 | 76 | hrmCounter = 100; |
Rohit Grover |
11:1d9aafee4984 | 77 | } |
Rohit Grover |
18:8a2e313f49cb | 78 | bpm[1] = hrmCounter; |
Rohit Grover |
11:1d9aafee4984 | 79 | ble.updateCharacteristicValue(hrmRate.getHandle(), bpm, sizeof(bpm)); |
Rohit Grover |
11:1d9aafee4984 | 80 | } |
Rohit Grover |
11:1d9aafee4984 | 81 | } |
Rohit Grover |
11:1d9aafee4984 | 82 | |
ktownsend | 0:87a7fc231fae | 83 | int main(void) |
ktownsend | 0:87a7fc231fae | 84 | { |
Rohit Grover |
3:24e2b056d229 | 85 | led1 = 1; |
Rohit Grover |
11:1d9aafee4984 | 86 | Ticker ticker; |
Rohit Grover |
11:1d9aafee4984 | 87 | ticker.attach(periodicCallback, 1); |
ktownsend | 0:87a7fc231fae | 88 | |
Rohit Grover |
15:7ba28817e31e | 89 | DEBUG("Initialising the nRF51822\n\r"); |
Rohit Grover |
15:7ba28817e31e | 90 | ble.init(); |
rgrover1 | 7:daab8ba5139e | 91 | ble.onDisconnection(disconnectionCallback); |
ktownsend | 0:87a7fc231fae | 92 | |
Rohit Grover |
15:7ba28817e31e | 93 | /* setup advertising */ |
rgrover1 | 7:daab8ba5139e | 94 | ble.accumulateAdvertisingPayload(GapAdvertisingData::BREDR_NOT_SUPPORTED); |
rgrover1 | 7:daab8ba5139e | 95 | ble.accumulateAdvertisingPayload(GapAdvertisingData::HEART_RATE_SENSOR_HEART_RATE_BELT); |
rgrover1 | 7:daab8ba5139e | 96 | ble.setAdvertisingType(GapAdvertisingParams::ADV_CONNECTABLE_UNDIRECTED); |
rgrover1 | 7:daab8ba5139e | 97 | ble.setAdvertisingInterval(160); /* 100ms; in multiples of 0.625ms. */ |
rgrover1 | 7:daab8ba5139e | 98 | ble.startAdvertising(); |
Rohit Grover |
3:24e2b056d229 | 99 | |
Rohit Grover |
26:e6ad33b227c6 | 100 | ble.addService(deviceInformationService); |
Rohit Grover |
11:1d9aafee4984 | 101 | ble.addService(hrmService); |
ktownsend | 0:87a7fc231fae | 102 | |
Rohit Grover |
11:1d9aafee4984 | 103 | while (true) { |
Rohit Grover |
11:1d9aafee4984 | 104 | ble.waitForEvent(); |
ktownsend | 0:87a7fc231fae | 105 | } |
ktownsend | 0:87a7fc231fae | 106 | } |