Setting up an MQTT Broker on Your Raspberry Pi

MQTT (Message Queuing Telemetry Transport) is a popular way for devices to communicate with each other over a network. It’s a lot of acronyms and jargon, but this article will break it down for you. You’ll learn how to set up your own MQTT broker on our Raspberry Pi using Mosquitto, a popular MQTT package.

Mosquitto packages can be installed on the Pi using the APT package manager. Once installed, they can be configured to start an MQTT Broker on the Pi. Moreover, additional setup options include remote access and better security.

In this tutorial, I’ll start with the theory to make sure we’re on the same page. Then we’ll install the Mosquitto packages on your Raspberry Pi and implement additional features like remote access and a credential-based authentication mechanism (i.e. username and password). Let’s do this!

If you’re new to Raspberry Pi or Linux, I’ve got something that can help you right away!
Download my free Linux commands cheat sheet – it’s a quick reference guide with all the essential commands you’ll need to get things done on your Raspberry Pi. Click here to get it for free!

MQTT: A Gentle Introduction

Before the technical installation steps, let’s learn what MQTT is.

What is MQTT and How Does it Work?

MQTT is a way for devices to communicate with each other over a network (typically the Internet). It has a “broker” that manages all the messages transmitted over a network.

Think of the broker as a software code that can run on any device and acts as a middleman for devices to talk to each other.

For instance, if you have several smart devices in your home (like a thermostat, smart lights, etc.) that you want to connect, the broker acts as a single point of connection between these devices.

MQTT allows your thermostat to send its readings to your phone app. You can then send it to any device connected to your network, such as an air conditioner that can monitor the temperature and turn on when it gets hot.

Interesting, right? It might become one of your top tools for building a Raspberry Pi smart home.

If you have several devices whose data you would like to access individually, you can easily do so with MQTT. It has features like topics that allow you to isolate a particular device’s data (we will look at this in detail in the next section).

Now that we understand MQTT, let’s briefly cover its key components and dive into the technical details.

MQTT Key Components

Based on what we understood in the previous section, three main components make up this communication protocol:

• Publishers: These are the devices that send data within the network.
• Subscribers: These devices listen to a particular data stream and perform an action using it.
• Broker: This can be considered the brains of the network. It manages and routes the data within the entire network. The network can have one or multiple brokers depending on its size.

But, how do publishers and subscribers know where to send/receive data? MQTT solves this problem with Topics and Messages:

• Topic: The topic is like a unique tag added to the data so the broker knows where and how to route it. Subscribers use this same tag to specify what data they want.
• Message: The message is the actual data sent or received by the client (publisher or subscriber).

Taking the above example, you can consider the topic to be “thermostat/temperature” and the message as the actual temperature readings (for instance, 22 degrees).

So, if you have 3 light bulbs in your home that you would like to control with MQTT, you can create 3 topics:

• livingroom/lights
• bedroom/lights
• kitchen/lights

The topics provide a way to segregate these messages and act as an identifier that can be used by applications.

Additionally, MQTT also provides advanced features like:

1. Scalability: a single broker can manage thousands of devices and there can be multiple brokers within a network as well.
2. Reliability: MQTT has a unique functionality called QoS (Quality of Service), which gives the broker the capability to store messages for a certain time, so if a device is offline at a given time, the broker will wait for it to come online and then send the message to it.

That’s all the theory we will cover on MQTT in this article. Now, we will learn how to set up our Raspberry Pi as a MQTT Broker.

Setting up a MQTT Broker on the Pi

Before we get started with the actual tutorial, let’s briefly go through the hardware/software requirements for this project:

• Raspberry Pi: Of course! You will need a Raspberry Pi. I suggest using a Raspberry Pi 5 with at least 2 GB RAM. However, any Raspberry Pi model will suffice for this tutorial.
• A Mobile Device for testing our broker with remote connections.
• A computer with an SD card reader (can be a Raspberry Pi with Imager on it).
  If you don’t have one, you can use a cheap USB adapter (like this one on Amazon).
