Development Status¶

The main design goal of this stack is something that's easy to understand and doesn't require end users to spend too much time in the core Bluetooth 4.0 specs themselves. Some familiarity with BLE is necessary, particularly the way data is structured and transmitted, but ideally you'll be able to cover common use cases with a few lines of code and without too much additional reading.

In order to improve things early in the design and development process we're opening up the initial code to the larger mbed community for review and feedback.

This allows us to know at an early stage if we're moving things in the right direction, but it also means that the code as it exists today is inherently unstable, and there may be major breaking changes to the API moving forward, and inevitably bugs and holes in the overall code.

Status Update: 4 April 2014¶

• An initial version the of the BLE stack has been published with native-mode drivers for the nRF51822 SoC.

Hardware Requirements¶

In order to use this early release BLE API, you will need the following setup:

• Nordic's PCA10001 board, available in the nRF51822 Evaluation Kit

API Examples¶

While the entire API is a work in progress, the current API has a reasonably flexible GAP and GATT API. GAP controls advertising and connections, while GATT allows services and characteristics to be defined once a connection is established with another device.

Two basic examples are shown below of how you can make use of the GAP and GATT classes in the real world:

Beacon/Advertising Example¶

Beacon is an advertising-only solution that makes uses a special field in the main advertising packet called Manufacturer Specific Data. It works by inserting a custom payload in the Manufactuter Specific Data field identifying our primary location (a store, office building, etc.) via a 128-bit UUID, and individual nodes in that location via two 16-bit values. Explaining the iBeacon payload is beyond the scope of this tutorial, but a sample payload is provided below.

To simulate an Beacon device with the mbed, we simply need to take a GapAdvertisingData instance and insert our custom payload into the MSD field via the generic .addData() function.

We also set the Flags field to BREDR_NOT_SUPPORTED via the dedicated .addFlag() helper function, which tells other listening devices that this node doesn't support older Bluetooth standards and is a BLE only device.

The mandatory GapAdvertisingParams instance is also configured to advertise in ADV_NON_CONNECTABLE_UNDIRECTED mode, which means any device can see the node, but connections can not be established with it (making this a broadcast only device, since no GATT services are present). The default advertising timing values are used, but they can optionally be adjusted in the constructor if you want a slower advertising interval for lower power.

Then we simply need to pass the advertising data and advertising parameters into the radio and start advertising, as follows, and the device should be visible on any supported iOS device using an appropriate application as an Beacon node (you may need to tweek the payload contents depending on the app you are using):

#include "mbed.h"
#include "nRF51822n.h"

nRF51822n   nrf;                /* BLE radio driver */

DigitalOut  led1(LED1);
DigitalOut  led2(LED2);
Ticker      flipper;
Serial      pc(USBTX,USBRX);

void tickerCallback(void);

/**************************************************************************/
/*!
    @brief  Program entry point
*/
/**************************************************************************/
int main(void)
{
    *(uint32_t *)0x40000504 = 0xC007FFDF;
    *(uint32_t *)0x40006C18 = 0x00008000;
    
    /* Setup blinky: led1 is toggled in main, led2 is toggled via Ticker */
    led1=1;
    led2=1;
    flipper.attach(&tickerCallback, 1.0);

    /* Initialise the nRF51822 */
    pc.printf("Initialising the nRF51822\n\r");
    nrf.init();
    
    GapAdvertisingParams advParams ( GapAdvertisingParams::ADV_NON_CONNECTABLE_UNDIRECTED );
    GapAdvertisingData   advData;
    GapAdvertisingData   scanResponse;

    /* Define an Beacon payload
       --------------------------------------------------------------
       128-Bit UUID = E2 0A 39 F4 73 F5 4B C4 A1 2F 17 D1 AD 07 A9 61
       Major/Minor  = 0000 / 0000
       Tx Power     = C8
    */
    uint8_t beaconPayload[25] = { 0x4C, 0x00, 0x02, 0x15, 0xE2, 0x0A, 0x39, 0xF4, 0x73, 0xF5, 0x4B, 0xC4, 0xA1, 0x2F, 0x17, 0xD1, 0xAD, 0x07, 0xA9, 0x61, 0x00, 0x00, 0x00, 0x00, 0xC8 };

    /* Make sure we get a clean start */
    nrf.reset();

    /* Beacon includes the FLAG and MSD fields */
    advData.addFlags(GapAdvertisingData::BREDR_NOT_SUPPORTED);
    advData.addData(GapAdvertisingData::MANUFACTURER_SPECIFIC_DATA, beaconPayload, sizeof(beaconPayload));

    /* Start advertising! */
    nrf.getGap().setAdvertisingData(advData, scanResponse);
    nrf.getGap().startAdvertising(advParams);

    /* Do blinky on LED1 while we're waiting for BLE events */
    for (;;)
    {
      led1 = !led1;
      wait(1);
    }
}

/**************************************************************************/
/*!
    @brief  Ticker callback to switch led2 state
*/
/**************************************************************************/
void tickerCallback(void)
{
    led2 = !led2;
}

Heart Rate Service Example¶

The heart rate monitor example shows how to create a simple GATT service and update the value of a GATT characteristic in that service.

GATT Services are encapsulated in the GattService class, and GATT Characteristics in the GattCharacteristic class.

Note: For information on officially adopted Bluetooth Low Energy Services and Characteristics, consult the Bluetooth Definition Browser