Sample Code in Android to read any iBeacon PDU

I have created a sample code to read iBeacon PDU in Android.

I will not go into details of how iBeacon PDU look like. You can find a lot of blogs, StackOverFlow posts regarding the same.


This code is inspired from Bluetooth Application Accelerator available at the Bluetooth SIG website

Please do a code review and share your comments/feedback.

You can get complete source code at my GitHub repository here.

First create a simple Beacon class that will hold all elements of iBeacon.

package com.boskysoft.beaconscanner.modal;
/**
* @author bosky
*
* This is a sample modal class for iBeacon
*
*/
public class Beacon {
private final String proximityUUID;
private final String name;
private final String macAddress;
private final int major;
private final int minor;
private final int measuredPower;
private final int rssi;

public Beacon(String proximityUUID, String name, String macAddress,
int major, int minor, int measuredPower, int rssi) {
this.proximityUUID = proximityUUID;
this.name = name;
this.macAddress = macAddress;
this.major = major;
this.minor = minor;
this.measuredPower = measuredPower;
this.rssi = rssi;
}

public String getProximityUUID() {
return proximityUUID;
}

public String getName() {
return name;
}

public String getMacAddress() {
return macAddress;
}

public int getMajor() {
return major;
}

public int getMinor() {
return minor;
}

public int getMeasuredPower() {
return measuredPower;
}

public int getRssi() {
return rssi;
}

}

} 

Next, in MainActivity.java declare, 

private BleWrapper mBleWrapper = null;

Initialize mBleWrapper

mBleWrapper = new BleWrapper(this, new BleWrapperUiCallbacks.Null() {
@Override
public void uiDeviceFound(final BluetoothDevice device, final int rssi, final byte[] record) {
handleFoundDevice(device, rssi, record);
}
}); 

In handleFoundDevice, capture scanRecord byte array and parse:
 

protected void handleFoundDevice(BluetoothDevice device, int rssi,
byte[] scanRecord) {
String scanRecordAsHex = HashCode.fromBytes(scanRecord)
.toString();
for (int i = 0; i < scanRecord.length; i++) {
int payloadLength = unsignedByteToInt(scanRecord[i]);
if ((payloadLength == 0) || (i + 1 >= scanRecord.length)) {
break;
}
if (unsignedByteToInt(scanRecord[(i + 1)]) != 255) {
i += payloadLength;
} else {
if (payloadLength == 26) {
if ((unsignedByteToInt(scanRecord[(i + 2)]) == 76)
&& (unsignedByteToInt(scanRecord[(i + 3)]) == 0)
&& (unsignedByteToInt(scanRecord[(i + 4)]) == 2)
&& (unsignedByteToInt(scanRecord[(i + 5)]) == 21)) {
String proximityUUID = String.format(
"%s-%s-%s-%s-%s",
new Object[] {
scanRecordAsHex.substring(18,
26),
scanRecordAsHex.substring(26,
30),
scanRecordAsHex.substring(30,
34),
scanRecordAsHex.substring(34,
38),
scanRecordAsHex.substring(38,
50) });
int major = unsignedByteToInt(scanRecord[(i + 22)])
* 256
+ unsignedByteToInt(scanRecord[(i + 23)]);
int minor = unsignedByteToInt(scanRecord[(i + 24)])
* 256
+ unsignedByteToInt(scanRecord[(i + 25)]);
int measuredPower = scanRecord[(i + 26)];
String msg = "uiDeviceFound: "
+ device.getName() + ", rssi:" + rssi
+ ", Mac Address:"
+ device.getAddress()
+ " PROXIMITYUUID:" + proximityUUID
+ " MAJOR:" + major + " MINOR:" + minor
+ " MEASURED POWER:" + measuredPower;
Log.d(LOGTAG, msg);
// use myBeacon as per your need
Beacon myBeacon = new Beacon(proximityUUID,
device.getName(), device.getAddress(), major,
minor, measuredPower, rssi);
}
}
}
}
}

 

// use myBeacon as per your need
Beacon myBeacon = new Beacon(proximityUUID,
device.getName(), device.getAddress(), major,
minor, measuredPower, rssi); 

Profile, Services and Characteristics

GATT transactions in BLE are based on high-level, nested objects called Profiles, Services and Characteristics, which can be seen in the illustration below:

