Getting start with MQTT Mosquitto Broker on Raspberry Pi, Windows, macOS and Linux [update]

mqtt mosquitto broker mqttfx
Table of Contents
drapeau france
level advanced

Mosquitto is an Open Source MQTT (Broker) server that can be installed on a Raspberry Pi (but also on other platforms) to facilitate communication between connected objects (M2M). Mosquitto is an ideal tool for integrating objects connected to a home automation server such as Jeedom, openHAB, Domoticz or Home Assistant.

In this tutorial we will install Mosquitto on Raspberry Pi and discover how to use it directly from Terminal, Node-RED and MQTT.fx (Windows).

What is an MQTT broker?

MQTT (Message Queuing Telemetry Transport) is a messaging protocol that works on the principle of underwriting / publishing that was developed at the base to simplify communication between the machines. To run it is necessary to install a server, which is designated by Broker. You can install your own Broker, which we will do in this article. You can install it on almost all platforms including the most common (Windows, Linux, Mac OS X ….) but also on a Raspberry Pi (which works under Linux after all).

Since November 2014, version 3.1.1 of MQTT has become an international standard for communication between machines (M2M) and objects (IoT). It is supported by the OASIS foundation, which brings together leading IT and telecom companies (BlackBerry, Cisco, IBM, Kaazing, LogMeIn, M2Mi, MachineShop, PTC, Red Hat, Software AG, TIBCO …).

In addition to simplifying communication, MQTT was designed to save as much as possible the battery of the mobile devices on which it is used. It is 11 times less energy consuming to send messages and 170 times less to receive than HTTP. MQTT is also 93 times faster than HTTP.


With MQTT you have the possibility to set QoS, that is to say how for each message sent you can choose how the broker must manage it: The notion of QoS in messages that transit through MQTT.

  • QoS0. The sent message is not stored by the Broker. There is no acknowledgment of receipt. The message will be lost if the server or client is shut down. This is the default mode
  • QoS1. The message will be delivered at least once. The client returns the message until the broker sends back an acknowledgment.
  • QoS2. The broker saves the message and transmits it until the subscribers connected receive it

Other useful functions

  • Persistence of messages on a Topic. The messages are stored on the Broker.
  • It is possible to manage the subscription / publication rights for each Topic.
  • It is possible to secure the transport of the messages in SSL / TLS as well as by identification of the user (identifier and password)
  • Topics and the tree are created on the fly. There is nothing to configure on the Broker. It is the “publisher” who created the Topics tree (at the time of publication).

Which Broker MQTT open-source choose?

There are several open-source brokers

  • ActiveMQ that allows you to add MQTT to an Apache Web server (Developed by the Apache Foundation)
  • JoramMQ for the integration of MQTT in Java
  • Mosquitto, the open-source broker most used in DIY projects supported by the foundation
  • RabbitMQ, an open source project also available with commercial support
  • EMQTT, a project developed in Erlang / OTP available for Windows, Mac Os X and Linux designed to receive very many connections (up to 1 million per server). It is possible to create a cluster (server network) to increase the number of simultaneous connections.
  • ActiveMQ and JoramMQ are quite specific brokers. RabbitMQ is more business-oriented with its commercial offer. Mosquitto is widely used in projects based on esp8266, Arduino and Raspberry. This is the one I advise you to use.

Install Mosquitto on Raspberry Pi or Linux

Before installing Mosquitto, it is always a good idea to upgrade your system

sudo apt-get update

The installation of the Mosquitto Broker is very simple.

sudo apt-get install mosquitto

If you want to run tests on your Raspberry, you can install mosquitto_sub clients (to subscribe), mosquitto_pub (to post messages) and mosquitto_passw (to set up users and passwords).

sudo apt-get install mosquitto-clients

If you want to make developments in python, install python-mosquitto. You can also install everything in one order

sudo apt-get聽install mosquitto mosquitto-clients python-mosquitto

To do your first try, you can use the test server Attention to what you published is an accessible server for everyone! It is directly accessible without the need to create an account or user.

Install Mosquitto on Windows or macOS X

You do not yet have Raspberry Pi, no problem, you can install the Mosquitto Broker on almost all platforms (link to the download page).

There are two versions available depending on the version of your Windows

For Windows Vista and above: mosquitto-1.4.8-install-win32.exe (~ 200 kB) (developed with Visual Studio Community 2013)

For Windows XP: mosquitto-1.4.8-install-cygwin.exe (~ 200 kB)

On Mac OS X, you will already have to install and execute the following command in the Terminal

brew install mosquitto

Send / receive your first MQTT messages

Now that the broker is ready, publish our first message. One connects to the server (-h) localhost on the Topic (-t) sensor / temperature and publishes the message (-m) 22.5

mosquitto_pub -h localhost -t "sensor/temperature" -m 22.5

In another Terminal, run the command

