BlackBerry 10 - Bluetooth LE primer for developers@blackberry.com

URL : https://supportforums.blackberry.com/t5/Native-Development-Knowledge/BlackBerry-10-Bluetooth-LE-primer-for-developers/ta-p/2287377

.....

This “smarter” variant is called Bluetooth Low Energy and you’ll find it specified in the latest Bluetooth 4.0 specification. There’s some terminology that’s worth nailing from the start:

 

• Bluetooth BR and Bluetooth BR/EDR: “BR” stands for “Basic Rate” whilst “EDR” stands for “Enhanced Data Rate”. In essence there terms capture the evolution of Bluetooth along the “bigger, faster” trajectory. These terms identify what has become known colloquially as “Classic” Bluetooth.
• Bluetooth LE: is commonly used as a short name for “Low Energy”.
• Bluetooth Smart: This is a marketing brand to identify ultra low energy devices that can connect to Bluetooth Smart Ready devices.
• Bluetooth Smart Ready: This is a marketing brand used to identify products such as phones, TVs, tablets, PCs, etc., that can connect with the ultra low energy Bluetooth Smart Devices.

 

What is Low Energy?

 

Put simply: it’s a new technology:

• The designers started with a blank sheet of paper;
• It has been optimised for ultra low power;
• It is different from classic Bluetooth technology.

 

Ok, that’s a pretty sweeping statement to say it’s a “New Technology” but how much is new and how much is based on classic Bluetooth. Well, it’s new in the sense that:

• It uses very efficient discovery and connection procedures;
• It exploits a new asymmetric design for peripherals;
• It uses very small packets;
• It uses client/server architecture.

......

Figure 3 - Bluetooth functional layers

  

A closer look at the LE Architecture

 

One of the key points to understand is that in Bluetooth 4.0 the LE and classic BR/EDR pillars of the Bluetooth stack are partly separated, with some shared components. The architecture diagram here (Figure 2) shows this. The details are not relevant but the main key point is to note that the box outlined in green is the LE component whilst the box outlined in red is the classic (BR/EDR) component. 

 

This means that a Bluetooth 4.0 device can elect to implement only the classic (BR/EDR) elements; only the LE elements, or both. Devices like phones or tablets will typically implement both BR/EDR and LE allowing it to communicate with both classic peripherals, such as headsets, as well as new LE devices like heart rate monitors.

Figure 2 - Overall Bluetooth 4.0 Architecture

 

Low power peripheral devices will probably implement only the LE elements and hence not be visible or able to communicate with devices that implement only the classic (BR/EDR) stack.

 

In this article we’re more interested in the application level interaction between Bluetooth LE devices and as such, the diagram below (Figure 3) is the one we’ll use to focus on the appropriate elements of the Bluetooth LE stack.

Figure 3 - Bluetooth functional layers

 

To a large extent the details of the various layers below the application layers are of little concern to an application developer but it’s of value to have an understanding of how Bluetooth is an incredibly resilient technology and able to operate in environments that are electrically hostile.

 
Bluetooth operates in the 2.54 GHz band which it shares with Wi-Fi, digital cordless phones and microwave ovens! Bluetooth LE still retains its fundamental resilience by splitting its radio traffic across 40 channels as shown below (Figure 4).

Figure 4 - Bluetooth LE frequency channel usage

 

Bluetooth LE Radio traffic hops around these channels in a pseudo random manner so that the data with get through even though it’s in an areas shared by a number of Wi-Fi networks, or microwave ovens. One of the differences between Bluetooth LE and classic Bluetooth is the number and use of these channels.

 

Bluetooth LE from an Application Perspective

 
Right, we’ve now got a basic sense of what Bluetooth LE is and its overall architecture. From a topology perspective LE devices can take on a number of roles. The diagram below (Figure 5) shows a number of devices labelled variously as:

 

• Scanner
• Advertiser
• Master
• Slave

 

The roles of “Scanner” and “Advertiser” are adopted by devices before connections have been established.

Figure 5 - Roles used during discovery and connection establishment 

 

