Using the Android MQTT client sample

You can easily get a sample Android app exchanging messages using an MQTT server. Here we show you how. When you've mastered this, you can get on with including mobile messaging in your own Android applications.

Prerequisite

  • Get the right tools.
  • Setup an MQTT Server. It must support the MQTT version 3.1 protocol.
  • Clone the source code of org.eclipse.paho.mqtt.java via git. Run maven build: mvn clean install to build org.eclipse.paho.client.mqttv3-{VERSION}.jar and org.eclipse.paho.android.service-{VERSION}.jar

Building from source

The MQTT client sample Java™ app for Android uses a client library from the MQTT SDK, and exchanges messages with an MQTT server.

  • Import the org.eclipse.paho.android.service.sample app project into Eclipse.
  • Copy the org.eclipse.paho.client.mqttv3-{VERSION}.jar and org.eclipse.paho.android.service-{VERSION}.jar library into the libs folder in the Android project.
  • Make sure no compilation errors and then run as Android application. Or install and start the MQTT client sample Java app on an Android device. See the developer.android.com Running your app page.

Run the MQTT Android application

Use the MQTT Android application to connect to MQTT server, subscribe, and publish to a topic.

  • Open the MQTT sample application.

  • Connect to an MQTT server.

    • Click the plus sign (+) to open a new MQTT connection
    • Enter any unique identifier into the client ID field. Be patient, the keystrokes can be slow.
    • Enter the Server field into the IP address of your MQTT server. E.g. iot.eclipse.org
    • Enter the port of the MQTT connection. The default port number for a normal MQTT connection is 1883.
    • Click Connect. If the connection is successful, you see a Connecting message.

  • Subscribe to a topic.

    • Click the Connected message. The Connection Details window opens with the history listed:

    • Click the Subscribe tab, and enter a topic string.

    • Click the Subscribe action. A Subscribed message appears for a short time.
    • Click the History tab. The history now includes the subscription:

  • Now publish to the same topic.

    • Click the Publish tab, and enter the same topic string as you did for subscribing. Enter a message.

    • Click the Publish action. Two messages are displayed for a short time, Published followed by Subscribed. The publication is displayed in the status area (pull the separator bar down to open the status window).

    • Click the History tab to view the full history.

  • Disconnect the client instance.

    • Click the menu icon in the action bar. The MQTT client sample application adds a Disconnect button to the MQTT Connection Details window.
    • Click Disconnect. The connected status changes to disconnected:

  • Click Back to return to the list of sessions.

    • Click the plus sign (+) to start a new session.
    • Click the disconnected client to reconnect it.
    • Click Back to return to the launchpad.

  • Click the task button to list running apps. Locate the MQTT client app and swipe the icon off the screen to close it.

Congratulations!

If you built the sample app yourself, you are ready to start developing your own Android apps that call MQTT libraries to exchange messages. You can model your Android apps on the classes in this sample.