How to Build an Android iBeacon [Updated] 1/3

Here’s the deal - Retailers are always looking for the next great way to generate sales. Beacons are one technology that have taken the spotlight. Even years after their launch, Beacons are still featured in the news, mostly under the name “iBeacon” – Apple’s protocol using Beacon technologies.

The reason for iBeacon being so prominent is mostly thanks to Apple. They’ve been using beacons on iPhones since the 4S! They were also the first company to come out with Beacon protocols, but we’ll get into that later.

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 a 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 10.0 was just released and has a new location permission model that requires beacon apps to make changes to target SDK version 29+. Newer versions of Android require that you request location permission from the user at runtime in order to detect beacons.This is very new to Android phones, so expect the Beacon phenomenon to get bigger in the near future!

Types of Beacons & Their Differences

iBeacon:

iBeacon was created by Apple and was the first beacon protocol introduced. It’s pretty easy to use, and it is very widely supported.

Eddystone:

Eddystone is Google’s answer to Apple’s iBeacon. Previously named UriBeacon, it is very flexible and, since it’s created by Google, works very well with all Google products and devices.

AltBeacon: 

Designed by Radius Networks, it doesn’t favor one vendor over another. It is open-source, which provides for customizable source code.

GeoBeacon:

This open-source beacon protocol was created by Tecno-World. It features 8 types of user data, and is open-source, so it’s pretty flexible with various mobile platforms.

But First - API Keys

The first thing you’ll need to do before getting started is to 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 dissect the signal emitted by beacons and then 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 more-extensive 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. Which is great because the original Beacons can only advertise information!

By the way, we've already published our tutorials for iOS iBeacon and Tessel beacon. So if those are more your cup of tea, check them out!

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 structured in a predefined way, depending on what AD type the previous type defined.

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.

First AD Structure

The first structure has 3 bytes:

• The first byte: 0x02 because we only count the following bytes.
• The second byte: 0x01 which indicates we have a "Flag" AD type.
• The last byte represents these flags. These flags express whether the emitting device is, in “Limited Discoverable Mode”, “General Discoverable Mode”, etc… The byte computes 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:0x1A

That’s it for the first AD structure! Now Let’s look into the second one, which contains most of the information we need.

Second AD Structure

The second structure can be of different sizes according to the protocol. We will take the example of AltBeacon, which 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 to 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, and the 4 next bytes can be subdivided anyway you want. We are going to divide them into 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 at 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 0xB5.

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 from the emitting device.

This is 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

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.

Check out our full Android Beacon detector tutorial and example app.

Turn your Android into an Emitting (publisher) Beacon

Similarly, the first thing 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!

Sum it Up

We’ve gone over the signal emitted by beacons, computing distances to beacons, and how to scan beacons on Android devices. You should have all the info you need now to create a new Android BLE package.

Next, let’s go in-depth on how to build the beacon detector. Then we’ll show you how to build the emitter.