Get started with device management (Node.js)

Article
07/24/2024

Back-end apps can use Azure IoT Hub primitives, such as device twins and direct methods, to remotely start and monitor device management actions on devices. This article 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.

Note

The features described in this article are available only in the standard tier of IoT Hub. For more information about the basic and standard/free IoT Hub tiers, see Choose the right IoT Hub tier for your solution.

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 article shows you how to create:

dmpatterns_getstarted_device.js: a simulated device app with a direct method that reboots the device and reports the last reboot time. Direct methods are invoked from the cloud.
dmpatterns_getstarted_service.js: a .NET console app that calls the direct method in the simulated device app through your IoT hub. It displays the response and updated reported properties.

Prerequisites

An IoT hub in your Azure subscription. If you don't have a hub yet, you can follow the steps in Create an IoT hub.
A device registered in your IoT hub. If you don't have a device in your IoT hub, follow the steps in Register a device.
Node.js version 10.0.x or later. Prepare your development environment describes how to install Node.js for this article on either Windows or Linux.
Make sure that port 8883 is open in your firewall. The device sample in this article uses MQTT protocol, which communicates over port 8883. This port may be blocked in some corporate and educational network environments. For more information and ways to work around this issue, see Connecting to IoT Hub (MQTT).

Create a device app with a direct method

In this section, you:

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.

Create an empty folder called managed-device. In the managed-device folder, create a package.json file using the following command at your command prompt. Accept all the defaults:
```
npm init
```
At your command prompt in the managed-device 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
```
Using a text editor, create a dmpatterns_getstarted_device.js file in the managed-device folder.

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;

Add a connectionString variable and use it to create a Client instance. Replace the {yourdeviceconnectionstring} placeholder value with the device connection string you saw when you registered a device in the IoT Hub:
```
var connectionString = '{yourdeviceconnectionstring}';
var client = Client.fromConnectionString(connectionString, Protocol);
```

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 occurred 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!');
};

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);
    }
});

Save and close the dmpatterns_getstarted_device.js file.

Note

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

Get the IoT hub connection string

In this article, you create a backend service that invokes a direct method on a device. To invoke a direct method on a device through IoT Hub, your service needs the service connect permission. By default, every IoT Hub is created with a shared access policy named service that grants this permission.

To get the IoT Hub connection string for the service policy, follow these steps:

In the Azure portal, select Resource groups. Select the resource group where your hub is located, and then select your hub from the list of resources.
On the left-side pane of your IoT hub, select Shared access policies.
From the list of policies, select the service policy.
Copy the Primary connection string and save the value.

For more information about IoT Hub shared access policies and permissions, see Access control and permissions.

Create a service app to trigger a reboot

In this section, you create a Node.js console app 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.

Create an empty folder called trigger-reboot-on-device. In the trigger-reboot-on-device folder, create a package.json file using the following command at your command prompt. Accept all the defaults:
```
npm init
```
At your command prompt in the trigger-reboot-on-device folder, run the following command to install the azure-iothub Device SDK package and azure-iot-device-mqtt package:
```
npm install azure-iothub --save
```
Using a text editor, create a dmpatterns_getstarted_service.js file in the trigger-reboot-on-device folder.

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;

Add the following variable declarations and replace the {iothubconnectionstring} placeholder value with the IoT hub connection string you copied previously in Get the IoT hub connection string:

var connectionString = '{iothubconnectionstring}';
var registry = Registry.fromConnectionString(connectionString);
var client = Client.fromConnectionString(connectionString);
var deviceToReboot = 'myDeviceId';

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.");  
        }
    });
};

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.');
    });
};

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);
```
Save and close the dmpatterns_getstarted_service.js file.

Run the apps

You're now ready to run the apps.

At the command prompt in the managed-device folder, run the following command to begin listening for the reboot direct method.
```
node dmpatterns_getstarted_device.js
```
At the command prompt in the trigger-reboot-on-device 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
```
You see the device response to the reboot direct method and the reboot status in the console.

The following shows the device response to the reboot direct method sent by the service:

The following shows the service triggering the reboot and polling the device twin for the last reboot time:

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 article, 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 How to do a firmware update.

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