Bidirectional Communication With Azure IoT Hub

Introduction

 

In this article, we're going to learn about bidirectional communication in a hands-on manner. Let us start by reviewing the basics of Azure IoT Hub communication and then dive in and work through some scenarios together. In our first exercise, we'll create an instance of Azure IoT Hub. Once we have our hub, we'll then create a device that we can use for testing. That device will allow us to then send and receive messages using tools provided by Microsoft. Those same tools will allow us to monitor the messages that are sent back and forth from our hub. Finally, we'll see how we can simulate a device sending and receiving messages all without writing a single line of code.

 

I do want to quickly discuss how we'll approach demos in this module. For example, what if we wanted to create a device? There are actually several ways we could accomplish that. We could use the Azure portal, or we could use the command line in the Azure CLI, or we could create the device using the Azure IoT Toolkit extension for VS Code.

Road Map

1. Creating an IoT hub
2. Creating a device (VS Code)
3. Creating a device (Azure CLI)
4. Sending a D2C Messages (VS Code)
5. Sending D2C Messages (Azure CLI)
6. Sending C2D Messages (VS Code)
7. Sending C2D Messages (Azure CLI)

Bidirectional communication basics

 

Let's consider an example corporation, that wants to be able to monitor tens of thousands of hardware assets all across the world, but they don't just want to monitor the assets, they need to be able to send commands to the assets too. That means the solution we provide needs to support bidirectional communication. The assets need to be able to push information up to the cloud, and then we need to be able to send messages back down to the assets as well. We need to provide a solution that can support this two-way communication at the scale our client corporation is talking about. Fortunately for us, Microsoft Azure IoT Hub can fulfill these requirements. Specifically, Azure IoT Hub provides two types of messages that we can leverage for our client corporation. The first is cloud-to-device, or C2D, messaging. As you can probably guess from the name, a C2D message is sent down from the cloud to a specific device. To handle messaging the other way, IoT Hub also supports device-to-cloud, or D2C, messaging. A device can send a D2C message to the hub, where it can then be routed for processing. I do want to point out that Azure IoT Hub actually supports other forms of communication too. It supports file uploads from a device to the cloud, as well as higher-level concepts such as device twins and direct methods.

 

Creating an IoT hub

 

Before we can really explore the capabilities and features of azure IoT hub, we need to create a hub for us to test with. We'll be using the Azure portal for this demo.

 

The first thing we're going to do is create a new resource group. You can think of a resource group like a folder, but it's for organizing. We can create a new resource group by going to resource groups and clicking the Add button.

 

 

First, we need to pick the subscription we're going to use. I only have one, but if you have access to multiple subscriptions, be sure you select the right ones here. Next, we need to name our resource group. Finally, we can choose the location for this resource group. These locations are the different Microsoft Azure data centers or regions around the world you typically want to create. Your resource is within the same region.

 

Finally, click on Review and Create, which will validate the options that you have chosen.

 

 

Now, I can click on my resource group to go into it. This resource group is pretty boring right now because it's empty. So, let's fix that by creating a new instance of IoT Hub. To do that, we can click this Add button, which brings up a list of Azure Resources that we can add to the group. I find that the easiest way to locate something is to search for it. 

 

So let's search for IoT hub and there it is IoT hub for Microsoft. Let's go ahead and create this.

 

 

There are several options we can configure for our new hub. Once you’ve done this, move on to the size and scale options. Here we can configure the pricing and scale tier. Microsoft has some guidance on how to pick the right tier for your solution. It really comes down to how much data you plan to move in which features of IoT Hub you need. You can always change between tiers after you create your hub. With one exception: If you pick the free tier, you cannot upgrade to a basic or standard tier later where you're going to go with a free tier for this demo. But for a real solution, you would want to go with either basic or standard, depending on your needs. Let's change to the F one free tier with the free tier.

 

 

We can't really adjust other options, so let's just go ahead and click on review and create. Everything looks good. So let's create our hub.

 

 

This process can take a few minutes.

 

 

We now have a hub and we can jump to it by clicking on Go to resource. The summary view shows us some basic stats about our hub, and if we scroll down, we can see how many messages we've sent, as well as how many devices we have while we're here.

 

 

We could actually go ahead and define devices to by going to the IoT devices Explorer here. But instead, let's see how we can use other tools to interact with our hub.

 

Creating a device (VS Code)

 

