Skip to contentSkip to navigationSkip to topbar
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.



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(link takes you to an external page).

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:

-uYour broker account username
-PYour broker account password
--cafileThe 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
--certThe path to your X.509 client authentication certificate
--keyThe 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(link takes you to an external page) includes code that shows you how this can be done.

Download the CA file here(link takes you to an external page). You will also need to generate a client certificate and key as outlined here(link takes you to an external page). 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: