[GUIDE] Communicate between iOS and Raspberry Pi using MQTT

[GhostRaider]

Table of Contents
1. Introduction
2. The Basics of MQTT
3. Set Up the Mosquitto MQTT Server
4. Testing the Mosquitto MQTT Server Installation
5. Create an App on iOS using Swift
6. Testing the iOS MQTT app using Simulator
7. Create a program on Raspberry Pi using Python
8. Testing the communication between iOS and Raspberry Pi using MQTT
9. What's Next?

Introduction

Let's say that you have an LED connected to a GPIO pin and you want to turn it on and off. One way to solve this problem is to use a button. You connect a button to another GPIO pin. From here, you would create a program that detects changes in the button's state and determine whether to turn the LED on or off. This gets the job done!

However, what if you were far away from that button? It would be a hassle to walk back to the Raspberry Pi and press the button to turn the LED on or off. Wouldn't it be nice if you could just turn the LED on or off remotely from a portable device like an iPhone or iPad? If so, you're in the right place!

In this guide, I will talk about how you can establish a connection between an iOS device and a Raspberry Pi so you can do stuff like controlling GPIO pins remotely. Since this guide will go in depth, you will need to get your hands dirty which means that you will be required to code. Don't worry, the code will be provided but the main goal is for you to understand how to implement such task manually instead of relying on someone else to do it. Raspberry Pi is of course a great platform to learn about programming and to stimulate ideas.

Let's begin!

The Basics of MQTT

MQTT is a popular lightweight messaging protocol used by Internet of Things (IoT) devices. Since this is a lightweight protocol, very little power is used. The idea is simple. The MQTT architecture is made up of clients and an MQTT server (sometimes referred to as MQTT broker). The clients are the devices connected to the MQTT server.



For this guide, an iOS device and a Raspberry Pi will be our clients. These clients will connect to the MQTT server. The question is, who is the MQTT server?



This might sound weird, but the Raspberry Pi is the MQTT server. In other words, the Raspberry Pi is a client and is the MQTT server at the same time. It will communicate with itself.



But this makes sense. To be clear, the MQTT server is simply a program that will run in the background on the Raspberry Pi. The MQTT server will receive the messages sent by the clients and send them to other clients connected to the MQTT server. A client that sends messages is known as a publisher. A client that receives messages is known as a subscriber. Each message sent by a publisher contains a topic. A subscriber that is subscribed (or signed up) to that topic will receive the message. For this example, let's assume that the publisher is the iOS device and the subscriber is the Raspberry Pi. The message created by the publisher has the topic of "resetGPIO" and the Raspberry Pi is subscribed to the topic "resetGPIO".



As you can see from the top image, the iOS device is the publisher. It sends a message with a topic of "resetGPIO". This message is received by the MQTT server. The MQTT server searches for the subscriber that is subscribed to the topic of the message. Since the Raspberry Pi is subscribed to the topic "resetGPIO", the MQTT server sends the message to the Raspberry Pi itself and the message is successfully delivered. Now, what happens if the publisher sends a message with a topic that no subscriber is subscribed to?



The message simply gets thrown out since there is no destination for it.

Since we're on the discussion on sending messages from a publisher to a subscriber, can a client be a publisher and a subscriber at the same time? The answer to that is yes! Let's assume that an iOS device publishes to the topic "resetGPIO" and is subscribed to the topic "sensorData". The Raspberry Pi publishes to the topic "sensorData" and is subscribed to the topic "resetGPIO".



From the top image, the iOS device sends a message with the topic of "resetGPIO" and is received by the MQTT server. Since the Raspberry Pi itself is subscribed to the topic "resetGPIO", the MQTT server sends the message to itself and the message is successfully delivered. The Raspberry Pi sends a message with the topic of "sensorData" and since the MQTT server is running on the Raspberry Pi itself, it sends the message to itself. Since the iOS device is subscribed to the topic "sensorData", the MQTT server sends the message to the iOS device and the message is successfully delivered.

Does it sound confusing? If so, that's fine since we're now going to see what is happening behind the scenes. This should clear things up. For this example, we have two clients that will communicate with each other. The two clients are an iOS device and a Raspberry Pi. The iOS device will run an application that implements the MQTT protocol while the Raspberry Pi will run a program that implement the MQTT protocol.



The iOS application will contain code that implements the publisher and/or subscriber model. The same goes for the Raspberry Pi. The Raspberry Pi program implements the publisher and/or subscriber model. All that is left is the MQTT server program. It makes sense for the Raspberry Pi to run the MQTT server program as well since it is really easy to get it up and running on the Raspberry Pi platform.



The Raspberry Pi is now running two programs, the MQTT server and a program that implements the publisher and/or subscriber model. For the MQTT protocol to work, each client registers itself with the MQTT server program. The client will provide its name, network address, and subscribed topics, if any. When a publisher (client that sends messages) sends a message, the message goes to the Raspberry Pi where the MQTT server will intercept the message. The MQTT server will determine the topic of the message received and search for the registered subscribers (clients subscribed to a specific topic) subscribed to that topic. If the Raspberry Pi itself is subscribed to that topic, then the MQTT server will send the message to the Raspberry Pi itself but now the message will now be received by the Raspberry Pi program instead. This explains why the Raspberry Pi sends messages to itself. It is either to send the message to the MQTT server program or for the Raspberry Pi program to receive the message sent by the MQTT server.

The last thing that you might be wondering is, what exactly does a message contain? Very simple, a topic and a message! But from a coding perspective, the topic and message are simply strings like "1234567890" or "online" or "true" or "tv is on".

