GettingStarted

Introduction

To run mqtt-spy you need to have an appropriate version of Java, either installed or present on your operating system.

The latest version of mqtt-spy requires at least Java Runtime Environment (JRE) 8 Update 40. You can download it from the Oracle website. At the point of writing this Wiki page the best place to get it from is:

http://www.oracle.com/technetwork/java/javase/downloads/jre8-downloads-2133155.html

You can also use OpenJDK version 8, but you need to remember to install JavaFX packages as well. Otherwise it probably won't work and you're going to get "Error: Could not find or load main class pl.baczkowicz.mqttspy.Main". Also see Frequently Asked Questions wiki page.

To check the version of your installed Java use the following command:

java -version

If it says the version is 1.8.0_40 or later, you are ready to go - see the 'Running with the default Java' section.

If you have an older version, and you want to keep it as the default one, or you don't want to install Java, then - see the 'Running with custom Java version' section.

For instructions in French see the 'Espionner des thèmes MQTT' blog post kindly written by Bernard - http://blogs.media-tips.com/bernard.opic/2015/01/25/espionner-des-themes-mqtt/.

Download

Make sure you download the latest version of mqtt-spy from https://github.com/eclipse/paho.mqtt-spy/wiki/Downloads.

Running with default Java

Ways of starting mqtt-spy

• Double click on the jar
• Start from the command line

Starting mqtt-spy by double clicking on the jar (Windows/Linux)

You can simply double click on the mqtt-spy jar file to start it, assuming a double click on a jar file means 'start with Java 8'.

If this doesn't work, try starting it from the command line.

Starting mqtt-spy from the command line (Windows/Linux)

To start mqtt-spy from the command line, using the default version of Java, use the following command:

java -jar mqtt-spy-0.3.0-jar-with-dependencies.jar

Note: this assumes your jar file is in your current folder/directory from which you are running this command.

Note: the above version of mqtt-spy is only an example of how to run it - always use the latest from the Downloads section

Running with custom Java version

If for any reason you don't want to install Java 8 as your default Java, just download the tar.gz distribution from the provided link (see the Introduction).

Unpack it to your chosen location (in the following example it is a JDK unpacked to /usr/local/java/).

Then, run the java executable (found in the bin directory of the JRE) with the mqtt-spy jar.

Windows

Note: versions of Java and mqtt-spy shown below are only examples - always use the latest versions

"C:\Program Files\Java\jdk1.8.0_51\bin\java.exe" -jar mqtt-spy-0.3.0-jar-with-dependencies.jar

or

"C:\Program Files\Java\jdk1.8.0_51\bin\java.exe" -cp mqtt-spy-0.3.0-jar-with-dependencies.jar pl.baczkowicz.mqttspy.Main

Create shortcut / Pin to Start Menu

You can also create a Windows shortcut, which you can then pin to your "Start Menu" or "Taskbar". Use one of the above commands as the "Target" and the folder where your mqtt-spy jar file is as the "Start in".

Linux

Note: versions of Java and mqtt-spy shown below are only examples - always use the latest versions

/usr/local/java/jdk1.8.0_51/jre/bin/java -jar mqtt-spy-0.3.0-jar-with-dependencies.jar

Running with additional JARs on the classpath

If you need additional packages on the classpath (for instance to do custom encoding/decoding), you can start mqtt-spy with additional JARs (or other resources) on the classpath.

Below are examples of how to do it in Windows and Linux. Make sure you run this from the directory where your mqtt-spy jar file and the lib folder are.

Windows (with default Java)

Note: versions of Java and mqtt-spy shown below are only examples - always use the latest versions

java -cp mqtt-spy-0.3.0-jar-with-dependencies.jar;lib\xmlsec-1.5.5.jar;lib\commons-logging-1.1.1.jar
pl.baczkowicz.mqttspy.Main

Linux (with custom Java)

Note: versions of Java and mqtt-spy shown below are only examples - always use the latest versions

/usr/local/java/jre1.8.0_51/bin/java -cp
"mqtt-spy-0.3.0-jar-with-dependencies.jar:lib/xmlsec-1.5.5.jar:lib/commons-logging-1.1.1.jar"
pl.baczkowicz.mqttspy.Main

Specifying a custom location for the configuration file

To start mqtt-spy with a custom location for the configuration file, use the "--configuration" parameter (as shown in the example below).

Windows (with default Java)

Note: versions of Java and mqtt-spy shown below are only examples - always use the latest versions

java -cp mqtt-spy-0.3.0-jar-with-dependencies.jar pl.baczkowicz.mqttspy.Main --configuration="C:\mqtt-spy\labs.xml"

First steps after start-up

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

The first message is indicating that no configuration file has been found - simply click on this message to resolve this. A pop-up will appear asking you what to do:

At this point, either best to create a configuration file with sample content, or an empty one.

If you haven't decided to have sample content, either click on the message saying that you haven't got any connections configured, or from the main menu select 'Connections -> New connection'. Once you have put all the broker details, hit 'Apply' to save this to the configuration file.

Alternatively, from the main menu select 'Connections -> Manage connections' to revise the sample configuration.

When ready, either click on 'Open connection' in the 'Manage connections' window, or on the control panel click the connection name to open/connect.

If all is fine, your connection tab will go green indicating you have successfully connected to an MQTT broker!

If still having problems...

If the above doesn't work, get in touch on Twitter (@mqtt_spy) or put a comment below.