Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
158 lines (97 sloc) 7.12 KB

MODE-AndroidSDK

Download MIT License

Overview

MODE-AndroidSDK provides a wrapper for the MODE cloud API and handles the data objects connecting Android apps, devices and Smart Modules.

With this SDK, you can implement Android apps for your MODE project with ease.

Requirements

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.

Installation

MODE-AndrolidSDK 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:modeapp:1.1.0'
}

(Replace 1.1.0 with the latest version number.)

Classes

All classes are under the com.tinkermode package.

MODEApp

ModeApp defines the API wrapper class that interacts with the MODE cloud service. Each method corresponds to a MODE cloud API endpoint.

All methods are asynchronous, so you need to pass in a callback class object, either of class Completion<T> or CompletionError. Whenever an error happens, Error has a non-null value. Otherwise it means the call was successful.

The callback block is called in the main GUI thread by default. So you can call other UI-related APIs from the callback. If you want to change the behavior, please uncomment "super(true);" in the ResponseHandler constructor.

See the comments in MODEApp.java for detailed documentation on the class methods.

MODEData

ModeData defines the data classes, each corresponding to a JSON schema defined by MODE. A JSON object is parsed and each of its properties is stored as the expected data type. One exception is eventData in DeviceEvent. It is of type HasMap<String, Object>, as its actual structure is determined by developers.

MODEEventListener

MODEEventListener is a class for maintaining a WebSocket connection to the MODE cloud and receiving events delivered by MODE. Do not delete the object while your app is waiting for events.

When you want to close the WebSocket connection and recreate another session, please call the stopListenToEvents() method first. Otherwise it would keep trying to reconnect until the object is trashed by Java's GC.

Usage Example

The following is a code snippet that listens to events. The sample code doesn't check for errors, so make sure you add more error checking if you want to reuse the code.

You need to define a project on the MODE Developer Console. You also need to define an app for your project. For detailed instructions on setting up a MODE project, see the Getting Started tutorial. Here we assume projectId is 1234 and appId is SampleApp1

// You have to trigger somewhere with button or menu.
MODEAppAPI.initiateAuthenticationWithSMS(getApplicationContext(), 1234, "YOUR PHONE NUMBER",
  new MODEApp.Completion<MODEData.SMSMessageReceipt>() {
    @Override
    public void done(MODEData.SMSMessageReceipt ret, Error e) {
      if (e != null) {
        // Error handling
      } else {
        // Succeeded!
      }
    }
  });

You will get your verification code via SMS. In the following code snippet, replace CODE VIA SMS with this code. Now your app can listen to the events coming from devices or Smart Modules.

MODEEventListener listener; // Maybe you should define this as property in the class to keep the object alive.

if (listner != null) {
  // Please make sure the previous session is killed.
  listener.stopListenToEvents();
  listner = null;
}

MODEAppAPI.authenticateWithCode(1234, "YOUR PHONE NUMBER", "SampleApp1", "CODE VIA SMS",
    new MODEApp.Completion<MODEData.ClientAuthentication>() {

      @Override
      public void done(MODEData.ClientAuthentication auth, Error e) {

        if (e != null) {
          // Error handling
        } else {
          // Succeeded to authentication
          listner = new MODEEventListener(auth) { 
            @Override
            public void didReceive(MODEData.DeviceEvent event) {
              processEvent(event);
            }
          };

          listener.startListenToEvents();
        }
      }
});

MODEEventListener.didReceive() is called in a different thread from the main GUI thread. So you may need to use android.os.Hanlder as follows to call UI-related APIs from the callback.

final android.os.Handler notifyHandler = new android.os.Handler();

void processEvent(MODEData.DeviceEvent event) {
  notifyHandler.post(new Runnable() {
    @Override
    public void run() {
      // Call UI-related APIs
      notifyDataSetChanged();
    }
  });

}

Example App

Also included with this SDK is an example app called Lumos. It is a simple controller app for a smart light system.

Before you run your app, 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.

Build the app and run it in the Android simulator or your Android machine. You should see the following screen when the app launches:

Lumos screen

Find your Project ID on the console of sample project. Type the Project Id in the text field and press arrow button at the top left corner. Then you should see the following launch screen:

Lumos screen

If you want to change the Project ID, you can press the 'Configure Project' link and jump to the project setting activity again. For full instructions on building an iOS app for your MODE project, see this tutorial.

The App ID is fixed as controller_app in DataHolder.java. controller_app is already predefined in the Sample project. Please replace it if you want to assign other App ID and rebuild Lumos on Android Studio.

  // You would need to setup appId according to your App settings.
  // The sample project pregenerates "controller_app" App. So you don't have to change the project
  // if you use it as it is.
  // Please see more detail (http://dev.tinkermode.com/tutorials/getting_started.html) to get them.
  public static final String appId = "controller_app";

Author

Naoki Takano, honten@tinkermode.com

License

MODE-AndroidSDK is available under the MIT license. See the LICENSE file for more info.