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 use of 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 a Beacon device with the mbed, we simply need to insert our custom payload into the MSD field via the generic .accumulateAdvertisingPayload() function.

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

The advertising type is set to ADV_NON_CONNECTABLE_UNDIRECTED, which means any central 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 could be used, but they can optionally be adjusted using .setAdvertisingInterval() if you want a slower advertising interval for lower power.

Then we simply need to start advertising, 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):

/* mbed Microcontroller Library
 * Copyright (c) 2006-2013 ARM Limited
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#include "mbed.h"
#include "BLEDevice.h"

BLEDevice  ble;                /* BLE radio driver */

DigitalOut mainloopLED(LED1);
DigitalOut tickerLED(LED2);
Ticker     flipper;
Serial     pc(USBTX,USBRX);

/*
 * For this demo application, populate the beacon advertisement payload
 * with 2 AD structures: FLAG and MSD (manufacturer specific data).
 *
 * Reference:
 *  Bluetooth Core Specification 4.0 (Vol. 3), Part C, Section 11, 18
 */

/*
 * The Beacon payload (encapsulated within the MSD advertising data structure)
 * has the following composition:
 * 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
 */
const static uint8_t beaconPayload[] = {
    0x4C, 0x00, // Company identifier code (0x004C == Apple)
    0x02,       // ID
    0x15,       // length of the remaining payload
    0xE2, 0x0A, 0x39, 0xF4, 0x73, 0xF5, 0x4B, 0xC4, // UUID
    0xA1, 0x2F, 0x17, 0xD1, 0xAD, 0x07, 0xA9, 0x61,
    0x00, 0x00, // the major value to differenciate a location
    0x00, 0x00, // the minor value to differenciate a location
    0xC8        // 2's complement of the Tx power (-56dB)
};

void tickerCallback(void)
{
    tickerLED = !tickerLED;
}

void setupAppHardware(void)
{
    /* Setup blinkies: mainloopLED is toggled in main, tickerLED is
     * toggled via Ticker */
    mainloopLED = 1;
    tickerLED   = 1;
    flipper.attach(&tickerCallback, 1.0);
}

int main(void)
{
    setupAppHardware();

    pc.printf("Initialising BTLE transport\n\r");
    ble.init();

    ble.accumulateAdvertisingPayload(GapAdvertisingData::BREDR_NOT_SUPPORTED);
    ble.accumulateAdvertisingPayload(GapAdvertisingData::MANUFACTURER_SPECIFIC_DATA,
                                     beaconPayload,
                                     sizeof(beaconPayload));

    ble.setAdvertisingType(GapAdvertisingParams::ADV_NON_CONNECTABLE_UNDIRECTED);
    ble.setAdvertisingTimeout(0);    /* disable timeout. */
    ble.setAdvertisingInterval(160); /* 100ms; in multiples of 0.625ms. */
    ble.startAdvertising();

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

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