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 connecting Internet of Things (IoT) systems like digital picture frames.

In many articles on this website, I have used 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 operate, but occasionally, 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 you forgot.

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

Check security settings

The default configuration was changed to enhance security in December 2020 with the release of Mosquitto version 2.0.0.

Before this version, the broker allowed anonymous connections by default.

Starting with version 2.0.0, anonymous access is disabled unless explicitly enabled in the configuration file. This means that, by default, clients must authenticate to connect to the broker, or you have to allow it expressively that an anonymous user can connect.

To do this, check the config file and amend

sudo nano /etc/mosquitto/mosquitto.conf

If these two lines

allow_anonymous true
listener 1883 0.0.0.0

are not included, add them at the end of the file.

Restart Mosquitto with

sudo systemctl restart mosquitto

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 (in the virtual environment of picframe)

source venv_picframe/bin/activate

install paho-mqtt

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

Requirement already satisfied: paho-mqtt in ./venv_picframe/lib/python3.11/site-packages (2.1.0)

then you’re fine.

If the answer is

Successfully installed paho-mqtt-2.1.0

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.

This is the standard that I use:

mqtt:
  use_mqtt: True                         
  server: "localhost"              
  port: 1883                              
  login: ""                          
  password: ""               
  tls: ""             
  device_id: "picframe"                   
  device_url: ""                   

If you have installed Mosquitto on your local Raspberry Pi, enter the IP address of your system or “localhost”. The latter is more manageable because your IP address can change.

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)

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 it has already been installed.

mosquitto-clients is already the newest version  (2.0.11-1.2+deb12u1).

Use MQTT Explorer to listen to the MQTT traffic

Whenever I experiment 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.

Connect to your local or remote broker, and you will see everything happening.

If you are 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 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 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 prevented you from successfully deploying MQTT 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 many applications that you can 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.