SDK for building device driver to run on Android platforms.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

Device SDK for Android

This is an SDK for developing MODE device driver on Android.

Download MIT License


This SDK is for anyone implementing MODE device drivers on Android. It contains a library for the device to communicate with the MODE cloud, and a sample program that shows how the library can be used in a typical use case.

If you want to make an app on Android instead of device driver, please refer to the MODE Android SDK.


This SDK works on Android API level 16 and up. The library depends on Jackson, Java-WebSocket and android-async-http. See more details in build.gradle.


Device SDK for Android is available through the JCenter Maven repo. To install, simply add the following line to your app's build.gradle file:

dependencies {
   compile 'com.tinkermode:androiddevice:1.1.0'

(Replace 1.1.0 with the latest version number.)

Usage Examples

The SDK can do three things:

  • Turn on/off claim mode.
  • Trigger events.
  • Listen to commands.

To turn on/off claim mode, instantiate a MODEDevice object. Then call the interface as follows:

  MODEDevice modeDevice = new MODEDevice(deviceId, apiKey);
  modeDevice.EnableClaimMode(this, 30, true, new MODEDevice.Completion<MODEData.Device>() {
            public void done(MODEData.Device ret, Throwable err) {
                if (err != null) {
                    // Handle error
                } else {
                  // You can get ret.claimExiprationTime here.

For triggering events, pass event type and parameters with a hash map as follows:

  final HashMap<String, Object> params = new HashMap<>();
  params.put("latitude", gpsTracker.getLatitude());
  params.put("longtitude", gpsTracker.getLongitude());
  modeDevice.TriggerEvent(getApplicationContext(), "location", params, new MODEDevice.CompletionError() {
            public void error(Throwable err) {
                if (err != null) {
                    // Handle error

You should create a MODEDeviceService object when you want to listen to commands. The object has to be kept alive while the device wants to keep listening. So you may want to instantiate it inside a service.

  final android.os.Handler handler = new android.os.Handler();
  MODECommandListener listener = new MODECommandListener(deviceId, apiKey) {
    public void didReceive(MODEData.Command command) { Runnable() {
        public void run() {
          // Call UI-related APIs

MODECommandListener.didReceive() is called in a different thread from the main thread. So you may need to use android.os.Handler to call APIs from the callback which requires a looper.

Sample Program

The source code contains a demo program under the app folder. It keeps track of GPS location and sends events with location information every minute. Also it returns the location information when it receives a query_location command.

Before you run your program, you need to set up a Project and an App on the MODE Developer Console. If you are not familiar with the Developer Console, please read our documentation first.

Please pick a device instance and get Device ID and Device API Key from the MODE console. Locate the following lines in

    static final int deviceId = 1234;
    static final String apiKey = "xxxx";

Change the values of deviceId and apiKey according to your device settings. Build the program and run it in the Android simulator or your Android hardware. Please make sure your Android hardware is turned on with GPS location functionality and grants the sample program access to the location service.

Once the program launches, please launch the App Simulator on the MODE console. Add the device to your home under your user account. If you are not sure how to claim a device into a home, please refer to this tutorial.

Once the device is claimed, you should see events coming from the device to the App Simulator periodically as follows:

Location event

Also, you can send commands from App Simulator to the device and query its current location. To do that, choose your device from the Target drop-down menu. Enter query_location in the Action field as follows:

Location command

Note that the target device ID will be different from yours. Click the SEND COMMAND button. You will receive a notification on your Android device/simulator, and you will receive the location information as an event on the App Simulator.

Copyright and License

Code and documentation copyright 2015 Mode, Inc. Released under the MIT license.