There are more Cloud Services out there for IoT Device than you can shake a stick at, but some users may prefer to “go off grid”. There can be several reasons for this. Maybe your IT department will not allow outgoing connections to services like AWS, Azure, Google, etc. If you happen to have a good server on site and the development staff to build a Cloud specific for your application. This means there are no use service fees to 3rd party services and you have full control over how your data is aggregated and consumed. In this article we will walk through connecting the MQTT Gateway to Mosquitto which is a fully functional MQTT Broker and can even be used as an MQTT Client for diagnostic purposes. There are of course other MQTT Brokers out there you can install but Mosquitto definitely seems to be the standard.
What can I install it on?
Mosquitto can be installed on nearly any computer as long as it runs Linux, Mac, or Windows. Many users run it on devices as small as a Raspberry Pi.
Mosquitto is a full fledged MQTT Broker with handling for Security built right in. Setup Client authentication to Open, Basic, or fully functional TLS with x.509 certificates. This means you can make your Mosquitto Broker as Open or secure as you want. Don’t think Mosquitto is not secure, it is just as secure as any of the main stream cloud services. You can view more on Mosquitto TLS on the manual page here.
Keep in mind a full Cloud server consists of many parts. The MQTT Broker and Clients are just a part of that system. MQTT in itself is a communication protocol commonly used to communicate data between peers. It does not have any sort of logging or automation capabilities. Think of it like HTTP. It can get data from Point A to B in a structured and very playable way. MQTT is what IoT is built on. All major cloud services use MQTT to communicate data from clients to other clients or other applications such as data bases.
It is not the intent of this article to explain how to consume data received over MQTT. We will put out another article later on where we will pull data from the MQTT Broker and log it to a data base, or perhaps perform some automation tasks.
Mosquitto MQTT Installation and Initial Setup
Installation of Mosquitto varies between different operating systems. However it can be installed on Linux, Mac, and Windows. Visit the Official Download Page to install the proper version for your OS.
Once installed you should have access to Mosquitto through your terminal. Starting it up should be as simple as entering mosquitto in your terminal. This is the simplest way to launch the Mosquitto broker on your computer. You can however specify a configuration file to use which configures settings for the Broker such as authentication. We’ll leave it to the Official Documentation page for Mosquitto to explain more on that. Once you dig into how configurable Mosquitto is you will see it really is a “heavy duty” tool.
Start the Mosquitto MQTT Broker
If you have not already to ahead and start the Mosquitto Broker by entering the following in your terminal:
That will simply start the Mosquitto Broker on your computer. Leave this Terminal Open
Connect an MQTT Client to the Mosquitto Broker and listen for data
Open another terminal window. In the second terminal enter the following:
mosquitto_sub -t 'Important_Messages'
This command will connect an MQTT Client on your computer to the Mosquitto broker also running on your computer. Since both the Broker and the Client are on the same computer we don’t have to tell Mosquitto much about what we want. However we are telling the Mosquitto broker that we are interested in messages that come through the Topic Important_Messages. This means we will now receive a payload whenever any other client publishes to the Important_Messages topic. Pretty sweet huh? Keep this terminal open also.
Publish a Message
Now in a new terminal (Yes you should have 3 open now) enter:
mosquitto_pub -t 'Important_Messages' -m 'This is an Important Service announcement, Mosquitto is working'
You’ll see in that Subscribe terminal you opened that you received a message. Congratulations you have Mosquitto running properly on your computer.
MQTT Gateway Setup
Now that the Mosquitto MQTT Broker is running on your computer we’re ready to start feeding some meaningful data into it. To do this we will connect an MQTT Gateway up to it.
The MQTT Gateway will receive wireless transmissions from our Enterprise Line of products. When the gateway receives these wireless transmissions from the sensors it will parse the packet converting it into a JSON object and then it will publish that JSON object to an MQTT Topic relative to that particular sensor. So lets get it setup.
I recommend opening the Setup Guide for The MQTT Gateway. That guide goes into great detail on the setup of the Gateway.
You’ll need to enter the network credentials for the WiFi Network you want it to connect to. For our testing purposes connect it to the same WiFi Network as the computer running Mosquitto.
Next you you’ll want to tell it what MQTT Broker it should connect to. For this enter the IP address of the computer running Mosquitto into the Server Settings IP field(leave the Domain field blank). Also enter something for the Client ID field (something as simple as Gateway will work for now). Lastly Mosquitto by default listens For MQTT Client connections on port 1883 so be sure that is what is entered in the Port field(it should be by default).
Take a look at Message Settings, this will allow you to customize the Topics the Gateway reports sensor data to as well as how the message data is formatted. More information is available in The MQTT Setup Guide.
Once you have settings entered as desired click the Save Settings button on The MQTT Gateway. It will reboot, connect to the WiFi Network, and attempt to connect to The MQTT Broker with the information you have entered. If all goes as expected after a few seconds the LED on the Gateway should turn solid Green. If it does you’re all good to proceed to the next step. If for some reason it has problems the LED may flash Red. If this is the case double check the information you entered in the Gateway. If all settings appear correct then make sure something like Windows Firewall/Defender is not blocking the connection. By default Windows will not allow incoming connections so you may need to open up port 1883 which is the default port Mosquitto accepts client connections.
Monitor the Messages coming from The MQTT Gateway
Now right now the Subscriber you have running in the terminal window is listening for messages being published to the Important_Messages topic, however that is not the Topic the Gateway is publishing messages to so let’s correct that.
MQTT supports a scheme called Wild Cards for subscribing to topics. Topics can be constructed in a nested scheme like this: Gateway_ID/Sensor_ID. By default this is how your MQTT Gateway will publish messages. Now if you have 30 sensors hooked up to the same Gateway it could be a bit of a pain to create an MQTT subscription for each of those messages. Instead we can leverage a Wild Card Subscription on MQTT. Something like Gateway_ID/#. To subscribe using a Wild Card you just use the ‘#’ symbol. In fact you can subscribe to literally everything if you like. To do this cancel your current subscriber for Important_Messages by just canceling the task running in that window (Press CTRL+C). Then enter this command in that terminal:
mosquitto_sub -v -t '#'
Notice we added the -v flag in the command this time. That will cause the topic as well as the message to be printed to the terminal. This is very handy for diagnostics and learning. Go ahead and press the reset button on one of your sensors. You should see something like this roll into the terminal window running that wild card subscriber:
There are two parts here. The first part you will see is the Topic this message was published to. In this case it is:
The second part listed in the terminal is the message payload. In this case it is:
If you look at the message settings in The MQTT Gateway(I’m using the defaults) you’ll see this matches up to what is entered there. So lets say we wanted to subscribe to all sensor readings that are coming through this particular gateway. To do that you would enter this in the terminal:
mosquitto_sub -t 'gateway/30:AE:A4:DA:3F:BC/sensor/#'
Notice we didn’t add the -v flag this time. We just want to see the message payload since we now have an understanding of how the Topic works and that information is irrelevant. Using the # wild card indicator we can now get all sensor readings published by this gateway.
Conclusion and Next Steps
So by this point you should have a good understanding of how MQTT works and how to setup our MQTT Gateway with Mosquitto. I recommend reading more about Mosquitto and securing the system using Basic Auth or TLS. Mosquitto has some great documentation on the Mosquitto Documentation Site. Head over there and learn all you can about it’s capabilities.
This really is just the first step in creating a fully functional Cloud. You’ll still want to do something with this information like display it to users in software, log to data bases, or possibly perform some automation tasks, but the great thing is you have taken the first step and you are using the Industry Standard for IoT device communication.