Developing made easy with BLELabs

Menu

Introduction

This tutorial continues the tutorial BL_T0001. You will learn how to use Bluegiga’s BGLib to connect the BLE112-Protostick with other Bluetooth Low Energy devices and exchange informations with them. You will use UUIDs and handles to get specific informations or even change them if you want and you will activate a notification service which provides you with up to date data. The source code from the previous tutorial BL_T0001 was modified accordingly to make it as easy as possible for you to enter the world of services and characteristics of Bluetooth Low Energy.

Profile_development_kit_developer_guide_v29.pdfExplains how to create, compile and flash custom firmware for the BLE112 modul.

Bluetooth_Smart_API_11_11032013.pdfComplete description of the Bluegiga-API (BGAPI), here you can get details about message flow and the structure of messages.

BLEGUI_User_Guide_v1.7.pdfComplete description how to use this tool.

The Plan

Our start point is the previous tutorial BL_T0001, so make sure you already have all needed components installed and properly configured before you continue with this tutorial. If not do so now.

We have two BLE112-Protosticks BLE112-Protostick #1 and BLE112-Protostick #2. BLE112-Protostick #1 is equipped with the uartdemo firmware and BLE112-Protostick #2 is equipped with the bgdemo firmware.

Insides of firmware bgdemo

Let’s first take a look under the hood of the bgdemo firmware used by BLE112-Protostick #2 especially the GATT configuration in which those services and characteristics are defined we want to work with. The interesting code lines are highlighted.

The first line we want to take a closer look to is line 9. This line defines the value of the characteristic 0x2a00 which is attached to (a sibling of) the service 0×1800. The service characteristic 0×1800 is the very basic service characteristic every BLE device has to define, it is called Generic-Access-Profile. In the Generic-Access-Profile you’ll find informations about a device, i.e. the previously mentioned characteristic 0x2a00 defines the device name, it is an officially defined GATT characteristic. More of these GATT characteristics you’ll find at Bluetooth Developer Portal. In the portals page main menu click on “GATT specifications” there you’ll find every information you need to implement an BLE device (Services, Profiles, Declarations, Descriptors).

Line 37 defines the characteristic properties of the service “Battery Status”. This characteristic holds the voltage level value of the devices power supply. In this case the interesting part is the property “notify” which is set to true which means that the service “Battery Status” is able to notify us about a actualized characteristic value (Notifications) – we will later activate this function to get informed about the actual battery status.

In line 45 the property “write” of the characteristic is set to true which means we are able to overwrite the characteristics value. As you can see the characteristics UUID is 16 bytes long and not 2 bytes long like the others which means that this is not an official UUID but an unique UUID defined by Bluegiga. This unique UUID describes the value of the Service “Bluegiga Demo Service” – we will later overwrite this value and then read it out to be sure all works fine.

Insides of firmware uartdemo

Now let’s take a closer look to the BLE112-Protostick #1 firmware uartdemo. The firmware has an endpoint to the BGAPI via USART which means that data send to the USART will be interpreted and executed by the BGAPI. The endpoint to the BGAPI is set in the uartdemo project file hardware.xml:

This endpoint definition is what makes it possible for us to use the BGLib in our program to communicate with the BLE112 modul and let us control its behaviour.

But the BLE112-Protostick can not only be controlled by the BGLib, it is also possible to use the tool BLEGUI which comes with Bluegiga’s SDK. This visual tool gives you an easy way to control the BLE112 modul by using only buttons and dialogs. You can learn a lot about the BGAPI by watching the tools log functionality which shows the communication between the tool and the BLE112 modul in detail. We will use the BLEGUI to get some informations (handles, UUIDs) before we start, we’ll need this information later in the tutorial example this will avoid us some work.

Procedure

Start to wire BLE112-Protostick #1 and BLE112-Protostick #2 properly like described in BL_T0001 and connect the BLE112-Protostick #1 with the PC.

Connect to the BLE112-Protostick #2 – You’ll need the targets MAC-address for that. You already know this address from the previous tutorial or you can use the BLEGUI tool to get it.

Request information from BLE112-Protostick #2 with only one command

Read a characteristics value by its UUID

Overwrite a characteristics value by its handle and read it back by its long UUID

Activate an notification service and listen to its notifications

Preparations

We are lazy programmers so lets get us some informations we need later.

Open the BLEGUI tool from the SDK location:

BLEGUI Location

Choose the USB-USART converter connected to the BLE112-Protostick #1 and connect BLEGUI with the BLE112-Protostick #1 by clicking “Attach”. You should see a green highlighted field now.

BLEGUI choose device & attach

Start to scan for other devices by clicking the according button on the left side. Make sure the BLE112-Protostick #2 is powered. Now you should get some device informations like the MAC-address and the RSSI valure. If not press the “Refresh” button in the lower right. Press “Connect” and then “GATT”. Don’t forget to write down the MAC-address.

BLEGUI discovery

Now you should see a white area with buttons named i.e. “Read” and “Write”. There you press “Service Discovery” to get all primary services of the BLE112-Protostick #2.

BLEGUI connect

After the Service Discovery process is done the white area should show you all primary services. There should be exactly four services which are defined by the bgdemo project file gatt.xml. Now click on the service 0xe001 to select it and then press “Descriptors Discover”.

BLEGUI select service

We now got all the details of the selected characteristic we need to activate the notification service. We need specifically the characteristic 0×2902 (for details see Bluetooth Developer Portal). We write down the handle of characteristic 0×2902 (17) and the handle of characteristic 0xe101 (16).

