mbed-x / SimpleBLE

Library that exposes BLE characteristics as ordinary variables.

Dependents:   SimpleBLE-Example-mbed-os-5 SimpleBLE-Example ObCP_ENSMM_Test SimpleBLE-ObCP_ENSMM_V2019_Test_BLE

Looking for example code? See SimpleBLE-Example.

Looking for the blog post about this library? See A new Bluetooth library: SimpleBLE.

SimpleBLE is a library which allows you to easily add Bluetooth Low Energy support to any application, without having to change the way you write code. It's goal is to expose any value or sensor over BLE in a single line of code. Let's say you're reading a sensor value every second from pin A0:

uint16_t lightValue;

AnalogIn light(A0);
void read() {
  lightValue = light.read_u16();
  printf("Value is now %d\n", lightValue);
}

Ticker t;
t.attach(&read, 1.0f);

Now we can expose this sensor to any BLE client using SimpleBLE:

SimpleChar<uint16_t> lightValue = ble.readOnly_u16(0x8000, 0x8001);

AnalogIn light(A0);
void read() {
  lightValue = light.read_u16();
  printf("Value is now %d\n", lightValue);
}

Ticker t;
t.attach(&read, 1.0f);

SimpleBLE will automatically gather services for you, bootstrap the BLE runtime, react to write callbacks and update the underlying BLE characteristic whenever the variable gets changed.

Setting up the library

First import this library to the application where you want to use it. Then load SimpleBLE like this:

#include "mbed.h"
#include "SimpleBLE.h"

SimpleBLE ble("DEVICE_NAME"); // second argument is the advertisement interval (default: 1000 ms.)

// variables here!

int main(int, char**) {
    ble.start();
    while (1) {
        ble.waitForEvent();
    }
}

You'll also need to import the BLE library for your platform (e.g. nrf51822 for nRF51-DK and micro:bit). If you grab the example program, all should be set.

After you build and flash this application the device will now show up as 'DEVICE_NAME' in any BLE scanner like nRF Master Control Panel.

Reading and writing values

Every variable that you declare after creating the `SimpleBLE` object, and calling `start()` will automatically be exposed over BLE. We have three different types of objects:

  • readOnly - Variable can only be read over BLE.
  • readWrite - Variable can be read and written over BLE.
  • writeOnly - Variable can be written over BLE, but not read.

Creating a new variable is done by calling the respective function on the simpleBLE object, postfixed by the type you want the variable to have:

SimpleBLE ble("DEVICE_NAME");

SimpleChar<uint8_t> myVar = ble.readOnly_u8(0x8200, 0x8201); // creates uint8_t

The postfix has to be either: u8 (uint8_t), u16 (uint16_t), u32 (uint32_t), i8 (int8_t), i16 (int16_t), i32 (int32_t), bool (bool) or float (float).

The functions take four (non-write) or five (write) arguments:

  • serviceUUID - Which service should this variable fall under. Either use a uint16_t (shorthand) or you can use a string (full UUID).
  • characterUUID - Which character this variable should have. Also, use uint16_t or a string.
  • observable - Whether a BLE client can subscribe to updates on this characteristic (default: true).
  • defaultValue - Default value of the characteristic (default: 0 or 0.0f, depending on your type).
  • callback - Function to be called whenever the value of your characteristic was updated over BLE (only available for variables that support writing).

For example, this is how we make a non-observable readWrite characteristic, with a default value of 100, and a callback function:

SimpleBLE ble("DEVICE_NAME");

void updated(uint32_t newValue) {
  printf("My value was updated, and is now %d\n", newValue);
}

SimpleChar<uint32_t> myVar = ble.readWrite_u32(0x9341, 0x9342, false, 100, &updated);

Just like normal variables

SimpleBLE variables behave just like normal variables, you can read and write straight from them. For example, this will compile just fine:

SimpleChar<uint8_t> heartrate = ble.readOnly_u8(0x180d, 0x2a37, true, 100);

