MQTT.fx: A Messaging Swiss Army Knife
What is MQTT.fx?
MQTT.fx is a cross-platform (Windows, Mac, Linux) tool that is very useful for testing and debugging your MQTT broker and topics. It is developed by Jens Deters
It is a fully functional Pub/Sub client with additional tools like scripted interactions. If you are new to the world of MQTT check out our introduction in What is MQTT?
My favourite use is that it can quickly discover all topics passing through your broker. This is especially useful when you need to discover unknown topics used by tools or projects where you don’t have control over the topic definition.
Download and Setup
The packages can be downloaded from http://mqttfx.org/
As each operating system has its own install routine I won’t go through that here. Once installed open the program to bring up the main window
Click the gear icon near the Connect button to go to the broker setup page. Sometimes the program has a default broker configured so you need to click the + symbol in the bottom left to configure a new connection.
- Profile Name is whatever you want to call the connection. If you have more than one broker you use specifying a descriptive name can be useful
- Unless you are connecting to Google Cloud leave Profile Type as MQTT Broker
- For Broker, Address enter the IP Address or Hostname of your broker
- Unless you are using a non-standard port or SSL your Broker Port will be 1883
- I recommend clicking the Generate button next to Client ID to get a truly unique ID
- The items on the General tab can be left as is
If your broker requires a User Name & Password (It really should). Click on the User Credentials Tab Fill in User Name & Password with the appropriate credentials.
If your broker uses SSL/TLS click on that tab and click enable and choose the Protocol and appropriate Certificate settings for your environment
Now click OK and you should be ready to connect by clicking the big blue Connect button at the top.
The Connect button should disable and the Disconnect button will now be clickable. On the right-hand side of the window you’ll see a green dot to tell you it connected OK. If using SSL the lock icon will be closed.
At this point, the setup has been successful
Publishing
To publish to a topic, you need to be on the Publish tab.
- Basic publishing is as simple as filling a topic in the text area next to the >>
- The in the large white area below put the message you would like to publish
- Then click the Publish button
- You can also set you Quality of Service levels and whether or the topic should be retained on the buttons to the right
- Topics you use will be retained in the dropdown list in the topic text area
In the example below sending a 1 to the selected topic will turn that light on.
If you have more complex messages that you would like to store for later use. You can right-click on the message area and choose Add to Messages Clipboard
You will be asked to name the clipboard message. Enter one and click OK
Clicking the >> next to the topic field will expand a window to show your clipboard.
Clicking << will close it.
Clicking on a name will replace the message field with the stored text
Subscribing
Subscriptions are done on the Subscribe tab
- Just like on the Publish tab topics are entered into the dropdown text area.
- Then click the no longer greyed-out Subscribe button.
- Again you can also choose the expected Quality of Service level (QOS)
- The Autoscroll button determines whether or not received messages should automatically scroll to the bottom as messages arrive or not
Once a message has arrived you can click on it to see the payload
Depending on the type of data contained in the payload you may need to change the decoder type at the bottom right of the screen
Topics Collector
One of the best features in my mind of this tool is the Topics Collector on the Subscribe tab. Once you click the Scan button. It listens to the broker for any and all topics and collects a list. This can be especially useful if a client isn’t behaving as expected as you can monitor for spelling or configuration mistakes in topic names. It’s also very useful if you have a client which for example is publishing Home Assistant or Homie autoconfiguration topics that you can’t change but want to monitor or use. A good example of this is the Ring Alarm MQTT project which publishes a series of topics for each device but with no really simple way to see the unique ID for them all.
Depending on how often devices publish changes or states it may take some time for all your topics to appear. In my example I let the scan run for about 20 mins and it collected 125 topics but I know there are more in use in my environment but some devices only publish a couple of times a day.
Scripting
MQTT.fx has a scripting engine built-in using something called the Java8 Nashorn JavaScript Engine. I can’t find much documentation on it but there a short YouTube video about it available at https://www.youtube.com/watch?v=nZ2aYobu454
Broker Status
The Broker Status tab allows for retrieving status information from your broker that is published to $SYS and its subtopics. This only works for the Mosquitto and HiveMQ brokers. It provides client connection and message information about the broker
Logs
The Log tab is about what you’d expect it shows messages received on subscribed topics as well as those published from within the program. It will show any errors that may have occurred.
Conclusion
Hopefully, you can now catch a glimpse of the power of this tool. Whether you have a working MQTT messaging system and just want to check under the hood. Or you are having issues with devices failing to communicate and need to track down the error. This tool can help with that.
Watch out for more in our series on MQTT coming soon
This article was produced both as part of our ongoing look into MQTT and as part of a similar series on https://iotrant.com/