• Wired/Wireless Connection: In this tutorial, I will assume that you have your Pi connected to your home network through a wired Ethernet connection or Wi-Fi. We will need this to set up and test remote connections.
• A micro-SD card to install the latest Raspberry Pi OS on the Raspberry Pi.
  Here is my current recommendation for the best performance, but any model will do for this tutorial.
• Raspberry Pi Imager: We will use it to flash the latest Raspberry Pi OS image on our SD card.
  You can read my Raspberry Pi Imager tutorial here if you are new to this.

So, once you have everything set up, we are ready to get our hands dirty and set up our very own MQTT Broker.

Step 1: Installing Mosquitto Packages

The first step is to install two packages: mosquitto (the actual MQTT broker package) and the mosquitto-clients package (which will help us to test your broker locally).

This is pretty straightforward; it’s as easy as running the following command on your terminal window:

sudo apt install mosquitto mosquitto-clients

Step 2: Enabling the Mosquitto MQTT Broker

In most cases, the broker will be started automatically, but to be sure, let’s explicitly enable it and check its status. Enable the broker by running the following command in your terminal:

sudo systemctl enable mosquitto

This command will enable the broker on your Pi if it isn’t already active. To confirm this, run the following command:

sudo systemctl status mosquitto

If your broker is active and running, you should see the following output on your terminal window.

Look for the highlighted Active section in the logs, it should say that the broker is active (running) which means that your MQTT broker on the Pi is up and running!

Now let’s see the broker in action by configuring and testing it with some clients.

MQTT Broker in Action

In this section, we will see interesting demos that use our Raspberry Pi as an MQTT Broker and Client (when we test locally on the Pi). So, let’s start with testing our broker locally.

Local Testing: Connecting to our Broker from the Pi

In this section, we will test our Pi’s MQTT Broker by creating clients on separate terminal windows of our Raspberry Pi (one will be a publisher and the other a subscriber). Sounds interesting, right? Let’s begin.

• First, open a new terminal window on your Pi. We will first create a subscriber.
  Note that you will need the mosquitto-clients package which we have already installed. Just execute the following command in the new window:
  
  mosquitto_sub -v -t test/message
  
  This will turn our terminal window into a subscriber within our network. Let’s understand the above command:
  
  -v prints additional information about the message.
  -t lets us specify the topic name we want to subscribe to.
  
  So, if any publisher sends a message to the “test/message” topic, it will be printed on our terminal window.
  
  
• Next, in a new terminal window, execute the following command to start a local MQTT publisher.
  It sends the classic “Hello World!” message to our subscribers who are listening to the “test/message” topic and see the magic.
  
  mosquitto_pub -t test/message -m 'Hello World!'
  
  This will publish the Hello World message on the specified test/message topic.
  
  
  
• Voila! You should see the same “Hello World!” message on our subscriber window as well as illustrated in the following screenshot:
  
  
  Congratulations! You just completed your first test for your MQTT broker hosted on the Raspberry Pi. Although local access is nice, it isn’t useful to only use this within our Pi. So, let’s see how we can go further and use this remotely within our local network.

Remote Access to our Broker

In this section, we will enable remote access for our MQTT Broker, allowing devices within our local network to use our Pi’s MQTT broker to communicate with each other. In addition to this, we will also add additional security measures for our MQTT network.

Enabling Remote Access and Authentication

By default, remote access and authentication features are disabled for our broker. To enable them, we need to modify the config file for our MQTT broker. We need to change two things in the config file. Follow the steps shown below:

• Let’s create the username and password we will use for authentication.
  You can do this with a single command which we create a password file for our Broker so it can check it against all incoming and outgoing message requests.
  
  The command we need to run is as follows:
  
  sudo mosquitto_passwd -c /etc/mosquitto/passwd pat
  
  This will prompt you to enter a password of your choice. Once you do that, press enter and the credentials for the user will be stored in the generated password file.
  
  
• Once the user has been created, we can configure our Broker to enforce this authentication and allow remote connections.
  For this, we need to modify the mosquitto config file. Just execute the following command to open the configuration file:
  
  sudo nano /etc/mosquitto/mosquitto.conf
  
  This will open an editor on your terminal. Just add the following lines at the end of the file to add the required configurations:
  
  listener 1883
