Preface
This tutorial assumes some background knowledge of programming, but no prior experience with Raspbian (or any Linux distribution), GPIO microprocessors (Pi, Arduino, etc), or Python. References may be made to previous tutorials.
My main programming languages are Java, C#.NET, and VB.NET. You may notice some slight differences between my Python code and the standard conventions and formatting for Python. This should not affect your understanding of the code.
Goal
Send a cloud-to-device message using Microsoft Azure’s IoT Hub that alters the physical state of an LED attached to a Raspberry Pi 3.
Example Use Cases
- Remote-controlled servos for a webcam
- Simple wall-mounted digital message board
- Smart Home systems like automatic blinds
Getting Started
You’ll need to set up the proper coding environment for this tutorial first. The instructions for doing so come with the Pi’s online documentation and are described in Part 0 of the tutorial, so here are the basic steps:
- Install Raspbian Jessie
- Check for updates to your distribution
- Physically prepare your device with a breadboard connected to the Pi’s pinouts or some other form of wiring.
Now that your Pi is up and running, we need to install the IoTHub library. There are two methods to do this; either you can access Github (https://github.com/Azure-Samples/iot-hub-python-raspberrypi-client-app), download the repository as a Zip, and extract the files, or; you can clone the repository via terminal.
sudo apt-get install git-core
git clone https://github.com/Azure-Samples/iot-hub-python-raspberrypi-client-app.git
To compile the Python library, run the following (adjusting the directory path as necessary):
cd ./iot-hub-python-raspberrypi-client-app
sudo chmod u+x setup.sh
sudo ./setup.sh
Tips
- You can change directories using *wildcards if you have no other similarly-named directories. In the above example: “
cd ./iot-*
” will get you to the correct directory. - The base directory “./” here refers to “/home/pi”. You’ll find the new folder and files here if you used git clone. Otherwise, replace it with your downloaded and extracted zip folder location.
- As the Github documentation states, you may find that
iothub_client.so
gets stuck while compiling. To prevent this from happening, open a second terminal and prepare to run
“free -m
” whenever you see the compiling slow down. It is possible that having an active VNC connection causes this problem; try viewing your Pi via HDMI or control it via SSH if the freezes persist. If the system does freeze completely, it is safe to forcefully reboot the Pi by disconnecting and reconnecting the power source.
For the purposes of this tutorial, either method will work, since we will be pulling a file from the example directory to use.
You’ll also need to set up an IoT Hub on Azure for this tutorial. The steps for that are extensively detailed in this Microsoft Helpdoc: Stop when you reach the section “Set Up Raspberry Pi”.
If you can’t get to the webpage at the moment, follow these basic instructions. Create a New Resource, namely an IoT Hub. Set the proper subscription (a Free one will work, or a Pay-as-you-go) and the region closest to you. Continue with setting up your desired pricing and scale, and finish the creation. It will take some time to deploy. Afterwards, open your IoT Hub and select “IoT devices” in the menu, under Explorers. Add a new device, and take note of this new device’s connection string.
Make sure you keep your IoT Hub Device Details page open, either on a separate device or on your Pi. You’ll need to use some values to set up the proper authentication with your Pi later.
The Library
After compiling, you’ll find a file “iothub_client.so” approximately 3.6 MB in size, described as a shared library. This is the Python-ready library compiled from the original C code. You’ll also find, nestled in the directories “device/iothub_python”, the Python wrapper source code. It serves as a decent reference for all the methods and parameters you will need to write a IoTHub device.
This iothub_client.so library (henceforth referred to as ‘the library’) contains the networking protocol and various classes that will shortcut us into immediately writing useful applications. Although there are a lot of functions and callback methods at your disposal, for this starter tutorial, we’ll only be using a few of them. Of course, I strongly encourage you to explore the many facets of the library and to introduce new code wherever you fancy – but I won’t be, for now.
Setting Up the Code
Important note: Python 3 uses a different set of method calls than Python 2 for initializing stuff. This library and tutorial will not work with Python 3. Ensure you’re using Python 2. In Raspbian Jessie, both options will be available under the Programming menu item – ensure that you select “Python 2 (IDLE)”.
Once you’ve launched Python, you’ll need to create a new document via File>New File. Let’s set up the file with the important import
statements:
from iothub_client import IoTHubClient, IoTHubClientError, IoTHubTransportProvider,
IoTHubClientResult, IoTHubMessage, IoTHubMessageDispositionResult, IoTHubError,
DeviceMethodReturnValue
import sys
import time
import Pi.GPIO as GPIO
Tip: Don’t simply copy-and-paste the code snippets here. Due to special formatting, they might not behave as you’d expect in the IDE.
The most important iothub_client
imports we’ll be using here are IoTHubClient
, which is the client class that provides messaging capabilities, and IoTHubMessageDispositionResult
, which is oddly important as we’ll see later on.
Let’s also create some variables to keep our code clean. We’ll store your device’s Connection String, as well as the state of the (not yet connected) LED.
CONNSTR = "HostName=hubname.azure-devices.net;...;..."
LIGHTON = True
CLIENT = 0
The connection string should have the format “HostName=…;DeviceId=…;SharedAccessKey=…
”. If this is not correct, your client will fail to initialize.
Tip: If your client fails to instantiate and throws an exception but the string format matches the above, ensure you have copied the key from your Device Details page and not the IoTHub page. The key formats are identical but serve different purposes.
Alternatively, if you’d prefer, you can create three variables to store each part of the connection string. However, the client only accepts a connection string formatted as described above.
Now that we have our document set up, we can start creating the client that will communicate with our Hub. I recommend saving and running the module periodically to ensure your code works. Go ahead and give it a try.
If you’ve followed the steps above, you may notice that Python doesn’t recognize your imports! This is because you haven’t created a copy of the library in the same directory as your Python file. Find where “iothub_client.so” resides, and make a copy of it into the directory where you saved your code. Recall that this should be in the repository directory, and will not exist until the “setup.sh” script has been run.
Some files and folders may be hidden, and you may need to run an elevated File Manager to see them. If that’s the case, execute “sudo pcmanfm
” in a terminal.
Try running the module again, if it failed at first. It should run fine, and stop execution immediately. If not, double check the error and resolve it as necessary.
Creating a Client
In order to keep our code clean and organized, we’ll be making functions for each task. The first task at hand is to initialize an IoTHubClient
.
def setupClient():
global CONNSTR
client = IoTHubClient(CONNSTR, IoTHubTransportProvider.MQTT)
client.set_option("product_info", "RPI-Python")
return client
This function gives us an IoTHubClient
object that can send and receive messages. Let’s create the main
method to run this code as well. Finally, at the end of the file, have it run main()
. Remember, Python is an indent-sensitive language. Your code should look like this:
def main():
global CLIENT
CLIENT = setupClient()
print ("Starting IoT Hub Client...")
main()
That’s not very exciting, but give it a Run anyways. If your connection string is correct and your Pi has internet access, your code will run and exit without problem.
What we have now is an established connection to the cloud. All we need to do now is receive a message from the Hub, and to do something when that happens.
Setting Up the Callback Methods
The IoTHubClient
utilizes callback methods to trigger events, and a received message will need its own callback method. Let’s set that up.
def gotMail(message, context):
message_buffer = message.get_bytearray()
size = len(message_buffer)
msg = message_buffer[:size].decode("utf-8")
print ("Server says: %s" % (msg))
Tip: Python’s string
formatting is as follows: “%s abcdef %s …” % (arg1, arg2, …)
Now that we have this function, we need to inform the IoTHubClient
. We’ll do that right as we instantiate a client in setupClient()
. Modify your previously written setupClient
method.
def setupClient():
global CONNSTR, gotMail
client = IoTHubClient(CONNSTR, IoTHubTransportProvider.MQTT)
client.set_option("product_info", "RPI-Python")
client.set_message_callback(gotMail, 0)
return client
Tip: While Python is indent-sensitive, it is not line-sensitive. You may adjust spacing between code, comments, and functions as you see fit.
Note: The global variables declared have been updated to include gotMail.
Give the code a Run. Again, it seems to stop execution almost immediately, even without throwing any errors. That’s because upon reaching the last line of code, Python doesn’t account for the fact that we’re waiting for the server to send us a message. Let’s create some code to keep the application running even if there’s nothing left to do.
...
print ("Starting IoT Hub Client...")
main()
while True:
time.sleep(1)
Tip: time.sleep(n)
takes n in seconds. It can take floats as well, to get fractions of a second.
Ah, the infamous “while True
” loop. This will periodically (every one second) set the main thread to sleep, again and again. Unfortunately, this means your code won’t ever come to a natural stop. We can still halt code execution with Ctrl+C in the Python shell, however.
Run the code again. You’ll notice that the shell no longer immediately informs us that it has RESTARTed. This means our code is continually running, even if there’s no physical indication of it doing so. Let’s leave our code running for a bit and turn towards the Azure page for your IoT Hub.
Sending a Message
If you have your Device Details page open, read on. If not, you can find it via Home>Your Hub>IoT Devices>Your Device. Remember, this is the page with your device’s Connection String on it, not the Hub’s connection string.
On the upper menu of Device Details, you’ll see a button labelled “Message To Device”. Opening that will bring you to a simple form that supports sending a message and some additional information. Type something into the Message Body portion of the form, and click Send Message at the top.
Note: You cannot transmit “unidentified ASCII symbols” through the messaging portal.
If everything is set up properly, your Python shell should indicate that the server has sent a message. Congratulations, you’ve just sent data from your internet browser to your Raspberry Pi.
Setting Up the LED
Now that we’ve established that you can make a connection and transfer information from server to client, let’s make this a more visual experience. Prepare a standard LED and a resistor of about 100 ohms, and locate a free pin on your Pi3. For this tutorial, we’ll be using GPIO pin 6 as labelled by the Pi3 pinout, but you may choose any number that supports GPIO.
Connect the LED’s positive terminal (the longer leg) to pin 6, and connect the negative terminal to the resistor. Finally, connect the resistor to ground (GND). This should be a circuit in series, not parallel.
The Pi3 GPIO pinouts all deliver 3V – if you see that the LED is extremely bright, remove it immediately and replace your resistor with a higher value resistor. If your LED is dim, reduce your resistor value. If your LED suddenly turns off, disconnect and test it with a 1.5 V source (AA battery or similar) – it may have burned out.
Note: If you’re unfamiliar with resistors or circuitry, follow all of the given values and pin selection exactly. This will help reduce the chance of malfunction.
Now that the circuit is complete, we need to program the pin in our code.
...
GPIO.setmode(GPIO.BCM)
GPIO.setup(6, GPIO.OUT)
...
We’ve informed our Pi that we want to use GPIO 6 as an output pin. Now, we need a way to set the signal to our desired position. Let’s make some more methods. Remember that these method declarations must be written before they are called, so it helps to group all your declarations at the top of the document.
def turnLightOn():
global LIGHTON
LIGHTON = True
GPIO.output(6, GPIO.HIGH)
print ("LED on!")
def turnLightOff():
global LIGHTON
LIGHTON = False
GPIO.output(6, GPIO.LOW)
print ("LED off.")
def toggleLight():
global LIGHTON
print ("Toggling...")
if LIGHTON:
turnLightOff()
else:
turnLightOn()
To keep our code deterministic, let’s make sure we set a default state for our LED. Also, let’s make things interesting by having the LED blink.
...
turnLightOn()
print ("Starting IoT Hub Client...")
main()
while True:
toggleLight()
time.sleep(1)
Run your code - your LED should be blinking every second. If not, double check your wiring and pin number. Also keep track of your indents. If it helps, you can include ‘fake’ endings for your methods by using comments:
def func():
code code code
Continuous Execution
Rather than using Ctrl+C to stop code execution, let’s send a message from the Hub to your Pi and see what happens. You’ll notice that the blinking stops and your code stops as well, for some reason. As it turns out, the callback method for receiving messages needs to return a value in order for your thread to remain running. Let’s go back and edit that code.
def gotMail(message, context):
...
print ("Server says: %s" % (msg))
return IoTHubMessageDispositionResult.ACCEPTED
Running this should now allow your LED to continue blinking even if multiple messages are received.
Interactive LED
Finally, let’s hook up the Hub messages and our LED. We want to be able to set the state of our LED through the server by sending a simple string
.
First, we need to disable the blinking LED. You can do this by commenting it out with a pound (#) or deleting the line within the ‘while True
’ loop.
Unfortunately, Python doesn’t have a Switch
-case structure, so we can’t use that to set up our commands. For now, we’ll stick with the If
-ElseIf
structure to determine what the incoming message says.
def gotMail(message, context):
...
if msg == "turn on" or msg == "on":
turnLightOn()
elif msg == "turn off" or msg == "off":
turnLightOff()
elif msg == "toggle":
toggleLight()
else:
print ("I don’t know how to ‘%s’." % (msg))
return ...
Tip: Python doesn’t use “elseif
” or “else if
”, but rather, “elif
”. It also doesn’t use &&
or ||
.
Note: Notice that the unnecessary initial print statement has been commented out here.
Run the module, and start sending messages from your Hub webpage. You should be seeing your LED behave exactly as you tell it to; sending “turn on” should light the LED up, and “toggle” should switch between on and off. If you’re seeing the Python shell announce that it is turning the LED on and off but you don’t see it happening in reality, check your wiring and ensure your LED hasn’t burnt out.
Conclusion
Congratulations! You’ve set up an Azure Internet of Things Hub, connected your Raspberry Pi 3 as an IoT Device, received server messages sent from the Hub webpage, and altered the state of an LED via specifically written commands.
What Can I Do Next?
Explore the Python language and clean up the code you’ve written. Add detail into your code, such as the omitted ‘context’ fields. Attempt to connect a second LED to another GPIO pin, and create a command interpreter that can control a specific LED’s state given its number. Add some error handlers with Try
-Except
blocks to automatically handle exceptions.
Continue
Tutorial 2 | Tutorial 3