Connecting to Thingstream using MQTT Spy

Click the Paho MQTT Spy Download button, then from the github page select and download mqtt-spy-1.0.0.jar from the Assets section. Alternatively, go direct to the GitHub website.

Running mqtt-spy

Once downloaded mqtt-spy can be started by double clicking on the jar file.

Alternatively, mqtt-spy can be started from the command line, using the following command:

java -jar mqtt-spy-1.0.0.jar

Windows users may want to create a shortcut to the jar file and copy it to: 

C:\ProgramData\Microsoft\Windows\Start Menu\Programs\MQTTSpy

Then click on the Start menu, find MQTTSpy in you apps list, right click on it and pin it to Start.

First Steps

Before you start using mqtt-spy you'll need to have an active IP thing within Thingstream. 

Creating a new Thingstream IP thing

In the Thing directory, click the ADD dropdown and select New Thing.

A new entry at the top of your Thing table will have been created. You'll notice that it's Type is set to IP thing. When you create new Things (i.e. MQTT clients) they'll all be of type IP thing so you can easily tell what they are. Other types you may see here are Button (which is for Thingstream button devices) and SIM (for devices connected via a Thingstream SIM card). Other devices will be appear automatically in your Things directory when you purchase them or activate them using an Activation Code. 

Note: You CANNOT connect to Thingstream via MQTT using the ID of a button. You MUST use creds from an IP thing for this.

Once you have an IP thing it's a good idea to give this new device a name and some tags so you can easily find it in the future. For example, if you're going to use this client in mqtt-spy, then you could call it "mqtt-spy". To set the name or add tags, click the +name or +tags link.

Thingstream mqtt-spy connection configuration file

For ease of use you can download a mqtt-spy connection configuration file for your IP things from within Thingstream. For single IP things, Click the overflow menu (ellipses icon on the right hand side of the row) and select Show Credentials.

In the Credentials modal, on the MQTT tab, you will see a link to download a mqtt-spy configuration (xml) file for this thing. Click the link to download the file.

To create a configuration file for multiple things, select the checkboxes of all the IP things you want to configure in the Thing Directory. Then from the Actions dropdown select MQTT Spy Config.

Loading connection configuration file into mqtt-spy

Now you have generated a connection configuration file you can load this into mqtt-spy.

When you start your mqtt-spy for the first time, you will see a screen similar to this:

Click the top panel, labeled "No configuration file found". In the Configuration file not found modal select the Copy existing mqtt-spy configuration file option.

In the file browser window, choose the XML configuration file you downloaded from Thingstream.

Making a connection

Once the configuration file has been loaded you should now see your Thingstream connections listed in the connections section of the Control panel. The connection will have the name of thing given in Thingstream plus it's deviceId (appended in case it has no name or duplicated name).

In the second panel, click on the grey Open... button with the name of your connection to open and create a new tab for this connection.

Note: The button label will change from "Open ..." to "Connect to ...". Click the button again to make the connection.

The new tab should highlight green to signify a successful connection has been made.

You can also verify a successful connection by going to the Thingstream portal. Choose Events in the Thingstream sidebar to open the Domain Events page, from here you should see an entry indicating that your MQTT client has connected.

Simple subscription

Now we have a connection, let's look at how we receive messages. 

To create a subscription click on the mqtt-spy tab then click the New folder tab in the Subscriptions and received messages section.

At this point, you may want to enable the detailed perspective, this will enable you to choose additional functionality such as QOS. Select Window from the ring menu, then Change perspective, followed by Detailed.

In the Topic Filter modal:

• Enter the topic of interest, this can include wildcards like + or #. For example, if we wanted to listen to publish events of all buttons we could enter "device/+/publish" or we could listen to ALL topic by entering "#"

Once the topic is entered click the Subscribe button. 

A new tab for this subscription should now be created. From within this tab you will see all received messages that match this subscription.

Simple publication

You could generate a publication event by pressing your Thingstream button, you should see the payload appear in your "device/+/publish" subscription. Alternatively, you could publish a message through mqtt-spy.

In the Publish message section enter the topic you wish to publish to and the data you wish to publish, e.g:

• Topic: device/test/publish

• Data: {"hello":"world"}

Select the Publish button to publish the message to the given topic.

In the above example, you should see the publication in your "device/+/publish" subscription.