That's it for the basics of MQTT! If you are still interested in using MQTT and want to lean how implement it, continue to read on!

Set Up the Mosquitto MQTT Server

We will be installing the Mosquitto MQTT server on the Raspberry Pi. There are two choices. You can either build the latest version of Mosquitto MQTT server from Eclipse Mosquitto or download an older stable release from the Mosquitto Debian repository. Regardless of your choice, both will work for this guide.

OPTION 1: Stable Release from Mosquitto Debian Repository

First, you must import the Mosquitto repository package signing key. Run these commands in Terminal:

Code: Select all

wget http://repo.mosquitto.org/debian/mosquitto-repo.gpg.key
sudo apt-key add mosquitto-repo.gpg.key

You need to change the working directoy of Terminal to add the repository. Run the command:

Code: Select all

cd /etc/apt/sources.list.d/

Next, add the repository to apt so that you can use it to download Mosquitto. Choose the appropriate command depending on the version of Raspbian you're using and run it:

Raspbian Wheezy

Code: Select all

sudo wget http://repo.mosquitto.org/debian/mosquitto-wheezy.list

Raspbian Jesse

Code: Select all

sudo wget http://repo.mosquitto.org/debian/mosquitto-jessie.list

Raspbian Stretch

Code: Select all

sudo wget http://repo.mosquitto.org/debian/mosquitto-stretch.list

Update apt by running the command:

Code: Select all

sudo apt-get update

Install Mosquitto MQTT server by running the command:

Code: Select all

sudo apt-get install mosquitto

You may get an error saying that some packages are missing. This error mostly appears in Raspbian Stretch installations. If so, the packages required for Mosquitto are libwebsockets3 and libssl1.0.0. You will need to install these packages manually in Raspbian Stretch. Follow the instructions below. Otherwise skip the 6 steps listed below if you do not have this problem.

1. Change the working directory to your home folder by entering the command below:

Code: Select all

cd

2. Download libssl1.0.0 using the command below:

Code: Select all

wget http://security.debian.org/debian-security/pool/updates/main/o/openssl/libssl1.0.0_1.0.1t-1+deb8u7_armhf.deb

3. Install the libssl1.0.0 debian file using the command below:

Code: Select all

sudo dpkg -i libssl1.0.0_1.0.1t-1+deb8u7_armhf.deb

4. Download libwebsockets3 using the command below:

Code: Select all

wget http://ftp.us.debian.org/debian/pool/main/libw/libwebsockets/libwebsockets3_1.2.2-1_armhf.deb

5. Install libwebsockets3 using the command below:

Code: Select all

sudo dpkg -i libwebsockets3_1.2.2-1_armhf.deb

6. Try to install Mosquitto MQTT server again using the command below:

Code: Select all

sudo apt-get install mosquitto

Are links not working? Please let me know so I can update them!

That's it! Mosquitto MQTT server should now be installed! Now read "Testing the Mosquitto MQTT Server Installation" section below to test the installation.

OPTION2: Latest Release from Eclipse Mosquitto

We will compile the Mosquitto MQTT server source code from Eclipse Mosquitto. Before you continue, make sure that the Raspberry Pi has the "build-essential" package installed. This pacakge is necessary to compile programs from source. Most newer releases of Raspbian and Raspbian Lite already include "build-essential" package. If you are not sure, simply run this command in Terminal:

Code: Select all

sudo apt-get install build-essential

It will either tell you that you want to install the package or the package is already installed. If it is not installed, install it.

Now, change the working directory to your Home folder by running this command in Terminal:

Code: Select all

cd

We are now ready to download the latest Mosquitto MQTT server. Run this command in Terminal:

Code: Select all

wget https://mosquitto.org/files/source/mosquitto-1.6.2.tar.gz

*If the link does not work, make sure to change the version number to the latest release. Any other Terminal command down below may refer to an older version number, so change the version number to the latest version as well. Official releases of Eclipse Mosquitto are found here: https://mosquitto.org/download/

An archive file named "mosquitto-1.6.2.tar.gz" will be found in your home folder. Extract the contents of this archive file by running this command:

Code: Select all

tar xavf mosquitto-1.6.2.tar.gz

Now, change the working directory to the Mosquitto folder. If your Terminal is already pointing to your home folder simply use this command to change to the mosquitto folder:

Code: Select all

cd mosquitto-1.6.2

Before you begin compiling Mosquitto, you need to install some dependencies. Run this command in Terminal and install all required packages:

Code: Select all

sudo apt-get install cmake libssl-dev libwebsockets-dev uuid-dev libc-ares-dev

Assuming that Terminal is already pointing to the Mosquitto folder, simply run this command:

Code: Select all

cmake -DWITH_WEBSOCKETS=ON .

Once Terminal has finished compiling Mosquitto, run this command:

Code: Select all

make -j4

The make file has now been created. Finally, to install Mosquitto, run this command:

Code: Select all

sudo make install

After Mosquitto has been installed, the commands "mosquitto_pub" and "mosquitto_sub" may not work as they are not registered in the linker library cache. To fix that, run this command:

Code: Select all

sudo /sbin/ldconfig

That's it! Mosquitto MQTT server should now be installed! Now read "Testing the Mosquitto MQTT Server Installation" section below to test the installation.

Testing the Mosquitto MQTT Server Installation

Now that Mosquitto MQTT server has been installed on the Raspberry Pi, let's test it!

To run Mosquitto, run the command below:

Code: Select all

mosquitto -v

The "-v" flag simply means verbose mode, where Mosquitto MQTT server will print out any activity that is currently happening. If you see the screen above, it means that Mosquitto is working correctly!

However, if you get "-bash mosquitto: command not found" instead, it means that your user account is not authorized to execute commands from /usr/local/sbin. The fix is simple. You need to add "usr/local/sbin" to PATH. In Terminal, change the working directory to your home folder. Then run the command:

Code: Select all

nano .bashrc

Add this code at the bottom of your .bashrc file:

Code: Select all

export PATH=$PATH:/usr/local/sbin

Once you have made those changes, save the file and reboot your Raspberry Pi. The "mosquitto" command should now be working!

At anytime, to terminate the Mosquitto MQTT server, press CTRL+C on the Terminal window. Now that the Mosquitto MQTT server is installed and running correctly, all that is left is to create an application for iOS and to create a program for Raspberry Pi that implements the MQTT protocol. Then you will see what the MQTT protocol can really do! If you are up for the challenge, let's continue!

[GhostRaider]

Create an App on iOS using Swift

In order to create an app for iOS, you would need to use the macOS operating system whether it'd be on a Mac computer or a PC running macOS. The software used to create iOS apps is called Xcode and the programming language that will be used to code the app in this tutorial is Swift. You don't really need a physical iOS device to test the application since if the app works in simulation, then running the app on a real iOS device will work as well.

Now, if you are not familiar with working with Xcode or Swift, there are plenty of guides out there on the Internet. Probably the best way to learn about iOS app development is through YouTube. In all honestly, it's not that hard to understand. For this guide, we will build a very basic app.

Now, before we dive into coding, we need to figure out what this app will do. Here is a task that a boss has sent us to do:

Create an iOS app that will control an LED attached to the GPIO pin on the Raspberry Pi.

How do you solve this problem? Well let's break it down. We know that we can use the MQTT protocol to send messages from an iOS device to the Raspberry Pi. We know that the iOS device needs to register itself with the MQTT server which means we need some sort of button to connect to the MQTT server as well as a button to disconnect from the MQTT server when we are done. And probably we need some sort of switch on the app to toggle the state of the LED. As for which GPIO pin to control, for this guide, we will focus on GPIO pin 40. In short:

1) Implement the MQTT Protocol
2) Add a button to connect to the MQTT Server and another button to disconnect from the MQTT server
3) A simple switch to toggle the state of the GPIO pin 40

iOS does not have an implementation of MQTT which means we need to rely on an external library. This library is called CocoaMQTT which is designed to work with iOS and macOS using Swift. External libraries are installed by using CocaPods. If this is your first time using CocoaPods, then most likely it is not installed on your computer. To install CocoaPods, run this command in Terminal:

Code: Select all

sudo gem install cocoapods

This is a sample output after installing CocoaPods. Your Terminal window might appear differently and say you have installed more than 1 gem. Regardless, CocoaPods should have installed successfully. Now run this command:

Code: Select all

pod setup --verbose

You should get something similar to this after the command has finished executing. CocoaPods is now ready to use!

Now lets start to create the iOS app. Open Xcode and click on "Create a new Xcode project". On the template window, select "Single View App" and click Next.



For "Product Name", name it anything you want. For "Team", select your Apple Developer account. You can select "None" for now if you don't have one but you will need to add an Apple Developer account later if you want to build and run your app. For "Organization Name" it can be anything. For "Organization Identifier", usually it is prefilled with "com.organizationname". Make sure that "Language" is set to Swift. Click Next.

You will now select where to save the project. For convenience, save it on the Desktop since we will need to use Terminal to attach a CocoaPod to the project. After saving it, close Xcode.

Open Terminal and change the working directory to the project folder on your Desktop. Changing the working directory in macOS Terminal is the same as Linux. Assuming that the Terminal window has your home folder as the working directory, you would use the command:

Code: Select all

cd Desktop/nameofproject

Once your Terminal window has the project folder as the working directory, run the command:

Code: Select all

pod init

This will create a pod file. A pod file is used to add external libraries from the CocoaPods library. Then run the command:

Code: Select all

open -a Xcode Podfile

This will open the pod file using Xcode. We need to edit the pod file to include the CocoaMQTT external library. You should see something similar to this:



Remove line 1 and remove the # symbol on line 2. On the same line, change '9.0' to '10.0'. Remove line 5 and remove line 8. You should now have something like this:



Under "use_frameworks!", add this code under it:

Code: Select all

pod 'CocoaMQTT'

So now your pod file should look something like this:



Save the pod file by going to File > Save. Close Xcode. Go back to your Terminal window or open a new Terminal window. Make sure that the working directory is the project folder on your Desktop. Run this command:

Code: Select all

pod install

If CocoaMQTT library was installed successfully to the project, you should get something like this:



That's it! Now we are ready to utilize the CocoaMQTT library in our project! You can safely move the project folder to wherever you like. To start editing the project, open the project folder. There should be a file called "nameofproject.xcworkspace". Anytime you want to edit the project, you need to click on this xcworkspace file as this contains the workspace need to allow you to access external libraries. Click on the xcworkspace file to open the project.

Let's start by creating the UI of our iOS app. Click on the "Main.storyboard" file on the left sidebar.



The storyboard shows you what iOS device you're working on. At the bottom of the window, you should see a button that says "View as" where it shows the name of the iOS device. You can change what iOS screen size you want the project to be optimized for. In my case, I'm working with iPhone 8 which means it should look the same if I ran it on iPhone 7, iPhone 6 or iPhone 6s. Now let's add the UI elements. We need to add 2 buttons and a switch. We will also have to add a label since we want to know what the switch controls. The elements can be found on the bottom right corner. Scroll through this to find Label, Button, and Switch. Click on the element and drag it onto the view controller. In total, your view controller should have 1 label, 2 buttons, 1 switch.