allow_anonymous false
password_file /etc/mosquitto/passwd
  
  
  The first line allows remote connections, the second line enables authentication, and the third line tells the broker what credentials are allowed to publish and subscribe messages within the network (which is the user pat in my case).
  
  Save these changes by pressing “Ctrl + O” and then Enter twice to save the file and then quit the editor by pressing “Ctrl + X”.
  
• Finally, once you have made the changes, restart the MQTT broker to enforce the changes.
  You can do this by executing the following command:
  
  sudo systemctl restart mosquitto
  
  You can recheck the status to ensure everything is working as expected. Now we are ready to test our broker using devices within our network!

Remote Access Testing with Your Device

Now that everything is set, let’s test our local MQTT network with an external device that connects to our Pi’s Broker.

• To test, we will need an MQTT client on one of our devices.
  Our smartphone is the obvious choice when it comes to this. We will download a popular and lightweight application called “EasyMQTT” on our device to test our broker.
  
  
  
• Once you have the application on your device (don’t worry, it’s available for Android). Just open the application and configure your MQTT Broker by adding the requested details after pressing the “Add broker” button.
  
  
  Enter all the information as instructed in the image above (The name can be of your choosing). You can easily get your Pi’s IP address with the ip a command as shown below.
  
  
  Once you have added everything, press the Save button at the bottom. This completes the broker setup on the application. Next, let’s subscribe to a topic through our application.
  
• Before you subscribe to a topic, don’t forget to press the button for your broker in the application to connect to it (I missed it and couldn’t see my published messages).
  
  
• Once you’ve connected to your broker, navigate to the Subscribe window by selecting it from the options at the bottom.
  There you will enter the topic you would like to subscribe to and check any messages on this topic. Add the “test/temperature” topic.
  
  
  As shown in the image above, type the topic name you would like to subscribe to and then press the Subscribe button, which should show the topic in the Subscribed Topics list.
  That is all we need to set up in the application.
• Now, head back to your Pi’s terminal and execute the following commands:
  
  mosquitto_pub -h <pi-ip-add> -t test/temperature -m 22 -u pat -P <password>
mosquitto_pub -h <pi-ip-add> -t test/temperature -m 24 -u pat -P <password>

  Here are example commands with the filled-in template values for your reference:
  
  
  
• You should see these values on your EasyMQTT application as well. Just open the Show Messages section and you should be able to see the published messages on the application!
  
  

Now, instead of these just being values, imagine them being something like a digital gauge and the publisher being a device with several sensors. The applications for this are endless! This marks the end of this tutorial.

Going further with MQTT

We are at the end! We successfully set up and tested our MQTT broker on the Raspberry Pi. Based on our demonstration, there are several use cases where this protocol will be useful. Some of these are:

• Smart Homes: This is a popular application area for MQTT. Hosting a broker on a public server will allow us to use the broker over the internet and control our devices from anywhere in the world instead of over the local network.
• Wake-on-Lan Server: Can You Wake a Raspberry Pi Remotely?
• Industrial Sensors: MQTT can also be used in factories and manufacturing environments for monitoring equipment remotely by enabling them to send sensor readings and alerts via MQTT.
• Remote Patient Monitoring: In healthcare, MQTT can help various wearable devices and central monitoring systems communicate with one another, improving overall patient care.

These are just some areas where MQTT can play an essential role. This is only the start of your journey with MQTT.

Whenever you’re ready, here are other ways I can help you:

Test Your Raspberry Pi Level (Free): Not sure why everything takes so long on your Raspberry Pi? Take this free 3-minute assessment and see what’s causing the problems.

The RaspberryTips Community: Need help or want to discuss your Raspberry Pi projects with others who actually get it? Join the RaspberryTips Community and get access to private forums, exclusive lessons, and direct help (try it for just $1).

Master your Raspberry Pi in 30 days: If you are looking for the best tips to become an expert on Raspberry Pi, this book is for you. Learn useful Linux skills and practice multiple projects with step-by-step guides.

Master Python on Raspberry Pi: Create, understand, and improve any Python script for your Raspberry Pi. Learn the essentials step-by-step without losing time understanding useless concepts.

You can also find all my recommendations for tools and hardware on this page.