Devices such as phones or tablets would generally (but not exclusively) adopt the role of “Scanner” and would “discover” other devices that have adopted the “Advertiser” role by a process called discovery which can be active (“are there any devices out there?”) or passive (“I’ll listen whilst devices advertise their presence”). Devices that adopt the “Advertiser” role are generally (but not exclusively) smaller footprint devices such as heart rate monitors or temperature sensors.

 
Once devices have discovered one another one will act as an “Initiator” (typically the phone or tablet type device) and attempt to connect to one of the devices that it has discovered. If successful it will adopt the role of “Master” and the other will adopt the role of “Slave”. “Master” devices will initiate commands and requests to “Slave” devices which will respond.

 
One of the first task of a Bluetooth LE application, such as on BlackBerry 10, is to discover other Bluetooth LE devices that it can connect to. A process called “bonding” can also be used whereby devices that have discovered one another in the past can cache important information about each other for use at a later time.

 

Services

 
Once a device has been discovered the next task is to figure out what services are offered by the device. So, what’s a service? Well, a service consists of:

 

• A Service Specification, which consists of:
• A collection of characteristics;
• References to other service.

 

Hmm, ok, that was a bit opaque. I tend to think visually and so here’s a diagram (Figure 6) to help cement the concept. We need to introduce some more terminology when talking about services. Remember we encountered the roles of “Master” and “Slave” once two devices had connected to one another? Well, when talking about services we use the names:

 

• Server
• Client

 

This highlights the client/server model that is used at this level of the architecture.

Figure 6 - Services and Characteristics 

 

A server device would typically be something like, say, a heart rate monitor, or thermometer; whereas, a client device would typically be something like a phone or a tablet, such as a BlackBerry 10 device.
Services maintain attributes called “Characteristics”. Think of a Characteristic as something that you can measure and be read from the device or be written to the device. It could be something like a speed, measured in metres per second, a counter used to measure the occurrence of some event, or perhaps, a voltage used to measure the status of a battery measured in, say, millivolts.

 

In fact if we really want to be accurate, a Characteristic is really a data type, analogous to a class. A server could and often does, have more than one instance of a given characteristic available and each such instance has a unique, temporary identifier called a "Handle". Such instances are therefore analogous to simple objects and a Handle analogous to an object reference. We'll use the term "Characteristic" in a slightly more relaxed way in this article; the context should make our meaning clear.

 

.....

The terms Notification and Indication are another set of terms of which you should have some understanding.

 

• Notification – this is a procedure whereby a Server can asynchronously notify a client of a change in the value of a characteristic it’s measuring. For example, in the case of a heart rate monitor the current heart rate would be sent to the client whenever its value changes or once a fixed time has elapsed. No acknowledgement is required from the client.
• Indication – this procedure is the same as an Indication except that an acknowledgement is required from the client.

 

Understanding the services offered by a device, how they are identified and accessed is key to the development of a Bluetooth LE application.

 

Services in More Detail

 
How are services and characteristics implemented? How are they named? How do we know that a “Temperature” service offered by one device is the same as one offered by another? This is the responsibility of GATT (Generic Attribute Profile). GATT rigorously defines the concepts around how services and their attributes are organised. It’s important to recognise that it does not define rules for their use.

 
Here’s a verbose description (Figure 7) of three services offered by a smart thermometer as an example. Two of these are defined by architecture (GAP and GATT) and allow the device to describe itself to the client.

Figure 7 - How Services and Characteristics are organised

 

It is able to identify itself by name and appearance ("I’m a digital clinical thermometer" for example); it’s able to offer some more detailed information about itself and finally it’s able to describe its "Temperature" service.

 
In effect the server maintains a small "database" consisting of the services, their descriptions, characteristics and values. If we supply more detail (Table 1) to this verbose description we can see that each attribute in the server has been assigned a "handle".

Table 1 - Detailed description of Services and Characteristics

 

The handle for the temperature characteristic’s value is 0x0022. This number is arbitrary and assigned by the server but is used by the client to uniquely identify the temperature value when it wants to access it.

 

Characteristics also have permissions so we can see that the Temperature value itself has a: “Read” permission – the client can read it!

 
All Bluetooth attributes are identified by UUIDs. There are two types:

 