We now have an IoT hub provisioned in Azure, but it's pretty boring because there's nothing there. Let's see how we can use the VS Code and the Azure IoT Hub Toolkit extension to create a device. If you didn't install the Toolkit yet, you can get it from here.

 

Here we are in VS Code. We've already installed the Azure IoT Hub Toolkit extensions for VS Code, but how do we get to those extensions? We can access it through the Command Palette. One way to get to the Command Palette is by going to the View menu and choosing Command Palette, like this.

 

 

But we can also get there by using keyboard shortcuts. By default, Ctrl+Shift+P will activate the Command Palette. That's what I'll be doing throughout the remainder of this course. Anyway, to get started with the Azure IoT Hub Toolkit extension, let's type welcome in our Command Palette, then choose to show the Azure IoT Hub welcome page.

 

 

This welcome page has some links and instructions to help us get started. We already have a hub, so let's choose to select an existing hub.

 

 

That opens up the command Palette where we can select the subscription to use, and then we can select the hub we want to use.

 

 

Easy enough, right? Now that we're connected, we can expand the Azure IoT Hub Devices panel down here, and we can see that we have no devices yet.

 

 

We can hover over the panel, click the Action menu, and then choose Create Device.

 

 

That will again pop open the Command Palette, this time for us to type a name for our device. I'm going to go with test-device-01.

 

 

And there we are, now we have provisioned a device on our hub. This is just one way to create the record for a device. Let's see how to accomplish the same task using the Azure CLI.

 

Creating a device (Azure CLI)

 

There is more than one way to create a device in our new hub. In this demo, we'll create one using the Azure CLI. If you were following along, but you haven't installed the CLI yet, you can download it from here. You will need the IoT extensions for the CLI too. Those are easy to install. Just follow the directions from this link. I'm here in a PowerShell console running inside of Hyper, and I've got the Azure CLI tooling installed along with the IoT extensions, so we're all set.

 

 

You will need to log in. Now we're ready to create our device identity. We do that using this command. It is a bit long, so let's walk through it piece by piece. First, we have az iot, which means we're going to execute an Azure CLI command in the IoT extension package; then we have hub device-identity, which means we're going to be working with a hub's device identities; and then here's the action we're going to perform, create, so we're creating a device identity. Now we have our options. The first, --device-id, that's our device ID, which in this case is test-device-02. Finally, we have the --hub -name, which that's the name of the IoT hub we're targeting.

 

 

Do note that you could abbreviate these last two properties using the -d parameter and the -n parameter. Let's go ahead and run this command, and if it all worked you should see output like this.

 

 

There's quite a bit of interesting information in here, including the authentication settings for this device along with our deviceId. Now that we know how to create a device, let's see how to actually send and receive data.

 

Sending a D2C Messages (VS Code)

 

Now that we've created device identities on our hub, we're ready to explore sending and receiving messages, but how are we going to do that without a real device? Well, we actually don't need a real device, because Microsoft has given us tools that allow us to send and receive messages as if we were using a real device. We'll start by sending a device-to-cloud message using VS Code. We're picking up from where we left off, so we've already connected VS Code to our IoT hub. We can send a D2C message using VS Code by right-clicking on a device from our list and choosing Send D2C Message to IoT Hub.

 

 

That will open the Command Palette for us to type the message that we want to send. Let's send Hello from VS Code.

 

 

Well, it looks like it worked, but how can we be sure? We need some way to monitor and see what messages our IoT Hub is actually receiving. Fortunately for us, we can do that right here in VS Code. Let's right-click on our device again, and this time let's choose Start Monitoring D2C Message.

 

 

Now let's send another message. Let's give this message a different payload so we can tell the difference between this message and the one we sent before.

 

 

And look at that, there's our message. It arrived at the hub exactly as we expected.

 

 

We're finished with the IoT Hub monitor for now, so let's shut it down. You can right-click in the output window, and then choose Stop Monitoring D2C Message. Good. We can do the same thing using the Azure CLI. Let's see how.

 

Sending D2C Messages (Azure CLI)

 

Now we're going to quickly see how we can use the Azure CLI to send device-to-cloud messages, as well as how we can monitor those messages from the command line. We're back in our PowerShell console. This time we're going to execute the Send D2C Message command. This is another verbose command, so let's walk through it.

First, we have az iot again, because this is an IoT extension command,

Then, we have device because this command is operating on a device,

Here's the action, send-d2c-message,

Then, we have the hub name, this time using the -n parameter since that's shorter to type, and then there's the device we're going to send the message from with the -d parameter,