You can arrange the position of the elements in the view controller to however you want. I decided that I will make the app look like this:



You can edit the attributes of each element. For example click on the label. On the right sidebar you will see the attributes you can change. We know that the switch will control GPIO pin 40. For the label text, I would change it so it says "GPIO Pin 40". You may need to resize the label element if the whole text doesn't fit.



By doing this change, it is clear that the switch is meant to control the state of GPIO pin 40. Do the same for the two buttons. Change the text of the buttons so that one says "Connect" and the other "Disconnect".



We are now done with the app UI! We just need to connect these elements to our code so that we can interact with them. On the left sidebar, click on "ViewController.swift".



This is where we will add the code needed to get the app working so that it can send messages and be able to communicate with the MQTT server. Go back to Main.storyboard and on the top right there is a venn diagram icon. The view will split so on side it shows the storyboard and the other side shows ViewController.swift. You may need to resize the Xcode window to see both views.



The elements that we need to interact with our code are the Connect and Disconnect buttons, and the switch. Click on the switch once. Now, CTRL-Drag the switch to the ViewController.swift file, preferably under the didReceiveMemoryWarning function.



You will see a popup. This popup allows you configure what the switch will do. It can either be an output, or trigger an action when the switch state changes. In our case, we want the switch to trigger an action. Click on the drop down menu on Connection and select "Action". On Name, type a name for the switch button. In this case, call it "gpio40SW". Click on the drop down menu on Type and select "UISwitch". When you are done with the changes, click on Connect to add the function to ViewController.swift.





We will now do the same for the Connect button. Click on the Connect button and CTRL-Drag the button to the ViewController.swift file. The button will trigger an action when it pressed, so on the popup, click the drop down menu on Connection and select "Action". On Name, type "connectButton". Click on the drop down menu on Type and select "UIButton". When you are done with the changes, click on Connect to add the function to ViewController.swift.





Again, we will do the same for the Disconnect button. Click on the Disconnect button and CTRL-Drag the button to the ViewController.swift file. The button will trigger an action when it pressed, so on the popup, click the drop down menu on Connection and select "Action". On Name, type "disconnectButton". Click on the drop down menu on Type and select "UIButton". When you are done with the changes, click on Connect to add the function to ViewController.swift.





We are now able to interact with the Connect and Disconnect buttons, and the switch. Whenever the buttons get pressed or the switch changes states, their functions will get called and the code inside the function will execute. While still in Main.storyboard, on the top right, click the button to the left of the venn diagram icon to return to normal view. Then click on ViewController.swift on the left sidebar. We no longer need to modify Main.storyboard and we now focus on coding the app.



I have cleaned up and commented on ViewController.swift so you can get a better understanding on what is going on. Don't worry about the functions "override func viewDidLoad()" and "override func didReceiveMemoryWarning()". The function "@IBAction func gpio40SW(_ sender: UISwitch)" only executes when the switch state has been changed. If you press the switch button, it will execute since it will toggle the state of the switch from being ON to OFF or OFF to ON. The functions "@IBAction func connectButton(_ sender: UIButton)" and "@IBAction func disconnectButton(_ sender: UIButton)" will execute if their buttons get pressed.

From this point on, you must have an Apple Developer account since we will need to build and run the app. Creating an Apple Developer account is free. It only costs money if you want to submit your macOS/iOS app on the App Store. You can create an Apple Developer account by simply using your Apple ID.

To add an Apple Developer account to your project, click on the top blue icon that has the project name next to it on the left sidebar. Under Signing, click on the drop down menu on Team and select Add an Account.



A window will appear that will ask you to sign in. Sign in with your Apple ID and your Apple ID will be used as the Apple Developer account for your project. Any future projects you make using Xcode will automatically use your Apple ID to build and run the app. Again, all of this is free.



Now Xcode should allow you to build and run the app. Make sure that under Signing, your Apple ID name appears on Team. If not, you may need to manually select it from the Team drop down menu.

Return to the ViewController.swift file. Under the line "import UIKit", we need to import CocoaMQTT so that we can implement the MQTT protocol to our app. Type or copy the code below and add it under "Import UIKit".

Code: Select all

import CocoaMQTT

Now you might get an error saying that the module was not found. This is to be expected because we have not built the project with the new external libraries. Simply go to Product > Build to build the project. While the project might build successfully, you may still have the error show up. This is an Xcode refresh bug but you can get rid of it by retyping "import CocoaMQTT".

The next thing we need to do is instantiate the CocoaMQTT class. Under "class ViewController: UIViewController", type or copy the code below:

Code: Select all

let mqttClient = CocoaMQTT(clientID: "iOS Device", host: "192.168.0.X", port: 1883)

Modify the host string and replace it with your Raspberry Pi's network address.



The variable clientID accepts a string. It is used by the MQTT Server to identify the connected device. The host variable is used to find the MQTT Server on the network and connect to it. The port variable is used to connect to the MQTT Server and the MQTT protocol uses port 1883.

Now, we will write a single line of code for connectButton function. All we want to do when we press the connect button is to connect to the MQTT server. Type or copy the code below and place it inside the connectButton function:

Code: Select all

mqttClient.connect()

We will do the same thing for disconnectButton function. When we press the disconnect button, we want to disconnect from the MQTT server. Type or copy the code below and place it inside the disconnectButton function:

Code: Select all

mqttClient.disconnect()

