MQTT.fx Extras - HiveMQ MQTT Toolbox

MQTT.fx Extras - HiveMQ MQTT Toolbox

author Jens Deters

Written by Jens Deters

Category: MQTT Toolbox MQTT

Published: February 9, 2016

Short Profile

Attribute MQTTBox
Type Graphical user interface, JavaFX-based
License Apache 2.0 license
Operating Systems Mac OSX, Windows and Linux

General Information

MQTT.fx aims to be an quick and easy to use desktop tool for MQTT debugging and testing. Since about 2 years it is continuously extended (and bug-fixed) by Jens Deters.

Recently version 1.0.0 was released, including:

  • Connection Profiles for different setup of MQTT broker connections
  • ad-hoc connections
  • publish / subscribe
  • username/password authentication
  • SSL/TLS support
  • clipboard for predefined messages
  • $SYS-Topics / Broker Status (HiveMQ & mosquitto)
  • proxy-support
  • stored history of last used topics (per profile)
  • Scripting support via Nashorn Engine
  • logging console
  • bundled installers for all platforms
  • update check
  • Free! (Apache 2.0 license)

MQTT.fx - A closer look

The first part of this blog post series was an overview about the major features of MQTT.fx 1.0.0. However having a closer look at the details, there is some more to mention.


For instance the “Application” tab of the settings dialog allows to keep all detached tabs always in top. So they won’t be hidden by other windows in the foreground. Also the check for updates at applicatIon start can be controlled here.


In addition to the publish topic the QoS level can be chosen and whether the message should be send “retained” (when a new client is subscribed to this topic it receives all the previously published messages).

Reminder: MQTT Essentials Part 6: Quality of Service 0, 1 & 2

Level Means Cool
QoS 0 At most once “fire and forget”: A message won’t be acknowledged by the receiver or stored and redelivered by the sender. Use this level, e.g. with ambient sensor data where it does not matter if an individual reading is lost as the next one will be published soon after.
QoS 1 At least once A message will be delivered at least once to the receiver. Messages are assured to arrive but duplicates may occur.
QoS 2 Exactly Once Message are assured to arrive exactly once. Use this level when duplicate or lost messages could lead to incorrect conditions.

Also the topic drop-down can be cleared via the “gears” menu.

Messages Clipboard

Messages can be stored for re-use on the “Messages Clipboard”. Stored messages are saved with the Connection Profile. Thus each profile has its own space of saved messages.

Store a Message

To store a message simply choose “Add to Messages Clipboard” in the context menu of the message area:

and enter a logical name for the message

A new message tile is created and the button to send the message is labeled according to the entered logical name.

When the hover on a Clipboard Message some options for modifcations get visible

See the Message Clipboard in action here:

YouTube clip: MQTT.fx 1.0.0 - Messages Clipboard


A closer look at the topic subscription bar:

Option Does
Clear All Topic Clear subscribed topics history
Clear Not Subscribed Topics Clear on topics from history, that are currently not
Clear Messages Clear received messaged buffer
Subscribe to all recent topics Subscribe to all topics in history with one click
Unsubscribe from all topics Unsubscribe from all current topics with one click

Also the QoS can be chosen on subscriptions. But there is a difference to the publish QoS. QoS on subscription set the maximum quality of service to subscribe the topic(s) at. Messages published at a lower quality of service will be received at the published QoS. Messages published at a higher quality of service will be received using the QoS specified on the subscribe.

Show only lastest option shows only the last received message per topic.

When Notifications is selected, Desktop notifications on received messages are turned on.

When “Use dynamically scaled fonts” is enabled in the setting, MQTT.fx tried to auto scale the display of message body/payload in received messaged view.

However it is also possible to set a fixed font size for the message rendering here.

Topics of received messages can be copied when marked with CMD + C (Mac) or CRTL + C

I case the message body is multi lined the first line is rendered with ending “…” and there is a toggle to expand the message:

When subscribed to wildcard topics the matching pattern is displayed in light gray below the full topic of the message:


A short intro, about scripting with MQTT.fx can be found here:

YouTube clip: MQTT.fx 1.0.0 - Scripting

Scripts can be easily made available for execution via the UI. At start MQTT.fx is scanning a folder named “scripts” located in the MQTT.fx working directory. The location of this directory differs per OS:


[USER_HOME]/Library/Application Support/MQTT-FX/scripts





In case this folder does not exists it is automatically created by MQTT.fx containing some default/demo scripts.

To be found by MQTT.fx scripts must follow the naming convention:

Following this convention, files in the “scripts” folder are names like this:

… and the drop-down menu in Scripts tab is shown like this:

Scripts can be easily edited instantly by click on “Edit”. The default editor assigned to “*.js” files will be opened to edit the script. Scripts are loaded prior to each execution thus changes are taking effect when the edited script is saved. It is very easy to play with scripts playing the edit-save-execute game.

If the system default editor for JavaScript filed should no be used for editing MQTT.fx scripts there is a setting option to define a certain editor:

Broker Status

As per default, it is not meant to subscribe manually to $SYS/# topics. There is an option to bypass this restriction though. Open the Preferences/Settings and


The application configuration file is located at the default working directory (see section “Scripts”). Basically there is no need to edit this file as MQTT.fx is taking care. But in case of issues, e.g. on application start “runSetup” could be set to “true” manually. If this file is broken or missing, MQTT.fx is creating a new fresh default configuration for you at application start.

author Jens Deters

About Jens Deters

Jens Deters has held various roles in IT and telecommunications over the past 22 years: software developer, IT trainer, project manager, product manager, consultant and branch manager. Today Jens leads the Professional Services Team at HiveMQ. As a long-time expert in MQTT and IIoT and developer of the popular GUI tool MQTT.fx, he and his team support HiveMQ customers every day in implementing the world’s most exciting (I)IoT UseCases at leading brands and enterprises.

mail icon Contact Jens
newer posts MQTT Inspector - HiveMQ MQTT Toolbox
MQTT.fx - HiveMQ MQTT Toolbox older posts