Profiles

To use Bluetooth wireless technology, a device must be able to interpret certain Bluetooth profiles. Bluetooth profiles are definitions of possible applications and specify general behaviors that Bluetooth enabled devices use to communicate with other Bluetooth devices.

A Profile doesn't actually exist on the BLE peripheral itself, it's simple a pre-defined collection of Services that has been compiled by either the Bluetooth SIG or by the peripheral designers.

Services

Services are used to break data up into logic entities, and contain specific chunks of data called Characteristics. A service can have one or more characteristics, and each service distinguishes itself from other services by means of a unique numeric ID called a UUID, which can be either 16-bit (for officially adopted BLE Services) or 128-bit (for custom services).


Characteristics
 
The lowest level concept in GATT transactions is the Characteristic, which encapsulates a single data point (though it may contain an array of related data, such as X/Y/Z values from a 3-axis accelerometer, etc.). Similarly to Services, each Characteristic distinguishes itself via a pre-defined 16-bit or 128-bit UUID.

Characteristics are the main point that you will interact with your BLE peripheral, so it's important to understand the concept. They are also used to send data back to the BLE peripheral, since you are also able to write to characteristic. You could implement a simple UART-type interface with a custom 'UART Service' and two characteristics, one for the TX channel and one for the RX channel, where one characteristic might be configured as read only and the other would have write privileges.

What makes BLE consumes less power

There are three characteristics of Bluetooth low energy technology that underlie its ULP performance: maximized standby time, fast connection, and low peak transmit/receive power.

Switching the radio “on” for anything other than very brief periods dramatically reduces battery life, so any transmitting or receiving that has to be done needs to be done quickly. The first trick Bluetooth low energy technology uses to minimize time on air is to employ only three “advertising” channels to search for other devices or promote its own presence to devices that might be looking to make aconnection. In comparison, Classic Bluetooth technology uses 32 channels.

This means Bluetooth low energy technology has to switch “on” for just 0.6 to 1.2ms to scan for other devices, while Classic Bluetooth technology requires 22.5ms to scan its 32 channels. Consequently, Bluetooth low energy technology uses 10 to 20 times less power than Classic Bluetooth technology to locate other radios.

Once connected, Bluetooth low energy technology switches to one of its 37 data channels. During the short data transmission period the radio switches between channels in a pseudo-random pattern using the Adaptive Frequency Hopping (AFH) technology pioneered by Classic Bluetooth technology (although Classic Bluetooth technology uses 79 data channels).

Another reason why Bluetooth low energy technology spends minimal time on air is because it features a raw data bandwidth of 1Mbps – greater bandwidth allows more information to be sent in less time. An alternative technology that features a bandwidth of 250kbps, for example, has to be “on” for eight times as long (using more battery energy) to send the same amount of information.

Bluetooth low energy technology can “complete” a connection (i.e. scan for other devices, link, send data, authenticate, and “gracefully” terminate) in just 3ms. With Classic Bluetooth technology, a similar connection cycle is measured in hundreds of milliseconds. Remember, more time on air requires more energy from the battery.

Classic Bluetooth technology uses a long packet length. When these longer packets are transmitted the radio has to remain in a relatively high power state for a longer duration, heating the silicon. This changes the material’s physical characteristics and would alter the transmission frequency (breaking the link) unless the radio was constantly recalibrated. Recalibration costs power (and requires a closed-loop architecture, making the radio more complex and pushing up the device’s price).

In contrast, Bluetooth low energy technology uses very short packets - which keeps the silicon cool. Consequently, a Bluetooth low energy transceiver doesn’t require power consuming recalibration and a closed-loop architecture.

Generic Attribute Profile (GATT)

GATT comes into play once a dedicated connection is established between two devices, means you have already gone through the advertising process governed by GAP. GATT defines the way that two BLE devices transfers data back and forth using concepts called Services and Characteristics. It make use of a generic data protocol called Attribute Protocol, which is used ti store Services, Characteristics and related data in simple lookup table using 16 - bit IDs for reach entry in table. These 16 - bit IDs are called UUIDs.

Note: Important thing to note here is, GATT connections are EXCLUSIVE. That means a BLE Peripheral device can only be connected to one central device at a time.


How Connections Works

