This is a demonstration of how to create a GATT service and characteristic.

Dependencies:   BLE_API mbed nRF51822

Fork of BLE_EvothingsExample_GATT by Austin Blackstone

Intro

This code demonstrates how to use the BLE_API to create a GATT service and characteristic to toggle a LED on / off.

Overview

This code is a demonstration of how to create a custom service (UUID=0xA0000) with two characteristics, a read only characteristic (UUID=0xA001) and a write characteristic (UUID=0xA002). What is written to the write characteristic will be copied across to the read characteristic and broadcast out. If a single byte is written it will be used to toggle the on board LED, if more than 1 byte is written the data will be written out to the terminal. The default max size is 10bytes.

Video

This is a video of how to use this example. Please note that in this video Android is used to read / write the characteristics. This could just as easily been done with the Evothings App listed below or an equivalent iOS app. Any app that can read/write characteristics could have been used.

Details

characteristic and service UUID's are initialized here

UUID's

uint16_t customServiceUUID  = 0xA000;
uint16_t readCharUUID       = 0xA001;
uint16_t writeCharUUID      = 0xA002;


We set up the list of available UUID's that will be advertised as part of the GAP advertising packet here. (it is good form to make this match the services you are actually advertising, so in this case we should set it to be 0xA000, but we are choosing to set it to 0xFFFF so it is easier to distinguish on the scanning app)

Set_ServiceID's

static const uint16_t uuid16_list[]        = {0xFFFF};
...
ble.accumulateAdvertisingPayload(GapAdvertisingData::COMPLETE_LIST_16BIT_SERVICE_IDS, (uint8_t *)uuid16_list, sizeof(uuid16_list)); // UUID's broadcast in advertising packet


Next we set up the characteristics and then put them together into a service. Notice that each characteristic has a maximum of 10Bytes of Value space, this can be expanded up to 512B.

Setup_Service_&_Characteristics

// Set Up custom Characteristics
static uint8_t readValue[10] = {0};
ReadOnlyArrayGattCharacteristic<uint8_t, sizeof(readValue)> readChar(readCharUUID, readValue);
 
static uint8_t writeValue[10] = {0};
WriteOnlyArrayGattCharacteristic<uint8_t, sizeof(writeValue)> writeChar(writeCharUUID, writeValue);
 
// Set up custom service
GattCharacteristic *characteristics[] = {&readChar, &writeChar};
GattService        customService(customServiceUUID, characteristics, sizeof(characteristics) / sizeof(GattCharacteristic *));


Next we setup the writeCharCallback() function that will be called when a BLE onDataWritten event is triggered (when someone writes to a characteristic on the device). This function will check to see what characteristic is being written to and then handle it appropriately. In this case there is only one writable characteristic so its redundant, but good form for more complex service/characteristic combinations.

On_Characteristic_written_to_callback

void writeCharCallback(const GattCharacteristicWriteCBParams *params)
{
    // check to see what characteristic was written, by handle
    if(params->charHandle == writeChar.getValueHandle()) {
        // toggle LED if only 1 byte is written
        if(params->len == 1) {
            led = params->data[0];
            ...}
        // print the data if more than 1 byte is written
        else {
            printf("\n\r Data received: length = %d, data = 0x",params->len); 
            ...}
        // update the readChar with the value of writeChar
        ble.updateCharacteristicValue(readChar.getValueHandle(),params->data,params->len);
    }
}
...
// register callback function
ble.onDataWritten(writeCharCallback);
...


The last thing to do is register the service with the BLE object so it is available.

Add_Service_to_BLE_Object

...
    // add our custom service
    ble.addService(customService);
...

Viewing Data

You can use either the LightBlue app on iOS or the nRF Master Control Panel application on Android to view the advertising data. Alternatively you can use a custom GATT Evothings App to view the data.

Evothings?

Evothings is a rapid prototyping environment that uses cordova to enable you to rapidly develop smartphone applications in Javascript. Please download the Evothings workbench to your computer and the Evothings client to your smartphone. The Evothings workbench will come with a program called "mbed Evothings GATT", this Evothings Smartphone program is meant to be used with the embedded mbed code. For instructions on how to use evothings please see the reference section below.

Reference

Changes

RevisionDateWhoCommit message
22:406127954d1f 2015-11-09 andresag Update example to comply with initialisation changes in BLE API. default tip
21:73f42c00b1db 2015-10-20 andresag Removed redundant .orig file.
20:fcc752d401ec 2015-10-20 andresag Merged updated version of main.cpp with upstream.
19:477567297aac 2015-10-20 andresag Updated BLE and mbed dependencies, also modified demo code to comply with changes to the API.
18:7d89c4fba362 2015-10-20 melmon Now compatible with library updates
17:32973972d2dd 2015-04-02 mbedAustin fixed small issue with API change
16:feee85aefb34 2015-04-02 mbedAustin updated libraries
15:35f06d4f2130 2015-03-18 mbedAustin updated library that was causing a conflict
14:176225700bed 2015-03-18 mbedAustin updated library revisions
13:62b1d32745ac 2015-03-17 mbedAustin minor prettification fixes
12:6d1f77d0cb37 2015-03-17 mbedAustin switched out characteristics with macros initializations and removed customservice.h;
11:b59226338001 2015-03-11 mbedAustin updated code with printf's for LED on / off
10:6acaa9f0ef85 2015-03-10 mbedAustin Finished for Alpha Release
9:b33f42191584 2015-03-09 mbedAustin Final Publishable version;
8:60ede963dfe2 2015-03-09 mbedAustin Got everything working
7:f6814152873c 2015-03-09 mbedAustin changed default name to match Evothings Example, added UUID's to braodcast in advertising packet
6:97b22b5bfbb8 2015-02-14 mbedAustin added writeCharCallback handler, now when something is written we can handle it
5:d0548c64e2e7 2015-02-14 mbedAustin added write characteristic handler.
4:7ef90665b399 2015-02-14 mbedAustin it compiles!!!!
3:0fb60f81f693 2015-02-14 mbedAustin Full skeleton in place, not working
2:e84c13abc479 2015-02-14 mbedAustin further updates to the example program, still incomplete
1:94152e7d8b5c 2015-02-14 mbedAustin added a little more skeleton to it, still needs to be fully flushed out, tossed the HeartRate service code into the custom service.h file, added link to Grove Colour Sensor example for inspiration for later
0:cd5b6733aeb1 2015-02-13 mbedAustin initial commit of skeleton for mbed-Evothings custom GATT service/characteristic example