Introducing Luch — a New Library for BLE Beacon Scans on Android

Photo by Paulius Dragunas on Unsplash

Bluetooth Beacons are the small devices that transmit small packages of data according to the BLE protocol. These signals can be picked up by nearby devices like smartphones, and these devices can act accordingly.

For the last couple of months, I’ve been trying out BLE APIs on Android. I wanted to build a beacon scanner library that would fit my needs perfectly while being as simple as possible. The general curiosity about how things work in the land of BLE on Android was also one of the main drivers.

(You see, I’m doing my best to avoid calling it a severe case of Not-Invented-Here syndrome).

The result of these explorations is the new library called Luch* which has the following features:

• Easy to use API;
• Small footprint — the entire AAR is a little bit over 50 Kb;
• Good test coverage (at the time of this writing it stands at 94% according to the Codecov reports);
• Support of different beacon types (AltBeacon beacons are supported out of the box, other beacons can be supported by providing the beacon layout);
• Distance calculation for detected beacons with RSSI filters to smooth out some shakiness of RSSI data.

But first, let’s take a look at the existing solutions.

Comparison

To make matters simpler, I decided to put the data on the solutions I’ve been looking at while working on Luch into a single table:

I’d say that the choice boils down to this:

1. If you need to detect beacons when the app is backgrounded or killed, choose between AltBeacon and iBeacon scanner android (but you might have to change your plans regarding background detections soon, more on that later**).
2. If you need to detect non-iBeacon beacons when the app is backgrounded or killed, choose AltBeacon.
3. Another thing to consider is whether the library is still supported or not. The last commit to iBeacon scanner android was in April 2018, so this may or may not affect your decision. AltBeacon is still supported, and I feel like the maintainer has no reason to stop supporting it. :)
4. Otherwise, I’d recommend giving Luch a try.

Now, let’s look at some APIs (I’ll consider AltBeacon beacons for the most of the article).

Installation

The library is added to jCenter, so you only need to add a dependency to your app’s build.gradle file:

implementation 'aga.android:luch:(insert latest version)'

Setting up the scans

If all you want*** is to be notified about all beacons that surround you periodically, you need to create a BeaconScanner first:

Later, you will need to start the scans when the app is in the foreground and stop them when it gets backgrounded. I usually write my apps according to the Single Activity style, so these starts and stops naturally correspond to the onResume and onPause callbacks:

You’ll need to check that the app holds location permission before starting and stopping the scans, but I omitted that for brevity.

Also, this in my example points to the Context which is needed to access BLE APIs on Android.

Don’t forget to check that Bluetooth and Location Services are turned on, and the necessary permissions are given; the library won’t crash or show any popups if they aren’t.

And that’s it!

Filtering by the beacon data

Now, let’s consider something else. What if you want to make sure the library only looks for some specific AltBeacon beacons? To do that, you set up your BeaconScanner with someRegions :

Each AltBeacon beacon is identified by three fields, named id1 (16-byte long field), id2 and id3 (both are 2-byte long integer fields). The setUuidField method in the code above sets up id1, the first setIntegerField invocation sets up id2; the second invocation sets id3.

Then you pass your regions into the scanner. You can provide multiple regions when you’re setting up the scanner; I used a single one to simplify an example.

Voilà, we’re done.****

Beacon formats

If you want to look for the different beacons, you can do that by specifying the custom beacon layout format:

The format of beacon layouts is somewhat similar to the one supported by AltBeacon library(see setBeaconLayout method) with the number of exceptions:

1. The only field prefixes supported at the moment are ‘m’, ‘i’, ‘p’ and ’d’.
2. Little-endian fields are not supported yet, as variable-length fields.

Distance calculation

You can range your beacons if you want to. To do that, build your BeaconScanner with ranging support:

Once you start beacon scans, you can access the scanner’s Ranger object. This object does the distance calculation for a detected beacon:

The ranging works only for the beacons that provide the TxPower value in their advertisement packages (AltBeacon is one of them).

Another component of distance calculation is RSSI value, which changes over time. Due to the nature of BLE, RSSI values can change quite suddenly, even if you’re not moving and just standing in front of the beacon.

To smooth these sudden changes, Luch uses the RSSI filtering technique. The default filter is running average filter, but you can replace it with ARMA (autoregressive–moving-average filter):

You can provide your own filters by extending the RssiFilter class.

This is more or less all I wanted to mention about this library, there’re some additional examples in the repository’s readme and sample module. I’ve been using it myself for close to a month now, and all the use-cases I’ve been interested in work flawlessly.

I recommend anyone interested in beacons on Android to give this library a try and share your feedback!

Notes

* Luch (луч) means Beam (or Ray) in Russian.

** The reason you might want to reconsider the idea of background beacon scans is that these scans require the location permission. And, as you might know, Google is cracking down on the background location access yet again.

In a nutshell, you have to either provide a piece of really compelling evidence that your use-case justifies background location access, or you need to remove it from your app. The failure to comply will result in the app’s removal from Google Play Store.

** If you want to listen to individual beacon’s enter/exit/update events, you can do that too:

**** If you’re curious about why you need to add a null field into your Region first, the reason is quite simple. An AltbBeacon’s beacon layout looks like that:

m:2-3=beac,i:4-19,i:20-21,i:22-23,p:24-24,d:25-25

The first field is a beacon type field that occupies the 2nd and 3rd bytes and has a value of "beac". Then we have an id1 identifier field (bytes 4-19), id2 identifier field (bytes 20-21), id3 identifier field (bytes 22-23), and two additional single-byte fields. Since we don’t want to filter by the beacon type, we ignore it by specifying the null value for that field.

You might be tempted to ask — yeah, that’s a good explanation, but why do we even need that null field? Can’t we omit it somehow?

We certainly can, but it’ll only make the implementation of the BeaconParser a little bit more challenging to grasp. ‘Explicit is better than implicit’, as they say in “The Zen of Python”. :)