Welcome back!

In this lesson, I'll cover cloud-to-device communication which is all about how IoT Hub can send data to a device.

When you want to send messages from the cloud to devices, you won’t typically just send it directly. Because, besides the security concerns, you also have no guarantees that the device will be available.

So how do you send a message from the cloud to devices if you can’t ensure the devices will be connected to the internet?

This a task well suited for message brokers. Message brokers are designed to be highly scalable, and highly available, and that allows them to hold on to any messages intended for devices until the device can process the message.

The way it works is that messages are held in a queue and await processing by the devices. The queue is a temporary storage mechanism that allows you specify a time-to-live for messages. If they’re not processed successfully in the time-to-live window then the message is moved to a dead letter queue.
Once a message is queued up devices can download them in the order they were queued. After the message is downloaded the device can process the message locally.

When the device downloads the message from the queue, it doesn’t remove it from the queue right then. Rather, it locks it for a period of time, which by default is one minute. That message becomes invisible while locked and no other processes can see it.

When the device processes the message and is done with it, it can mark the message as complete. And the act of marking it complete removes it from the queue.

If for some reason you don’t mark the message as complete during that lock window, the message will reappear in the queue to be processed again. However, there is a maximum deliver count, that makes sure a message that isn’t marked complete doesn’t stay on the queue forever. If that max is hit, then the message moves to the dead letter queue.

The message queue has some limitations that you should be aware of when planning your projects.

First up, the queue is temporary storage, and a message has a maximum retention time of 48 hours.

Next, the message queue only holds 50 messages per devices, trying to add anything after that returns an error.

And, the max size of a message that you can send to a device is 64 kilobytes.

Okay let's try cloud-to-device with a demo.

We are here in our PowerShell script. We have our device simulator, and we have a new command to handle a message.

This makes the device simulator wait for messages sent from a service.

Let's run this.

For the service side we have a new command called “send message", to send a message to a device. We can specify a message body, for example, a JSON document.

If I move the console window so we can see what happens, and now it I send the message from the service, you can see that it arrived on the device simulator.

There’s a second command here that is the same, except it has another parameter that allows us to acknowledge when a message is received by a device.

So, if we run the command again, notice that the message is received and you can see that in the service we get an acknowledge from the DeviceId, indicating success.

So, let's see how the code is implemented.

In the "DeviceService" we have a command named "send message" and if we follow the method, you can see that here we have a DeviceId parameter, a message body and an acknowledge parameter.

Then there is “SendMessageAsync" to create the actual message. This is where the message is queued up with the service client, by calling the SendAsync method.

Here we loop while we wait for the feedback receiver to send its feedback.
You can look into these records, and you see some information about the device and the result, and then you can complete the message to remove it from the feedback queue.

If no feedback is required, then the serviceClient just invoke the SendAsync method immediately to the DeviceId.
Once you do something with the feedback message, you can either complete the message to remove it from the feedback queue or abandon it.

Alright, let’s wrap up here and summarize what we’ve covered in this lesson.

In this lesson we talked about how cloud to device messages are queued up temporarily in a message queue. The queue has some limits on how long the message will be held, as well as the max message size. And once a device has processed the message, it can complete the message to remove it from the queue.
In the next lesson we’ll talk more about device configuration.

Okay, I’ll see you in the next lesson!