Estimote SDK for Android

Overview

The Estimote SDK for Android is a library that allows interaction with Estimote beacons & stickers. The SDK system works on Android 4.3 or above and requires device with Bluetooth Low Energy (SDK's min Android SDK version is 9).

It allows for:

• beacon ranging (scans beacons and optionally filters them by their properties)
• beacon monitoring (monitors regions for those devices that have entered/exited a region)
• nearables (aka stickers) discovery (see quickstart)
• Eddystone scanning (see quickstart)
• beacon characteristic reading and writing (proximity UUID, major & minor values, broadcasting power, advertising interval), see [BeaconConnection] (http://estimote.github.io/Android-SDK/JavaDocs/com/estimote/sdk/connection/BeaconConnection.html) class and demos in the SDK

Learn more:

• Comprehensive JavaDoc documentation.
• Play with SDK Examples (includes scanning beacons, nearables, Eddystone beacons, connecting to Estimote beacons).
• Download Estimote app from Play Store to see what SDK is capable of.
• Check our Estimote Forums where you can post your questions and get answers.
• Estimote Community Portal

What is ranging?

Ranging allows apps to know the relative distance between a device and beacons. This can be very valuable – consider for example an indoor location app of a department store. The app can determine which department (such as footwear, clothing, accessories etc) you're closest by. Information about this proximity can be used within the app to show fitting guides or offer discounts.

As Bluetooth Low Energy ranging depends on detecting radio signals, results will vary depending on the placement of Estimote beacons and whether a user's mobile device is in-hand, in a bag or a pocket. Clear line of sight between a mobile device and a beacon will yield better results so it is recommended that Estimote beacons not be hidden between shelves.

To enjoy consistent ranging it is good practice to use the app in the foreground while the user is holding the device in-hand (which means the app is on and running).

Apps can use the startRanging method of the BeaconManager class to determine relative proximity of beacons in the region and can be updated when this distance changes. Ranging updates come every second to listeners registered with the setRangingListener method of the BeaconManager class. Ranging updates contain a list of currently found beacons. If a beacon goes out of range it will not be presented on this list.

Ranging is designed to be used for apps running in the foreground.

What is monitoring?

Region monitoring is a term used to describe a Bluetooth device's usage and detect when a user is in the vicinity of beacons. You can use this functionality to show alerts or provide contextually aware information as a user enters or exits a beacon region. Beacon regions are defined by the following beacon properties:

• proximity UUID: 128-bit unique identifier,
• major: 16-bit unsigned integer to differentiate between beacons within the same proximity UUID,
• minor: 16-bit unsigned integer to differentiate between beacons with the same proximity UUID and major value.

Note that all of these values are optional, meaning that a single region can encompass multiple beacons — which creates interesting use cases. Consider for example a department store that is identified by a particular proximity UUID and major value. Different sections of the store are differentiated further by a different minor value. An app can monitor region defined by their proximity UUID and major value to provide location-relevant information by distinguishing minor values.

Apps can use the startMonitoring method of the BeaconManager class to start monitoring regions. Monitoring updates come to listeners registered with the setMonitoringListener method of the BeaconsManager class.

Monitoring is designed to perform periodic scans in the background. By default it scans for 5 seconds and sleeps for 25 seconds. This means that it can take by default up to 30 seconds to detect entering or exiting a region. Default behaviour can be changed via BeaconManager#setBackgroundScanPeriod.

Installation

Note: SDK version 0.5 switched from jar distribution to aar archive. There is no longer need to change your AndroidManifest.xml as it is being done automatically.

Eclipse users: Mark Murphy on his blog explained how to use aar format in Eclipse.

Note about AAR Manifest Merger: SDK's AndroidManifest.xml will be automatically merged into your app. Right now it declared min SDK level 18. You can override this declaration as described here.

1. Create libs directory inside your project and copy there estimote-sdk.aar.
2. In your build.gradle add flatDir entry to your repositories

repositories {
  mavenCentral()
    flatDir {
      dirs 'libs'
    }
}

3. Add dependency to Estimote SDK. All needed permissions (BLUETOOTH, BLUETOOTH_ADMIN and INTERNET) and services will be merged from SDK's AndroidManifest.xml to your application's AndroidManifest.xml.

dependencies {
  compile(name:'estimote-sdk', ext:'aar')
}

4. Initialize Estimote SDK in your Application class if you are using Estimote Cloud.

//  App ID & App Token can be taken from App section of Estimote Cloud.
EstimoteSDK.initialize(applicationContext, appId, appToken);
// Optional, debug logging.
EstimoteSDK.enableDebugLogging(true);

Usage and demos

SDK Demos are located in Demos directory. You can easily build it with Gradle by typing gradlew installDebug (or gradlew.bat installDebug on Windows) in terminal when your device is connected to computer. If you use Android Studio you can just simply open build.gradle.

Demos include samples for ranging beacons, monitoring beacons, nearable discovery, calculating distance between beacon and the device and also changing minor value of the beacon.

Quick start for beacon ranging

  private static final String ESTIMOTE_PROXIMITY_UUID = "B9407F30-F5F8-466E-AFF9-25556B57FE6D";
  private static final Region ALL_ESTIMOTE_BEACONS = new Region("regionId", ESTIMOTE_PROXIMITY_UUID, null, null);

  private BeaconManager beaconManager = new BeaconManager(context);

  // Should be invoked in #onCreate.
  beaconManager.setRangingListener(new BeaconManager.RangingListener() {
    @Override public void onBeaconsDiscovered(Region region, List<Beacon> beacons) {
      Log.d(TAG, "Ranged beacons: " + beacons);
    }
  });

  // Should be invoked in #onStart.
  beaconManager.connect(new BeaconManager.ServiceReadyCallback() {
    @Override public void onServiceReady() {
      try {
        beaconManager.startRanging(ALL_ESTIMOTE_BEACONS);
      } catch (RemoteException e) {
        Log.e(TAG, "Cannot start ranging", e);
      }
    }
  });

  // Should be invoked in #onStop.
  try {
    beaconManager.stopRanging(ALL_ESTIMOTE_BEACONS);
  } catch (RemoteException e) {
    Log.e(TAG, "Cannot stop but it does not matter now", e);
  }

  // When no longer needed. Should be invoked in #onDestroy.
  beaconManager.disconnect();

Quick start for nearables discovery

  private BeaconManager beaconManager = new BeaconManager(context);
  private String scanId;

  // Should be invoked in #onCreate.
  beaconManager.setNearableListener(new BeaconManager.NearableListener() {
    @Override public void onNearablesDiscovered(List<Nearable> nearables) {
      Log.d(TAG, "Discovered nearables: " + nearables);
    }
  });

  // Should be invoked in #onStart.
  beaconManager.connect(new BeaconManager.ServiceReadyCallback() {
    @Override public void onServiceReady() {
      scanId = beaconManager.startNearableDiscovery();
    }
  });

  // Should be invoked in #onStop.
  beaconManager.stopNearableDiscovery(scanId);

  // When no longer needed. Should be invoked in #onDestroy.
  beaconManager.disconnect();

Quick start for Eddystone

Eddystone is an open protocol BLE protocol from Google. Estimote Beacons can broadcast the Eddystone packet.

With Estimote SDK you can:

• find nearby Eddystone beacons (BeaconManager#startEddystoneScanning)
• configure Eddystone ralated properties:
  • URL property of Eddystone-URL (see BeaconConnection#eddystoneUrl)
  • namespace & instance properties of Eddystone-UID (see BeaconConnection#eddystoneNamepsace, BeaconConnection#eddystoneInstance)
• configure broadcasting scheme of beacon to Estimote Default, Eddystone-UID or Eddystone-URL (see BeaconConnection#broadcastingScheme)

SDK Examples contains Eddystone related samples.

Note that you can play with Estimote Beacons broadcasting the Eddystone packet and change their configuration via Estimote app on Google Play.

In order to start playing with Eddystone you need to update firmware of your existing Estimote beacons to 3.1.1. Easiest way is through Estimote app on Google Play. Than you can change broadcasting scheme on your beacon to Eddystone-URL or Eddystone-UID.

Following code snippet shows you how you can start discovering nearby Estimote beacons broadcasting Eddystone packet.

  private BeaconManager beaconManager = new BeaconManager(context);
  private String scanId;

  // Should be invoked in #onCreate.
  beaconManager.setEddystoneListener(new BeaconManager.EddystoneListener() {
    @Override public void onEddystonesFound(List<Eddystone> eddystones) {
      Log.d(TAG, "Nearby Eddystone beacons: " + eddystones);
    }
  });

  // Should be invoked in #onStart.
  beaconManager.connect(new BeaconManager.ServiceReadyCallback() {
    @Override public void onServiceReady() {
      scanId = beaconManager.startEddystoneScanning();
    }
  });

  // Should be invoked in #onStop.
  beaconManager.stopEddystoneScanning(scanId);

  // When no longer needed. Should be invoked in #onDestroy.
  beaconManager.disconnect();

FAQ

There is Estimote SDK FAQ on wiki. There is also Estimote SDK for Android forum where you can post your questions.

Changelog

To see what has changed in recent versions of Estimote SDK for Android, see the CHANGELOG.