WHAT IS MQTT? MQTT (Message Queue Telemetry Transport) is a simple and ‘lightweight’ way for internet-connected devices to send each other messages. This is important for home-automation because devices need to send messages back and forth like ‘turn on the lights’ or ‘turn off the sprinklers.’ Devices using MQTT communicate by publishing data to topics. MQTT devices subscribe to a topic, and when data is published to that topic it is pushed to all the subscribers.
Gidday, Michael here from Core Electronics once again, welcome back to the lab. Today we are going to be setting up a simple MQTT program on the Raspberry Pi. So let’s just jump into it. First we need to download some tools for MQTT, so we can use pip for that, if you’re running pixel pip should already be installed. Pip is a package manager for python. So we’re going to run sudo pip install paho-mqtt and we’ll see that doing it’s thing - OK that is successfully installed. We can close that terminal and in your documents folder, that’s where we are going to keep our scripts today. I’ve already copied them from our tutorial and included them in our documents folder so lets just open that up and we’re just going to have a quick look at the code. Just to get a better understanding for it. This is the client, the MQTT client that’s going to run on our Raspberry Pi. Just ignoring all the centre text here, the first command is to import the mqtt client structure from the package that we just downloaded. So that’s where I’m putting that and we’re calling it mqtt. Ignoring the definitions here our code is just this bottom part here and all it’s really doing is setting up a client suite with, we’re creating a variable or an object called client and we’re invoking our mqtt package so client is being defined as an mqtt client object. The next 2 lines of code we’re just attaching some routines to the client object, so an mqtt client object, which we’ve called client, this full stop represents sub-routines that can be called and they’re standardised so any time that the client does something like connect to a server or receive a message, whatever we attach is what is going to be called and in this case we’re attaching a routine we’ve written called on_connect - that’s this top routine here.
The same is true for client_on_message, we’re attaching our own routine called on_message. So just to reiterate every time the client makes a connection, the on_connect routine is called and very time a message is received the on_message routine will be called. Then after just attaching those objects we’re going to have our client connect to the test.mosquitto.org and there’s a few port and I think time out characteristics there as well. Once it’s connected it just loops forever, this is also just another built in function of the paho-mqtt package. So the actual script that runs is quite short,the power of this script comes from the functions that we write that we attach to the client object. The on_connect routine that we write, all we’re saying is that we, we’re printing the result code so essentially that is just a status code that we can get at the terminal to tell us if we successfully connected or not and then on the connection we’re subscribing to 2 topics and here I’ve just called them CoreElectronics/test and CoreElectronics/topic. This means that every time we re-connect it will re-subscribe to these topics, this handles things if we lose connection for instance. The on_message callback that we have here, all we’re doing in this is printing the topic name for any incoming data and then we’re printing any data that was, that’s known as the payload.
That’s just for a bit of fun so we can see the raw data that comes through and what topic it’s coming through on . After that we do a little bit of string comparing, we’re checking the payload to see if its equal to some predefined strings and if that is the case we can choose to execute some other code. In this case all I’m doing is printing to the shell but this could be anything, this is where the home automation comes in. This could be turning on some lights, turning on a pool pump, turning on the air conditioner, whatever you like. Thats the kind of thing that would sit in these parts of the code. So that’s the client, let’s have a quick look at the publish code. This is the publish demo and just as before we’re importing something from the paho-mqtt package we’re importing a publish library and all that is happening here is that we area publishing two messages, so we’re publishing the text hello to one of the topics and we’re publishing the message world to another topic. So we’ve got CoreElectronics/test and CoreElectronics/topic. The host name is just the serve that we would like to use and this of course has to be the same host that we connected to in the client script. So let’s give this a quick run just to see how it works. I’m just going to minimise these and open up terminal, so this left terminal is going to be representative of our own Raspberry Pi, this is going to be the local machine for instance. Lets just navigate to documents and I want to run the client demo so we execute python mqtt client_demo.py and we’ve connected with result code 0 so that means we’ve successfully connected. If you get anything else here you might want to check that you’re connected to the network correctly and that the network is connected to the internet. So that is setting up the client, it is currently running and is looping forever. Now I’m going to open up another terminal and this terminal could be representative of any internet connected device.
So even though at the moment it’s running on the same Raspberry Pi this could be another Raspberry Pi across the planet, it could be another computer, a SparkCore for instance or a Particle so this is just for this demonstration to keep it simple but this could be absolutely anything, anything that could publish to a mqtt topic. So again lets change directories into documents and lets run the publish code that’s python mqtt publish_demo.py and we can see that the script finished successfully and over on the first terminal we can see something happening. So we got our connection, that was when we ran the client code and then it was looping for ever and then when something was published we got though the on_message received callback. So it’s printing the topic that it received data on and it’s printing the data and because hello was one of our predefined strings that we’re comparing to - remember hello was one of the strings that we are comparing that if the payload is equal to hello we want to print receive message #1 do something and that is exactly what came up. The same thing happened again for the data world coming in on the other topic we received message #2 so we did something else.
So that’s basically it, this is now a functioning mqtt client that we can have execute code conditionally based off the data it receives. Just out of a little bit of interest we can use Control C to end that script, I’m just going to clear the console and lets edit our client demo. Let’s change this world to hello core and save that, so now the string has changed - the string that we’re comparing to has changed. If we’re using the up arrow key, if we re-run the client demo and we can see that it’s connected successfully and if we up arrow key again we can publish to that and this time the output has changed a little bit. We still get hello and we still receive message # 1 so we can execute some code but then we received the data world! on the upper topic but we haven’t actually received message # 2 - we don’t execute the upper code and that’s because the publish demo is always publishing world and we just changed our client to compare for Core. So because the incoming data is world and not core we’re not actually executing the print receive message to do something else, we’ve only receive message # 1 so we’re only doing one of the tasks that are possible.
That is essentially it, so by now you’ve got the basic building blocks to create an mqtt client and also to publish to it but from another device. Because we’re running python this code should be able to run on many many different platforms. So that should be a useful tool to get you started with doing some home automation projects. As always if you have any questions you can hit us up in our forums or comment on the tutorial post :-)