Get Your Beac On Part 3

In part one and part two, I described some of the key issues for developers of beacon applications, introduced the AltBeacon advertising format and reviewed a prototype Android museum guide application using the AltBeacon Android API. In this third part, I’ll describe how I tested the museum guide application.

Roll Your Own Beacon

I don’t have any ready-made beacons which use the AltBeacon format in my collection of Bluetooth development equipment (although continue to watch the tools from the SIG and we’ll show you how to make your own beacon from a Raspberry Pi board). I do have a good collection of Bluetooth developer boards. Developer boards are programmable microcontroller units or even full computers which have a Bluetooth Smart stack on them. They’re typically used for implementing profiles for new products, with the firmware developed on the board, and eventually being flashed onto the final product or simply for experimentation and learning. I decided to use a couple of my developer boards to create my own beacons so I could test my Android museum guide.

I used a Bluegiga DKBLE and an Intel Edison kit. The Bluegiga board is programmed in a scripting language called “BGScript”. The Intel Edison runs Linux and there are a range of options for programming it. I opted to use Node.js which is an event driven JavaScript framework for which I knew there was a suitable Bluetooth Smart module available.

Turning Bluegiga into an AltBeacon

Bluegiga’s BGScript is a simple and easy to learn scripting language which has access to a rich function library provided by the Bluegiga framework. Creating a Bluegiga application with BGScript involves working with a text editor to create script files and other project configuration files. Projects are compiled and uploaded to the board over USB in one simple step using a software update tool which is part of the Bluegiga SDK.

Scripts consist of variable and buffer declarations, procedures and event handlers. Call backs are an essential part of the programming model and often making a call to one of the standard Bluegiga functions will result in a call back to an event handler. Equally, the framework can make calls into event handlers in response to other situations which arise outside of your script.

Implementing a beacon on any platform involves working with the Bluetooth Generic Access Profile (GAP) and requires advertising packet content to be set and advertising parameters to be configured.

The key elements of my Bluegiga AltBeacon implementation are presented below.

I started by declaring some buffers.

Figure 1 – Declaring Buffers

Setting up advertising takes place in one of the Bluegiga standard event handlers “system_boot” which is called by the system when the board is powered up or reset. I started by setting up a buffer containing the Flags field which contains a collection of bits, each of which indicates something about the way in which Bluetooth Smart (LE) and/or Bluetooth BR/EDR are supported.

The fields which an advertising packet may contain are called AD data types and are defined in the Bluetooth Core Specification Supplement in Part A, the Data Types Specification. AD data types have a standard structure comprising a single byte length field (the value of which does not include the byte occupied by the length field itself), a single byte data type indicator and the value of the field. Data type values are defined in the Assigned Numbers document for the Generic Access Profile.

Here’s the code for this first part of the initialisation process.

Figure 2 – Defining the flags AD type in the system_boot event handler

I introduced the AltBeacon format in part 1 of this series and explained that data is encoded within the GAP Manufacturer Specific Data AD field. I prepared this data in the next 20 bytes of the same buffer.

Figure 3 – Defining the AltBeacon data in the Manufacturer Specific Data field

I also set up a local name for the device, which will be returned in a scan response if a GAP central mode device is performing active scanning. This value is another AD type and I set it up in its own buffer. As you can see, the local name specified is “AltBeacon”.

Figure 4 – Setting up a local name for use in scan responses

Configuring advertising parameters involves making calls to a number of Bluegiga functions and makes use of the two buffers that were populated with data earlier on:

Figure 5 – Configuring GAP advertising

And that’s pretty much it. My Bluegiga custom AltBeacon is ready.

Figure 6 – AltBeacon on Bluegiga DKBLE

AltBeacon on Intel Edison

Node.js is modular in design and there is a wide selection of modules available for various purposes. Modules are similar to libraries in the world of Node.js. The module “Bleno” provides functions for applications which act as Bluetooth GAP peripherals including, where relevant, the definition and implementation of a GATT profile. It’s open source and was created by Sandeep Mistry who also created the Noble module which allows software for GAP central mode devices to be created. Bleno is in github and so is Noble.

The standard distribution of Bleno doesn’t support the AltBeacon format but does support iBeacon. Consequently, I cloned the Noble github repository and changed Bleno so that I could generate GAP advertisements in the AltBeacon format. The changes I made are described next.

I added a new function to the standard bleno.js source file so that I could initiate advertising with a given set of parameters from a node.js application. My new function looks like this:

Figure 7 – New function in bleno/lib/bleno.js

All that’s happening in this code is that a buffer is being populated with the required AltBeacon data and then a call is being made to another function I added to the Linux bindings.js source file. Bleno works with the BlueZ Bluetooth stack on Linux and functions exposed by Bleno for use by applications ultimately get mapped to calls to BlueZ functions when executing on a Linux based platform. I had to change some of the Linux-specific parts of Bleno to achieve my goal of adding support for AltBeacon.

Figure 8 – New function in bleno/lib/linux/bindings.js

 

Figure 9 – New function in bleno/lib/linux/hci-ble.js

All these functions do is prepare a buffer containing the required advertising data in much the same way as on the Bluegiga board, and then pass it down through the Bleno API layers until it can be passed directly to BlueZ’s Host Controller Interface (HCI).

The AltBeacon Node.js Application

Having modified Bleno to support AltBeacon, all that was left to do was to create a Node.js application which used my new bleno.js function to start advertising using the AltBeacon format. The whole application is the 7 lines of code shown in Figure 10.

Figure 10 – The AltBeacon node.js application

To run my AltBeacon application I use Putty to establish a terminal session with the Intel Edison and then run the node.js application from the command line.

Putty Establishing a Terminal Session

And that’s all there is to it!

Demonstration

FEATURED DOWNLOAD

An Introduction to Bluetooth Beacons

This self-study educational resource covers both the theory and practice of developing Bluetooth beacons and integrating beacons into existing products and applications. 

DOWNLOAD NOW