For the gpio40SW function, we will need to have an "if" statement. We first check the state of the switch. If the switch is in the OFF state, then do something. Else, if the switch is in the ON state, do something else. Now, this is where we also implement the publisher function which includes the topic and the message. We want the Raspberry Pi to receive our messages saying to turn on or off the LED on GPIO pin 40. Type or copy the code below and place it inside the gpio40SW function:

Code: Select all

	if sender.isOn {
            mqttClient.publish("rpi/gpio", withString: "on")
        }
        else {
            mqttClient.publish("rpi/gpio", withString: "off")
        }

The string "rpi/gpio" is the topic and the variable withString contains the message which is "on" or "off".

Overall your ViewController.swift file should look similar to this.



All we need to do now is build our project again to make sure everything is typed correctly and we aren't missing anything. Build the project by going to Product > Build. If you get a Build Succeeded message, you have finished creating an app on iOS that uses the MQTT protocol! Let's see how the app looks like. Most likely you built the app to look good on iPhone 8. We would need to simulate an iPhone 8 and run the app in the simulator. On top, there is a button that should say "iPhone 8".



If you click that button, you will see other devices that you can simulate and see how the app looks in those devices. However, simulating an iPhone 8 is fine. On top, you will see a play button. Click the play button to run the simulator and see how your app looks like!



The simulator is very much alive. This means that if you interact with the Connect and Disconnect buttons, or change the state of the switch, it will start to execute the code you wrote for the app. I think we are ready to do a little test drive!

Testing the iOS MQTT app using Simulator

Now that the simulator is running your MQTT app, let's see what the app does! Go to your Raspberry Pi and open Terminal. Open Mosquitto MQTT Server by running the command:

Code: Select all

mosquitto -v

The Mosquitto MQTT server is now ready to register clients and send/receive messages. On the simulator, press the Connect button. In the Terminal window, you should now see that the iOS app has successfully registered and connected with the MQTT server. It will send/receive ping responses every few seconds to make sure that the connection to the client is still alive.



If nothing happens, double check to make sure that you have typed the correct network address of the Raspberry Pi in your iOS app. Let's see what happens when we turn the switch off.



The MQTT server has successfully received a message that contains the topic "rpi/gpio". The actual message received however will need to be decoded by the Raspberry Pi MQTT program. Finally let's press the Disconnect button.



The iOS device has successfully deregistered and disconnected from the MQTT server. You are now done with your iOS App! All that is left is to create the Raspberry Pi MQTT program to decode the messages and control the GPIO!

[GhostRaider]

Create a Program on Raspberry Pi using Python

Your boss is happy with your progress so far! Our iOS app can send messages to the MQTT server but of course the MQTT server has no destination to send our messages. Let's now focus on our Raspberry Pi. We need to create our Raspberry Pi MQTT program so that the messages sent by the iOS device get delivered and get decoded.

First, we need to install some external Python libraries. The RPi.GPIO library allows us to access the Raspberry Pi's GPIO pins. The Eclipse Paho library allows us to implement the MQTT protocol onto our program.

We begin by installing the Python development tools. Run the command below in Terminal:

Code: Select all

sudo apt-get install python-dev

Install the RPI.GPIO python library by running the command below (newer versions of Raspbian might have this included already):

Code: Select all

sudo apt-get install python-rpi.gpio

We need to install pip to be able to download and install Eclipse Paho library. Run the command below (full version of Raspbian might have this included already):

Code: Select all

sudo apt-get install python-pip

Finally, install the Eclipse Paho library by running the command below:

Code: Select all

pip install paho-mqtt

Now that we have installed all the needed libraries for our Raspberry Pi program, we just need to code it. You can use any Python IDE on your Raspberry Pi to code this program. For this guide, I will be using Geany IDE.



Start with a blank python file. We need to import RPI.GPIO and Eclipse Paho libraries. To do this, type or copy the code below onto your python file:

Code: Select all

#!/usr/bin/env python
# -*- coding: utf-8 -*-

import paho.mqtt.client as mqtt
import RPi.GPIO as gpio

When working with Python, functions are normally declared on top while methods are placed after all functions. Let start by writing a method to call a function that will set up GPIO pin 40 as an output. Type or copy the code below onto your python file:

Code: Select all

gpioSetup()

Now we will create the gpioSetup() function on top of the call method. Type or copy the code below onto your python file:

Code: Select all

def gpioSetup():
	
	gpio.setmode(gpio.BCM)
	gpio.setup(21, gpio.OUT)
	

Now that we have set GPIO pin 40 as an output, we can now implement the MQTT protocol onto our program. First we need to declare variables for our client name and the MQTT server address. Again, declarations and call methods are always placed after function declarations. Type or copy the code below onto your python file:

Code: Select all

clientName = "RPI"
serverAddress = "192.168.0.X"

The string variable clientName can be anything. Remember to modify the string variable serverAddress with your Raspberry Pi's network address.



Now we need to instantiate Eclipse Paho. The parameter that will be passed is the client's name. Type or copy the code below onto your python file:

Code: Select all

mqttClient = mqtt.Client(clientName)

Now we need to set the calling functions to mqttClient. Basically what happens here is when the MQTT program connects or receives a message from the MQTT server, these functions will execute. Type or copy the code below onto your python file:

Code: Select all

mqttClient.on_connect = connectionStatus
mqttClient.on_message = messageDecoder

When mqttClient receives a connect message, it calls the function connectionStatus. When mqttClient receives a message from the MQTT server, it calls the messaeDecoder function. Let's define these functions. Type or copy the code below onto your python file:

Code: Select all

