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:
- connect to a broker,
- publish a message and
- disconnect when we are done.
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 |
|---|---|
AT_MOST_ONCE |
0 |
AT_LEAST_ONCE |
1 |
EXACTLY_ONCE |
2 |
For more details check Part 6 of the MQTT Essentials from HiveMQ.
Retain
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