MQTT Tutorial for Raspberry Pi, Arduino, and ESP8266

Send MQTT messages between 3 different platforms

mqtt tutorial

This week’s MQTT Tutorial connects a Raspberry Pi, ESP8266 (or Arduino), and a PC together. Remember last week’s post provided an overview of message brokers and MQTT. We learned that MQTT is a hub and spoke protocol for sending messages between IoT devices. Clients can subscribe or publish messages to a central server, called a broker.

Now it’s time to connect our IoT devices together!

For this MQTT tutorial, I have three main elements:
•    My Computer, which will act as the broker.
•    Raspberry Pi running Python
•    ESP8266 controlling an LED

The idea is that the Pi (via Python) will send messages to the PC broker to tell the ESP8266’s LED what to do. For our simple MQTT tutorial, the Pi will blink an onboard LED on the ESP8266 one time.

In this MQTT Tutorial

I am not going to cover how to connect to your network (at least not in detail.) There are plenty of tutorials on that piece for each of the devices mentioned here.

Instead, I am only going to give an overview of communicating with MQTT on each IoT piece.


There are quite a few options for an MQTT server. Services like Amazon’s AWS IoT and AdafruitIO are cloud-based brokers. Each offers some advantages. Depending on your project needs you may or may not need the full support of a cloud-based service.


If you want to host a broker, the open source MQTT Mosquitto is an excellent option. This fully compliant MQTT broker also comes with command-line utilities for publishing and subscribing.

For Windows, there are binary installers on For Linux, check your package manager for “mosquitto” or “mosquitto-mqtt.” On Mac, you can use homebrew to install mosquitto.

Note, on my Mac (my “real” Mac…) I had to add /usr/local/sbin to my PATH.

Running Mosquitto

By default, mosquitto runs on port 1883 with virtually no security. For getting started, this is fine, but eventually, we need to look at adding some security stuff (hey, future post idea!).

I recommend running mosquitto in verbose mode, so you can get a good idea of what it is doing.

MacMan:~ james$ mosquitto -v
1456272937: mosquitto version 1.4.5 (build date 2015-11-09 14:23:46-0800) starting
1456272937: Using default config.
1456272937: Opening ipv4 listen socket on port 1883.
1456272937: Opening ipv6 listen socket on port 1883.

Testing Mosquitto

With the server code running in verbose mode, open up two more command prompts. We are going to use mosquitto_pub and mosquitto_sub to send ourselves test messages.

Subscribing to MQTT Topic with Mosquitto

First we are going have our client subscribe to a topic called “debug”. Use this command line in your “subscriber” window.

mosquitto_sub -h -i testSub -t debug
  • The host flag (-h) is the server running mosquitto, in this case, localhost.
  • The identity flag (-i) isn’t required. When a client id is not provided, mosquitto_sub will create one.
  • The topic flag (-t) is the topic we want to subscribe to, in this case, “debug”.

Notice on the server I didn’t create the topic, the topic is created when the subscriber or publish first hooks into it.

Publish to MQTT Topic with Mosquitto

Now that we have a client listening to a topic, let’s have a client publish to it, here’s the command for that.

mosquitto_pub -h -i testPublish -t debug -m 'Hello World'

mosquitto running on pc

And we see our client window comes back with our published message! Check out the —help flag on both the mosquitto_sub and mosquitto_pub utilities. There are lots of useful options for both, including -l which reads the message from STDIN.

Okay, now that we have our mosquitto broker running, let’s communicate with our devices.

MQTT for Raspberry Pi (or Python)

One option for MQTT messaging on the Raspberry Pi is just to install mosquitto! You can use the same mosquitto_pub and mosquitto_sub command line tools to communicate with an MQTT server.

The other option is to use an MQTT library for your preferred language. In this case, let’s look at Python.

Install MQTT for Python

The MQTT library I’m using is the Paho Python Client. It’s open source and supports the latest version of MQTT.

Installation is simple. First, install “pip” and then run:

pip install paho-mqtt
Don’t forget if you’re using python v3 (like for the QT GUI), you’ll need to run “pip3” instead of “pip”.

Example MQTT Python Code for Raspberry Pi