def connectionStatus(client, userdata, flags, rc):
	mqttClient.subscribe("rpi/gpio")

def messageDecoder(client, userdata, msg):
	message = msg.payload.decode(encoding='UTF-8')
	
	if message == "on":
		gpio.output(21, gpio.HIGH)
		print("LED is ON!")
	elif message == "off":
		gpio.output(21, gpio.LOW)
		print("LED is OFF!")
	else:
		print("Unknown message!")

What happens here is when the Raspberry Pi MQTT program connects to the MQTT server, it subscribes to the topic "rpi/gpio" which is the same topic that our iOS app is sending messages to. This means that when we change the state of the switch in our iOS device, it will send the message "on" or "off" with the topic "rpi/gpio". Since the Raspberry Pi will register itself to receive messages with the topic "rpi/gpio" with the MQTT server, the MQTT server will send the message to the Raspberry Pi program and the program will execute the messageDecoder function.

Inside the messageDecoder function, the function will decode the message received and will get a string. The iOS app sends a message of "on" or "off", therefore we use an if statement to check the string. If the string decoded says "on", then the LED connected to pin 40 will turn on. Else if the string decoded says "off", then the LED will turn off. There is also and else statement but for this program, it will never execute.

All that is left is to implement two more methods. Type or copy the code below onto your python file:

Code: Select all

mqttClient.connect(serverAddress)
mqttClient.loop_forever()

Here the method mqttClient.connect(serverAddress) causes the MQTT program to connect to the MQTT server and mqttClient.loop_forever() runs the MQTT program forever and will call the functions connectionStatus and messageDecoder whenever a new message was received or there was a change in the connection to the MQTT server.

Congrats! You have now finished coding the Raspberry Pi MQTT program! Remember to save the python file and check to make sure that there are no spelling errors or anything missing. Else, the program will not work. We will now make the python file an executable file so we can easily run it in Terminal.

Using Terminal, change the working directory to where your python file was saved. In my case, I saved it in my Documents folder. To make the python file an executable, run the command:

Code: Select all

chmod +x nameofpythonfile.py

To run the Raspberry Pi MQTT program, run the command:

Code: Select all

./nameofpythonprogram.py

We get an error! But actually there is nothing to worry about. The most important thing here is as long as you get the error "socket.error: [Errno 111] Connection refused", then it means your Raspberry Pi MQTT program works! But why do we get this error? We get this error because the Mosquitto MQTT server isn't even running for this program to work!

Our journey is almost coming to an end. Now we need to put all the pieces together and let's see what we've accomplished!

[GhostRaider]

Testing the communication between iOS and Raspberry Pi using MQTT

This is it! Your boss is really happy to see that you figured out how to turn on an LED connected to the Raspberry Pi's GPIO pin using your iOS device. Now your boss wants you to demonstrate what you've accomplished!

First, let's run Mosquitto MQTT Server on our Raspberry Pi. Go to Terminal and run the command:

Code: Select all

mosquitto -v

Open another Terminal window. We will run the Raspberry Pi MQTT program. Change the working directory of the Terminal window to where you saved the python file. Since we made the python file an executable file, simply run the command:

Code: Select all

./nameofpythonfile.py

When you run the Raspberry Pi MQTT program, if you look in the Terminal window that Mosquitto MQTT Server is running, you should see that your Raspberry Pi has succesfully registered itself and is subscribed to the topic "rpi/gpio".

Finally, go to your computer running macOS and open your iOS project's xcworkspace file.



Make sure that the correct iOS device to simulate is selected.



For this case, an iPhone 8 will be simulated. Press the Play button to run the iOS app in Simulator.



To establish a connection to the Mosquitto MQTT Server, press the Connect button.



If you go back to the Terminal window where Mosquitto MQTT Server is running, it will say that your iOS device has successfully registered and established a connection with the MQTT server! Now here comes the part we have all been waiting to see!

Go back to the iOS Simulator and press the switch button. If the switch was previously set to ON, then it should now be OFF. If the switch was previously set to OFF, then it should now be ON. Continue clicking on the switch and if you go back to the Terminal windows where the Mosquitto MQTT Server and Raspberry Pi MQTT program are running, you should see some interesting messages!


*Right Click > Open Image in New Tab to see full size image.

You can see from the image on top that the MQTT server has received messages from the iOS device with the topic of "rpi/gpio" and has delivered them successfully to the Raspberry Pi MQTT program which then turns the LED on and off on GPIO pin 40!

After you are done playing around with the iOS app and the Raspberry Pi, disconnect the iOS app from the MQTT server by pressing the Disconnect button. You can now close Xcode and the iOS Simulator. Over on the Raspberry Pi, disconnect the Raspberry Pi MQTT program by pressing CTRL+C on the Terminal window. You can safely close the Terminal window. Terminate the Mosquitto MQTT Server by pressing CTRL+C on the Terminal window. You can safely close the Terminal window.

What's Next?

For this guide, the goal was for users to learn what the MQTT protocol was and how you can implement this protocol into your Raspberry Pi projects for those who use iOS devices. The iOS app and the Raspberry Pi MQTT program demonstrated in this guide are very basic, but it shows you how a simple connection can me made between an iOS device and a Raspberry Pi.

Now, it is possible to make a macOS app that also uses the MQTT protocol to establish a connection from your Mac or computer running macOS to your Raspberry Pi. You can also make an Apple TV app that communicates with the Raspberry Pi. The CocoaMQTT library works on iOS, tvOS, and macOS.

