IoT Foundation for Android

IBM IoT foundation Messaging library for Android

Bluemix setup

To use this library, you should have a Bluemix account and setup the following :

• Internet of Things Foundation Starter application
• Internet of Things Foundation service
  The latter service should be bound to the application and your application should be running.

To find all your credentials and parameters necessary to build an Android IoT Foundation project go to dashboard in Internet of Things Foundation service

From there you can manage :

• creation of device that will give you : DEVICE_ID, DEVICE_TYPE and AUTHENTICATION_TOKEN
• creation of access token that will give you : API_KEY,API_TOKEN
• get organization id from the main page IOT_ORG
• In beta : creation of gateway that will give you : GATEWAY_TYPE, GATEWAY_ID and AUTHENTICATION_TOKEN

Include into your project

compile 'fr.bmartel:iotf-library:0.3'

Usage

Applications

• Application

AppHandler mHandler = new AppHandler(context, IOT_ORG, "MyApplicationID", API_KEY, API_TOKEN);

• Scalable Application

AppScalableHandler mHandler = new AppScalableHandler(context, IOT_ORG, "MyApplicationID", API_KEY, API_TOKEN);

ApplicationID is a user defined unique string identifier for the client.
ApplicationID cant be empty and cannot contain following characters :

• /
• :

Devices

DeviceHandler mHandler = new DeviceHandler(context, IOT_ORG, DEVICE_TYPE, DEVICE_ID, AUTHENTICATION_TOKEN);

Gateway (still in Beta)

GatewayHandler mHandler = new GatewayHandler(context, IOT_ORG, GATEWAY_TYPE, GATEWAY_ID, AUTHENTICATION_TOKEN);

MQTT callback

With MQTT callback, you get all events about connections success/failure, messages delivered/received :

mIotCallback = new IMessageCallback() {

    @Override
    public void connectionLost(Throwable cause) {
        // connection is lost
    }

    @Override
    public void messageArrived(String topic, MqttMessage mqttMessage) throws Exception {
        // a message has arrived
    }

    @Override
    public void deliveryComplete(IMqttDeliveryToken messageToken) {
        // a message has been delivered to server
    }

    @Override
    public void onConnectionSuccess() {
        // connection success
    }

    @Override
    public void onConnectionFailure() {
    	// connection failure
    }

    @Override
    public void onDisconnectionSuccess() {
    	// disconnection successfull
    }

    @Override
    public void onDisconnectionFailure() {
    	// disconnection has failed
    }
};

mHandler.addIotCallback(mIotCallback);

Connection / Disconnection

• Connect

mHandler.connect();

• Connect with SSL support

mHandler.setSSL(true);
mHandler.connect();

• Disconnect

mHandler.disconnect();

Subscribe

All subscription API have two version : one with boolean isRetained, QosPolicy qos, IMqttActionListener completionListener and one version without these parameters :

• For Applications and Scalable Applications

• For Devices

• For Gateways (Beta)

wildcard "+" can be used to match all type of a specific parameter

mHandler.subscribeDeviceEvents("+", "+", "+");

will subscribe to all deviceType / device ID / eventId

Unsubscribe

• For applications and Scalable Applications

• For Devices

• For Gateways (Beta)

wildcard "+" can be used to match all type of a specific parameter

mHandler.unsubscribeDeviceEvents("+", "+", "+");

will unsubscribe all deviceType / device ID / eventId

Publish

All subscription API have two version : one with QosPolicy qos, IMqttActionListener completionListener and one version without these parameters :

• For applications

• For Devices

• For Gateway (Beta)

Connection parameters

• set QOS (default QosPolicy.QOS_POLICY_AT_MOST_ONCE)

mHandler.setQos(QosPolicy.QOS_POLICY_AT_MOST_ONCE);

possible values :

• set keep alive in seconds (default 60s)

mHandler.setKeepAlive(60);

• set connection timeout in seconds (default 30s)

mHandler.setConnectionTimeout(30);

• set clean session (default false)

mHandler.setCleanSession(false);

Complete Application example

This example include an automatic reconnection mechanism when connection is lost.
This will also subscribe to all device events when connected to server :

private AppHandler mHandler;

private boolean exit = false;

private IMessageCallback mIotCallback;

@Override
protected void onCreate(Bundle savedInstanceState) {

    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_connect);

	mHandler = new AppHandler(this, BuildConfig.BLUEMIX_IOT_ORG, getPackageName(), BuildConfig.BLUEMIX_API_KEY, BuildConfig.BLUEMIX_API_TOKEN);

	mIotCallback = new IMessageCallback() {
	    @Override
	    public void connectionLost(Throwable cause) {
	        Log.i(TAG, "connection lost");
	        if (cause != null) {
	            Log.e(TAG, "connection lost : " + cause.getMessage());
	        }
	        if (!exit) {
	            Log.i(TAG, "trying to reconnect");
	            mHandler.connect();
	        } else {
	            Log.i(TAG, "not trying to reconnect");
	        }
	    }

	    @Override
	    public void messageArrived(String topic, MqttMessage mqttMessage) throws Exception {
	        Log.i(TAG, "messageArrived : " + topic + " : " + new String(mqttMessage.getPayload()));
	    }

	    @Override
	    public void deliveryComplete(IMqttDeliveryToken messageToken) {
	        try {
	            Log.i(TAG, "deliveryComplete : " + new String(messageToken.getMessage().getPayload()));
	        } catch (MqttException e) {
	            e.printStackTrace();
	        }
	    }

	    @Override
	    public void onConnectionSuccess() {
	        Log.i(TAG, "subscribe to device events ...");
	        mHandler.subscribeDeviceEvents("+", "+", "+");
	    }

	    @Override
	    public void onConnectionFailure() {
			// connection failure
	    }

	    @Override
	    public void onDisconnectionSuccess() {
	    	// disconnection successfull
	        if (exit) {
	            mHandler.removeCallback(mIotCallback);
	        }
	    }

	    @Override
	    public void onDisconnectionFailure() {
			// disconnection has failed
	    }
	};

	mHandler.addIotCallback(mIotCallback);

	mHandler.setSSL(true);
}

public void onResume() {
    super.onResume();
    Log.d(TAG, "connecting");
    mHandler.connect();
}

public void onPause() {
    exit = true;
    Log.d(TAG, "disconnecting");
    mHandler.disconnect();
    super.onPause();
}

Library dependencies

The following dependencies are included :

• com.google.android.gms:play-services:6.5.87
• com.android.support:support-v4:22.1.0
• org.eclipse.paho:org.eclipse.paho.client.mqttv3:1.0.3-SNAPSHOT

If you want to include one of theses libraries in your project, you can use an exclude directive as following :

compile 'com.google.android.gms:play-services:9.0.1'

compile ('fr.bmartel:iotf-android:0.3'){
   exclude group: 'com.google.android.gms'
}

Note that Security Provider will update when com.google.android.gms:play-services current version is deprecated or a new update is available

IBM Messaging Documentation

• https://github.com/ibm-messaging/iotf-rtd/blob/master/docs/getting_started/concepts.rst
• https://github.com/ibm-messaging/iotf-rtd/blob/master/docs/applications/mqtt.rst
• https://github.com/ibm-messaging/iotf-rtd/blob/master/docs/devices/mqtt.rst
• https://github.com/ibm-messaging/iotf-rtd/blob/master/docs/gateways/mqtt.rst

References

An Android starter kit implementing a MQTT Device client :

• https://github.com/ibm-messaging/iot-starter-for-android

External Libraries

• Eclipse Paho MQTT open source client

License

The MIT License (MIT) Copyright (c) 2016 Bertrand Martel