The course is part of this learning path
Developing For The Raspberry Pi and Azure IoT Hub
When it comes to IoT there are multiple layers. It’s not just an application deployed out on virtual machines, where the users interact with a web browser. In this course we’ll go through the process of setting up both the cloud and device side of an IoT solution.
This course focuses on how to implement a basic IoT solution. We’re going to setup a Raspberry Pi 3 B, with the Raspbian operating system. We’ll use a breadboard to wire up a DS18B20 temperature sensor, and 2 LEDs. And we’ll use a Node.js application to interact with the sensor, LEDs, and IoT Hub.
We’ll check the temperature every second, and if it’s changed since the last read, we’ll send a message to IoT Hub. Any time we send a message, we’ll make the green LED blink. And if the temperature hits 70 degrees or higher, we’ll turn the red LED on, as a warning light that it’s getting too warm; the only way to disable the warning light is to use an IoT Hub device-method.
So that’s what we’re going to build on the device side of things. On the cloud side of things, we’re going to use IoT Hub to hold the messages in its queue. We’ll implement an Azure Function to listen for messages, and then it’s going to take the message and save it in Document DB.
Here’s what you’ll need to build this for yourself.
First, you’ll need an Azure Subscription, because we’re going to use 3 Azure Services as our cloud back-end. We’ll use IoT Hub, Azure Functions and DocumentDB. You’ll also need a Raspberry Pi. I’m using a Raspberry Pi 3 B, for this demo. Since the pin layout may be different for different versions, you may need to adjust things for your implementation. You’ll also need an SD card for the Pi and a power supply. Most kits come with these. You’ll need a mouse, keyboard and HDMI compatible display for the initial OS setup. You’re going to need a breadboard. You’ll need two LEDs, ideally two different colors. You’ll need a temperature sensor, in particular, if you want to follow along and use the code I’ve prepared, you’ll want to use a DS18B20. When it comes to wiring up this project, you could use some male-to-female wires and connect to the pins on the Raspberry Pi directly. Or, you can use a breakout board, with male-to-male wires, which is what I’ll be using. You’ll also need some resistors, I’m using a 10k resistor with the sensor, and then a 220 ohm resistor with each LED.
Raspberry Pi Kits / Sensors
Here’s some recommended reading if you’re new to IoT.
Developing For The Raspberry Pi and Azure IoT Hub: What You'll Learn
|Lecture||What you'll learn|
|Course Intro||What to expect from this course|
|Service Setup||Creating the services|
|Configuring The Services||Configuring the services and testing them|
|Preparing The Raspberry Pi||Getting the OS installed and configured|
|Preparing The Breadboard||Wiring up the solution|
|Reviewing The Code||Reviewing the application|
|Running The Code||Testing the solution out|
|Next Steps||What's next|
Welcome back! This is going to be a fun lesson; because we’re going get the services we created in the previous lesson configured and and we’re going to send some messages from a simulated device, and watch them flow through the services.
Here’s our agenda for this lesson.
First we’ll setup the iothub-explorer app
Then we’ll create a device in the portal
Then we’ll configure an Azure function to listen for messages from IoT Hub and save to DocumentDB
And finally we’ll test that everything is working
So let’s start with our first item which is to install the iothub-explorer app. First, I should explain what the iothub-explorer is, incase you’re not familiar.
The iothub-explorer is a Node.js command line application that allows you to perform some device management tasks. It also serves as a device simulator. In this lesson we’ll use it to send some sample messages to IoT Hub so we can make sure we’ve wired everything up correctly.
Later in the course we’ll use it to invoke a device-method on the Raspberry Pi.
To install iothub-explorer, you’ll need node.js and npm installed. I’m here in a terminal and I’m going to paste the command directly from the GitHub page. The command is “npm install -g iothub-explorer.”
This takes just a moment. Once this is done we’ll be able to log in, and send some simulated data.
Okay, it’s now installed, so we’ll need to log in with the login subcommand. If you’ve never used iothub-explorer before, it might not be obvious where you get the credentials to login. The answer is that we can use the connect string from an access policy.
Let’s head into the portal. I’m on the overview tab of the IoT Hub app we created earlier. To access the credentials we need, click on Shared access policies. Notice there are a few default options for access, ranging from permission to read the device registry, to service and device permissions. Let’s use the iot hub owner policy for now, since it has the most access. Selecting it opens up a blade with a summary of its permissions as well as the shared access keys and connection strings.
A connection string is really just made up of some info we could put together ourselves, such as the host name, policy name and access key. Since we need a connection string to login with the iothub-explorer, let’s click the copy button next to the connection string for the primary key.
With this copied, let’s go back into the terminal. We’re going to pass this as an argument to the login subcommand, though we need to wrap in in double quotes first.
Running this will give us a session that’ll last for 1 hour.
Now we’re logged in, so we let’s test things out by sending a device-to-cloud message. To do that we need a device registered with IoT Hub. You have options for how can do this. You can use iothub-explorer, or the portal. Of course, you could use SDK to do this for yourself, however, let’s use the portal for this demo.
So in the portal of our IoT Hub app, open the “Device Explorer” blade, and then click Add.
You can see that we’re presented with a blade that requires some info for the device. Let’s name our simulated device something original, we’ll call it…”Simulated Device.”
We’ll use symmetric keys, and we’ll use the auto generate option at the bottom here. So all we need to do is click “Save”. Alright, now that we have a device created, we can use iothub-explorer as a device simulator to send test messages.
Let’s use the “simulate-device” subcommand on the command line to send a message.
I have a command already prepared here, it uses the simulate-device subcommand followed by the name of the device, which is the SimulatedDevice we created in the registry, and then a message to send.
If I run this, it’ll keep sending the messages...so, I’ll stop it with control-c. Okay, we’ve just sent messages to IoT Hub successfully. However we still aren’t doing anything with them, so now it’s time to create an Azure function.
Let’s head back into the portal, and into the Functions app we created earlier. Let’s start by adding a new function, to do that click the plus sign next to Functions.
I’m going to select the custom option at the bottom...and I want to filter by a language of C#.
Now, I’ll select an EventHubTrigger. The default endpoint for IoT Hub events is compatible with EventHub, which means we can use the EventHub trigger.
I’ll name this SaveMessage, since that’s its job.
And now I need the Event Hub info, namely the name and connection string. This info exists inside the IoT Hub app. I recommend using multiple tabs for this part, one for each of our 3 services.
In the IoT Hub app, go to endpoints and select the event endpoint. Notice in the blade that pops up that there’s some event hub details. First, let’s copy the name, and switch tabs back to the functions app, and paste it into the event hub name field.
Now we need the connection string, so let’s click new to create one. The name of the connection string is just for your reference, so it can be whatever you’d like.
Next we need the connection string itself and if you’ve used Event Hub before you know the format required, if not here’s a look at the required format.
The string is comprised of 3 parts, the Endpoint, the key name and the key value, it’s a semicolon separated set of key-value pairs.
Let me show you where to find these values. Back in the portal, the endpoint is here in the same location as the event hub name.
The key name and value come from a shared access policy. In this case I’m using the service policy since it’s designed to allow permission to services to access the messages. The key name is the name of the policy, and the key value is the shared access key. I have this connection string created here, so I’ll copy it and paste it into the connection string field. If it’s a well formed string, it’ll show a green checkbox.
This will take a moment to update, and now let’s click create...this will take a few seconds...okay.
This code will just grab the message from the IoT Hub event queue and then print it in the log. Let’s see if it works…
Let’s run the device simulator again to send some messages...there we go, a few messages have been sent. Switching back to the function log, you can see that it’s picked them up and printed them out into log.
So we know that we can send a message to IoT Hub and we also know the function is able to pick them up; so this tells us things are wired up correctly so far.
Now, let’s change the function to save to DocumentDB. To do that click on integrate…
We need to add a new output…so scroll down to DocumentDB a click select.
I’m going to change the name of the parameter to outDoc. I’ll change the collection to “IoTMessages”...and make sure to check the box here to auto create the collection and database, unless you’ve created them for yourself. I’ll change the database name to IoTDemo.
Next we need to set the DocDB account, so I’ll select the account we created previously.
Since we’re using an out parameter, we’ll need to edit the code…
This is going to set the outDoc parameter to be the message picked up from the queue. And that means we need to add the out param to the method signature...and let’s save this.
Let’s test this out by clearing the log...and now we’ll fire off the messages again, which will just keep sending.
Notice the log is populating again.
Let’s head to the DocumentDB tab and see if our documents are there…
By clicking refresh here you can see our collection is here. If we use the query explorer, and we run this, you can see we have some documents.
Let’s go back to the terminal and change the message to see if it flows through. So let’s change the message to “hey” and run this so it’s sends a few messages...and I’ll cancel it with control-c.
Now, back in the query explorer let’s adjust the query to use a WHERE clause of WHERE c.message = ‘hey’
Running this shows 3 messages.
This all may not look like much, but the back-end for our project is now up-and-running. We can now submit messages to IoT Hub and have them saved to DocumentDB via an Azure Function.
That means we’re now ready to get start preparing the Raspberry Pi.
Alright, if you’re ready to prepare the Raspberry Pi with an OS, then let’s get started with the next lesson!
About the Author
Ben Lambert is the Director of Engineering and was previously the lead author for DevOps and Microsoft Azure training content at Cloud Academy. His courses and learning paths covered Cloud Ecosystem technologies such as DC/OS, configuration management tools, and containers. As a software engineer, Ben’s experience includes building highly available web and mobile apps.
When he’s not building the first platform to run and measure enterprise transformation initiatives at Cloud Academy, he’s hiking, camping, or creating video games.