Intro to BLE with

Introduction The purpose of this workshop is to help you get acquainted with the basics of BLE (Bluetooth Low Energy) by leveraging ARM® mbed™ tools. If you are not already familiar with these tools check out the Getting Started with mbed doc. In this workshop, we will approach BLE from a product development perspective. To this end we will be covering the existing standards, how BLE works, and how to make the most of a BLE system. As such we will be skipping much of the low-level interfaces that are only seen by stack developers and are of no concern to high level design. We will instead focus on GATT/GAP and SIG approved profiles and services. The prerequisites for this class are having a BLE enabled smartphone and an mbed enabled BLE development platform. This document is best viewed as a digital document. Here is a permalink to the document in case you are viewing it offline: http://goo.gl/VR2rki

Table of Contents: Introduction What is BLE? BLE Stack

GAP Generic Access Profile GATT Generic Attribute Profile

BLE States: advertising vs connected Physical Layer Layout of BLE Packets GAP: Advertising Payload PDU GATT: profiles, services, and characteristics UUID’s Development and Testing

BLE Apps Examples

GAP: URIBeacon GATT: Heart Rate Profile

Evothings Example : BLE Discovery

Moving Forward Other Tools

What is BLE? Bluetooth Low Energy, aka BLE, aka Bluetooth Smart, is part of the Bluetooth v4.x specification. BLE is not compatible with traditional Bluetooth. BLE is a low-power short-range communication protocol ideal for mobile and embedded devices. The low power aspect is achieved by having infrequent, small data packets with a max bit rate of about 30KB/s. Thus BLE is not recommended for high throughput applications such as video or audio streaming. It is common to see BLE applications that run on coin cell batteries for a year or more.

BLE Stack The BLE stack has many layers. For the purpose of this tutorial, though, we will only be covering the topmost layers: GATT and GAP. The only reason to have intimate knowledge of anything beneath these layers is if you are a stack developer. If this is the case I recommend reading the core bluetooth spec.

GAP: Generic Access Profile The GAP layer takes care of various control functions. Things like security, connection management and advertising are all part of the GAP layer.

GATT: Generic Attribute Profile The GATT layer takes care of data exchange and data organization. The GATT layer uses the Attribute Protocol (ATT) as transport for data exchanges between devices.

BLE States: Advertising vs Connected BLE operates in two basic states: advertising and connected. If you look at the BLE spec there are actually a bunch of sub-modes with special names for every case (broadcaster, initiator, advertiser, etc), but in general all cases fall into these two states. In advertising mode the advertiser broadcasts data out to any scanner that is listening, sometimes with the intent to connect, sometimes with no intention of forming a connection. There is no guarantee of data being transferred; it is simply broadcast out for anyone to find. This is a one-to-many transfer. The advertising mode uses the GAP layer of the BLE stack.

In connected mode two BLE devices are directly connected. In the connection a server serves data to a client. The terms ‘client’ and ‘server’ are used to express the directional flow of data, and as such both devices will be clients and servers during a two way flow of information. During a connected information transfer, data is guaranteed to be sent and is verified with a checksum. This is a one-to-one transfer. The connected mode uses the GATT layer of the BLE stack.

Physical Layer The BLE radio uses the 2.4 GHz band and divides it into forty channels (2.4000-2.4835 GHz) with 37 data transfer channels and three advertising channels spread throughout the spectrum. As can be seen in the image below, the three orange channels are used for advertising and the blue channels are for data transfer.

Figure 3: Frequency layers Source

BLE uses a frequency-hopping scheme where radios will periodically jump by a prescribed number of channels to avoid collisions between nearby radios. This allows BLE to effectively broadcast data in the cluttered 2.4Ghz band.

Layout of BLE Packets All BLE packets are at most 47 bytes. This is, however, a little deceiving, as there are not 47 bytes of user­accessible information in each transfer. Rather, those 47 bytes get whittled down by each layer of the BLE stack and usually wind up giving the user about twenty bytes of usable information. The full 47B layout can be seen below.

Preamble 1B

Access Address

4B

Packet Data Unit (PDU)

(2 … 39B) CRC 3B

The PDU section sub­divides into a two­byte header and a type­specific payload. Some of the available payload types are listed below:

Advertising Channel PDU (CH 37,38,39): Advertising Payload (GAP) Scanner Request/Response Payload Connection Initiation Payload

Data Channel PDU (CH 0­36): Link Layer Control Payload Data Payload

L2CAP Signaling Channel Security Manager Protocol Attribute Protocol (GATT)

