How to Build an Android iBeacon 1/3

Crafting Beacons: Utilizing BLE for Android Devices

Here’s the deal - Retailers are always seeking innovative ways to boost their sales. Beacons, specifically BLE (Bluetooth Low Energy) beacons, have become one technology that continues to draw attention. Even years after their introduction, Beacons, also known as Bluetooth beacons, are still making headlines, primarily under the name “iBeacon” – Apple’s protocol utilizing Beacon technologies.

iBeacon's prominence can be largely attributed to Apple's early adoption of this technology. They've been integrating beacons into iPhones since the 4S model, making iOS devices synonymous with BLE beacon technology! They were also the pioneers in developing Beacon protocols, but more on that later.

In the Android ecosystem, only a handful of devices possess the necessary hardware to function as beacons. For instance, under the testing version of Android 5.0, the Nexus 5 was equipped to act as a beacon. However, due to limitations in the chip not allowing multiple simultaneous beacon emissions, the final release of Android Lollipop rendered the Nexus 5 incapable of using this technology. Fast forward to the present, Android 12.0 has now introduced a new location permission model, necessitating beacon apps to make changes to target SDK version 29+. In Android versions 6.0 and above, it's essential for apps to request location permissions from users at runtime to detect beacons. This development is relatively new to Android phones, so expect the BLE devices and Beacon phenomenon to gain more traction in the near future, especially with the emergence of IoT device control!

Types of Beacons & Their Differences

iBeacon

Apple's iBeacon was the first beacon protocol to be introduced. It's user-friendly and enjoys wide-ranging support.

Eddystone

Eddystone is Google’s response to Apple’s iBeacon. Initially named UriBeacon, it offers flexibility and, being a Google product, seamlessly integrates with all Google products and devices, including those using WIFI connectivity.

AltBeacon

The brainchild of Radius Networks, AltBeacon does not show any vendor preference. Its open-source nature allows for customizability of the source code, making it a versatile choice for app development.

GeoBeacon

GeoBeacon is an open-source beacon protocol developed by Tecno-World. It offers 8 types of user data, and its open-source nature ensures compatibility with various mobile platforms. This makes it a powerful tool in geolocation scenarios, leveraging BLE beacons and Bluetooth technology.

But First - API Keys to use with a Beacon app project

Before you dive in, you'll need to signup for a PubNub account. We offer an incredibly generous free sandbox tier for development! You'll need the API keys at the outset of this tutorial. You can find more about this in our PubNub doc.

Android iBeacon Project Overview

In this tutorial, we delve into the signal emitted by beacons and then leverage this knowledge to utilize the Android BLE package. This blog post is the starting point of our series. Following this, check out our in-depth tutorials on building an Android beacon emitter (publisher), and Android beacon detector (listener).

This tutorial is a part of our comprehensive series on building smarter beacons, which you can explore via the beacon series overview here. We’ll guide you on initiating a two-way communication with a beacon - a significant leap from the original Beacons which could only broadcast information!

What a Beacon’s Advertisement Looks Like

As per the Bluetooth core specification, a beacon broadcasts a data package termed the Scan Response Data.

This Data can contain up to 31 bytes. If we generate a smaller scan response, the remaining bytes will be filled with zeros.

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:

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 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. Refer to the log below.

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.

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:

<uses-permission android:name="android.permission.BLUETOOTH"/>
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>

The crux of the package lies with the Bluetooth Adapter, a tool permitting access to your hardware. For instance, in your onCreate method, as seen in Android 12.0:

@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  setContentView(R.layout.activity\_your\_activity);
  mBluetoothAdapter = BluetoothAdapter.getDefaultAdapter();
}

That’s all you need to get started. Let's delve into more specific instances of beacon scanning and emission. Be aware that when using the Android BLE package, the first AD structure is read or created automatically. Our focus will be on the second AD structure. Notably, the SDK automatically identifies or creates manufacturer-specific data structures, circumventing the need to edit the first 2 bytes defining the size and the data type. The company ID is also automatically edited, requiring only the decimal value of the ID. This simplifies the process significantly.

Scanning Beacons on Android

Initiating this process requires instantiation of a Bluetooth LE scanner:

mBluetoothLeScanner = mBluetoothAdapter.getBluetoothLeScanner();

Android's package allows users to create filters, enabling the detection of beacons that match our filter. To detect an altBeacon, you'll first need to build a scan filter. Create an array of bytes, of size 24. The first 2 bytes will be the altbeacon identifier prefix: `**0xBE 0xAC**`. Insert the 16 bytes for the UUID of the beacons you're aiming to detect, typically this would be your organization's UUID. The remaining bytes can be left as zeros.

Construct another array, of size 24, containing one from index 0 to 17 and the remaining ones with zeros. This indicates that only the first 18 bytes are mandatory and that the scanner should produce results for scan records that match our Manufacturer data's beginning only.

Turn your Android into an Emitting (publisher) Beacon

Start by instantiating a Bluetooth LE Advertiser:

mBluetoothLeAdvertiser = mBluetoothAdapter.getBluetoothLeAdvertiser();

To build your data, 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 successfully created the beacon!

Sum it Up

We've examined the signal emitted by beacons, computing distances to beacons, and how to scan beacons on Android devices. With this knowledge, you can create a new Android BLE package using Android 12.0.

Next, let's drill deeper into how to build the beacon detector. Then, we'll guide you through how to build the emitter.