And finally, we have the message we actually want to send.

 

The command is verbose, but I find that it's actually quite easy to read once you get used to the way the commands are structured. Let's go ahead and execute this command. Well, there are no errors, so that's probably a good sign, but how do we know if this worked?

 

 

Let's open a second terminal, or if you're using something like Hyper, go into a second tab. Now, let's start a monitor that will watch for messages arriving at our hub. This az command is going to target a hub, and the action is monitor-events, which just needs to know which hub to monitor events for. Easy enough, right? Let's execute it.

 

 

Now that our monitor is running, let's go back over to our first terminal, and let's send another message.

 

 

The message sent, so let's go over to our monitor, and there's our message.

 

 

So this is how you can send a message to your hub, as well as how you can monitor what is being sent. When you're finished with this monitor, all you need to do is press Ctrl+C to stop it. Good. Now that we know how to send data up to our hub using VS Code and the CLI, let's turn our attention to messages going from the cloud down to our devices.

 

Sending C2D Messages (VS Code)

 

We don't need a real device to explore how IoT Hub handles cloud-to-device messaging. All we need is our trusty IoT extensions for VS Code. Let's check it out. Sending a cloud-to-device message is basically the same as sending a device-to-cloud message. We right-click the device and choose to "Send C2D Message to Device".

 

 

That opens the Command Palette where we can drop in the value we want to send, and off the message goes. VS Code also gives us the ability to receive that message without the need for a real device.

 

 

We can right-click on our device again, and this time choose Start Monitoring C2D Message.

 

 

Now let's send another message. VS Code received the message on behalf of our device from the hub just like a real device would.

 

 

Let's not forget to clean up after ourselves. We can stop the C2D monitor by right-clicking in the output and choosing Stop Monitoring C2D Message.

 

Sending C2D Messages (Azure CLI)

 

For those of you that prefer the command line, let's see how to send a C2D message using the Azure CLI. Hopefully, this is going to start feeling a little familiar now. Let's go ahead and drop in the command that we need to send a message from our hub down to our device. We're operating on a device using the IoT Hub extensions. This time we're working with c2d messages and the action we want to perform is a send. We're still using the same hub that we created, still sending to the same test device, and then, of course, we have the payload that we want to send.

 

 

When we run this command, we don't really get any feedback as long as everything worked. We'd like to see it arrive similar to how we did that using the VS Code. Things actually work a little differently with the CLI. Instead of starting a monitor, we can use the CLI to receive a message from the hub. We just run this command. Again, we're working with a device and a c2d message, but this time we're going to receive instead of send. When we execute the command, we receive that message that we just sent.

 

 

This is what a real device would actually receive from the hub. As you can see, it would have access to things like the time the message was enqueued, as well as a sequence number for the message. It would also have its unique ID, and then, of course, the actual payload that we sent. Sending and receiving messages one at a time like this is fine, but a real device isn't going to work this way. A real device is going to potentially send multiple messages while listening for new messages at the same time.

 

Simulating a Device

 

The Azure CLI provides a way to simulate a device. Unfortunately, the Azure IoT Toolkit for VS Code doesn't support this functionality, so even if you do prefer a GUI, you'll have to tough it out and use the command line this time, but don't worry, it's actually quite easy to use. Before we start a simulated device using the Azure CLI, let's go ahead and start a monitor so that we can see events as they arrive at the hub. We can do that by executing the az iot hub monitor-events command.

 

 

Now let's go to a new terminal, and let's execute a new command. This is an IoT command that targets a device, and the action we're running is simulated. That command needs to know the name of the device and the hub, what message we want to send, and how many messages to send. By default, the simulate command will wait 3 seconds between sending each message. Let's go ahead and execute this command, and these dots that are appearing, those are our messages being sent.

 

 

On our other monitor, messages are being received as they arrive. The simulator can do more than just send device-to-cloud messages, though. It can also receive cloud-to-device messages.

 

Summary

 

We took our first steps towards mastering IoT Hub in this module. We created our first Azure IoT Hub instance, and we learned how to create devices on our hub using both the Azure CLI and VS Code. We saw how IoT Hub allows our devices to communicate with it by sending device-to-cloud, or D2C, messages, and we sent messages back down to our hub using cloud-to-device, or C2D, messages. Finally, we saw how the useful simulate command of the Azure IoT CLI extensions allow us to launch a simulated device that's capable of both sending and receiving messages.