iotf-android

IBM IoT foundation Messaging library for Android

License	License The MIT License
GroupId	GroupId fr.bmartel
ArtifactId	ArtifactId iotf-library
Last Version	Last Version 0.3
Release Date	Release Date Jan 12, 2017
Type	Type aar
Description	Description iotf-android IBM IoT foundation Messaging library for Android
Project URL	Project URL https://github.com/bertrandmartel/iotf-android
Source Code Management	Source Code Management https://github.com/bertrandmartel/iotf-android

Download iotf-library

Filename	Size
iotf-library-0.3.pom
iotf-library-0.3.aar	40 KB
iotf-library-0.3-sources.jar	28 KB
iotf-library-0.3-javadoc.jar	75 KB
Browse

How to add to project

Apache Maven

<!-- https://jarcasting.com/artifacts/fr.bmartel/iotf-library/ -->
<dependency>
    <groupId>fr.bmartel</groupId>
    <artifactId>iotf-library</artifactId>
    <version>0.3</version>
    <type>aar</type>
</dependency>

Gradle Groovy

// https://jarcasting.com/artifacts/fr.bmartel/iotf-library/
implementation 'fr.bmartel:iotf-library:0.3'

Gradle Kotlin

// https://jarcasting.com/artifacts/fr.bmartel/iotf-library/
implementation ("fr.bmartel:iotf-library:0.3")

Apache Buildr

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

Apache Ivy

<dependency org="fr.bmartel" name="iotf-library" rev="0.3">
  <artifact name="iotf-library" type="aar" />
</dependency>

Groovy Grape

@Grapes(
@Grab(group='fr.bmartel', module='iotf-library', version='0.3')
)

Scala SBT

libraryDependencies += "fr.bmartel" % "iotf-library" % "0.3"

Leiningen

[fr.bmartel/iotf-library "0.3"]

Dependencies

compile (4)

Group / Artifact	Type	Version
com.android.support » support-v4	jar	22.1.0
org.eclipse.paho : org.eclipse.paho.android.service	jar	1.0.3-SNAPSHOT
org.eclipse.paho : org.eclipse.paho.client.mqttv3	jar	1.0.3-SNAPSHOT
com.google.android.gms » play-services	jar	6.5.87

Project Modules

There are no modules declared in this project.

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();

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

API	description
subscribeDeviceEvents(String deviceType, String deviceId, String eventId)	subscribe to device events
subscribeDeviceCommands(String deviceType, String deviceId, String commandId)	subscribe to device commands
subscribeDeviceStatus(String deviceType, String deviceId)	subscribe to device status
subscribeApplicationStatus(String appId)	subscribe to application status

For Devices

API prototype	description
subscribeCommand(String commandId)	subscribe to command ID

For Gateways (Beta)

API	description
subscribeCommands(String deviceType, String deviceId, String commandId)	subscribe to device command ID

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

API	description
unsubscribeDeviceEvents(String deviceType, String deviceId, String eventId)	unsubscribe device events
unsubscribeDeviceCommands(String deviceType, String deviceId, String commandId)	unsubscribe device commands
unsubscribeDeviceStatus(String deviceType, String deviceId)	unsubscribe device status
unsubscribeApplicationStatus(String appId)	unsubscribe application status

For Devices

API	description
void unsubscribeCommand(String commandId)	unsubscribe command ID

For Gateways (Beta)

API prototype	description
unsubscribeCommands(String deviceType, String deviceId, String commandId)	subscribe to device command ID

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

API	description
publishDeviceEvents(String deviceType, String deviceId, String eventId, String message)	publish a device event on behalf of the device
publishDeviceCommands(String deviceType, String deviceId, String commandId, String message)	publish device commands

For Devices

API	description
publishEvent(String eventId, String message)	publish an event

For Gateway (Beta)

API	description
publishOwnEvents(String eventId, String message)	publish an event on behalf of the gateway itself
publishDeviceEvents(String deviceType, String deviceId, String eventId, String message)	publish an event on behalf of a device

Connection parameters

set QOS (default QosPolicy.QOS_POLICY_AT_MOST_ONCE)

mHandler.setQos(QosPolicy.QOS_POLICY_AT_MOST_ONCE);

possible values :

enum value	qos value
QOS_POLICY_AT_MOST_ONCE	0
QOS_POLICY_AT_LEAST_ONCE	1
QOS_POLICY_ONCE	2

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

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

Versions

Version
0.3 Jan 12, 2017

iotf-android

License

GroupId

ArtifactId

Last Version

Release Date

Type

Description

Project URL

Source Code Management

Download iotf-library

How to add to project

Dependencies

compile (4)

Project Modules

IoT Foundation for Android

Bluemix setup

Include into your project

Usage

Applications

Devices

Gateway (still in Beta)

MQTT callback

Connection / Disconnection

Subscribe

Unsubscribe

Publish

Connection parameters

Complete Application example

Library dependencies

IBM Messaging Documentation

References

External Libraries

License

Versions