mosquitto_sub -h localhost -t "sensor/temperature"

mqtt mosquitto raspberry pi pub sub example exemple publication

It’s that simple!

Using MQTT with Node-RED

In this previous article, I introduced you quickly Node-RED, let’s see how simple it is to communicate with MQTT using Node-RED.

Add a node mqtt (input section). Double click on the node to open the configuration box. And press the pencil to add a new connection. If Node-RED runs on the same machine as the Mosquitto broker, enter localhost in the server field and 1883 in the port. Confirm.

mqtt mosquitto node-red raspberry pi 3

In the Topic field enter the topic to which you want to subscribe. In our example sensor / temperature. Add a node debug and deploy. Return to the Terminal and publish a new value on the topic. A new message has just been added in the debug window. Communicating with your connected objects becomes a real child’s play?

mqtt broker mosquito node-red subscribe

Some useful commands

Symbol #. It allows subscribing to all levels below the wildboard. For example, with the following command you will subscribe to all Topics (-t) on server (-h) localhost. All topics (“#”). The Topic will be displayed before its value (-v).

mosquitto_sub -h localhost -t "#" -v

Delete a topic and its contents (be careful not to go back)

mosquitto_pub -t <topic> -r -n

Secure Mosquitto with a password

By default, any client can connect to the Mosquitto broker. It is not very embarrassing if there is only basic information that is published (temperature measurement, CO2 rate, indicates IAQ …) but if you want to order devices, lamps or your electric gate , you must secure a minimum Mosquito.

Go to the Mosquitto configuration folder. On Linux (or Raspbian)

cd /etc/mosquitto/

On Windows, it is at the root of the hard drive (c:\mosquitto) by default.

Mosquot creates a file that contains the user’s name and password (encrypted). To add a new user run the command mosquitto_passwd -c username username. Replace filename with the file name that will contain the username and username, the name of the user to add

Mosquitto requests the password entry (2 times). The sudo command is required on Linux when in the / etc directory.

sudo mosquitto_passwd -c users projectsdiy

Open the Mosquitto configuration file with nano (sudo mandatory on Linux)

sudo nano mosquitto.conf

Add the allow_anonymous false command and specify the path to the password file (on Windows c:\mosquitto\user)

  • allow_anonymous false
  • password_file /etc/mosquitto/users
  • Now it only remains to restart Mosquitto to take into account the changes
sudo service mosquitto restart

To add another user, use the -b option of the mosquitto_passwd command with:

the name of the password file
the new user name
the password
What gives for example

sudo mosquitto_passwd -b users newuser password

Use the Linux cat command to verify that the new user has been added to the configuration file

mosquitto add user

Now, it will be necessary to authenticate to be able to publish or subscribe to a Topic. On the command line, we have the -u option to specify the user and -P for the password. What gives to publish a message

mosquitto_pub -h localhost -t test -m demo -u username -P password

And to subscribe

mosquitto_sub -h localhost -t "test" -v -u username -P password

MQTT.FX: Easily Publish / Subscribe Messages

Instead of Node-RED, you can also use MQTT.fx, a cross-platform open source software that you can download here. MQTT.fx is a fairly complete tool that will allow you:

  • To subscribe or publish messages by adjusting the QoS
  • To know the status of your Broker (number of clients connected, messages received, sent, stored, network traffic …)
  • Accessing the Broker Log
  • To create scripts in Javascript

mqtt mosquitto broker mqttfx

Click to rate this post!
[Total: 0 Average: 0]

Thanks聽for your reading

Did you like this project ? Don't miss any more projects by subscribing to our weekly newsletter!

Are you having a problem with this topic?

Maybe someone has already found the solution, visit the forum before asking your question
  1. Hi from Australia!

    Thank you for such an excellent article. I have been looking for a while for accurate information that was easy to follow to get me started on a project that will eventually involve using a Pi-camera to capture pictures automatically into an Excel spreadsheet. Most tutorials that I have tried assume a greater level of knowledge than I have, or seem to have been written from memory and something vital but not obvious has been left out.

    Your article just hit the spot! From another site, I learnt how to load Raspbian onto an SD card (shows my level of knowledge!) 30 minutes later following your article, I am sending messages from Windows to pi and vice versa! Still a long way from my final goal, but a lot closer than I was half an hour ago.

    There is one thing that needs to be fixed though. In the instructions for publishing, there should be quotes around the topic name.

    Again, an excellent and very useful article!!

    Thank You!!!!!

    • Hi Rebboc! I thank you very much. I’m really happy if my tutorials are useful. I hope you’ll find new posts as well. Thank you very much for the mistake, i’ll change that immediately. See you soon. Christophe from France.

  2. The easiest way on Windows 10 is to use WSL , read this post on how to do that, literally two steps.

Leave a Reply

Read more
DIY Projects
DIY Projects
%d bloggers like this: