In this post, we will see how we can do cloud to device messaging, something which is much harder when not using Azure IoT Hub. IoT devices will normally be low power, low-performance devices, like small footprint devices and purpose-specific devices. This means they are not meant to (and most often won’t be able to) run antivirus applications, firewalls, and other types of protection software. We want to minimize the attack surface they expose, meaning we can’t expose any open ports or other means of remoting into them. IoT Hub uses Service Bus technologies to make sure there is no inbound traffic needed toward the device, but instead uses per-device topics, allowing us to send commands and messages to our devices without the need to make them vulnerable to attacks.
Cloud to Device Messaging
When we want to send one-way notifications or commands to our devices, we can use cloud to device messages. To do this, we will expand on the EngineManagement application we created in our earlier posts, by adding the following controls, which, in our scenario, will allow us to start the fans of the selected engine.
To be able to communicate to our devices, we will first implement a ServiceClient in our class.
private readonly ServiceClient serviceClient = ServiceClient.CreateFromConnectionString("HostName=youriothubname.azure-devices.net;SharedAccessKeyName=iothubowner;SharedAccessKey=yoursharedaccesskey");
Next we implement the event handler for the Start Fans button. This type of communication targets a specific device by using the DeviceID from the device twin.
private async void ButtonStartFans_Click(object sender, EventArgs e)
{
var message = new Microsoft.Azure.Devices.Message();
message.Properties.Add(new KeyValuePair<string, string>("StartFans", "true"));
message.Ack = DeliveryAcknowledgement.Full; // Used for getting delivery feedback
await serviceClient.SendAsync(comboBoxSerialNumber.Text, message);
}
Process Message On Device
Once we have sent our message, we will need to process it on our device. For this, we are going to update the client application of our simulated engine by adding the following method.
private static async void ReceiveMessageFromCloud(object sender, DoWorkEventArgs e)
{
// Continuously wait for messages
while (true)
{
var message = await client.ReceiveAsync();
// Check if message was received
if (message == null)
{
continue;
}
try
{
if (message.Properties.ContainsKey("StartFans") && message.Properties["StartFans"] == "true")
{
// This would start the fans
Console.WriteLine("Fans started!");
}
await client.CompleteAsync(message);
}
catch (Exception)
{
// Send to deadletter
await client.RejectAsync(message);
}
}
}
We will run this method in the background, so update the Main method, and insert the following code after the call for updating the firmware.
// Wait for messages in background
var backgroundWorker = new BackgroundWorker();
backgroundWorker.DoWork += ReceiveMessageFromCloud;
backgroundWorker.RunWorkerAsync();
Message Feedback
Although cloud to device messages are a one-way communication style, we can request feedback on the delivery of the message, allowing us to invoke retries or start compensation when the message fails to be delivered. To do this, implement the following method in our EngineManagement backend application.
private async void ReceiveFeedback(object sender, DoWorkEventArgs e)
{
var feedbackReceiver = serviceClient.GetFeedbackReceiver();
while (true)
{
var feedbackBatch = await feedbackReceiver.ReceiveAsync();
// Check if feedback messages were received
if (feedbackBatch == null)
{
continue;
}
// Loop through feedback messages
foreach(var feedback in feedbackBatch.Records)
{
if(feedback.StatusCode != FeedbackStatusCode.Success)
{
// Handle compensation here
}
}
await feedbackReceiver.CompleteAsync(feedbackBatch);
}
}
And add the following code to the constructor.
var backgroundWorker = new BackgroundWorker();
backgroundWorker.DoWork += ReceiveFeedback;
backgroundWorker.RunWorkerAsync();
Call Remote Method
Another feature when sending messages from the cloud to our devices is to call a remote method on the device, which we call invoking a direct method. This type of communication is used when we want to have an immediate confirmation of the outcome of the command (unlike setting the desired state and communicating back reported properties, which has been explained in the previous two blog posts). Let’s update the EngineManagement application by adding the following controls, which would allow us to send an alarm message to the engine, sounding the alarm and displaying a message.
Now add the following event handler for clicking the Send Alarm button.
private async void ButtonSendAlarm_Click(object sender, EventArgs e)
{
var methodInvocation = new CloudToDeviceMethod("SoundAlarm") { ResponseTimeout = TimeSpan.FromSeconds(300) };
methodInvocation.SetPayloadJson(JsonConvert.SerializeObject(new { message = textBoxMessage.Text }));
CloudToDeviceMethodResult response = null;
try
{
response = await serviceClient.InvokeDeviceMethodAsync(comboBoxSerialNumber.Text, methodInvocation);
}
catch (IotHubException)
{
// Do nothing
}
if (response != null (&) & JObject.Parse(response.GetPayloadAsJson()).GetValue("acknowledged").Value<bool>())
{
MessageBox.Show("Message was acknowledged.", "Information", MessageBoxButtons.OK, MessageBoxIcon.Information);
}
else
{
MessageBox.Show("Message was not acknowledged!", "Warning", MessageBoxButtons.OK, MessageBoxIcon.Warning);
}
}
And in our simulated device, implement the SoundAlarm remote method which is being called.
private static Task<MethodResponse> SoundAlarm(MethodRequest methodRequest, object userContext)
{
// On a real engine this would sound the alarm as well as show the message
Console.ForegroundColor = ConsoleColor.Red;
Console.WriteLine($"Alarm sounded with message: {JObject.Parse(methodRequest.DataAsJson).GetValue("message").Value<string>()}! Type yes to acknowledge.");
Console.ForegroundColor = ConsoleColor.White;
var response = JsonConvert.SerializeObject(new { acknowledged = Console.ReadLine() == "yes" });
return Task.FromResult(new MethodResponse(Encoding.UTF8.GetBytes(response), 200));
}
And finally, we need to map the SoundAlarm method to the incoming remote method call. To do this, add the following line in the Main method.
client.SetMethodHandlerAsync("SoundAlarm", SoundAlarm, null);
Call Remote Method On Multiple Devices
When invoking direct methods on devices, we can also use jobs to send the command to multiple devices. We can use our custom tags here to broadcast our message to a specific set of devices.
In this case, we will add a filter to the engine type and manufacturer, so we can, for example, send a message to all main engines manufactured by Caterpillar. In our first blog post, we added these properties as tags on the device twin, so we now use these in our filter. Start by adding the following controls to our EngineManagement application.
Now add a JobClient to the application, which will be used to broadcast and monitor our messages.
private readonly JobClient jobClient = JobClient.CreateFromConnectionString("HostName=youriothubname.azure-devices.net;SharedAccessKeyName=iothubowner;SharedAccessKey=yoursharedaccesskey");
To broadcast our message, update the event handler for the Send Alarm button to the following.
private async void ButtonSendAlarm_Click(object sender, EventArgs e)
{
var methodInvocation = new CloudToDeviceMethod("SoundAlarm") { ResponseTimeout = TimeSpan.FromSeconds(300) };
methodInvocation.SetPayloadJson(JsonConvert.SerializeObject(new { message = textBoxMessage.Text }));
if (checkBoxBroadcast.Checked)
{
try
{
var jobResponse = await jobClient.ScheduleDeviceMethodAsync(Guid.NewGuid().ToString(), $"tags.engineType = '{comboBoxEngineTypeFilter.Text}' and tags.manufacturer = '{textBoxManufacturerFilter.Text}'", methodInvocation, DateTime.Now, 10);
await MonitorJob(jobResponse.JobId);
}
catch (IotHubException)
{
// Do nothing
}
}
else
{
CloudToDeviceMethodResult response = null;
try
{
response = await serviceClient.InvokeDeviceMethodAsync(comboBoxSerialNumber.Text, methodInvocation);
}
catch (IotHubException)
{
// Do nothing
}
if (response != null && JObject.Parse(response.GetPayloadAsJson()).GetValue("acknowledged").Value<bool>())
{
MessageBox.Show("Message was acknowledged.", "Information", MessageBoxButtons.OK, MessageBoxIcon.Information);
}
else
{
MessageBox.Show("Message was not acknowledged!", "Warning", MessageBoxButtons.OK, MessageBoxIcon.Warning);
}
}
}
And finally, add the MonitorJob method with the following implementation.
public async Task MonitorJob(string jobId)
{
JobResponse result;
do
{
result = await jobClient.GetJobAsync(jobId);
Thread.Sleep(2000);
}
while (result.Status != JobStatus.Completed && result.Status != JobStatus.Failed);
// Check if all devices successful
if (result.DeviceJobStatistics.FailedCount > 0)
{
MessageBox.Show("Not all engines reported success!", "Warning", MessageBoxButtons.OK, MessageBoxIcon.Warning);
}
else
{
MessageBox.Show("All engines reported success.", "Information", MessageBoxButtons.OK, MessageBoxIcon.Information);
}
}
Conclusion
By using IoT Hub we have a safe and secure way of communicating from the cloud and our backend to devices out in the field. We have seen how we can use the cloud to device messages in case we want to send one-way messages to our device or use direct methods when we want to be informed of the outcome from our invocation. By using jobs, we can also call out to multiple devices at once, limiting the devices being called by using (custom) properties of the device twin.
