Building your first native Android mobile messaging app
You can easily get a sample Android app exchanging messages with 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.
Before you begin
- In a hurry? You can skip the building bit and install our pre-built sample into an Android phone or tablet.
- Have you got the right stuff? You’ll be using a client library to develop your app - for supported MQTT client platforms, see Client requirements.
- Have you got a firewall on your client? You’ll need to make sure MQTT traffic can get through.
- Have you got the right version of Android? The MQTT client sample app works on Ice Cream Sandwich (Android 4.0) and up.
About this task
The MQTT client sample Java™ app for Android is called
mqttExerciser. This app uses a client library from the MQTT SDK, and exchanges messages with an MQTT server.
You can either build the sample app yourself then export it from Eclipse as mqttExerciser.apk, or use the pre-built sample app that is available as file mqttExerciser.apk in the sdkroot\SDK\clients\android\samples\apks folder of the IBM Messaging Telemetry Clients SupportPac. If you choose to build the app yourself, the development environment that you build is tailored to include mobile messaging into apps for Android. This should help you when you begin to include mobile messaging in your own apps.
- 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 MQ and IBM MessageSight. See Servers for Mobile Messaging & M2M.
- 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 Eclipse for Mobile Developers.
Finally, you need the Android SDK. You can get this from Get the Android SDK.
- Download the IBM Messaging Telemetry Clients SupportPac and install the MQTT SDK.
There is no installation program, you just expand the downloaded file.
- Download the IBM Messaging Telemetry Clients SupportPac, or download the clients and libraries under an open source license from the Eclipse Paho project.
- 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.
- Expand the compressed IBM Messaging Telemetry Clients SupportPac file contents into sdkroot. The expansion creates a directory tree that starts at sdkroot\SDK.
- 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.
- Start the Eclipse development environment with the JRE from the JDK.
eclipse -vm "JRE path"
- 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
Note: The SDK platform must be Android API level 16 or later. With earlier API levels, the project cannot be compiled successfully.
- Add the Android Development Tools (ADT) plug-in to Eclipse.
- Import the sample mqttExerciser app project into Eclipse, and fix errors.
- 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. Don't panic. You resolve the build errors in the next few steps.
- 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.
- Right-click the project folder, com.ibm.msg.android; click . Read and accept the license terms, then click Install.
- Right-click the project folder, com.ibm.msg.android; click .
- 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:
- Check and (if necessary) update your Android SDK and the corresponding Eclipse plugins to Android SDK version 17.
- Right-click the com.ibm.msg.android project folder, then select . 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.
- 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.
- Use the mqttExerciser sample app for Android to connect, subscribe, and publish to a topic.
- Open the MQTT client sample Java app for Android.
This window is open in your Android device:
- Connect to an MQTT server.
- Click the + sign to open a new MQTT connection.
- Enter any unique identifier into the client ID field. Be patient, the keystrokes can be slow.
- 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
- Enter the port number 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 followed by this window:
- 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.
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 Java app for Android 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 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.
- Click the task button to list running apps. Locate the MQTT client sample Java app. Swipe the icon off the screen to close it.
What to do next
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 mqttExerciser. To study the sample, generate the Javadoc for the classes in com.ibm.msg.android and com.ibm.msg.android.service in the mqttExerciser project.