Skip to content

Latest commit

 

History

History
250 lines (186 loc) · 13 KB

iot-hub-csharp-node-device-management-get-started.md

File metadata and controls

250 lines (186 loc) · 13 KB
title description services documentationcenter author manager editor ms.assetid ms.service ms.devlang ms.topic ms.tgt_pltfrm ms.workload ms.date ms.author
Get started with Azure IoT Hub device management (.NET/Node) | Microsoft Docs
How to use Azure IoT Hub device management to initiate a remote device reboot. You use the Azure IoT device SDK for Node.js to implement a simulated device app that includes a direct method and the Azure IoT service SDK for .NET to implement a service app that invokes the direct method.
iot-hub
.net
juanjperez
timlt
e044006d-ffd6-469b-bc63-c182ad066e31
iot-hub
multiple
article
na
na
11/17/2016
juanpere

Get started with device management (.NET/Node)

[!INCLUDE iot-hub-selector-dm-getstarted]

Introduction

Back-end apps can use primitives in Azure IoT Hub, namely the device twin and direct methods, to remotely start and monitor device management actions on devices. This article provides guidance and code for how back-end apps and devices work together to initiate and monitor a remote device reboot using IoT Hub.

To remotely start and monitor device management actions on your devices from a cloud-based, back-end app, use IoT Hub primitives such as device twin and direct methods. This tutorial shows you how a back-end app and a device can work together to enable you initiate and monitor remote device reboot from IoT Hub.

You use a direct method to initiate device management actions (such as reboot, factory reset, and firmware update) from a back-end app in the cloud. The device is responsible for:

  • Handling the method request sent from IoT Hub.
  • Initiating the corresponding device specific action on the device.
  • Providing status updates through the reported properties to IoT Hub.

You can use a back-end app in the cloud to run device twin queries to report on the progress of your device management actions.

This tutorial shows you how to:

  • Use the Azure portal to create an IoT Hub and create a device identity in your IoT hub.
  • Create a simulated device app that has a direct method which enables reboot which can be called by the cloud.
  • Create a .NET console app that calls the reboot direct method in the simulated device app through your IoT hub.

