How to Build an Android iBeacon 1/3
Published: 2024-01-18 14:35:49

Here’s the deal - [Retailers](https://pubnub.com/blog/ecommerce-transformed-cognitive-services-and-the-future/) 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](https://www.pubnub.com/solutions/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](https://www.pubnub.com/solutions/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](https://dashboard.pubnub.com/signup). 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](https://www.pubnub.com/docs/general/basics/set-up-your-account).

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)](https://pubnub.com/blog/build-android-ibeacon-beacon-emitter/), and [Android beacon detector (listener)](https://pubnub.com/blog/build-android-beacon-ibeacon-detector/).

This tutorial is a part of our comprehensive series on building smarter beacons, which you can explore via the [beacon series overview](https://pubnub.com/blog/building-smarter-beacons-bidirectional-beacon-communication/) 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!

![](/cdn/3prze68gbwl1/asset-17suaysk1qa1ht1/390c225f5a3d712a449ad6df71d656a9/nexus9-framed.gif?w=700&h=550)

What a Beacon’s Advertisement Looks Like
----------------------------------------

As per the [Bluetooth core specification](https://www.bluetooth.com/specifications/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:

-   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 “Li
    
    mited 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:

![](/cdn/3prze68gbwl1/41MNctRGxlM3f2cVZKjm3o/6a5cce32f5e53ae616c848f3ddf130c8/Screen-Shot-2015-04-13-at-9.49.01-AM.png)

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.

![](/cdn/3prze68gbwl1/asset-17suaysk1qa1hss/e66e14a10c6786db9b16531a146979d8/scan-response-structure.png)

Second AD Structure
-------------------

The second structure can be of different sizes according to the protocol. We will take the example of [AltBeacon](https://altbeacon.org/), 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](https://www.bluetooth.com/specifications/assigned-numbers/company-Identifiers/)
    
    . 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](https://altbeacon.org/) is an open-source project, we will use their algorithm, available [here](https://github.com/AltBeacon/android-beacon-library) and [here](https://stackoverflow.com/questions/20416218/understanding-ibeacon-distancing).

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](https://developer.apple.com/ibeacon/Getting-Started-with-iBeacon.pdf).

Using the Android BLE package for Beacons
-----------------------------------------

To use Bluetooth on Android device, you will first need to add permissions to your Android Manifest:

```js
<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:

```js
@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:

```js
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:

```js
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](https://www.pubnub.com/blog/tessel-ibeacon-tutorial-building-the-detector-data-beacon-subscriber/). Then, we'll guide you through [how to build the emitter](https://www.pubnub.com/blog/build-android-ibeacon-beacon-emitter/).

How can PubNub help you?
========================

This article was originally published on [PubNub.com](https://www.pubnub.com/blog/building-android-beacon-android-ibeacon-tutorial-overview/)

Our platform helps developers build, deliver, and manage real-time interactivity for web apps, mobile apps, and IoT devices.

The foundation of our platform is the industry's largest and most scalable real-time edge messaging network. With over 15 points-of-presence worldwide supporting 800 million monthly active users, and 99.999% reliability, you'll never have to worry about outages, concurrency limits, or any latency issues caused by traffic spikes.

Experience PubNub
-----------------

Check out [Live Tour](https://www.pubnub.com/tour/introduction/) to understand the essential concepts behind every PubNub-powered app in less than 5 minutes

Get Setup
---------

Sign up for a [PubNub account](https://admin.pubnub.com/signup/) for immediate access to PubNub keys for free

Get Started
-----------

The [PubNub docs](https://www.pubnub.com/docs) will get you up and running, regardless of your use case or [SDK](https://www.pubnub.com/docs)