GAP: Advertising Payload PDU The Advertising Payload is used to broadcast information about the BLE device. Lets take a closer look at the PDU for the Advertising Payload type. The 39 byte Advertising Payload PDU shrinks to a 31B Advertising Data section. This 31B section contains multiple advertising structures, each of which conveys a specific piece of information. There can be any number of AD Structs, as long as the total size of all structs does not exceed 31B. It is worth noting that each AD Struct has a 2B overhead associated with it.

A full list of the things that can be put in the AD Type field can be found on the SIG GAP page. Technically the AD Type has length N, but effectively it always has a length of 1B. A short list of the most common AD Types are listed below. Advertising Payload AD­Types:

0xFF Manufacturer Specific Data 0x01 Flags about connectability 0x08 Shortened Local Name 0x0A Tx Power Level And the rest...

Almost every advertising packet will have three bytes taken up by a flags struct detailing the broadcast mode of the advertisement. This leaves room for 26B of user data with 2B of overhead. A common use of this space is putting a custom data format into the Manufacturer Specific Data field. This can be seen in things like iBeacon and AltBeacon.

Please keep in mind that transferring data in the Advertising Data section does not guarantee delivery; missing 10­30% of packets is not uncommon. For things like temperature this is not a problem, but for real­time data like an accelerometer this could be an issue.

GATT: Profiles, Services, and Characteristics The GATT layer takes care of transferring data. There is a Data Payload PDU, but we’re not going to get into that because the actual size of data in GATT doesn't matter from a developer’s perspective. This is because the data in the GATT layer is sent as it is requested instead of all at once. This means only the data that is requested is sent, and nothing more.

The GATT layer organizes data into a hierarchy of services and characteristics. Services have one or more characteristics. Characteristics have one value of less than 512B, and can have zero or more descriptors. Characteristics have a header that defines read/write/notify on the value of the characteristic. Descriptors are great in theory for discovering what a characteristic represents, but in practice they are rarely used and more often totally neglected. It is far more common for someone to define their custom payload information and just publish the spec for it rather than trying to describe it with descriptors. For well defined services such as Heart Rate Monitor the values in characteristics are well known and do not have descriptors. Every service and characteristic has a UUID (more on that in the next section).

Profiles are an additional level of abstraction. They are not part of the GATT technical spec, but are useful for conceptual organization. Profiles are groups of services, much like services are groups of characteristics. There are well defined profiles provided by the SIG. A good example of a profile is the Heart Rate Monitor Profile. The HRM profile looks like this: S1: Heart Rate Service c1 : HR measurement c2 : sensor location S2: Device Information Service c1 : Manufacturer Name c2 : Model Number c3 : Revision Number c(n): etc

UUIDs UUID stands for Universally Unique ID. In BLE everything has a UUID. There are two sizes of UUID, 2B/16bit for those who pay money to the SIG and 16B/128bit for everyone who wants to roll their own. The 2B/16bit UUIDs are actually just a cheat; the first two bytes are used for the service/characteristic and the remaining 14 bytes are the same for every SIG uuid, so they can be implicitly filled in. Every service, characteristic and descriptor has a UUID. Profiles do not. UUIDs are used to describe everything in BLE transactions because they can be compressed with much greater efficiency than english descriptions. This has the effect of making BLE debugging a giant UUID lookup game. In most services at least one characteristic will be optional, meaning it may or may not be included. This makes it impossible to use the index of a characteristic to figure out its meaning, so instead UUIDs are used to define which characteristic is which. A complete list of UUIDs can be found under the GATT Specefications tab at developer.bluetooth.org:

Services Characteristics Descriptors

Development and Testing In order to develop and test BLE applications you will need two pieces: a client and a server. The server in our applications will be Nordic Semiconductor’s nRF51822 mkit, but any of the mbed enabled platforms with BLE will also work. For the client you will need a BLE-enabled smartphone with a BLE application. We are going to focus on the Heart Rate profile as it is rather simple and widely supported.

BLE Apps Because BLE has standard services and characteristics any BLE app that is standards-compliant can be used to communicate with standards-based devices. A quick search of the app store should reveal a bunch of apps that (should) work. Some particularly notable applications are the nRF Master Control Panel and nRF Toolbox for Android and LightBlue for iOS, the latter of which has a companion app that works on OSX as well.

The nRF Master Control Panel is really good for visualizing all BLE devices around you and organizing them by signal strength.

LightBlue has an easy to use interface and a good UUIDs-to-English translator.

Examples We are going to go over two examples, one each for GAP and GATT. Please make sure you have added the BLE­capable mbed­enabled platform to your compiler. If you don’t remember how to do this please see the previous document Getting Started With mbed.

GAP: URIBeacon Let’s take a look at URIBeacons, part of the Physical Web project. URIBeacons use BLE to broadcast out short URLs that redirect to websites or other URIs. In its most basic incarnation you can think of it as a QR code over BLE. URIBeacons use the GAP advertising packet to broadcast the URLs. To do so:

