Device management in Windows IoT Core
In Fall 2016, Microsoft announced Azure IoT Hub device management, providing the features and extensibility model, including an SDK for a wide range of platforms, to build robust device management solutions. With the recent release of the Windows 10 Creators Update, we are excited to announce the availability of the Windows IoT Azure DM Client Library. The open source library allows developers to easily add device management capabilities to their Azure connected Windows IoT Core device. Enterprise device management for Windows has been available for many years. The Windows IoT Azure DM Client Library makes these capabilities, such as device restart, certificate and application management, as well as many others, available via Azure IoT Hub device management.
A quick introduction
IoT devices, in comparison to desktops, laptops and phones, have in many cases a much more restricted connectivity, less local resources and in many cases no UI. Remote device management also requires devices to be provisioned for a DM service, adding another challenge to the device setup.
Azure IoT DM is designed for devices with resource and connectivity restrictions. Those devices will also use Azure IoT for their operation, so they need to be provisioned for Azure IoT. This makes Azure IoT DM a very attractive choice for remote device management for IoT devices.
Device management in Windows 10 is based on the Configuration Service Provider (CSP) model. A CSP is an interface in Windows that allows reading and modification of settings of a specific feature of the device. For example, a Wi-Fi profile can be configured with the Wi-Fi CSP, the Reboot CSP is used to configure reboot settings, and so on.
All the CSPs ultimately map into API calls, registry keys and changes in the file system. The CSPs raise the level of abstraction and offer a consistent interface that works on all editions of Windows – desktop, mobile and IoT. The Windows IoT Azure DM Client Library will use the same, proven infrastructure.
Windows IoT Core + Azure IoT Hub: Better together
Azure IoT Hub provides the features and an extensibility model that enable device and back-end developers to build robust device management solutions. Devices can report their state to the Azure IoT Hub and can receive desired state updates and management commands from the Azure IoT Hub.
Device management in Azure IoT is based on the concepts of the device twin and the direct methods. The device twins are JSON documents that store device state information (metadata, configurations and conditions). IoT Hub persists a device twin for each device that you connect to IoT Hub. The device twin contains the reported properties that reflect the current state of the device, and the desired properties that represent the expected configuration of the device. Direct methods allow the back-end to send a message to a connected device and receive a response.
The device twin and the direct methods can be used to support the business logic of your IoT solution as well as implementing the device management operations.
The Windows IoT Azure DM Client Library connects the CSP-based device management stack in Windows IoT Core with the cloud back-end based on Azure IoT Hub. The client runs on the device and translates the direct method calls and desired properties updates to the CSP calls. The client also queries the device state using the CSP calls and translates that into reported properties for the device twin in the Azure IoT Hub.
Before an IoT device can be managed through the Azure IoT Hub, it must be registered with a unique device identity and an authentication key. The authentication key needs to be securely stored on the device to prevent accidental or malicious duplication of the device identity. In Windows 10 IoT Core the key can be stored in the TPM. How this is done is described in the previous post Building Secure Apps for Windows IoT Core.
With the device provisioned with Azure IoT Hub credentials (connection information and authentication key), managing Windows 10 Core devices through Azure IoT Hub requires no additional enrollment or configuration.
In this post, we will focus mostly on the client aspects of the device management. Please refer to the general Azure IoT Hub device management documentation for a broader look at what the service provides. Below we explore how the Azure IoT Hub device twin and direct methods can be used to manage Windows IoT Core devices.
How to use the Windows IoT Azure DM Client Library
Devices connecting to Azure IoT Hub can only have one connection to the service. This means that all applications, including the DM library, must share an Azure IoT Hub connection. We will provide two sample implementations that you can use depending on if your device has other applications that will connect to the same IoT Hub, as the same device.
Standalone device management client
If your device only needs Azure IoT Hub for device management and no other application will connect to the same IoT Hub using the same Azure device ID, you can use the IoTDMBackground sample to add DM capabilities to your device.
The IoTDMBackground is a background app that can be deployed on your device. The IoTDMBackground app requires the device to be securely connected to Azure IoT. Once started, the IoTDMBackground will receive direct method calls and device twin updates from the Azure IoT Hub, and perform the device management operations.
Integrated device management client
There are scenarios where the capabilities of the standalone device management client are insufficient:
- Some device management, e.g. a device reboot or an application restart, might interrupt the normal operation of the device. In cases where this is not acceptable, the device should be able to declare itself busy and decline or postpone the operation.
- If your app is already connected to the Azure IoT Hub (for example, sending telemetry messages, receiving direct method calls and device twin updates), it cannot share its Azure identity with another app on the system, such as the IoTDMBackground.
- Some IoT devices expose basic device management capabilities to the user – such as the “check for updates” button or various configuration settings. Implementing this in your app is not an easy task even if you know which API or CSP you need to invoke.
The purpose of the integrated device management client is to address these scenarios. The integrated device management client is a .NET library that links to your IoT app. The library is called the IoTDMClientLib and is part of the IoTDM.sln solution. The library allows your app to declare its busy state, share device identity between itself and your app, and invoke some common device management operations.
To integrate the device management to your app, build the IoTDMClientLib project, which will produce the IoTDMClientLib.dll. You will reference it in your app.
The ToasterApp project in the IoTDM.sln solution is a sample application that uses the integrated client. You can study it and use it as an example, or if you prefer step-by-step instructions, follow the guidance below.
1. If your app is already connected to the Azure IoT Hub, you already have an instance of DeviceClient instantiated somewhere in your app. Normally it would look like this:
[code lang=”csharp”]
DeviceClient deviceClient =
DeviceClient.CreateFromConnectionString(connectionString, TransportType.Mqtt);
[/code]
2. Now use the DeviceClient object to instantiate the AzureIoTHubDeviceTwinProxy object for connecting your device management client to Azure IoT Hub:
[code lang=”csharp”]
IDeviceTwin deviceTwinProxy = new AzureIoTHubDeviceTwinProxy(deviceClient);
[/code]
3. Your app needs to implement the IDeviceManagementRequestHandler interface which allows the device management client to query your app for busy state, app details and so on:
[code lang=”csharp”]
IDeviceManagementRequestHandler appRequestHandler = new MyAppRequestHandler(this);
[/code]
You can look at ToasterDeviceManagementRequestHandler implementation for an example of how to implement the request handler interface.
Next, add the using Microsoft.Devices.Management statement at the top of your file, and the systemManagement capability to your application’s manifest (see ToasterAppPackage.appxmanifest file).
You are now ready to create the DeviceManagementClient object:
[code lang=”csharp”]
this.deviceManagementClient = await
DeviceManagementClient.CreateAsync(deviceTwinProxy, appRequestHandler);
[/code]
You can use this object to perform some common device management operations.
Finally, we will set up the callback that handles the desired properties updates (if your application already uses the device twin, it will already have this call):
[code lang=”csharp”]
await deviceClient.SetDesiredPropertyUpdateCallback(OnDesiredPropertyUpdate, null);
[/code]
The callback will be invoked for all the desired properties – those specific to device management and those that are not. This is why we need to let the device management client filter out and handle properties that it is responsible for:
[code lang=”csharp”]
public Task OnDesiredPropertyUpdate(TwinCollection desiredProperties,
object userContext)
{
// Let the device management client process properties
// specific to device management
this.deviceManagementClient.ProcessDeviceManagementProperties(desiredProperties);
// App developer can process all the top-level nodes here
return Task.CompletedTask;
}
[/code]
As an app developer, you’re still in control. You can see all the property updates received by the callback but delegate the handling of the device management-specific properties to the device management client, letting your app focus on its business logic.
To deploy and run your app, follow the instructions here.
The end-to-end solution
Obviously, the entire device management solution requires two parts – the client running on the device and the back-end component running in the cloud. Typically, your back-end component will consist of the Azure IoT Hub, which is the entry point into the cloud for your devices, coupled with other Azure services that support the logic of your application – data storage, data analytics, web services, etc.
Fortunately, you don’t need to build a full solution to try out your client. You can use the existing tools such as the DeviceExplorer to trigger direct method calls and device twin changes for your devices.
For example, to send the immediate reboot command to your IoT device, call microsoft.management.immediateReboot direct method on your device:
The device management client running on the IoT device will respond to the direct method and (unless it is in busy state) proceed with rebooting the device.
The Windows IoT Azure DM Client Library supports a variety of device management operations listed in the documentation on the GitHub site. In addition to the reboot management, application management, update, factory reset and more are supported. The list of capabilities will grow as the project evolves.
The Windows IoT Azure DM Client Library includes a sample called the DM Dashboard, which hides the implementation detail of the device management operations. Unlike the Device Explorer, you don’t need to consult the documentation and manually craft JSON to use it.
Here is how you can invoke the reboot operation using the DM Dashboard tool:
The DM Dashboard is a convenient tool for testing the client side of your device management solution, but since it operates on one device at a time, it is not suitable for managing multiple devices in a production environment.
Next steps
The Windows IoT Azure DM Client Library is still in beta phase and will continue to evolve. We’re very interested in your feedback, and we want to learn about your IoT needs. So, head over to our GitHub page, clone the repo and tell us what you think.