Welcome back!

In this lesson, we’ll talk about device configuration.

There are a lot of non-functional tasks that you may need to perform, such as device maintenance and IoT Hub provides some different options to handle this sort of thing.

You can use device twins which is a mechanism to synchronize the device state and configuration between the cloud and the device.
Then you have queries which are a tool to create dynamic reporting across device twins and jobs to check the device status and health.

You can also use direct methods that allow you to perform interactive actions on devices.

You also have jobs, though we won’t be covering them in this course.

Let’s go through these options and we’ll start with device twins.
So, what is a device twin?

A device twin is the logical representation of a device, it’s a JSON document that stores device information, such as tags, desired properties, and reported properties. The document is stored in IoT Hub, and not on the device, which allows you to query the info even if the device is offline.

The device twin is a JSON document, however there are some limitations.

For example, the maximum nesting depth is 5 layers, also the size of a property values can’t be larger than 8 kilobytes.

And while you can use, boolean, number, string, and objects, arrays are not allowed.

The document is updated and synchronized with the device and contains timestamps to handle versioning at the property level.

You may be wondering why you’d use a device twin instead plain old messages for configuration. And that’s a good question. Device twins allow you to adjust the desired properties, in a central location, and when devices connect they can pick up on the changes.

Devices also have their own local state, and the state will change over time. For example, battery level, if a switch is open or closed, etc. And you’ll want to be able to query the values of those properties.

Maybe you want to be able to see all vending machines with low inventory, for that you need the device to report its state. That's the role of reported properties. From the services point of view, IoT Hub receives a message from the device endpoint about the property updates, and changes it for the twin.

All the device twins are persisted in the device registry, in a sort of NoSQL database.

All data in the twins can be queried with a SQL-like language to perform any list or summary queries.

So device twins, are a great way to get and set desired properties.
What if we just want to invoke a method on a device? For example, what if you wanted to reboot a device? Or revert the device to the factory settings, or apply a firmware update?

This is the role of "direct methods".

Direct methods represent a request-reply interaction with the device, similar to an HTTP call, in that they succeed or fail immediately.

You use direct methods for operations that require an immediate confirmation. A device receives direct methods through a device-specific MQTT endpoint.

Now, let's try device configuration with a demo.

We are here in the PowerShell script, have a new command to "handle properties". Let’s run this. And you can see that something is already happening.

The application is reporting continuously the value of a property named "ReportedCounter". This is a fictional value that is increasing over time.

There is a delay from 100 milliseconds to 1,000 milliseconds between each notification.

So, if we go to the DeviceRegistry script, we can see that there is a new application that’s called IoT Hub Device Configuration that has some commands.

For example, we can execute the ”get" command on the device with an ID of Alert1. So let’s run this.

Notice that there is tag property named "location" with a value of, “Europe.” Then there are some desired properties, and some reported properties.

Take note of the reported properties, it’s currently 168.

So if we execute this again the value is now 192. So the reportedCounter is updated continuously by the device.

We can also look at the desired properties.

For example, we can change the value for sleep min and sleep max properties that specify the delay, let’s change sleep min property value to 1,000…Okay.

And then we can set the sleep max property value to 3,000…perfect!

Notice that on the device, the intervals have already changed.

So this is great, we can set a property and have it picked up. Let’s change one more, let’s change the location.

You can see that Alert1 is located in “Europe".

So, let’s change this location value, and let’s change it to America, and run this command.

And if I run the "get twin" command, and you see that location now is “America".

Awesome!

Now, we can also query twin data, and for that I have a query twin command and query name all parameter implemented in the device configuration.

If I run this, you can see it returns all the twin data. Alert1, North3, North6, South2..great.

Now we can execute a query that filters devices only located in America.

And you can see that we have only a couple of devices, which are Alert1 and North3.

So, that’s a look at how to programmatically work with device twins.

Alright, let’s try out direct methods now.

Let’s start the DeviceSimulator with the command "handle direct method".

Now using the DeviceService we can invoke "direct method”, and the method name parameter is set to uptime. So this should invoke an uptime method on the device itself.

Let’s run this, the DeviceSimulator traces when it receives an invoke request and returns a result.

And looking at the result of the service, there’s an OK message. So, direct method invocation is a great way to fire off methods on the devices.

Okay, let’s wrap up here.

Being able to configure devices with device twins will allow for scalable device configuration as well as provide you with the ability to query devices based on their properties.

And direct methods are a great way to run methods on one or more devices, and that provides a lot of power for making device changes.

In the next lesson, wrap up this course with some final thoughts.

I’ll see you in the next lesson!