Home español

IoT MQTT Hello World

Last updated: 1 June 2022

MQTTmessage queue telemetry transport is a lightweight M2Mmachine to machine protocol, used for communication over the internet (or an intranet) between devices (typically devices that incorporate a sensor) and other systems or devices, AKA IoTInternet of "Things". Examples are: home automation, home security, wearable health alarms for the elderly, remote agricultural and meteorological sensors.

MQTT is not the only M2M internet protocol but at the time of writing is the most popular and seems to gaining traction compared to the others.

This post will show how to set up the most basic IoT project using MQTT so you understand the essential principles.

Stuff you'll need

  • Access to an MQTT broker
  • An MQTT client installed on your PC

How MQTT works

MQTT allows IoT communication between decoupleddecoupled refers to the fact that a component in a system is unaware of and can operate independently of other components within the same system. remote devices by a special messaging strategy known as publish/subscribe. In a publish/subscribe pattern devices that send messages don't send messages directly to receiving devices; they publish the messages to brokerbasically a server sitting in the cloud which receives messages and sends them to subscribed clients, which relays the messages to subscribed clients.

Publishers must send their messages and subscribers must retrieve those messages from the same place on the server. This place is a sort of channel known as a topic.

Every time a client publishes a message to a topic, every client which is is subscribed to that topic will receive the message.

The message, by the way, doesn't need to be a piece of text; it can be an image, a spreadsheet, a PDF or a video, for example - any binary format up to 260MB.

IoT over MQTT protocol
IoT over MQTT protocol

To build our very first IoT project using the MQTT protocol we only need to set up a publicly available broker and configure a couple of clients: one to publish (send) a message and one to receive the message.

Steps

Create an account with a publicly available, free MQTT broker

We will use hiveMQ. There are others, which you can use of course, (notably Eclipse Mosquitto or CloudMQTT), but are not as simple to set up as hiveMQ or are not free.

Set up an account at hivemq

  1. Go to https://www.hivemq.com/ > Get started Now > Sign Up and fill in your username and password (note that the Sign Up link also serves as the log-in link even after you have created an account for some reason). Note that you can also install a broker on your local PC.
  2. Click Create new cluster and choose the free package.
    Creating an MQTT broker on HiveMQ
    Creating an MQTT broker on HiveMQ
  3. Note the exact URL of your broker (you'll need this).
    Your MQTT broker URL
    Your MQTT broker URL
  4. Click on the User Management tab and fill in a user name (1) and password (2, 3) to register client access; then hit Add.
    Your MQTT broker URL
    Your MQTT broker URL

Install an MQTT client on your PC

The MQTT CLI client seems to be the best. Eclipse mosquitto client is also good but gave me issues reading files and dealing with binary data. DO NOT download the MQTT CLI version displayed at the hiveMQ Get Started page! Get it from hivemq.github.io.

This page also includes installation instructions for Linux, Mac and Windows.

The Linux (Ubuntu/Debian) steps are simple. Just run the following two commands from a terminal window (enter your root password when prompted): 

wget https://github.com/hivemq/mqtt-cli/releases/download/v4.8.1/mqtt-cli-4.8.1.deb
sudo apt install ./mqtt-cli-4.8.1.deb

Test connectivity with the broker

Once the client is installed, issue the following from the terminal: 

mqtt test -h broker.hivemq.com

You should see the following information (or something very similar) appear in the terminal. This shows some status and configuration for MQTT versions 3 and 5: 

MQTT 3: OK
	- Maximum topic length: 65535 bytes
	- QoS 0: Received 10/10 publishes in 53.97ms
	- QoS 1: Received 10/10 publishes in 486.06ms
	- QoS 2: Received 10/10 publishes in 956.58ms
	- Retain: OK
	- Wildcard subscriptions: OK
	- Shared subscriptions: OK
	- Payload size: >= 100000 bytes
	- Maximum client id length: 65535 bytes
	- Unsupported Ascii Chars: ALL SUPPORTED
MQTT 5: OK
	- Connect restrictions:
		> Retain: OK
		> Wildcard subscriptions: OK
		> Shared subscriptions: OK
		> Subscription identifiers: OK
		> Maximum QoS: 2
		> Receive maximum: 10
		> Maximum packet size: 268435460 bytes
		> Topic alias maximum: 5
		> Session expiry interval: Client-based
		> Server keep alive: Client-based

Test the publish/subscribe functionality

Now we'll subscribe and publish a simple message to a topic using the MQTT CLI on the broker we just created.

  1. Subscribe to a new topic with the following command. Note that you need to change {URL} for the exact URL that you created at hiveMQ (copy and paste it from the My Clusters page); change {your user name} and {your password} for the user name and password you created at the Access Management page. {my/test/topic} is the topic name and can be anything you like; but any client will need to publish to the exact same topic name for subscribes to receive published messages: 
    mqtt sub -h {URL} -p 8883 -s -u {your user name} -pw {your password} -t '{my/test/topic}'
  2. Open a new terminal and enter: 
    mqtt pub -h {URL} -p 8883 -s -u {your user name} -pw {your password} -t '{my/test/topic}' -m "Hello world!"

Check the results

You should now see the following output in the first window:

Hello world!

If that worked, it's time to try to send data via MQTT to a mobile device. This next post shows you how to send text and images to your mobile phone.

© 2022