• A UUID which is 128 bits long like: 00000000-0000-1000-8000-00805F9B325A
• A short UUID which is 16 bits long (xxxx) for convenience but which is defined to map to a standard 128 bit UUID as: 0000xxxx-0000-1000-8000-00805F9B34FB

 

UUIDs are managed and assigned by the Bluetooth Special Interest Group. So that you can look up what the UUID should be for, say, Temperature and find its unique UUID.

 
Now, you may ask yourself why we need handles if characteristics are uniquely identified by UUIDs? Well, here’s an example to help solidify this concept. Suppose the LE device we’re using is a Blood Pressure monitor. Blood pressure is measured using two pressures (Systolic and Diastolic). Both are measured in millimetres of Mercury (mmHg) and both are identified by the same UUID that identifies the characteristic as a pressure measurement.

 
So, the same UUID may appear in a service several times. How do you distinguish one from the other? You figure out the Systolic from the Diastolic one by the way the services are described and locate the different handles that have been assigned, by the server, to each one. Once you have done that you can access each one subsequently via its unique handle.

 
These are the main concepts that you will need to have to be able to write a BlackBerry 10 Bluetooth LE client application.

 
In fact that’s exactly what we’re going to do now! We’re going to walk through an application that will gather information on Heart Rate data from a heart rate monitor!

 

The Heart Rate Monitor Application

.....

Know your device. Get the specs.

 
In general, if you’re considering developing an app for a given Bluetooth device or device family, you need to know a little more about exactly what it is able to do with Bluetooth. Typically, a device will support a specific Bluetooth profile and it should be possible to determine this from the Bluetooth product’s documentation. Bluetooth profiles have a specification and the specification tells us things like the Bluetooth service or services that the device runs. The concept of a Bluetooth service was explained earlier in this article and you can think of a service as something which runs on a device which acts as a server, in the usual client/server sense of the term and which is able to deliver data (characteristics) to a client, either in response to requests or, asynchronously, whenever relevant data is available. Bluetooth services also have their own specifications and from the service specification we can find out precisely what data characteristics are available, under what circumstances and what their structure and values are.

 
So, the first thing we needed to do with our Wahoo heart rate monitor was to find out what Bluetooth LE profile it supports and then obtain the specifications for the profile and any services it referenced. It so happens that there’s a Bluetooth Heart Rate profile and that’s exactly what the Wahoo Blue HR device supports. A glance at the Bluetooth Heart Rate profile specification revealed that there’s also a Bluetooth Heart Rate service. Specifications for both profiles and services are available at the Bluetooth SIG web site here:

 
https://www.bluetooth.org/Technical/Specifications/adopted.htm

 
Now the specifications led us to understand that heart rate data would be delivered by the HR device asynchronously using Bluetooth notifications. These are the types of Bluetooth Attribute Protocol (ATT) message that are delivered by a server to a client and which do not require a response. We also learned from the specification that heart rate data would be delivered in a Heart Rate Measurement characteristic and that this is a structure comprising a number of fields. The first of these fields is called the Flags field and its bits give further information about the content of the heart rate measurement characteristic. Basically, some of the data defined for the heart rate measurement characteristic is optional and so not all devices will support it. The Flags field tells us whether each such optional data item is supported by the device or not. A supported data item may or may not be available at a particular moment however, so the Flags field can also indicate this.

 
You can examine the full structure definition for the Heart Rate Measurement characteristic at the Bluetooth SIG web site here:

 
http://developer.bluetooth.org/gatt/characteristics/Pages/CharacteristicViewer.aspx?u=org.bluetooth....

 
One point to note is that the Heart Rate Measurement Value field, which contains the heart rate measure in beats per minute, has two possible forms. It can either be a uint8 field or a uint16 field. The Flags field indicates which of these it is. The uint16 variant is intended to hold values greater than 255 as might be required if you’ve strapped your heart rate monitor around the chest of a humming bird or a tiny, frightened hamster. We decided we were writing our app for humans and so coded specifically for the uint8 variant!

.....