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
Start with Android tutorial for monitoring & ranging beacons.
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
iBeacon allows for two basic interactions between apps and individual beacons or groups of beacons called regions:
- Region monitoring: actions triggered on entering/exiting region’s range; works in the foreground, background, and even when the app is killed.
- Ranging: actions triggered based on proximity to a beacon; works only in the foreground
Learn more about beacon ranging and monitoring
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.
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
.
Estimote Android SDK is available on Maven Central. Declare in your Gradle's build.gradle
dependency to this library.
dependencies {
compile 'com.estimote:sdk:0.8.8@aar'
}
Initialize Estimote SDK in your Application class.
// App ID & App Token can be taken from App section of Estimote Cloud.
EstimoteSDK.initialize(applicationContext, appId, appToken);
// Optional, debug logging.
EstimoteSDK.enableDebugLogging(true);
Eclipse users: Mark Murphy on his blog explained how to use aar
format in Eclipse.
- Create
libs
directory inside your project and copy there estimote-sdk.aar. - In your
build.gradle
addflatDir
entry to your repositories
repositories {
mavenCentral()
flatDir {
dirs 'libs'
}
}
- Add dependency to Estimote SDK. All needed permissions (
BLUETOOTH
,BLUETOOTH_ADMIN
andINTERNET
) and services will be merged from SDK'sAndroidManifest.xml
to your application'sAndroidManifest.xml
.
dependencies {
compile(name:'estimote-sdk', ext:'aar')
}
- 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);
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.
Android tutorial is available on Estimote Developer Docs. Tutorial is divided into three parts:
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();
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
(seeBeaconConnection#eddystoneUrl
) - namespace & instance properties of
Eddystone-UID
(seeBeaconConnection#eddystoneNamepsace
,BeaconConnection#eddystoneInstance
)
- URL property of
- configure broadcasting scheme of beacon to
Estimote Default
,Eddystone-UID
orEddystone-URL
(seeBeaconConnection#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. Then 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();
There is Estimote SDK FAQ on wiki. There is also Estimote SDK for Android forum where you can post your questions.
To see what has changed in recent versions of Estimote SDK for Android, see the CHANGELOG.