void updateHr() {
  heartrate = heartrate + 1;
  if (heartrate > 180) {
    heartrate = 100;
  }
}

Ticker t;
t.attach(updateHr, 1.0f);

What to use it for?

I wrote this library because I do quite a lot of workshops and hackathons, and I have seen that BLE_API is too complicated for people who do not do embedded development or C++ on a daily basis. Exposing a new sensor over Bluetooth should be a single line of code. So if you're running any workshops, give this lib a go and let me know your experiences.

Diff: SimpleBLE.h

Revision:
1:17c8f5afa7bc
Parent:
0:2ecd71f6ab04
Child:
2:15329a3de04c
--- a/SimpleBLE.h	Wed May 11 12:59:14 2016 +0000
+++ b/SimpleBLE.h	Tue May 17 19:33:34 2016 +0000
@@ -1,12 +1,61 @@
-/**
- * Because BLE_API is too hard
+/*
+ * Copyright (c) 2015 ARM Limited. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ * 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 <string>
 #include <sstream>
 #include <vector>
 #include <map>
 #include "ble/BLE.h"
 
+#define def_fn(T, postfix) \
+    SimpleChar<T> readOnly_##postfix \
+        (uint16_t serviceUuid, const UUID& charUuid, bool enableNotify = true, T defaultValue = T()) { \
+        return readOnly<T>(serviceUuid, charUuid, enableNotify, defaultValue); \
+    }\
+    SimpleChar<T> readOnly_##postfix \
+        (const char* serviceUuid, const UUID& charUuid, bool enableNotify = true, T defaultValue = T()) { \
+        return readOnly<T>(serviceUuid, charUuid, enableNotify, defaultValue); \
+    }\
+    \
+    SimpleChar<T> readWrite_##postfix \
+        (uint16_t serviceUuid, const UUID& charUuid, bool enableNotify = true, T defaultValue = T(), void(*callback)(T) = NULL) { \
+        return readWrite<T>(serviceUuid, charUuid, enableNotify, defaultValue, callback); \
+    }\
+    SimpleChar<T> readWrite_##postfix \
+    (const char* serviceUuid, const UUID& charUuid, bool enableNotify = true, T defaultValue = T(), void(*callback)(T) = NULL) { \
+        return readWrite<T>(serviceUuid, charUuid, enableNotify, defaultValue, callback); \
+    }\
+    SimpleChar<T> readWrite_##postfix \
+        (uint16_t serviceUuid, const UUID& charUuid, void(*callback)(T) = NULL) { \
+        return readWrite<T>(serviceUuid, charUuid, callback); \
+    }\
+    SimpleChar<T> readWrite_##postfix \
+    (const char* serviceUuid, const UUID& charUuid, void(*callback)(T) = NULL) { \
+        return readWrite<T>(serviceUuid, charUuid, callback); \
+    }\
+    \
+    SimpleChar<T> writeOnly_##postfix \
+    (uint16_t serviceUuid, const UUID& charUuid, void(*callback)(T) = NULL) { \
+        return writeOnly<T>(serviceUuid, charUuid, callback); \
+    }\
+    SimpleChar<T> writeOnly_##postfix \
+    (const char* serviceUuid, const UUID& charUuid, void(*callback)(T) = NULL) { \
+        return writeOnly<T>(serviceUuid, charUuid, callback); \
+    }
+
 using namespace std;
 
 /**
@@ -112,7 +161,9 @@
 
 class SimpleBLE {
 public:
-    SimpleBLE(const char* aName, uint16_t aInterval = 1000) : name(aName), interval(aInterval) {
+    SimpleBLE(const char* aName, uint16_t aInterval = 1000, bool aLogging = true) 
+        : name(aName), interval(aInterval), logging(aLogging) 
+    {
         ble = &BLE::Instance();
     }
     ~SimpleBLE() {}
@@ -128,6 +179,122 @@
     // Start up the BLE service and just run with it!
     void waitForEvent() {
         ble->waitForEvent();
+    }    
+    
+    void onDisconnection(Gap::DisconnectionEventCallback_t callback) {
+        ble->gap().onDisconnection(callback);
+    }
+    
+    void onConnection(Gap::ConnectionEventCallback_t callback) {
+        ble->gap().onConnection(callback);
+    }
+    
+    BLE* getBle(void) {
+        return ble;
+    }
+    
+    def_fn(uint8_t, u8)
+    def_fn(uint16_t, u16)
+    def_fn(uint32_t, u32)
+    def_fn(int8_t, i8)
+    def_fn(int16_t, i16)
+    def_fn(int32_t, i32)
+    def_fn(bool, bool)
+    
+private:
+    void bleInitComplete(BLE::InitializationCompleteCallbackContext *params)
+    {
+        if (logging) printf("bleInitComplete\r\n");
+        
+        BLE&        ble   = params->ble;
+        ble_error_t error = params->error;
+    
+        if (error != BLE_ERROR_NONE) {
+            if (logging) printf("BLE Init error %d\r\n", error);
+            return;
+        }
+    
+        /* Ensure that it is the default instance of BLE */
+        if(ble.getInstanceID() != BLE::DEFAULT_INSTANCE) {
+            return;
+        }
+
+        ble.gattServer().onDataWritten(this, &SimpleBLE::onDataWrittenCallback);
+        
+        // let's add some services yo (why is there no 'auto' in mbed?)
+        uint16_t uuid16_list[uint16_services.size()];
+        size_t uuid16_counter = 0;
+        {   
+            typedef std::map<uint16_t, vector<GattCharacteristic*>* >::iterator it_type;
+            for(it_type it = uint16_services.begin(); it != uint16_services.end(); it++) {
+                if (logging) printf("Creating service 0x%x\n", it->first);
+                uuid16_list[uuid16_counter++] = it->first;            
+    
+                GattCharacteristic* charTable[it->second->size()];
+                for (size_t git = 0; git < it->second->size(); git++) {
+                    charTable[git] = it->second->at(git);
+                }
+    
+                GattService service(it->first, charTable, it->second->size());
+                ble.gattServer().addService(service);
+            }
+        }
+
+        // 128 Bit services
+        const char* uuid128_list[uint128_services.size()];
+        size_t uuid128_counter = 0;
+        {
+            typedef std::map<string, vector<GattCharacteristic*>* >::iterator it_type;
+            for(it_type it = uint128_services.begin(); it != uint128_services.end(); it++) {
+                if (logging) printf("Creating service %s\n", it->first.c_str());
+                uuid128_list[uuid128_counter++] = it->first.c_str();            
+    
+                GattCharacteristic* charTable[it->second->size()];
+                for (size_t git = 0; git < it->second->size(); git++) {
+                    charTable[git] = it->second->at(git);
+                }
+    
+                GattService service(UUID(it->first.c_str()), charTable, it->second->size());
+                ble.gattServer().addService(service);
+            }
+        }
+
+        ble.gap().accumulateAdvertisingPayload(GapAdvertisingData::BREDR_NOT_SUPPORTED | GapAdvertisingData::LE_GENERAL_DISCOVERABLE);
+        ble.gap().accumulateAdvertisingPayload(GapAdvertisingData::COMPLETE_LIST_16BIT_SERVICE_IDS, (uint8_t *)uuid16_list, uuid16_counter);
+        ble.gap().accumulateAdvertisingPayload(GapAdvertisingData::COMPLETE_LIST_128BIT_SERVICE_IDS, (uint8_t *)uuid128_list, uuid128_counter);
+        ble.gap().accumulateAdvertisingPayload(GapAdvertisingData::COMPLETE_LOCAL_NAME, (uint8_t *)name, strlen(name));
+        ble.gap().setAdvertisingType(GapAdvertisingParams::ADV_CONNECTABLE_UNDIRECTED);
+        ble.gap().setAdvertisingInterval(interval);
+        ble.gap().startAdvertising();
+        
+        if (logging) printf("Started advertising\r\n");
+    }
+    
+    void onDataWrittenCallback(const GattWriteCallbackParams *params) {
+        // see if we know for which char this message is...
+        typedef std::map<GattCharacteristic*, Updatable* >::iterator it_type;
+        for(it_type it = writeCallbacks.begin(); it != writeCallbacks.end(); it++) {
+            if (it->first->getValueHandle() == params->handle) {
+                it->second->onDataWritten(params->data, params->len);
+            }
+        }
+    }
+    
+    void addToServices(uint16_t uuid, GattCharacteristic* c) {
+        if (uint16_services.count(uuid) == 0) {
+            uint16_services[uuid] = new vector<GattCharacteristic*>();
+        }
+
+        uint16_services[uuid]->push_back(c);
+    }
+    
+    void addToServices(const char* aUuid, GattCharacteristic* c) {
+        string uuid(aUuid);
+        if (uint128_services.count(uuid) == 0) {
+            uint128_services[uuid] = new vector<GattCharacteristic*>();
+        }
+
+        uint128_services[uuid]->push_back(c);
     }
     
     // === START READONLY ===