BLEGUI discover descriptors

At least we need the handle and the UUID of the Bluegiga-Demo-Service characteristic. In the white area click “Clear”. Then click “Service Discover” again, select the list entry with handle 18 and click “Descriptors Discover”. Now write down the characteristics handle (20) and its long UUID (f1b41cde-dbf5-4acf-8679-ecb8b4dca6fe).

BLEGUI – BGDemo Service – Characteristic

Eclipse-Project with Tutorial Source Code

Now you only have to repeat the steps described in BL_T0001 in chapter 4 with the source code for this tutorial to install our example in Eclipse. You can get the source code from GitHub ZIP URL. The Eclipse project should then look like shown on the right.

Application details

There are some new variables. We need to store connection settings, a possibility to exchange data with the application layer and some sort of program state control.

Connecting

We already know the MAC address of our target device BLE112-Protostick #2 so we don’t have to start a discovering process, instead we can directly connect it. Assign your devices MAC address to the variable target (see next listing). We are also defining there some connection settings. Details about the settings you can find in the BGAPI documentation on page 92 (Bluetooth_Smart_API_11_11032013.pdf).

If the command was executed successfully we receive the event “Connection Status” where we check if we are connected and if so we set a flag to be able notify the application layer (main) about the status change.

Request informations

The BGAPI gives us some possibilities to request data from the target device. Following commands are used in this tutorial.

Attribut protocol commands

Command

Description

Find Information

Finds all characteristics within a handle range, returns handle and UUID.

Find By Type Value

Finds all characteristics with a specific value within a handle range, returns handle.

Read By Group Type

Reads value of all characteristics with the same UUID within a handle range, returns characteristics group handle range besides the value.

Read By Type

Reads value of all characteristics with the same UUID within a handle range

Read

Reads characteristics value by its handle

Write

Write a characteristics value by its handle

If you us the complete possible handle range (0×0001 – 0xFFFF) with the command “Find Information” you get all characteristics the bgdemo firmware provides, that should be 20 in count, we’ll see that later.

We also want to do the same Service-Discover process like we did earlier with the BLEGUI tool. For that we request all primary GATT services which are defined by GATT_PRIMARY_SERVICES_UUID (0×2800), see next listing.

Write by handle

Before you overwrite a value you have to take care not to exceed the capacity of the values target. Next we want to overwrite an characteristic which holds 3 bytes (Bluegiga Demo Service – Characteristic).

After we have written a value we want to make sure we really nailed our goal. This time we use the 128-bit or 16-byte long UUID to read the characteristic value. The requested value is then printed out to the console.

Activate Notification and handling of a notification

Now it gets interesting. We can use services which are able to notify us about a change of their value without having to poll the value of interest every time we want it. To do that we have to adjust the characteristics configuration. The characteristics configuration itself is also a characteristic which is called “Client Characteristic Configuration” it has the UUID 0×2902. If you want to know the details how to adjust the configuration you can read it in the official specification (Bluetooth Developer Portal).

Do you remember we wrote down a handle of a characteristic with the UUID 0×2902 earlier with the BLEGUI? This was the handle of the configuration characteristic which controls the service “Battery Status”. We will now use that handle to activate the notification by overwriting the configuration characteristics value with 1.

We now receive periodically new values every time the “Battery Status” characteristics value is updated. So every time we get a notification we raise a flag to notify our application layer that a new value is available.

In the application layer (main) we wait for the flag raise which signals us a new available value we can print out to the console. We are doing this 10 times and then we disconnect from the BLE112-Protostick #2 which automatically ends the notifications.

/* Get notified 10 times ... */
printf("[###]Watch for notifications and print them if arriving[###]\n");
int notifications = 0;
while (notifications < 10) {
/* We have to check for BGLib messages, this was previously hidden within the wait_for_... functions. */
if (read_message()) {
printf("Error reading message\n");
exit(-1);
}
/* Check if everything is fine */
if (issetFlag(app_state, APP_ATTCLIENT_ERROR)) {
die();
};
/* Check if a notification is pending and if yes check for the handle of the battery service we are looking for */
if (issetFlag(app_state, APP_ATTCLIENT_NOTIFICATION_PENDING)) {
clearFlag(app_state, APP_ATTCLIENT_NOTIFICATION_PENDING);
/* We already know the handle of the custom battery service by looking it up with BLEGUI earlier */
/* Now lets see if it is the handle we've waited for. */
if (app_attclient.handle == serv_notification_handle) {
/* The service characteristics value is simply the battery voltage in 10th of a millivolt.
* First put the 16-bit value together and then convert the value to volts. */
uint16 voltage = (app_attclient.value.data[1] << 8) | app_attclient.value.data[0];
printf("[#] Notification %d - Battery Voltage: %1.3f Volt\n", notifications, voltage * 0.0001);
notifications++;
}
}
}

Complete Debug Output

If everything was configured and adjusted properly the debug console output should look like in the following listing (each step we’ve done previously is highlighted).

Conclusion

You are now able to build your own interesting application on top of the tutorials example by only changing small peaces of code. If you got stuck adjusting the BLE parts of the program to your needs you can always take a look into the BLEGUI tools logging console how the tool does something and then simply repeat it.

Now we know how the master/central side of a Bluetooth Low Energy communication works. We can use this knowledge to adapt BLE to other platforms i.e. the very popular Raspberry Pi and Arduino platforms. Soon there will be new tutorials covering these two platforms.

Afterwards we will take a closer look to the slave/peripheral side of the communication and how we can build our own sensor peripherals. Of course there will be new tutorials for this too.