How to quickly troubleshoot MQTT problems on your Raspberry Pi

MQTT is a great communication protocol for internet-connected devices of any size. It has proven especially helpful for linking up Internet-of-things (IoT) systems like a digital picture frame.

In many articles here on this website, I am using MQTT to control the playback of the picture frame with Pi3d, forward data to a home automation system like Home Assistant, or automate tasks like presence detection to save energy.

In principle, MQTT is very simple to set up and to operate, but every once in awhile, it just doesn’t work, and you may spend hours trying to find the bug only to eventually conclude that it was just a silly small thing that you forgot.

So the objective of this article is to save you a lot of time by systematically checking a few of the most common issues quickly.

Have you installed the paho package?

The Raspberry Pi needs the paho package to connect to an MQTT broker and to receive and send any messages.

Install it with

sudo pip3 install paho-mqtt

If you are not sure if you have installed it, run the above command. If the answer is

Requirement already satisfied: paho-mqtt in /usr/local/lib/python3.7/dist-packages (1.5.1)

then you’re fine.

If the answer is

Successfully installed paho-mqtt-1.5.1

then it wasn’t installed yet but is now.

Have you activated MQTT in Pi3D PictureFrame?

In configuration.yaml, you need to activate MQTT.

This line activates the use of MQTT in Pi3D:

  use_mqtt: True

Have you specified your MQTT server?

In configuration.yaml, you need to specify your MQTT server.

If you have installed Mosquitto on your local Raspberry Pi, just enter the IP address of your system. If you are using an external Cloud-based MQTT server, enter the URL like “mqtt.eclipse.org“

  server: "your_mqtt_broker"    #"localhost" or something like 192.168.178.50 (without quotes)

If you are using a local MQTT server, you don’t have to change anything in the next lines, unless you have specified a user and a password.

For any external server, enter the port and login credentials.

  port: 1883
  login: ""
  password: ""

Have you installed Mosquitto?

If you have specified a local MQTT server in your Pi3D config script, have you already installed Mosquitto?

Enter

sudo apt install -y mosquitto mosquitto-clients

This will either install Mosquitto or tell you that it is already installed.

mosquitto-clients is already the newest version (1.5.7-1+deb10u1).

Use MQTT Explorer to listen to the MQTT traffic

Whenever I am experimenting with MQTT, I launch a little app called MQTT Explorer to send and listen to MQTT messages.

MQTT is a free MQTT client written by Thomas Nordquist and available for Windows, macOS, and Linux.

Just connect to your local or remote broker, and you will see everything that happens.

If you are you using PiHelper or DashMQTT, you can immediately verify if messages are being sent and what their payload is.

It is an excellent tool for testing and debugging. Thanks, Thomas!

Listen on the command line

If there is a particular command that just doesn’t work, listen to MQTT on the command line of your Raspberry Pi by typing e.g.

mosquitto_sub -h localhost -v -t homeassistant/switch/picframe_paused/set ON

In this example, you will listen to the topic “homeassistant/switch/picframe_paused/set”, and any payload that you send e.g., via MQTT Explorer will be shown, like “ON” here:

pi@pi4:~ $ mosquitto_sub -h localhost -v -t homeassistant/switch/picframe_paused/set
homeassistant/switch/picframe_paused/set ON

Check your spelling of the topics

A classic mistake, but it’s always hard to spot your own typos. Is it “frame/paused” or “fram/paused”?

Also, did you set the “/” correctly?

It’s “frame/paused” not “/frame/paused”.

Conclusion

I hope you were able to quickly locate the issue that was preventing you from deploying MQTT successfully on your system.

If you have made another mistake that is not covered here or have found a better method for spotting bugs, please let me know.

My experience is that as soon as you understand MQTT, you will come up with a lot of applications where you can put it to use. Be it for automating tasks, maintenance, system warning, information, or just plain fun.

Click here to see all the articles featuring MQTT on this website to get some inspiration.

Thank you for your support and motivation.