@@ -234,12 +401,8 @@
     SimpleChar<T> writeOnly(uint16_t serviceUuid, 
                                       const UUID& charUuid,
                                       void(*callback)(T) = NULL) {
-        GattCharacteristic::Properties_t gattChar = enableNotify ? 
-            GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_NOTIFY :
-            GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_READ;
-
         SimpleCharInternal<T, WriteOnlyGattCharacteristic>* c = 
-            new SimpleCharInternal<T, WriteOnlyGattCharacteristic>(ble, charUuid, GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_NONE, defaultValue, callback);
+            new SimpleCharInternal<T, WriteOnlyGattCharacteristic>(ble, charUuid, GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_NONE, T(), callback);
 
         addToServices(serviceUuid, c->getChar());
 
@@ -254,7 +417,7 @@
                                       void(*callback)(T) = NULL) {
 
         SimpleCharInternal<T, WriteOnlyGattCharacteristic>* c = 
-            new SimpleCharInternal<T, WriteOnlyGattCharacteristic>(ble, charUuid, GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_NONE, defaultValue, callback);
+            new SimpleCharInternal<T, WriteOnlyGattCharacteristic>(ble, charUuid, GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_NONE, T(), callback);
 
         addToServices(serviceUuid, c->getChar());
 
@@ -263,121 +426,12 @@
         return *(new SimpleChar<T>(c));
     }
     
