Get started with device management (Node)

Back-end apps can use Azure IoT Hub primitives, such as device twin and direct methods, to remotely start and monitor device management actions on devices. This tutorial shows you how a back-end app and a device app can work together to initiate and monitor a remote device reboot using IoT Hub.

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 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 contains a direct method that reboots that device. Direct methods are invoked from 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 two Node.js console apps:

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.

dmpatterns_getstarted_service.js, 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:

  • 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.)

Create an IoT hub

Create an IoT hub for your simulated device app to connect to. The following steps show you how to complete this task by using the Azure portal.

  1. Sign in to the Azure portal.
  2. In the Jumpbar, click New > Internet of Things > IoT Hub.

    Azure portal Jumpbar

  3. In the IoT hub blade, choose the configuration for your IoT hub.

    IoT hub blade

    1. In the Name box, enter a name for your IoT hub. If the Name is valid and available, a green check mark appears in the Name box.
    2. Select a pricing and scale tier. This tutorial does not require a specific tier. For this tutorial, use the free F1 tier.
    3. In Resource group, either create a resource group, or select an existing one. For more information, see Using resource groups to manage your Azure resources.
    4. In Location, select the location to host your IoT hub. For this tutorial, choose your nearest location.
  4. When you have chosen your IoT hub configuration options, click Create. It can take a few minutes for Azure to create your IoT hub. To check the status, you can monitor the progress on the Startboard or in the Notifications panel.

    New IoT hub status

  5. When the IoT hub has been created successfully, click the new tile for your IoT hub in the Azure portal to open the blade for the new IoT hub. Make a note of the Hostname, and then click Shared access policies.

    New IoT hub blade

  6. In the Shared access policies blade, click the iothubowner policy, and then copy and make note of the IoT Hub connection string in the iothubowner blade. For more information, see Access control in the "IoT Hub developer guide."

    Shared access policies blade

Create a device identity

In this section, you use a Node.js tool called iothub-explorer to create a device identity for this tutorial.

  1. Run the following in your command-line environment:

    npm install -g iothub-explorer@latest

  2. Then, run the following command to login to your hub. Substitute {iot hub connection string} with the IoT Hub connection string you previously copied:

    iothub-explorer login "{iot hub connection string}"

  3. Finally, create a new device identity called myDeviceId with the command:

    iothub-explorer create myDeviceId --connection-string

Make a note of the device connection string from the result. This device connection string is used by the device app to connect to your IoT Hub as a device.

Refer to Getting started with IoT Hub to programmatically create device identities.

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 an 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 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. 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.
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.

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. The app uses device twin queries to discover the last reboot time for that device.

  1. Create an empty folder called triggerrebootondevice. In the triggerrebootondevice 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 triggerrebootondevice folder, run the following command to install the azure-iothub Device SDK package and azure-iot-device-mqtt package:

    npm install azure-iothub --save
    
  3. Using a text editor, create a dmpatterns_getstarted_service.js file in the triggerrebootondevice folder.
  4. Add the following 'require' statements at the start of the dmpatterns_getstarted_service.js file:

    'use strict';
    
    var Registry = require('azure-iothub').Registry;
    var Client = require('azure-iothub').Client;
    
  5. Add the following variable declarations and replace the placeholder values:

    var connectionString = '{iothubconnectionstring}';
    var registry = Registry.fromConnectionString(connectionString);
    var client = Client.fromConnectionString(connectionString);
    var deviceToReboot = 'myDeviceId';
    
  6. Add the following function to invoke the device method to reboot the target device:

    var startRebootDevice = function(twin) {
    
        var methodName = "reboot";
    
        var methodParams = {
            methodName: methodName,
            payload: null,
            timeoutInSeconds: 30
        };
    
        client.invokeDeviceMethod(deviceToReboot, methodParams, function(err, result) {
            if (err) { 
                console.error("Direct method error: "+err.message);
            } else {
                console.log("Successfully invoked the device to reboot.");  
            }
        });
    };
    
  7. Add the following function to query for the device and get the last reboot time:

    var queryTwinLastReboot = function() {
    
        registry.getTwin(deviceToReboot, function(err, twin){
    
            if (twin.properties.reported.iothubDM != null)
            {
                if (err) {
                    console.error('Could not query twins: ' + err.constructor.name + ': ' + err.message);
                } else {
                    var lastRebootTime = twin.properties.reported.iothubDM.reboot.lastReboot;
                    console.log('Last reboot time: ' + JSON.stringify(lastRebootTime, null, 2));
                }
            } else 
                console.log('Waiting for device to report last reboot time.');
        });
    };
    
  8. Add the following code to call the functions that trigger the reboot direct method and query for the last reboot time:

    startRebootDevice();
    setInterval(queryTwinLastReboot, 2000);
    
  9. Save and close the dmpatterns_getstarted_service.js file.

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. At the command prompt in the triggerrebootondevice folder, run the following command to trigger the remote reboot and query for the device twin to find the last reboot time.

    node dmpatterns_getstarted_service.js
    
  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 by using 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. You used the reported properties to report the last reboot time from the device, and queried 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 IoT Edge.