Twins

If you are old enough, the movie with Arnold Schwarzenegger and Danny De Vito might come to mind. In this section though, the twins we will talk about are of the more serious kind.

Device twins are part of the Azure IoT Device Management capabilities that were introduced end of 2016, beginning of 2017. Device twins offer several features that make managing your devices easier. Don't get your hopes up however, because System Center Configuration Manager for IoT devices it is not!

So what are device twins exactly? They are constructs, more specifically Json documents, that store device state information. You can use them in several scenarios:

• store device metadata like the location of the device (e.g. room Asterix)
• report state information from your device's application (e.g. connection information - Wifi, battery level - 83% , free memory - 26567 bytes)
• set desired properties for your device to listen to (e.g. reportInterval)
• keep track of longer running workflows such as the stages of a firmware update

Before the existence of device twins, you had to provide your own mechanisms to support the above scenarios. For instance, if you wanted to store the device's location, you had to do so in a separate store like Cosmos DB or SQL Server.

Note that you do not have to do anything special to create a device twin. When you create a device in IoT Hub as discussed in the Devices section, a device twin is implicitly created. You can see the device twin in the Azure Portal (click Device Twin link in the Device Details pane):

In the device twin Json document, there are three main sections:

• Tags: used by the solution back end to query devices (e.g. device in room Asterix, or all devices on the sixth floor); devices cannot read these tags using the MQTT protocol or device SDKs
• Desired properties: these properties are set by the solution back end and can be read by the device which is notified in real time (i.e. notification is real time due to an MQTT topic subscription and associated callback function in your code)
• Reported properties: these properties are set by the device and reported to the back end (i.e. set by an MQTT publish of a Json message on a specific system topic)

IoT Hub allows you to store 8KB of tags and properties.

Note that the device twin in the previous screenshot does not contain any tags. If you want to add a tag like room you can do so directly from the portal. Modify the Json so that it looks like the example below (added the tags object).

{
  "deviceId": "arduino",
  "etag": "AAAAAAAAAAE=",

  "tags": {
    "deviceLocation": {
      "building": "Ahlers",
      "floor": 6,
      "room": "Asterix"
    }
  },

  "properties": {
    "desired": {
      "$metadata": {
        "$lastUpdated": "2017-05-14T20:51:19.4161325Z"
      },
      "$version": 1
    },
    "reported": {
      "$metadata": {
        "$lastUpdated": "2017-05-14T20:51:19.4161325Z"
      },
      "$version": 1
    }
  }
}

Above, a Json object deviceLocation was added that contains the building, floor and room. We can now use the Azure Portal to query for devices based on these tags from the Device Explorer:

If you want to add a desired property, you can do so directly in the document as well. If you set a reported property, it will be removed because only devices can set a reported property (using the MQTT protocol).

The above query is of course very simple. The query language is capable of much more as discussed in the documentation.

In addition to setting tags and properties on device twins and querying device twins from the Portal, there are HTTP endpoints available for device twin management. The documentation for these APIs is in the larger Azure REST API reference. Some of the things you can do are:

• Get device twin: retrieve the entire device twin
• Update device twin: to set tags or desired properties

Ok, this section was mostly theory. Time for action! In the Connect with MQTT section, we will write an Arduino sketch that reads a desired property reportInterval to set the amount of milliseconds to wait between each send. When the device receives that desired property, it reports the reportInterval back to inform the back end that the change was implemented.