It is interesting to know, that a peripheral device can only be connected to one central device, such as a mobile device, at a time, but a central device can connect to multiple peripheral.

How Connection Works

Client/Server Relationship

Peripheral act as GATT Server and Central act as GATT Client. GATT Server holds ATT lookup data, services and characteristics, whereas GATT Client sends requests to this server.

All transactions are started by the master device, the GATT Client, which receives response from the slave device, the GATT Server.

When establishing a connection, the peripheral will suggest a 'Connection Interval' to the central device, and the central device will try to reconnect every connection interval to see if any new data is available, etc. Marconi Labs ADA iBeacons is an example of such peripheral device. 

Note: It's important to keep in mind that this connection interval is really just a suggestion, though! Your central device may not be able to honor the request because it's busy talking to another peripheral or the required system resources just aren't available.

Generic Access Profile (GAP)

GAP controls advertising and connections in Bluetooth. GAP makes your device visible to the outside world, and determines how two devices can or can't interact with each other.

Advertising Data Payload and Scan Data Payload

There are two ways to send advertising out with GAP - the Advertising Data payload and the Scan Response payload.

Both payloads are identical and can contain up to 31 bytes of data, but only the advertising data payload is mandatory, since this is the payload that will be constantly transmitted out from the device to let central devices in range know that it exists. 

The scan response payload is an optional secondary payload that central devices can request, and allows device designers to fit a bit more information in the advertising payload such a strings for a device name, etc.

How Advertising Process works

A peripheral device will set a specific advertising interval, and every time this interval passes, it re-transmit it's Primary advertising packet. A longer delays saves power but feels less responsive

How Scan Process works

If a listening device is interested in the scan response payload (and it is available on the
peripheral) it can optionally request the scan response payload, and the peripheral will respond with the additional data.

How advertising payloads and scan response payloads work

What is Broadcasting

Another cool feature in BLE is that devices can send unsolicited broadcasts of small chunks of data. Unlike real Bluetooth, scanning for devices in the LE world can be passive - you just listen for advertisement packets on the right channels and you hear all the advertisements. 

How Broadcasting Works

By including a small amount of custom data in the 31 byte advertising or scan response payloads, you can use a low cost BLE peripheral to sent data one-way to any devices in listening range. This data is also called Manufacturer Specific Data.

Note: This approach is used by Apple's iBeacon protocol. It inserts a custom payload in the main advertising packet. We will talk about this custom payload in later posts.

How Broadcast Works

Once you establish a connection between your peripheral and a central device, the advertising process will generally stop and you will typically no longer be able to send advertising packets out anymore, and you will use GATT services and characteristics to communicate in both directions.

Bluetooth Low Energy - Possibilities are endless!

What is Bluetooth Low Energy (BLE)

As the name suggests, Bluetooth Smart/LE are devices optimized for low power consumption. It is a light-weight subset of classic Bluetooth and was introduced as part of the Bluetooth 4.0 core specification.

I will be writing a series of posts to describe various elements of BLE. Please share your comments, experiences, suggestions regarding the same.

What makes BLE so interesting

When you think of Bluetooth, what comes in your mind? Headsets, earphones, speakers, transfer files etc. But there is lot more in-store for you. Thanks to Bluetooth Special Interest Group (Bluetooth SIG) and many companies supporting BLE, a wide variety of other devices have come up. From fitness devices to smart lights, from wearables to beacons, all using the technology as a building block towards the "Internet of Things."

BLE support

BLE support is available on most of the platforms as of the versions listed below:

• iOS 5+ (iOS 7+ preferred)
• Android 4.3+ (numerous bug fixes in 4.4+)
• Apple OS X 10.6+
• Windows 8 (XP, Vista and 7 only support Bluetooth 2.1), Windows 8.1 has added support for communicating with Bluetooth devices from the store applications. 
• GNU/Linux Vanilla BlueZ 4.93+

BLE Device Roles

There are two major roles - As Central or Peripheral

• Central: devices are usually the mobile phone or tablet that you connect to with. eg: i{hone, Android mobile or tablets
• Peripheral: devices are small, low power that connect to much more powerful central devices. eg: Temperature sensor, Heart rate sensor, iBeacon etc.

Note: 

• iPhone/iPad can act both as Central or Peripheral, 
• With Lollipop OS, Android can also act as both Central or Peripheral.