Getting started with the MQTT client for Java on Android

You can install an MQTT client sample Java app for Android that exchanges messages with an MQTT server. The app uses a client library from the MQTT SDK from IBM®. You can either build the app yourself, or download a pre-built sample app.

1. Choose an MQTT server to which you can connect the client app.

   The server must support the MQTT version 3.1 protocol. All MQTT servers from IBM do this, including IBM WebSphere® MQ and IBM MessageSight. See Getting started with MQTT servers.

2. Get the right tools.

   Install a Java development kit (JDK) Version 6 or later. Because you are developing a Java app for Android, the JDK must come from Oracle. You can get the JDK from Java SE Downloads.

   You also need an Eclipse development environment. This must be Eclipse 3.6.2 (Helios) or greater. Eclipse must have a Java compiler level of at least 6, to match your JDK. You can get all this from the Eclipse Foundation.

   Finally, you need the Android SDK. You can get this from Get the Android SDK.

3. Download the Mobile Messaging and M2M Client Pack and install the MQTT SDK.
   There is no installation program, you just expand the downloaded file.

   1. Download the Mobile Messaging and M2M Client Pack.
   2. Create a folder where you are going to install the SDK.

      You might want to name the folder MQTT. The path to this folder is referred to here as sdkroot.

   3. Expand the compressed Mobile Messaging and M2M Client Pack file contents into sdkroot. The expansion creates a directory tree that starts at sdkroot\SDK.
4. Optional: Build the mqttExerciser sample app for Android.

   Configure the Eclipse and Android tools, and import and build the mqttExerciser project from the MQTT SDK.

   Note: If you do not want to do this right now, you can use the pre-built sample app that is available as file mqttExerciser.apk in the sdkroot\SDK\clients\android\samples\apks folder of the MQTT SDK.
   1. Start the Eclipse development environment with the JRE from the JDK.

      eclipse -vm "JRE path"

   2. Select and install a set of packages and platforms from the Android SDK.
      See Adding Platforms and Packages for the list of platforms and packages that Google recommends.

      Note: The SDK platform must be Android API level 16 or later. With earlier API levels, the project cannot be compiled successfully.
   3. Add the Android Development Tools (ADT) plug-in to Eclipse.
   4. Import the sample mqttExerciser app project into Eclipse, and fix errors.
      1. Import the sample app project from the MQTT SDK, in the path sdkroot\SDK\clients\android\samples\mqttExerciser.

         The Problems view lists many build errors. You resolve the build errors in the next few steps.

      2. Copy the org.eclipse.paho.client.mqttv3.jar library into the libs folder in the Android project. For example, on Windows, this is under the sdkroot\SDK\clients\java folder. A File Operation window is displayed. Accept the Copy files selection then click OK.
      3. Right-click the project folder, com.ibm.msg.android; click Android tools... > Add Support Library.... Read and accept the license terms, then click Install.
      4. Right-click the project folder, com.ibm.msg.android; click Android tools... > Fix Project Properties.
      5. If the workspace still has about 84 errors, referring to overriding a super class method, the compiler compliance level is probably set to 1.5 or lower. Android SDK version 16 expects the compiler compliance level to be no greater than 1.5. To fix the remaining errors, complete the following steps:
         1. Check and (if necessary) update your Android SDK and the corresponding Eclipse plugins to Android SDK version 17.
         2. Right-click the com.ibm.msg.android project folder, then select Properties > Java Compiler. Check the Compiler compliance level, set it to at least 1.6, then rebuild the workspace.

   The project builds, with some warnings, and no errors.

5. Install and start the MQTT client sample Java app on an Android device.

   See the developer.android.com page Running your app.

   If you built the app yourself as an Eclipse project, you can start the app from Eclipse.

   If you have the application package (APK) file mqttExerciser.apk, you can install it outside of Eclipse by using the Android Debug Bridge (ADB) install command. This command takes the location of the APK file as an argument. If you are using the pre-built sample app, the location is sdkroot\SDK\clients\android\samples\apks\mqttExerciser.apk.

6. Use the mqttExerciser sample app for Android to connect, subscribe, and publish to a topic.
   1. Open the MQTT client sample Java app for Android.
      This window is open in your Android device:

      
   2. Connect to an MQTT server.
      1. Click the + sign to open a new MQTT connection.
         
      2. Enter any unique identifier into the client ID field. Be patient, the keystrokes can be slow.
      3. Enter into the Server field the IP address of your MQTT server.

         This is the server that you chose in the first main step. The IP address must not be 127.0.0.1

      4. Enter the port number of the MQTT connection.

         The default port number for a normal MQTT connection is 1883.

         
      5. Click Connect.
         If the connection is successful, you see a Connecting message followed by this window:

         
   3. Subscribe to a topic.
      1. Click the Connected message.
         The Connection Details window opens with the history listed:

         
      2. Click the Subscribe tab, and enter a topic string.
         
      3. Click the Subscribe action.

         A Subscribed message appears for a short time.

      4. Click the History tab.
         The history now includes the subscription:

         
   4. Now publish to the same topic.
      1. Click the Publish tab, and enter the same topic string as you did for subscribing. Enter a message.
         
      2. 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).

         
      3. Click the History tab to view the full history.
         
   5. Disconnect the client instance.
      1. Click the menu icon in the action bar.

         The MQTT client sample Java app for Android adds a Disconnect button to the MQTT Connection Details window.

         
      2. Click Disconnect.
         The connected status changes to disconnected:

         
   6. Click Back to return to the list of MQTT client sample Java app sessions.
      

      • Click the plus sign to start a new MQTT client sample Java app session.
      • Click the disconnected client to reconnect it.
      • Click Back to return to the launchpad.
   7. Click the task button to list running apps. Locate the MQTT client sample Java app. Swipe the icon off the screen to close it.