1. Download the Physical Web application for iOS or Android. 2. Import the mbed URIBeacon program into your compiler. 3. Compile the program and load it onto your board. 4. Open the Physical Web app and you should see a URIBeacon for "http://www.mbed.org". The Physical Web application also grabs a bit of info about the URL from the internet.

Now, try changing the URI to something else. Keep in mind that the maximum URI length is 17 bytes. Compile the code and load it onto your board. Remember to press Reset after programming. Use the Physical Web app to view your beacon.

Physical Web app scanning for URIBeacons Physical Web app displaying beacons

The URIBeacon is a special use of an Advertising Packet PDU. Specifically it uses the manufacturer­specific data field of the advertising data field. The specification for the URIBeacon can be seen below.

Notice the first two bytes are taken up by the ADLenth and ADType fields, so just like any other advertising data field you really only have 26 of the initial 31 bytes to work with. The

URIBeacon spec then uses eight of those 26 bytes for overhead, leaving seventeen bytes of space for the URI. If you take a look at the spec you will notice the prefixes (‘www.’, ‘http://’) and the suffixes (‘.com/’,’.org/’) are reduced to one byte each as part of the spec overhead.

GATT: Heart Rate Profile To demonstrate a GATT connection we are going to use the mbed BLE_HeartRate example.

1. Please add the example to your compiler and compile it to make sure there are no errors in the program.

2. Change the name of the device for easy identification. Change the following line to something you can easily identify:

3. Open the BLE scanner app of your choice and connect to your device. Tip: A good app is the nRF Toolbox, but any standards-compliant BLE app should

work. Please note that iOS caches names locally, so if you have connected to the BLE device before, the old name may be cached and you will not see the new name. Once connected you should be able to view the Heart Rate service’s Heart Rate Measurement characteristic. The value should be ticking up, going from 100 to 175 and then resetting. Try modifying the mbed code so it ticks up in multiples of 5 instead of 1.

Evothings Evothings is an open source project that provides a BLE plugin for the Cordova Smartphone Development Platform. It allows you to create applications in JavaScript that are hardware agnostic, using a standard BLE API. This means you can write an application in Evothings and run it on iOS or Android with little to no overhead for platform switching. Evothings has a handy executable that you can run on OSX, Windows and Linux for rapid prototyping and development.

1. Download the Evothings Studio Workbench from their website. 2. Download the Evothings Client app from the appstore (both iOS and Android). 3. Unzip the package to the folder of your preference and start the Evothings

Workbench.

Figure 6: Evothings Workbench on the desktop side

4. Open the client app (on your phone) and it will automatically start scanning for a

computer with an open workbench. 5. Once the client recognizes your workstation, connect to it. 6. You can now run any of the applications on the workbench by clicking the Run

button next to the application’s listing. 7. You can also take an existing project and modify it. Everything is in the examples

folder. The app is just a JavaScript file for the code and an index.html file for the GUI.

Example: BLE Discovery The BLE Discovery program is a good app to start with. It provides the option to connect to any nearby BLE device and explore its services and characteristics. You can use this app to connect to your device and double check that it is displaying the UUIDs you expect to see. For example,0x1800 refers to the Generic Access service while 0x180F refers to the Battery service. The complete list of services can be found here, if you’re interested. If you are interested in creating a custom UUID, the best practices can be found here.

Figure 7: BLE Discovery Application on a smartphone

Moving Forward Hopefully, you now have a better idea of the building blocks of the BLE stack. If you would like more example programs to explore on mbed, the official examples are all here. Download a few, try each of them out, see if you understand what the code is saying, then try out a solo flight. Remember - if you have any questions you can always post on the Question Forum to get in contact with our mbed/BLE experts. Happy coding!

Other Tools There are numerous tools available on other platforms for BLE development. Below is a short list of some of the best tools to emerge so far. Smart Device

Software: nRF Master Control Panel, nRF ToolBox, BLE Explorer … etc. Hardware: built­in.

OSX

Software: lightBlue ­ decent visualizer, but it uses UUIDs, not human readable names Has counterpart for iOS. XCode has some decent plugins.

Hardware: USB dongle or built­in.

Windows Software: Wireshark or TI's toolset (requires CC215x BLE dongle). Both of these

options are very intense. Windows does not have a native BLE API. Hardware: USB dongle or built­in.

Linux

Software: BlueZ hciconfig and gatttool. It’s all command line and not terribly friendly for beginners, but it works and is easily scriptable/extendable. Here is a good tutorial.

Hardware: USB dongle or built­in. Other

A number of Serial to BLE devices exist with Python libraries. These can be plugged into a computer and controlled via the command line.

BlueGiga LightBlue Bean iteadStudio