Paho makes communicating with your MQTT server very simple.

import paho.mqtt.publish as publish
import time
print("Sending 0...")
publish.single("ledStatus", "0", hostname="macman")
print("Sending 1...")
publish.single("ledStatus", "1", hostname="macman")

Seriously, it is that simple. Tell the script the hostname of your server (macman), the topic (ledStatus), and the message (0) or (1).

In this MQTT Tutorial example, we’re sending a ‘0’, waiting one second, and then sending a ‘1’. These actions will cause the LED on the ESP8266 to turn off briefly and then turn (back) on.

mosquitto mqtt and raspberry pi

Now that our Raspberry Pi is sending MQTT messages let’s receive them. The next section gets our ESP8266 (or could be an Arduino with WiFi/Ethernet Shield) receiving messages on the topic “ledStatus” and blink an actual LED!

MQTT for ESP8266 (and Arduino)

PubSubClient is an Arduino-based MQTT client. With just a few lines of code, it is very easy to either subscribe to topics or publish new ones.

In my setup, I am using the Arduino IDE to program my ESP8266. Read my ESP8266 caution post for why I use the Adafruit Huzzah and not the junk from eBay.

Install MQTT for Arduino IDE

Installing PubSubClient for the Arduino IDE is easy. Either install manually from GitHub or use the Arduino Package Installer. Simple!

installing PubSubClient for Arduino

Arduino ESP8266 and Uno Note

Switching between my Uno with Ethernet Shield and an ESP8266 took no effort on my part. The library works great with either.

Code Example for Arduino MQTT

The examples included with the PubSubClient are excellent. I think there are even ESP8266 examples particular to MQTT. Make sure you check those out when you are getting started.

Here’s my code for connecting to WiFi and subscribing to the topic “ledStatus”. When the ESP8266 receives a message, it acts by turning the “ledPin” on or off.

#include <EEPROM.h>
#include <ESP8266WiFi.h>
#include <PubSubClient.h>
#include <Wire.h>
#include <Adafruit_INA219.h>

// Connect to the WiFi
const char* ssid = "Dear John";
const char* password = "password123";
const char* mqtt_server = "macman";

WiFiClient espClient;
PubSubClient client(espClient);

const byte ledPin = 0; // Pin with LED on Adafruit Huzzah

