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.
Was this article helpful?
Thank you for your support and motivation.
Related Articles
- How to use the DashMQTT Android app to remote control your Raspberry Pi photo frame
- How to effortlessly select different image folders in Pi3D PictureFrame via mobile phone or voice
- How to use the free PiHelper iPhone app as a remote control for your Raspberry Pi picture frame
- How to adjust the default time setting of PictureFrame in Home Assistant