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 broker.hivemq.com -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 broker.hivemq.com -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 test.mosquitto.org.
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 test.mosquitto.org 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 test.mosquitto.org -p 8884 -t 'kw-test/1' -v --cafile mosquitto.org.crt --cert client.crt --key client.key
In a new command line window or tab, run:
mosquitto_pub -m "Zarjaz, Earthlings!" -h test.mosquitto.org -p 8884 -t kw-test/1 --cafile mosquitto.org.crt --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).