Rate this page:

How to Debug MQTT Connections

We strongly recommend first confirming access to your target broker using interactive tools you can run on your computer before you implement MQTT on Microvisor. This will help you resolve any issues that may emerge with your broker's security settings, and help you be sure you have all the files you will need to provide to Microvisor so that it can encrypt data sent to your broker and to authenticate. It is easier to do this ahead of time in an interactive environment like a shell rather than a non-interactive one, such as Microvisor’s logging facility.

If you are new to MQTT, we recommend reading HiveMQ’s MQTT Essentials guide to introduce yourself to the protocol and how it works.

To proceed, you will need to install the Mosquitto suite of tools locally. You can find instructions for your preferred platform – Windows, various Linux distros or Mac – at the Mosquitto site.

First, check that you can access the broker, and both publish and subscribe to a topic you know that it makes available for testing. Many third-party brokers offer just such a topic to help users debug their setups. We have used a couple of these testing services in the examples below.

First use the mosquitto_pub command line tool. At its most basic, you will need to supply your broker's hostname, port, a topic to publish to, and a message. These arguments are added with the -h, -p, -t, and -m flags, respectively. For example:

mosquitto_pub -h -p 1883 -t kw-test-topic/1 -m "Zarjaz, Earthlings!"

In the case of HiveMQ’s test broker, this will create the topic (if it doesn’t exist already) and post the message to it. If there are no errors, mosquitto_pub will exit cleanly.

With the test topic in place, you can subscribe to it with mosquitto_sub. This uses similar flags to those provided by mosquitto_pub but will not exit. Instead it will display messages published to the subscribed topic. Run mosquitto_sub in a new window or tab:

mosquitto_sub -h -p 1883 -t kw-test-topic/1

Now you can switch back to your previous command line window and run mosquitto_pub with a new message, which you will see printed by mosquitto_sub.

The examples above use an unencrypted and unauthorized service. To see how an encrypted service operates, you can use the broker at

Working with encryption and authentication uses other mosquitto_pub and mosquitto_sub flags; which you use will depend on your own broker's requirements:

Flag Argument
-u Your broker account username
-P Your broker account password
--cafile The path to a Certificate Authority file. This is the certificate of the CA that has signed the broker’s server certificate and may be provided to you by the broker
--cert The path to your X.509 client authentication certificate
--key The path to the client key use to sign your certificate

Typically, secured MQTT connections use port 8883, set using the -p flag.

These keys and certificates are the ones you will upload as secrets to the Microvisor cloud from where Microvisor system calls can retrieve and apply them to secure MQTT communications from the device. Our MQTT demo includes code that shows you how this can be done.

Download the CA file here. You will also need to generate a client certificate and key as outlined here. This makes use of OpenSSL, which you will need to have installed on your system.

With the CA file, client certificate and client key stored locally, run

mosquitto_sub -h -p 8884 -t 'kw-test/1' -v --cafile --cert client.crt --key client.key

In a new command line window or tab, run:

mosquitto_pub -m "Zarjaz, Earthlings!" -h -p 8884 -t kw-test/1 --cafile --cert client.crt --key client.key

If your command line is not at the directory containing your certificates and key, you will need to replace the filenames included in the above command with paths to those files.

You will be using a different broker, but the example above illustrates the components you will need to gather for encrypted communications. Your broker may also require you to authenticate access using a username and password combination. These values are passed in using the -u and -P flags, respectively.

Finally, there are three versions of MQTT in use today: 3.1, 3.1.1 and 5.0. Your broker may use one any of these. By default, mosquitto_pub and mosquitto_sub are set to use 3.1.1, but if you need to specify either of the others, use the -V flag with 31 or 5 as the argument (or 311 if you wish to state the default explicitly).

Microvisor supports only versions 3.1.1 and 5 (see How to Issue MQTT Requests Under Microvisor).

Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

Thank you for your feedback!

Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

Sending your feedback...
🎉 Thank you for your feedback!
Something went wrong. Please try again.

Thanks for your feedback!