This post is meant to be a quick start guide to pub/sub with MQTT on the m2m.io platform. The example is in Java utilizing the Paho Java client.
Account Setup
The first step in connecting to the m2m.io MQTT broker is to setup an account on the platform. An account can be created by visiting the m2m.io Developer Portal at http://app.m2m.io and clicking on the “Sign Up” link.
After completing the registration page a confirmation link will be sent to the email address provided. Click on the link to activate your account.
A new account starts with 5 licenses. A license allows one unique device or application to connect and publish data. Uniqueness is determined by MQTT client ID. More on MQTT client IDs later in this post.
Paho Java MQTT Client
This example depends on the Paho Java MQTT client library. This code can be found on GitHub: https://github.com/eclipse/paho.mqtt.java.
Once you have obtained the client code build the Paho client by running the Ant build script in the client directory:
Johns-MacBook-Pro:paho johnrotach$ git clone https://github.com/eclipse/paho.mqtt.java.git
Cloning into 'paho.mqtt.java'...
remote: Counting objects: 521, done.
remote: Compressing objects: 100% (233/233), done.
remote: Total 521 (delta 211), reused 454 (delta 144)
Receiving objects: 100% (521/521), 255.80 KiB, done.
Resolving deltas: 100% (211/211), done.
Johns-MacBook-Pro:paho johnrotach$ cd paho.mqtt.java/org.eclipse.paho.client.mqttv3
Johns-MacBook-Pro:org.eclipse.paho.client.mqttv3 johnrotach$ ant
Buildfile: /Users/johnrotach/tmp/paho/paho.mqtt.java/org.eclipse.paho.client.mqttv3/build.xml
~~~~~~~~~~~~~~~~~~~~~~~~
trimmed build output
~~~~~~~~~~~~~~~~~~~~~~~~
package:
[jar] Building jar: /tmp/Mqttv3ClientOut/ship/org.eclipse.paho.client.mqttv3.jar
BUILD SUCCESSFUL
Total time: 2 seconds
Johns-MacBook-Pro:org.eclipse.paho.client.mqttv3 johnrotach$
The output destination of the build can be modified by changing the output.folder and ship.folder properties in the build.xml file. As you can see I left the default /tmp/Mqttv3ClientOut folder.
Project Setup
For this example I’ve chosen to use Eclipse as my IDE. The project is quite simple so it should be a snap if you prefer a different environment.
First I create a new Java Project.
Add Paho Jar to Build Path
After the project is created, edit the project’s Build Path to add the Paho MQTT Client jar generated in the build above.
I chose to add the library as an External Jar.
Get Main Source File
The example Java source code can be found in this gist:
https://gist.github.com/m2mIO-gister/5275324
This file can be copied into the src folder created by Eclipse when the new project was created. It can also be brought into the project by doing a File—>New—>Class operation in Eclipse and pasting the code contents into the new class via the editor.
Editing Java Source File
The source file has placeholders for the MQTT connection information:
static final String BROKER_URL = "tcp://q.m2m.io:1883";
static final String M2MIO_DOMAIN = "<Insert m2m.io domain here>";
static final String M2MIO_STUFF = "things";
static final String M2MIO_THING = "<Unique device ID>";
static final String M2MIO_USERNAME = "<m2m.io username>";
static final String M2MIO_PASSWORD_MD5 = "<m2m.io...password)>";
You will need to edit the file to add your info.
- Broker URL - this is setup for the m2m.io MQTT broker. No change is required.
- Domain - this is the domain to which your account belongs in the m2m.io platform. Your domain can be found on the Account page of the developer portal (http://app.m2m.io)
- Stuff - this is a logical grouping of your things (devices) in your domain. The default of “things” can be used for testing. In the future you may wish to change this to group your things (temperature sensors, server monitors, etc)
- Thing - this is a unique identifier for the thing connected to the MQTT broker. A device is a thing. An instance of a client running on a PC is a thing. Uniqueness here is required within your domain to distinguish between things. The example code also uses the THING string to build the MQTT client ID.
- Username - this is the email address you used to create an account on the m2m.io platform. Your username can be verified by using it to log into the m2m.io developer portal.
- Password - this is the password you used to create your account on the m2m.io platform. It is important to note that this is the MD5 sum of your password. An MD5 sum can be generated on OS X by typing md5 -s in Terminal. In Linux the command is echo -n | md5sum. There are various online tools that can also be used.
A running instance of this example client can be a publisher, a subscriber or both. By default, a publisher will publish 10 messages on the topic (domain)/(stuff)/(thing). A subscriber will subscribe on this same topic and print any incoming messages to the console. If both are enabled the client will publish messages, receive them from the broker and print them to the console.
static final Boolean subscriber = true;
static final Boolean publisher = true;
Run in Eclipse
After any syntax errors are resolved the client can be run inside of Eclipse. The following is a shot of the client running as both a publisher and subscriber.
Web Based MQTT Client
A web-based MQTT client can be found at http://mqtt.io. The same broker URL (q.m2m.io) and port (1883) are used.
The Options tab contains fields for username and password.
The following shot shows the MQTT messages sent in the above run of the client from within Eclipse.
The following screen shot shows running the client in Eclipse set as a subscriber and receiving a message sent from the web client.
Note that this web client uses websockets to display messages in real-time and will not run in older versions of Internet Explorer. Chrome, Firefox or Safari are recommended.
A Note On MQTT Payload Format
MQTT payloads sent through the m2m.io platform should be formatted as JSON objects. As an example, suppose we wish to send a message containing a status of “normal” and a widget count of 1131. The following should be sent:
{"status":"normal, "widgets":1131}
This format is required if the message content is to be stored in the m2m.io data store. The broker will pass a malformatted message on from a publisher to any subscribers, however that message will not be stored in the data store and can’t be accessed at a later time through the API.
Linux
The steps in this example were tested on Ubuntu Linux 12 in a terminal without issue. An IDE was not tested but should be quite simple to configure.
Windows
The steps in this example were tested on Windows 7 in a CMD window without issue. An IDE was not tested but should be quite simple to configure.
There Are Obvious Improvements
This example was meant to be as simple as possible to allow a quick start with MQTT on m2m.io with minimal dependencies. Obvious areas of improvements exist (ability to configure client ID and credentials outside of code, some type of JSON processing library e.g. GSON) but are purposely left out for simplicity.
To Be Continued
A diferentiating feature of the m2m.io platform is the ability to query any message published to the platform through a REST API. In a future blog post I’ll provide a simple example on programmatically querying history data or published messages.