It's really up to you on what kind of communication you want to establish with your Raspberry Pi. There are other features that the MQTT protocol can provide such as authentication and the ability to unsubscribe from topics. Clients can be both subscribers and publishers meaning a client can send data to the Raspberry Pi and the Raspberry Pi can send data to the client. Possibilities are endless.

Hopefully this guide has helped in you in learning about the MQTT protocol and how to implement it from scratch using iOS and Raspberry Pi. I haven't seen a guide like this on the Internet that shows you how to do both of these at same time. The Raspberry Pi is a great little computer!

Resources:
https://github.com/emqtt/CocoaMQTT - CocoaMQTT
https://www.eclipse.org/paho/clients/python/docs/ - Eclipse Paho Documentation
https://mosquitto.org/documentation/ - Mosqutto MQTT Documentation

If there are any questions, comments, suggestions, or concerns, you are free to say down below.

[DougieLawson]

Why are you using a git clone to install Mosquitto. It's better to get the stable version from
https://mosquitto.org/2013/01/mosquitto ... epository/

[GhostRaider]

Why are you using a git clone to install Mosquitto. It's better to get the stable version from
https://mosquitto.org/2013/01/mosquitto ... epository/

When I started researching about MQTT at the time there were some issues of the repository not working after the release of Raspbian Stretch. To avoid the hassle I simply compiled it from GIT and it works. If it was fixed, then I wasn't aware of it. I will add your suggestion to the main guide for those who prefer the stable release. Thanks.

[GhostRaider]

Yes the stable version of Mosquitto has been fixed already so you no longer [hidden spamlink removed in quote] it via GIT. But yes kudos on presenting such an in-depth guide members of the community will really appreciate your work but do mind to place "Note:" somewhere at beginning of the post mentioning they could install it either way now to cut the hassle.

Thank you for your feedback! In the section to install Mosquitto, I did talk about two ways of installing it. Unless its not clear enough to see.

[playmaker1430]

Hello,
Thank You for the awesome GUIDE! You have done a great job in explaining each and every detail.

The connect and disconnect buttons are not working for me, although I am able to use the On Off switch and it displays messages as On and Off in my terminal on Raspberry Pi.
Please let me know what could be the issue. Also when I run mosquitto -v , it gives me an error :Address already in use. If you could also help me fixing this then that would be really great.


Thanks once again for the awesome tutorial.

[GhostRaider]

Hello,
Thank You for the awesome GUIDE! You have done a great job in explaining each and every detail.

The connect and disconnect buttons are not working for me, although I am able to use the On Off switch and it displays messages as On and Off in my terminal on Raspberry Pi.
Please let me know what could be the issue. Also when I run mosquitto -v , it gives me an error :Address already in use. If you could also help me fixing this then that would be really great.


Thanks once again for the awesome tutorial.

Glad to help! Let's get Mosquitto working properly. Did you install Mosquitto using Git and then compiling or did you used the repository? Normally when you get the error saying that "Address already in use", it means that Mosquitto is already running in the background and what you're trying to do is to load Mosquitto again but the address and ports are already in use by the other Mosquitto process.

That could also be the reason why the connect/disconnect buttons don't work too. Though if Terminal is showing that the Raspberry Pi has received the message, then the connect button must have worked or else it shouldn't display such message at all.

[kingofthenorth]

Great tutorial!

Is there a way to send a response back to the iOS app when something has completed (i.e. send response when an upload is finished to update a progress bar?)

Thanks for the effort in making this.

[DougieLawson]

Is there a way to send a response back to the iOS app when something has completed (i.e. send response when an upload is finished to update a progress bar?)

Publish a reply on another MQTT topic. I do that with my Arduino running a temperature sensor. I send a message on arduino/in/readC the arduino is subscribed to arduino/in/# it always sends the reply on arduino/out/sensor1 (in Celsius because I sent the request on readC).

