ReactiveBeacons

Android library scanning BLE (Bluetooth Low Energy) beacons nearby with RxJava

Library was tested with Estimote and Kontakt beacons.

This library has limited functionality, but its API is very simple:

ReactiveBeacons(context)
boolean isBleSupported()
boolean isBluetoothEnabled()
boolean isLocationEnabled(context)
void requestBluetoothAccess(activity)
void requestLocationAccess(activity)
Observable<Beacon> observe()

JavaDoc is available at: http://pwittchen.github.io/ReactiveBeacons/

min SDK = 9, but if you are using API level lower than 18, don't forget to check BLE support on the device.

Usage
Good practices
Examples
Beacon class
Filter class
Download
Tests
Code style
Static code analysis
References
License

Usage

Step 1

Initialize ReactiveBeacons object:

private ReactiveBeacons reactiveBeacons;

@Override protected void onCreate(Bundle savedInstanceState) {
  reactiveBeacons = new ReactiveBeacons(this);
}

Step 2

Create subscribtion:

private Subscription subscription;

@Override protected void onResume() {
  super.onResume();
  
  if (!reactiveBeacons.isBleSupported()) { // optional, but recommended step
    // show message for the user that BLE is not supported on the device
    return;
  }
  
  // we should check Bluetooth and Location access here
  // if they're disabled, we can request access
  // if you want to know how to do it, check next sections 
  // of this documentation and sample app

  subscription = reactiveBeacons.observe()
    .subscribeOn(Schedulers.io())
    .observeOn(AndroidSchedulers.mainThread())
    .subscribe(new Action1<Beacon>() {
      @Override public void call(Beacon beacon) {
        // do something with beacon
      }
    });
}

Step 3

Unsubscribe subscription in onPause() method to stop BLE scan.

@Override protected void onPause() {
  super.onPause();
  if (subscription != null && !subscription.isUnsubscribed()) {
    subscription.unsubscribe();
  }
}

Please note: Library may emit information about the same beacon multiple times. New emission is created everytime when RSSI changes. We can distinguish several beacons by their MAC addresses with beacon.device.getAddress() method.

Good practices

Updating Manifest

Add <uses-feature .../> tag inside <manifest ...> tag in AndroidManifest.xml file in your application if you support Android devices with API level 18 or higher. You can skip this, if you are supporting lower API levels.

<uses-feature
    android:name="android.hardware.bluetooth_le"
    android:required="true" />

Checking BLE support

Check BLE support if you are supporting devices with API level lower than 18.

if (!reactiveBeacons.isBleSupported()) {
  // show message for the user that BLE is not supported on the device
}

If BLE is not supported, Observable emitting Beacons will be always empty.

Requesting Bluetooth access

Use requestBluetoothAccess(activity) method to ensure that Bluetooth is enabled. If you are supporting devices with API level lower than 18, you don't have to request Bluetooth access every time.

if (!reactiveBeacons.isBluetoothEnabled()) {
  reactiveBeacons.requestBluetoothAccess(activity);
}

Requesting Location access

Since API 23 (Android 6 - Marshmallow), Bluetooth Low Energy scan, requires ACCESS_COARSE_LOCATION or ACCESS_FINE_LOCATION permissions. Moreover, we need to enable Location services in order to scan BLE beacons. You don't have to worry about that if your apps are targeted to lower APIs than 23. Nevertheless, you have to be aware of that, if you want to detect beacons on the newest versions of Android. Read more at: https://code.google.com/p/android/issues/detail?id=190372. Use requestLocationAccess(activity) method to ensure that Location services are enabled. If you are supporting devices with API level lower than 18, you don't have to request Location access every time.

if (!reactiveBeacons.isLocationEnabled(activity)) {
  reactiveBeacons.requestLocationAccess(activity);
}

Exemplary code snippet

With API methods, we can create the following code snippet:

private boolean canObserveBeacons() {
  if (!reactiveBeacons.isBleSupported()) {
    Toast.makeText(this, "BLE is not supported on this device", Toast.LENGTH_SHORT).show();
    return false;
  }

  if (!reactiveBeacons.isBluetoothEnabled()) {
    reactiveBeacons.requestBluetoothAccess(this);
    return false;
  } else if (!reactiveBeacons.isLocationEnabled(this)) {
    reactiveBeacons.requestLocationAccess(this);
    return false;
  }

  return true;
}

You can adjust this snippet to your needs or handle this logic in your own way.

After that, we can perform the following operation:

if(canObserveBeacons()) {
  // observe beacons here
}

Examples

Exemplary application is located in app directory of this repository.

If you want to know, how to use this library with Kotlin, check app-kotlin sample.

If you would like to know, how to use library inside Android Service, check app-service sample.

Beacon class

Beacon class represents BLE beacon and has the following attributes:

BluetoothDevice device;
int rssi;
byte[] scanRecord;
int txPower;

All of the elements are assigned dynamically, but txPower has default value equal to -59. It works quite fine for different types of beacons.

Beacon class has also getDistance() method, which returns distance from mobile device to beacon in meters and getProximity() method, which returns Proximity value.

Proximity can be as follows:

IMMEDIATE - from 0m to 1m
NEAR - from 1m to 3m
FAR - more than 3m

Beacon class has also static create(...) method responsible for creating Beacon objects.

Filter class

Filter class provides static filtering methods, which can be used with RxJava filter(...) method inside specific subscription.

Currently the following filters are available:

proximityIsEqualTo(Proximity)
proximityIsNotEqualTo(Proximity)
distanceIsEqualTo(double)
distanceIsGreaterThan(double)
distanceIsLowerThan(double)
hasName(String)
hasMacAddress(String)

Of course, we can create our own custom filters, which are not listed above if we need to.

Exemplary usage

In the example below, we are filtering all Beacons with Proximity equal to NEAR value.

reactiveBeacons.observe()
    .filter(Filter.proximityIsEqualTo(Proximity.NEAR))
    .subscribe(new Action1<Beacon>() {
      @Override public void call(Beacon beacon) {
        beacons.put(beacon.device.getAddress(), beacon);
        refreshBeaconList();
      }
    });

Download

You can depend on the library through Maven:

<dependency>
    <groupId>com.github.pwittchen</groupId>
    <artifactId>reactivebeacons</artifactId>
    <version>0.4.0</version>
</dependency>

or through Gradle:

dependencies {
  compile 'com.github.pwittchen:reactivebeacons:0.4.0'
}

Tests

Tests are available in library/src/androidTest/java/ directory and can be executed on emulator or Android device from Android Studio or CLI with the following command:

./gradlew connectedCheck

Code style

Code style used in the project is called SquareAndroid from Java Code Styles repository by Square available at: https://github.com/square/java-code-styles. Currently, library doesn't have checkstyle verification attached. It can be done in the future.

Static code analysis

Static code analysis runs Checkstyle, FindBugs, PMD and Lint. It can be executed with command:

./gradlew check

Reports from analysis are generated in library/build/reports/ directory.

References

Useful resources

Producers of BLE beacons

Other APIs and libraries

License

Copyright 2015 Piotr Wittchen

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

304NotModified / ReactiveBeacons