Retailers are always looking for the next great way to generate sales. Beacons are one technology that have taken the spotlight. Beacons have been featured in the news, mostly under the name “iBeacon” – Apple’s protocol using Beacon technologies.
The reason for iBeacon being so prominent is mostly because Apple has been using beacons on iPhones since the 4S! This is fairly early considering Android phones have only been able to scan BLE since Android 4.3 Jelly Bean (API level 18) but mostly can only act like beacons since Android 5.0 Lollipop (API level 21)!
There are very few devices that have the hardware to act as beacons. Under the Android 5.0 testing version, the Nexus 5 was able to act as beacon. However, because the chip would not allow multiple simultaneous beacon emissions, the final release of Android Lollipop prevents the Nexus 5 from using this technology! Android 5.0 was just release and only the Nexus 6 and Nexus 9 devices have access to this technology! This is very new to Android phones, so expect the Beacon phenomenon to get bigger in the near term!
Step 1: API Keys
The first thing you’ll need to do before getting started is signup for a PubNub account. We’ve got a more than generous free sandbox tier for development! You’ll need the API keys at the beginning of this tutorial.
Android iBeacon Project Overview
In this tutorial, we will dissect the signal emitted by beacons, and then we’ll use this knowledge to show you how you can use the brand new Android BLE package. This blog post is our series overview to get you started, and after that, check out our in depth tutorials on building an Android beacon emitter (publisher), and Android beacon detector (listener).
This tutorial is part of our larger series on building smarter beacons, and you can check out the beacon series overview here. We’ll show you how to start a two-way communication with a beacon when originally Beacons can only advertise information!
What a Beacon’s Advertisement Looks Like
According to the Bluetooth core specification, a beacon advertises a data package called the Scan Response Data.
This Data can be up to 31 bytes. If we create a smaller scan response, the remaining bytes will be filled with as many 0s.
The scan response is divided into what are called AD structures. They are sequences of bytes of various size, with a predefined structure that goes as follows:
- The first byte represents the number of bytes left to the end of the AD structure. This allows a receiver of this structure to know when it ends and when a new AD structure starts.
- The second byte is the ID of an AD structure type.
- The rest of the bytes are data that is structured in a predefined way depending on what AD type was defined by the previous byte.
That’s all there is to it. Just a succession of AD structures.
Most beacon protocols, if not all, have only 2 AD structures which are as follows.
The first one has 3 bytes:
- The first byte will be:
0x02 because we only count the following bytes.
- The second byte is:
0x01 which indicates we have a “Flag” AD type.
- The last byte represents theses flags. These flags express whether the emitting device is, in “Limited Discoverable Mode”, “General Discoverable Mode”, etc… The byte is computed the following way:
The 5 flags are represented by the first 5 bits of a byte. The value of these bits defines whether the flag is ON or OFF. The binary number is then written as a hexadecimal value which will be advertised. An example may clear things up:
The resulting binary value hence becomes:
b00011010. Converted into a hex, we get:
That’s it for the first AD structure! Now Let’s look into the second one, which contains most of the information we need.
The second structure can be of different size according to the protocol. We will take the example of AltBeacon, which really is nearly identical to others.
- First byte is
0x1B (27 in hexadecimal) which means we are taking all of the last available byte of our 31 byte scan response. This can vary according to protocols.
- The next byte is always
0xFF which means we have a “Manufacturer Specific” type of AD structure.
- As a result, the 2 following bytes represent the company identifier as defined on bluetooth.org. For our Nexus 9 device, the manufacturer of the bluetooth chip isn’t very clear so we’ll simplify this by using Google’s manufacturer ID which is 224. In hexadecimal value, this is equal 0x00E0. The ID, written as little endian takes up the 2 bytes. Here it will be
0x0E0 0x00 in this order.
- The rest is Manufacturer specific data! This is what changes the most between protocols.
For the AltBeacon protocol, the 2 first bytes of the manufacturer specific data are
0xBE 0xAC and identify altbeacon ADs. I personally really like that they decided to use the first 4 letters of beacon! Easy to remember. The next 16 bytes are a UUID representing the advertiser’s organizational unit, the 4 next bytes can be subdivided anyway you want. We are going to divide them in 2. We’ll have 2 bytes long numbers, similar to the major and minor in iBeacon. The following byte must be set according to your hardware, and the last byte can be left to 0, you can also decide to give it any meaning you want.
The byte which depends on the hardware represents the intensity of the signal at a meter away from your device. It is the two’s complement of the value in dB. The value of the intensity depends on a lot of factors, it often isn’t very precise. For my Nexus 9, -75dB seems like a correct estimation. This means the two’s complement will be
-75 + 256 = 181, so in hexadecimal value our byte becomes
Computing the Distance to a Beacon
One of the great strengths of beacon protocols is that they give you an approximate value of the distance that separates you to the emitting device.
This is always achieved by comparing the reference RSSI which is transmitted with the beacon scan response to the RSSI your phone detects. The algorithm to compute this value is often property of the beacon protocol owners (Estimote or iBeacon). However, because AltBeacon is an open-source project we will use their algorithm, available here and here.
We are going to use this algorithm in our example code to compute the distance. Note that regardless of the protocol you use, the computed value on the distance is not reliable and can’t be used to detect the exact location of the user. There’s more info on the limitations of beacons in Apple’s doc.
Using the Android BLE package for Beacons
In order to use Bluetooth on Android device, you will first need to add permissions to your Android Manifest:
The whole concept of the package is based around the Bluetooth Adapter which allows you to have access to your hardware. For example in your onCreate method:
That’s all you need to get started. Let’s look into more specific cases of emitting of scanning beacons. One thing you need to know when using the Android BLE package is that the first AD structure is automatically read or created. We will only need to work on the second AD structure. Moreover, the SDK automatically recognizes or creates manufacturer specific data structures, so we will not need to edit or use the 2 first bytes defining the size and the data type. The 2 bytes representing the company ID is also edited automatically, you only need the decimal value of the ID. This will make our life a little easier.
Scanning Beacons on Android
The first thing you need to do is to instantiate a Bluetooth LE scanner:
The android package allows users to create filters, so we can choose to detect beacons that correspond to our filter.
To detect an altBeacon, you will first have to build a scan filter. You will need to create an array, of bytes, of size 24. The first 2 bytes will be the altbeacon identifier prefix:
0xBE 0xAC. You will also insert the 16 bytes for the UUID of the beacons you want to detect. Commonly this is the UUID of your organization. You can leave zeros in the remaining bytes.
Build another array, of size 24, that contains one from index 0 to 17 and the remaining ones with zeros. This will indicate that only the first 18 bytes are mandatory and that the scanner should show us results for scan records that match the beginning of our Manufacturer data only.
Turn your Android into an Emitting (publisher) Beacon
Similarly, the first you need to do is instantiate a Bluetooth LE Advertiser:
To Build your data, you will use the advertise data builder. Similarly, create an array of bytes containing the AltBeacon prefix, your UUID, major, minor, and tx power. Once this is done you’ve completed the beacon!