Building your topic heirarchy is the hard part of MQTT design. Subscribing and publishing is trivial (and there's loads of free code to do that on various IoT devices).

[asandford]

Other message queue brokers are available with substantially more functionality; MQTT is a protocol, not a product.

[DougieLawson]

Other message queue brokers are available with substantially more functionality; MQTT is a protocol, not a product.

Eh?

The protocol has a limited number of commands (CONNECT,PUBLISH, etc.) and responses (CONNACK, PUBACK, etc), there's not much more a broker can do without breaking the protocol.

[GhostRaider]

Great tutorial!

Is there a way to send a response back to the iOS app when something has completed (i.e. send response when an upload is finished to update a progress bar?)

Thanks for the effort in making this.

What DougieLawson said is correct. In MQTT, there really is no way of confirming that a message was received from publisher -> subscriber or from subscriber -> publisher. Only from publisher -> mqtt server or subscriber -> mqtt server can receive a delivery confirmation. But, since you already know how to subscribe/publish to a topic, then you can make your publisher client (iOS device) a subscriber as well and the subscriber (Raspberry Pi) a publisher as well. That way, when Raspberry Pi has finished downloading, send a message to iOS device.

So you have to make the Raspberry Pi publish to a topic that the iOS device is subscribed to, and then send the appropriate message like "filedone" or something like that. In iOS, you would have a function that receives messages, decodes it and does a string comparison. So if message == "filedone", then do something.

[asandford]

Other message queue brokers are available with substantially more functionality; MQTT is a protocol, not a product.

Eh?

The protocol has a limited number of commands (CONNECT,PUBLISH, etc.) and responses (CONNACK, PUBACK, etc), there's not much more a broker can do without breaking the protocol.

Of course they can. Things like message storage. AFAIA the protocol doesn't state that only the last message is stored.

[asandford]

Great tutorial!

Is there a way to send a response back to the iOS app when something has completed (i.e. send response when an upload is finished to update a progress bar?)

Thanks for the effort in making this.

What DougieLawson said is correct.

No it's not, other brokers can automatically acknowledge MQTT messages.

[GhostRaider]

Great tutorial!

Is there a way to send a response back to the iOS app when something has completed (i.e. send response when an upload is finished to update a progress bar?)

Thanks for the effort in making this.

What DougieLawson said is correct.

No it's not, other brokers can automatically acknowledge MQTT messages.

How would that work? It's very interesting indeed but how would clients confirm to the mqtt broker that it received the message if brokers aren't allowed to subscribe or publish to anything other than just send messages to their destination? Unless its a modified protocol. I've researched this before, for example someone wanted to create a chat application but wanted to have a feature that the message was received by the other client. The answer was to use a workaround, meaning to use the subscriber/publisher model because you can never confirm that the client handled the message appropriately unless you manually check that message from the client side.

[axopax]

Hey,

Thanks for the great tutorial. I just had a few issues I wanted to verify.

After i wrote make in the mosquitto terminal, I got so many warnings. Mainly :

../lib/tls_mosq.c:130:5: warning: ‘ASN1_STRING_data’ is deprecated [-Wdeprecated-declarations]
data = ASN1_STRING_data(nval->d.dNSName);
^~~~

Second, when I added the "mosquitto -v" command, I got :1516409129:

mosquitto version 1.4.14 (build date 2018-01-20 00:39:52+0000) starting
1516409129: Using default config.
1516409129: Opening ipv4 listen socket on port 1883.
1516409129: Error: Address already in use

Could you please help as I am a beginner

[axopax]

Hey,

Thanks for the great tutorial. I just had a few issues I wanted to verify.

After i wrote make in the mosquitto terminal, I got so many warnings. Mainly :

../lib/tls_mosq.c:130:5: warning: ‘ASN1_STRING_data’ is deprecated [-Wdeprecated-declarations]
data = ASN1_STRING_data(nval->d.dNSName);
^~~~

Second, when I added the "mosquitto -v" command, I got :1516409129:

mosquitto version 1.4.14 (build date 2018-01-20 00:39:52+0000) starting
1516409129: Using default config.
1516409129: Opening ipv4 listen socket on port 1883.
1516409129: Error: Address already in use

Could you please help as I am a beginner

[GhostRaider]

Hey,

Thanks for the great tutorial. I just had a few issues I wanted to verify.

After i wrote make in the mosquitto terminal, I got so many warnings. Mainly :

../lib/tls_mosq.c:130:5: warning: ‘ASN1_STRING_data’ is deprecated [-Wdeprecated-declarations]
data = ASN1_STRING_data(nval->d.dNSName);
^~~~

Second, when I added the "mosquitto -v" command, I got :1516409129:

mosquitto version 1.4.14 (build date 2018-01-20 00:39:52+0000) starting
1516409129: Using default config.
1516409129: Opening ipv4 listen socket on port 1883.
1516409129: Error: Address already in use

Could you please help as I am a beginner

Warnings are expected. What matters is whether it runs or not. Normally when you get "Address already in use", it means that Mosquitto is already running. You can restart your Raspberry Pi to start fresh and try "mosquitto -v" again.

[scruss]

…
We will be installing the Mosquitto MQTT server on the Raspberry Pi. There are two choices. You can either build the latest (but could be unstable) version of Mosquitto MQTT server from Github or download a stable release from the Mosquitto Debian repository.

Out of interest, what's wrong with the third (and easiest) option:

Code: Select all

sudo apt install mosquitto

from the Raspbian repository? 1.4.10 worked for me.

[GhostRaider]

…
We will be installing the Mosquitto MQTT server on the Raspberry Pi. There are two choices. You can either build the latest (but could be unstable) version of Mosquitto MQTT server from Github or download a stable release from the Mosquitto Debian repository.

Out of interest, what's wrong with the third (and easiest) option:

Code: Select all

sudo apt install mosquitto

from the Raspbian repository? 1.4.10 worked for me.

Nothing really other than just minor bug fixes or improvements in later releases. It's up for you to decide but either choice will work as expected.

[DougieLawson]

Great tutorial!

Is there a way to send a response back to the iOS app when something has completed (i.e. send response when an upload is finished to update a progress bar?)

Thanks for the effort in making this.

What DougieLawson said is correct.

No it's not, other brokers can automatically acknowledge MQTT messages.

That's the PUBACK based on the message QOS setting, but that only tells you the message is delivered (and the communications are intact), it doesn't tell you that the subscriber has done anything useful with the message. You need a positive response message to confirm processing has happened on the subscribers system.

You won't want to argue with me, I've been working with messaging and queuing systems since December 1982 so I think I know how these things are meant to work.

[asandford]

You won't want to argue with me, I've been working with messaging and queuing systems since December 1982 so I think I know how these things are meant to work.

Get over yourself, your head really is too much up your own sphincter.

[asandford]

[quote=GhostRaider post_id=1261545 time=1516408691 user_id=174543

How would that work? It's very interesting indeed but how would clients confirm to the mqtt broker that it received the message if brokers aren't allowed to subscribe or publish to anything other than just send messages to their destination? Unless its a modified protocol. I've researched this before, for example someone wanted to create a chat application but wanted to have a feature that the message was received by the other client. The answer was to use a workaround, meaning to use the subscriber/publisher model because you can never confirm that the client handled the message appropriately unless you manually check that message from the client side.
[/quote]

There are other brokers available that have a great deal of added functionality and extend that to the MQTT protocol.