Hands-on Guide to MQTT

In this post you'll learn how to use the long-time “de-facto” standard for machine-to-machine (M2M) publish/subscribe messaging transport MQTT with the command-line.

"MQTT is a machine-to-machine (M2M)/"Internet of Things" connectivity protocol."

The accronym stands for Message Queuing Telemetry Transport and has seen several standardisation efforts:

Through OASIS:

and ISO

Where to start…

Our focus is to deliver a fast first-hand experience with MQTT. An easy way to get started quickly is the use of a publicly available endpoint to get a first impression of the technology.

One such public sandbox serve is available at mqtt.eclipse.org:1883 (powered by Eclipse Paho).

"The Eclipse Paho project provides open-source client implementations of MQTT and MQTT-SN messaging protocols aimed at new, existing, and emerging applications for the Internet of Things (IoT).

For the impatient

Now that we have a sandbox, we need a tool...after consulting MQTT Toolbox - The best MQTT Client Tools we went for MQTT CLI. A light-weight alternative might be the Command-line tools from Eclipse mosquitto. Since we are new to the topic (and were looking for a command-line tool) - the choice was mostly driven by our guts feeling. I'm pretty sure any of those tools mentioned in the toolbox would do the job, too.

MQTT CLI - MQTT CLI is a full MQTT 5.0 and MQTT 3.1.1 compatible command-line interface for MQTT clients…

You have two main options: Either via Installation using a package manager or Building from source

Ready for rumble...

Anyway, let’s continue with MQTT CLI and fire up the powerful interactive shell with (we’ve built the CLI from the source):

java -jar tools/mqtt-cli-1.1.1.jar shell

You should see the prompt mqtt> once the program has finished the initialization process.

In the following walk-through we’ll:

Let’s create a reusable client identified by probe connecting to the Eclipse Paho sandbox mqtt.eclipse.org:1883 with protocol version 3 and get started:

mqtt> con -i probe -h mqtt.eclipse.org -p 1883 -V 3
probe@mqtt.eclipse.org> pub --topic sample --message "hello MQTT world"
probe@mqtt.eclipse.org> dis
mqtt> exit

As you can see the prompt changed indicating a context switch.

Switch to another terminal and start a second instance of MQTT CLI.

Important: On the subscriber side we use the option --outputToConsole - otherwise the messages will be written to log-files.

mqtt> con -i logger -h mqtt.eclipse.org -p 1883 -V 3
logger@mqtt.eclipse.org> sub -t sample --outputToConsole
logger@mqtt.eclipse.org> hello MQTT world
logger@mqtt.eclipse.org> dis
mqtt> exit

The overall session is logged by the tool to .mqtt-cli/logs/mqtt_cli_2020-01-25.log:

2020-01-25 14:46:21 | 65043 | DEBUG | Client 'probe@mqtt.eclipse.org' sending PUBLISH ('hello mqtt world') MqttPublish{topic=sample, payload=16byte, qos=AT_MOST_ONCE, retain=false}
2020-01-25 14:46:21 | 65043 | DEBUG | Client 'probe@mqtt.eclipse.org' received PUBLISH acknowledgement MqttPublish{topic=sample, payload=16byte, qos=AT_MOST_ONCE, retain=false}
2020-01-25 14:46:21 | 65044 | DEBUG | Client 'logger@mqtt.eclipse.org' received PUBLISH ('hello mqtt world') MqttPublish{topic=sample, payload=16byte, qos=AT_MOST_ONCE, retain=false}

For more information (and commands - like subscribe, …) visit the documentation chapter Shell-Mode.

Advanced topics

Besides topic and payload you can easily spot two other important parameters of a message: qos and retain.

Quality of Service

With QoS (Quality of Service) it's possible to influence what guarantees are granted/expected when using MQTT.

QoS value

For more details check Part 6 of the MQTT Essentials from HiveMQ.


By default, the broker doesn't store a message so a client will have to wait for a new message to arrive to gain any insights from the subscribed channel...with the retain flag set the broker will store the last message of the topic and provides it to any newly connecting client.

I highly recommend Retained Messages - MQTT Essentials: Part 8 or MQTT Retained Messages Explained for more details on this topic.

Where to go from here

Other sources for newbies that provided helpful insights during our first steps are:

Other background material:

Have fun with your IoT devices...

Photo by Mathew Schwartz on Unsplash