-    // === END READWRITE ===
-    
-    
-    void onDisconnection(Gap::DisconnectionEventCallback_t callback) {
-        ble->gap().onDisconnection(callback);
-    }
-    
-    void onConnection(Gap::ConnectionEventCallback_t callback) {
-        ble->gap().onConnection(callback);
-    }
-    
-    BLE* getBle(void) {
-        return ble;
-    }
-
-    
-private:
-    void bleInitComplete(BLE::InitializationCompleteCallbackContext *params)
-    {
-        printf("bleInitComplete\r\n");
-        
-        BLE&        ble   = params->ble;
-        ble_error_t error = params->error;
-    
-        if (error != BLE_ERROR_NONE) {
-            printf("BLE Init error %d\r\n", error);
-            return;
-        }
-    
-        /* Ensure that it is the default instance of BLE */
-        if(ble.getInstanceID() != BLE::DEFAULT_INSTANCE) {
-            return;
-        }
-
-        ble.gattServer().onDataWritten(this, &SimpleBLE::onDataWrittenCallback);
-        
-        // let's add some services yo (why is there no 'auto' in mbed?)
-        uint16_t uuid16_list[uint16_services.size()];
-        size_t uuid16_counter = 0;
-        {   
-            typedef std::map<uint16_t, vector<GattCharacteristic*>* >::iterator it_type;
-            for(it_type it = uint16_services.begin(); it != uint16_services.end(); it++) {
-                printf("Creating service 0x%x\n", it->first);
-                uuid16_list[uuid16_counter++] = it->first;            
-    
-                GattCharacteristic* charTable[it->second->size()];
-                for (size_t git = 0; git < it->second->size(); git++) {
-                    charTable[git] = it->second->at(git);
-                }
-    
-                GattService service(it->first, charTable, it->second->size());
-                ble.gattServer().addService(service);
-            }
-        }
-
-        // 128 Bit services
-        const char* uuid128_list[uint128_services.size()];
-        size_t uuid128_counter = 0;
-        {
-            typedef std::map<string, vector<GattCharacteristic*>* >::iterator it_type;
-            for(it_type it = uint128_services.begin(); it != uint128_services.end(); it++) {
-                printf("Creating service %s\n", it->first.c_str());
-                uuid128_list[uuid128_counter++] = it->first.c_str();            
-    
-                GattCharacteristic* charTable[it->second->size()];
-                for (size_t git = 0; git < it->second->size(); git++) {
-                    charTable[git] = it->second->at(git);
-                }
-    
-                GattService service(UUID(it->first.c_str()), charTable, it->second->size());
-                ble.gattServer().addService(service);
-            }
-        }
-
-        ble.gap().accumulateAdvertisingPayload(GapAdvertisingData::BREDR_NOT_SUPPORTED | GapAdvertisingData::LE_GENERAL_DISCOVERABLE);
-        ble.gap().accumulateAdvertisingPayload(GapAdvertisingData::COMPLETE_LIST_16BIT_SERVICE_IDS, (uint8_t *)uuid16_list, uuid16_counter);
-        ble.gap().accumulateAdvertisingPayload(GapAdvertisingData::COMPLETE_LIST_128BIT_SERVICE_IDS, (uint8_t *)uuid128_list, uuid128_counter);
-        ble.gap().accumulateAdvertisingPayload(GapAdvertisingData::COMPLETE_LOCAL_NAME, (uint8_t *)name, strlen(name));
-        ble.gap().setAdvertisingType(GapAdvertisingParams::ADV_CONNECTABLE_UNDIRECTED);
-        ble.gap().setAdvertisingInterval(interval);
-        ble.gap().startAdvertising();
-        
-        printf("Started advertising\r\n");
-    }
-    
-    void onDataWrittenCallback(const GattWriteCallbackParams *params) {
-        // see if we know for which char this message is...
-        typedef std::map<GattCharacteristic*, Updatable* >::iterator it_type;
-        for(it_type it = writeCallbacks.begin(); it != writeCallbacks.end(); it++) {
-            if (it->first->getValueHandle() == params->handle) {
-                it->second->onDataWritten(params->data, params->len);
-            }
-        }
-    }
-    
-    void addToServices(uint16_t uuid, GattCharacteristic* c) {
-        if (uint16_services.count(uuid) == 0) {
-            uint16_services[uuid] = new vector<GattCharacteristic*>();
-        }
-
-        uint16_services[uuid]->push_back(c);
-    }
-    
-    void addToServices(const char* aUuid, GattCharacteristic* c) {
-        string uuid(aUuid);
-        if (uint128_services.count(uuid) == 0) {
-            uint128_services[uuid] = new vector<GattCharacteristic*>();
-        }
-
-        uint128_services[uuid]->push_back(c);
-    }
+    // === END WRITEONLY ===
 
     BLE* ble;
     const char* name;
     uint16_t interval;
+    bool logging;
     map<uint16_t, vector<GattCharacteristic*>* > uint16_services;
     map<string, vector<GattCharacteristic*>* > uint128_services;
     map<GattCharacteristic*, Updatable*> writeCallbacks;