At the end of this tutorial, you have a Node.js console device app and a .NET (C#) console back-end app:

dmpatterns_getstarted_device.js, which connects to your IoT hub with the device identity created earlier, receives a reboot direct method, simulates a physical reboot, and reports the time for the last reboot.

TriggerReboot, which calls a direct method in the simulated device app, displays the response, and displays the updated reported properties.

To complete this tutorial, you need the following:

  • Microsoft Visual Studio 2015.
  • Node.js version 0.12.x or later,
    Prepare your development environment describes how to install Node.js for this tutorial on either Windows or Linux.
  • An active Azure account. (If you don't have an account, you can create a free account in just a couple of minutes.)

[!INCLUDE iot-hub-get-started-create-hub]

[!INCLUDE iot-hub-get-started-create-device-identity]

Trigger a remote reboot on the device using a direct method

In this section, you create a .NET console app (using C#) that initiates a remote reboot on a device using a direct method and uses device twin queries to find the last reboot time for that device.

  1. In Visual Studio, add a Visual C# Windows Classic Desktop project to the current solution by using the Console Application project template. Name the project TriggerReboot.

    New Visual C# Windows Classic Desktop project

  2. In Solution Explorer, right-click the TriggerReboot project, and then click Manage NuGet Packages.

  3. In the NuGet Package Manager window, select Browse, search for microsoft.azure.devices, select Install to install the Microsoft.Azure.Devices package, and accept the terms of use. This procedure downloads, installs, and adds a reference to the Azure IoT service SDK NuGet package and its dependencies.

    NuGet Package Manager window

  4. Add the following using statements at the top of the Program.cs file:

     using Microsoft.Azure.Devices;

  5. Add the following fields to the Program class. Replace the placeholder value with the IoT Hub connection string for the hub that you created in the previous section and the target device.

     static RegistryManager registryManager;
 static string connString = "{iot hub connection string}";
 static ServiceClient client;
 static JobClient jobClient;
 static string targetDevice = "{deviceIdForTargetDevice}";

  6. Add the following method to the Program class. This code gets the device twin for the rebooting device and outputs the reported properties.

     public static async Task QueryTwinRebootReported()
 {
     Twin twin = await registryManager.GetTwinAsync(targetDevice);
     Console.WriteLine(twin.Properties.Reported.ToJson());
 }

  7. Add the following method to the Program class. This code initiates the reboot on the device using a direct method.

     public static async Task StartReboot()
 {
     client = ServiceClient.CreateFromConnectionString(connString);
     CloudToDeviceMethod method = new CloudToDeviceMethod("reboot");
     method.ResponseTimeout = TimeSpan.FromSeconds(30);

     CloudToDeviceMethodResult result = await client.InvokeDeviceMethodAsync(targetDevice, method);

     Console.WriteLine("Invoked firmware update on device.");
 }

  8. Finally, add the following lines to the Main method:

     registryManager = RegistryManager.CreateFromConnectionString(connString);
 StartReboot().Wait();
 QueryTwinRebootReported().Wait();
 Console.WriteLine("Press ENTER to exit.");
 Console.ReadLine();

  9. Build the solution.

Create a simulated device app

In this section, you will

  • Create a Node.js console app that responds to a direct method called by the cloud
  • Trigger a simulated device reboot
  • Use the reported properties to enable device twin queries to identify devices and when they last rebooted

  1. Create a new empty folder called manageddevice. In the manageddevice folder, create a package.json file using the following command at your command prompt. Accept all the defaults:

    npm init

  2. At your command prompt in the manageddevice folder, run the following command to install the azure-iot-device Device SDK package and azure-iot-device-mqtt package:

    npm install azure-iot-device azure-iot-device-mqtt --save

  3. Using a text editor, create a new dmpatterns_getstarted_device.js file in the manageddevice folder.

  4. Add the following 'require' statements at the start of the dmpatterns_getstarted_device.js file:

    'use strict';

var Client = require('azure-iot-device').Client;
var Protocol = require('azure-iot-device-mqtt').Mqtt;

  5. Add a connectionString variable and use it to create a Client instance. Replace the connection string with your device connection string.

    var connectionString = 'HostName={youriothostname};DeviceId=myDeviceId;SharedAccessKey={yourdevicekey}';
var client = Client.fromConnectionString(connectionString, Protocol);

  6. Add the following function to implement the direct method on the device

    var onReboot = function(request, response) {

    // Respond the cloud app for the direct method
    response.send(200, 'Reboot started', function(err) {
        if (!err) {
            console.error('An error occured when sending a method response:\n' + err.toString());
        } else {
            console.log('Response to method \'' + request.methodName + '\' sent successfully.');
        }
    });

    // Report the reboot before the physical restart
    var date = new Date();
    var patch = {
        iothubDM : {
            reboot : {
                lastReboot : date.toISOString(),
            }
        }
    };

    // Get device Twin
    client.getTwin(function(err, twin) {
        if (err) {
            console.error('could not get twin');
        } else {
            console.log('twin acquired');
            twin.properties.reported.update(patch, function(err) {
                if (err) throw err;
                console.log('Device reboot twin state reported')
            });  
        }
    });

    // Add your device's reboot API for physical restart.
    console.log('Rebooting!');
};

  7. Add the following code to open the connection to your IoT hub and start the direct method listener:

    client.open(function(err) {
    if (err) {
        console.error('Could not open IotHub client');
    }  else {
        console.log('Client opened.  Waiting for reboot method.');
        client.onDeviceMethod('reboot', onReboot);
    }
});

  8. Save and close the dmpatterns_getstarted_device.js file.

    [AZURE.NOTE] To keep things simple, this tutorial does not implement any retry policy. In production code, you should implement retry policies (such as an exponential backoff), as suggested in the MSDN article Transient Fault Handling.

Run the apps

You are now ready to run the apps.

  1. At the command prompt in the manageddevice folder, run the following command to begin listening for the reboot direct method.

    node dmpatterns_getstarted_device.js

  2. Run the C# console app TriggerReboot- right click on the TriggerReboot project, select Debug and Start new instance.

  3. You see the device response to the direct method in the console.

Customize and extend the device management actions

Your IoT solutions can expand the defined set of device management patterns or enable custom patterns through the use of the device twin and cloud-to-device method primitives. Other examples of device management actions include factory reset, firmware update, software update, power management, network and connectivity management, and data encryption.

Device maintenance windows

Typically, you configure devices to perform actions at a time that minimizes interruptions and downtime. Device maintenance windows are a commonly used pattern to define the time when a device should update its configuration. Your back-end solutions can use the desired properties of the device twin to define and activate a policy on your device that enables a maintenance window. When a device receives the maintenance window policy, it can use the reported property of the device twin to report the status of the policy. The back-end app can then use device twin queries to attest to compliance of devices and each policy.

Next steps

In this tutorial, you used a direct method to trigger a remote reboot on a device, used the reported properties to report the last reboot time from the device, and queried for the device twin to discover the last reboot time of the device from the cloud.

To continue getting started with IoT Hub and device management patterns such as remote over the air firmware update, see:

Tutorial: How to do a firmware update

To learn how to extend your IoT solution and schedule method calls on multiple devices, see the Schedule and broadcast jobs tutorial.

To continue getting started with IoT Hub, see Getting started with the IoT Gateway SDK.