void callback(char* topic, byte* payload, unsigned int length) {
 Serial.print("Message arrived [");
 Serial.print("] ");
 for (int i=0;i<length;i++) {
  char receivedChar = (char)payload[i];
  if (receivedChar == '0')
  // ESP8266 Huzzah outputs are "reversed"
  digitalWrite(ledPin, HIGH);
  if (receivedChar == '1')
   digitalWrite(ledPin, LOW);

void reconnect() {
 // Loop until we're reconnected
 while (!client.connected()) {
 Serial.print("Attempting MQTT connection...");
 // Attempt to connect
 if (client.connect("ESP8266 Client")) {
  // ... and subscribe to topic
 } else {
  Serial.print("failed, rc=");
  Serial.println(" try again in 5 seconds");
  // Wait 5 seconds before retrying

void setup()

 client.setServer(mqtt_server, 1883);

 pinMode(ledPin, OUTPUT);

void loop()
 if (!client.connected()) {
Notice that HIGH and LOW are reversed for the LED pin…

All of the magic happens inside of the function “callback”. In your real code, you probably want to write a function to handle receiving messages. Since I’m only sending single character messages on one topic, this simple code works.


This MQTT tutorial is pretty basic. However, it shows the minimum necessary to connect a Raspberry Pi, ESP8266 (or Arduino), to a PC running an MQTT Broker.

In the future, I’ll be addressing how to send more complex messages over MQTT. Make sure you subscribe to the RSS feed or email notifications to know when those become available.

Question: Is there a device you’d like to run MQTT on, other than these? You can leave a comment by clicking here.

Long comments, URLs, and code tend to get flagged for spam moderation. No need to resubmit.

ALL comments submitted with fake or throw-away services are deleted, regardless of content.

Don't be a dweeb.

Leave a comment

147 thoughts on “MQTT Tutorial for Raspberry Pi, Arduino, and ESP8266

  1. I found out where I went wrong. I can not use the IP, this is the IP that my station assigned to mosquitto that runs it. I therefore have to use the IP that the router attached to my linux – in the case

    Now it’s working.

    Still, grateful and congratulations for your article!

  2. Hi my friend,
    Congratulations for your post.  Maybe you can help me solve this problem.

    I have a mosquitto broker on local ip port 1883 (default)

    Tested and working from a terminal window. My system is a Ubuntu 15.10.

    I can’t connect from a sketch with ESP8266 to the broker, receive state -2.

    The code to connection to the broker is:

    #define BROKER_PORT 1883
    #define LAT “-29.1838681”
    #define LONG “-54.8528838”
    #define ID_MQTT “-29.1838681/-54.8528838”

    IPAddress localMQTT(127,0,0,1);
    MQTT.setServer(localMQTT, BROKER_PORT);
    void reconnectMQTT() {
    while (!MQTT.connected()) {
    if (MQTT.connect(ID_MQTT)) {
    } else {
    Serial.print(“reconnect failed status “);
    Serial.println(“Try to reconnect again 2 sec”);

    In terminal windows I can access the broker. Publish and subscrib to topics. But from the sketch can not.

    I saw you use a dns to specify the mqtt_server :

    const char* mqtt_server = “macman”;

    I don’t know how to do this, then I use the IP., port 1883

    But is not working….

    Do you have any idea what might be happening?

    Thank you and regards.

  3. Hi
    how can tested the mosquitto in windows , I ready installed also I check the service for mqtt is running


  4. Hi James, great tutorials. I’ve learned so much from your site and videos. So, thank you and please keep them coming! I’m currently learning all of this stuff concurrently, no easy task. I have the mosquitto broker setup on my NAS. Eventually, I’d like to be able to send temp inputs and other various inputs to the MQTT broker, then populate an SQL database on my website on the internet. And be able to communicate the other way, from pushing a button on a web page, which will send to the broker and back down to the ESP8266. All of this with security in place. I’ve had some success using a json file, but security is tough to implement and the refresh rate is slow and clumsy. This turorial has me on my way and I’m guessing it will take me a few hours to start communicating between my broker and ESP. The challenge will then be security and reaching out to the internet and a hosted server. I’d love any help or thoughts you could lend on any of this moving forward.
    Ideally I’d setup a web page on the internet which would communicate via MQTT to my in house NAS and allow me to control my ESPs that way.
    Cheers and thanks again for this tutorial!

    • Security is something I plan to look at soon. When I have devices communicating on my own network, I’m less concerned about security. If I were to communicate with an outside server, I would probably look at a RESTful API for MQTT Broker to Web Server communication. For example, I would have a script subscribed to a MQTT feed and when messages are received, post a REST call to my web server. That chain I would encrypt with SSL using self-signed keys. That way I’m not dealing with “authentication” but have a secured connection.

      • I have used the Blynk app on my smart phone. It requires a configured sketch on a wifi equipped arduino ( used a sparkfun ESP8266 Thing). You can build a really nice Human-Machine-interfface on the Blynk app. I could control microprocessor driven stuff at home from anywhere i could get celll service for 3g connectivity.
        Blynk supplies the code for the sketch btw.

  5. James,
    Where did you get the ESP8266WiFi.h file? Is it from the community library?

  6. Thanks for the tutorial. Clean and to the point. I adjusted the code for an Arduino + ethernet shield. Works great, and I can now build on these basic principles.

  7. Unable to install Mosquitto on Win 10. After installed libeay32.dll and ssleay.dll that was missing I got next issue: Can’t find number 175 in DLL-file \\mosquitto.exe.
    Installed: “binary installers on”


  8. Is there a way to use the arduino connected to the pi through serial, to send the messages through. I was thinking of building sensors using the Adafruit Feather 32u4 RFM95W LoRa Radio – 900MHz and then using another or an uno with the radio breakout as the gateway to connect to the pi. I’m hoping to avoid wifi for the network of sensors/nodes, and if I can avoid buying an ethernet breakout board or shield and save a little money, that would be good.