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.

A note if you run picframe3. Most of the checks below are about the old pi3d PictureFrame and its configuration.yaml, which picframe3 does not have. On picframe3 there are only three things to check, and the first two are on the Settings page of the frame's own web interface: is MQTT switched on, and is the host right. The third is that MQTT settings only take effect after a restart, which the Settings page says and offers to do for you. Then run picframe3 doctor, which checks the broker connection along with everything else and prints what to do about it. Its topics are picframe/picframe/… by default — <topic_prefix>/<device_id>/… — and because it uses Home Assistant auto-discovery, there is no hand-written YAML on the Home Assistant side that could be wrong.

The sections on Mosquitto, on paho-mqtt, and on MQTT Explorer below apply to both.

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

pip install paho-mqtt

(That used to read just install paho-mqtt, which was a typo on my part and does nothing. It needs pip.)

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)

(That python3.11 is whatever Python your virtual environment was built with — Bookworm's. On Trixie it will say python3.13. Either is fine.)

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 its address here.

I used to name mqtt.eclipse.org as the example, and CloudMQTT elsewhere on this site. Both are gone — the Eclipse public broker was retired and CloudMQTT has shut down. I am not going to name a replacement I have not run myself for a year; if you are using a hosted broker, check first that it is still operating. For a picture frame there is very little reason to use one at all: a local Mosquitto on the frame's own Pi is a two-command install, keeps your photo library's metadata off somebody else's server, and cannot go out of business.

  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).

The exact version does not matter — deb12 there just means Bookworm; on Trixie you will see a deb13 build with a higher version number. What you are looking for is the words “already the newest version”.

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

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 “picframe/pause” or “picfame/pause”?

Also, did you set the “/” correctly? A leading slash is a different topic: picframe/picframe/pause/set is not the same as /picframe/picframe/pause/set, and the broker will happily accept both and match neither to the other.

The easiest way to settle it is not to type the topic at all. Subscribe to everything with mosquitto_sub -h localhost -v -t '#', or open MQTT Explorer, and read the topic your frame is actually publishing on off the screen. (I used frame/paused as the example here for years, from my own hand-rolled scripts. pi3d PictureFrame uses picframe/… and homeassistant/switch/picframe_…; picframe3 uses picframe/picframe/…. Which is rather the point — look, don't guess.)

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.