Governing your IoT devices

The need for IoT governance is important to manage all IoT initiatives in an organization and to get maximum benefits from those initiatives. In Part 1 of this series, we discussed IoT governance practices and how an IoT governance model can drive standardization across all IoT initiatives and enforce governance processes. In this article, Part 2 of this series, we describe the need to govern the devices.

IoT device governance guides the management of IoT devices, establishing how devices (and related monitored data) will be adopted and how those devices will be managed over time. For this article, we developed a sample application by using the REST APIs of IBM Watson IoT Platform to show device lifecycle and device management support in IBM Watson IoT Platform.

Governing IoT devices throughout the IoT device lifecycle

Complex IoT solutions typically include a very large number of IoT devices. Your IoT governance model must consider the lifecycle of an IoT device, which includes these steps or stages:

  1. Choose and procure appropriate IoT devices for your architecture. IoT devices often vary from small-scale, limited-capacity sensors to advanced microcomputers. Appropriate IoT devices must be selected and procured based on the criteria like compatibility (such as supported protocol, connectivity, size, or security), features offered, performance, or cost.
  2. Deploy, provision, and manage the IoT devices. This phase includes creating the device type (if it does not already exist), adding the device into IoT platform by using the proper protocols, provisioning authentication, and updating device attributes and location.
  3. Upgrade the IoT devices, including upgrading the firmware, applying security patches, or updating installed scripts on the devices. This phase is only applicable for managed devices with support for device management operations. This phase is being explored widely by IoT platforms; more device management operations are being evaluated. Currently, IBM Watson IoT Platform supports device reboot, factory reset, firmware download, and firmware upgrade operations. More details about this phase and device management operations are provided in the subsequent sections of this article.
  4. Decommission the device, such as taking the device offline or removing it from the IoT system altogether. In this phase, devices and device types (if needed) can be deleted from the IoT platform and IoT system.
  5. Evaluate how the device is being used, what data is being collected, and identify changes that are needed for its continued use in your IoT system. IoT devices such as sensors and microcomputers can collect a wide range of data from different applications across industries. One important architectural aspect of using these applications in your IoT system is effectively analyzing and using the data that you collect from your IoT devices. Different tools and techniques are used in this phase, which also involves many offline activities such as the analysis of collected data, the creation of business rules and the execution of the business rules.

Many IoT platforms provide the core device management capabilities of provisioning, upgrading, or decommissioning devices, and they integrate a device management protocol. You can read more about device management protocols and device management capabilities in this article, “Managing your IoT devices.”

Overview of the Device Management Dashboard demo application

Because managing IoT devices is at the heart of device governance practices, it’s important to see how device management features are implemented in your IoT platform. To demonstrate how device management works in IBM Watson IoT platform, we developed a sample application called the Device Management Dashboard. This sample application is a simple and interactive front-end application that you can use to manage IoT devices and operations. The dashboard is developed with Node.js and the Watson IoT Platform device management features and APIs.

To run the demo application, click the Run the app button. To download or view the code for the demo application, click the Get the code button.

Get the codeRun the app

The Watson IoT platform dashboard supports most of the device management operations that we discuss in this article. However, the objective of this demo application is to specifically show how to use the device management REST API that is available in Watson IoT platform to manage the devices programmatically based on your IoT solution needs.

In the login screen, you need to enter the details of the IoT organization or select the demo mode. In demo mode, a sample organization and space will be used to demonstrate the functions of the application. Click the Demo button.

alt

The main dashboard screen displays the devices types and devices for the organization. The different operations that you use to manage IoT device types and devices are available from this main screen.

alt

We’ll review the device management capabilities in the sections that follow, within the context of the IoT device lifecycle. We will show the screens from the dashboard demo application, but we will also show a Node.js code snippet that is used to complete the device management operations.

Initialize the IoT application client in Node.js

Before you can invoke the device management APIs of Watson IoT Platform, you need to initialize your Node.js client as shown in the code fragment below:


var IBMIoTF = require('ibmiotf');

var appClientConfig = {
          org: req1.body.input_org,
          id: req1.body.input_id,
          "auth‑key": req1.body.input_key,
          "auth‑token": req1.body.input_token
        };

var appClient = new IBMIoTF.IotfApplication(appClientConfig);

Get organization details

Use the following code to gather the details of your organization.


appClient.getOrganizationDetails().then (function onSuccess (response) {
    console.log("Success");
    console.log(response);
}, function onError (error) {
    console.log("Fail");
    console.log(error);
});

Deploying or provisioning devices

After you have procured the IoT devices for your overall IoT architecture, you must deploy and provision them into your organization. Deploying and provisioning is stage 2 of the IoT device lifecycle. This stage involves defining and adding device types, adding the devices, and updating the metadata associated with your devices.

Identify the device types that are used in your organization

Use the following code to get a list of all the device types that are registered in your organization.


appClient.getAllDeviceTypes().then (function onSuccess (response) {
    console.log("Success");
    console.log(response);
}, function onError (error) {
    console.log("Fail");
    console.log(error);
});

List devices of a specific device type

Use this code to get a list of all devices of a specific device type.


appClient.listAllDevicesOfType(selectedDeviceType).then (function onSuccess (response) {
    console.log("Success");
    console.log(response);
}, function onError (error) {
    console.log("Fail");
    console.log(error);
});

The previous screen is a combination of outputs from these calls.

Add a device type

You can click the Add Device Type button to add a new device type.

alt

You can use the following code to add a device type.


var type = req6.body.type_name;
var desc = req6.body.type_desc;
var metadata = {"customField1": req6.body.custom_field1, "customField2": req6.body.custom_field2, "customField3": req6.body.custom_field3, "customField4": req6.body.custom_field4};
var deviceInfo = {};

appClient.
    registerDeviceType(type,desc,deviceInfo,metadata).then (function onSuccess (argument) {
        console.log("Success");
        res6.redirect(307,'/refresh‑org');
}, function onError (argument) {
        console.log("Fail");
        res6.redirect(307,'/refresh‑org');
 });


Add a device

Click the Add Device button to add a device.

alt

Only the device id, auth token, and device type are required parameters in the add device screen. All other parameters are optional.

Use this code to add a device.


var type = req6.body.type_select;
var deviceId = req6.body.device_id;
var authToken = req6.body.auth_token;
var metadata = {"customField1": req6.body.custom_field1, "customField2": req6.body.custom_field2};
var deviceInfo = {"serialNumber" : req6.body.serial_number, "manufacturer":
req6.body.manufacturer, "model" : req6.body.model, "deviceClass": req6.body.device_class, "descriptiveLocation": req6.body.descriptive_location, "fwVersion":
req6.body.firmware_version, "hwVersion": req6.body.hardware_version};
var location = {"longitude": req6.body.longitude, "latitude": req6.body.latitude, "elevation": req6.body.elevation, "accuracy": req6.body.accuracy, "measuredDateTime": req6.body.measured_datetime};

appClient.registerDevice(type, deviceId, authToken, deviceInfo, location, metadata).then (function onSuccess (response) {
console.log("Success");
console.log(response);
res6.redirect(307,'/type‑submit');
    }, function onError (error) {
console.log("Fail");
console.log(error);
res6.render('device_add', { title : 'Add Device', appConfig : appClientConfig,
selected_org : selected_org, failed : 'true', error: error});
});

Update the metadata of a device

Update device operation can be used to update the details of device. Device information and metadata can be updated by using this option. The dashboard opens a new screen with editable JSON strings when you select this option. If you click the Edit button in the main screen, this update screen opens.

alt

Use this code to update a device.


appClient.updateDevice(type, deviceId, deviceInfo, status, metadata,extensions).then
(function onSuccess (response) {
    console.log("Success");
    console.log(response);
}, function onError (error) {
    console.log("Fail");
    console.log(error);
});

Managing devices

Stage 3 of the IoT device lifecycle includes upgrading firmware, applying security patches, and updating installed scripts or software on the devices. Many IoT platforms provide these device management capabilities.

Defining an IoT device as a managed device

Before you can use the Watson IoT Platform device management capabilities on your IoT devices, you must first define it as a managed device within Watson IoT Platform. Devices with support for remote management can register themselves with the platform as managed devices.

A managed device can be created by the below code by using Node JS.


var deviceClient = new iotf.IotfManagedDevice(config);

deviceClient.on('connect', function(){
var rc = deviceClient.manage(4000, true, true);
    console.log("rc ="+rc);
        deviceClient.publish('myevt', 'json', '{"hello":"world"}', 0);
        deviceClient.updateLocation(77.598838,12.96829);

    //deviceClient.disconnect();
});

deviceClient.manage() API takes three parameters. Parameter 1 denotes lifetime (number of seconds in which the device must make another managed device request). But Parameters 2 and 3 indicate support for firmware management (firmware download or firmware upgrade) and device management (reboot and factory reset).

The dashboard opens a new screen upon selection of device manage option.

alt

The function initiateDeviceManagementRequest() can be used to initiate a device management request.


var id = req1.body.dev_id;
var type = req1.body.dev_type;
var action = '';
var parameters = [];    
var devices = [{ "typeId": type, "deviceId": id }];
if (req1.body.dev_man1 == 'reboot')
    action = "device/reboot";
else if (req1.body.dev_man1 == 'fwDownload')
    res1.redirect(307,'/fwDownload');
else if (req1.body.dev_man1 == 'fwUpgrade')
    action = "firmware/update";
else if (req1.body.dev_man1 == 'facReset')
    action = "device/factoryReset";
   
appClient.initiateDeviceManagementRequest(action, parameters, devices).then (function onSuccess (response) {
console.log("Success");
console.log(response);
res1.render('manage_resp', { title : 'Manage Device', dev_id : id, dev_type : type, req_id : response.reqId, resp_msg : response.message});
    }, function onError (error) {
      console.log("Fail");
      console.log(error);
      res1.render('manage_resp', { title : 'Manage Device', dev_id : id, dev_type : type, req_id : 'NA', resp_msg : error.data.message});
});

Rebooting a device

Use the following code to reboot a device.


deviceClient.on('dmAction', function(request){
console.log('Action : '+request.action);
if(deviceClient.isRebootAction(request)) {
try {
//perform reboot
    if(!rebootedSupported) {
            deviceClient.respondDeviceAction(request,deviceClient.RESPONSECODE.FUNCTION_NOT_SUPPORTED,"Reboot not supported");
            return;
    }
    console.log("Initiating reboot...");
    //process.reboot(1); 
    console.log("Reboot complete...");
    //inform the IoT platform know that reboot is initiated immediately.
          deviceClient.respondDeviceAction(request,deviceClient.RESPONSECODE.ACCEPTED,"Reboot complete");
} catch(e) {
//inform the IoT platform know that reboot has failed.
deviceClient.respondDeviceAction(request,deviceClient.RESPONSECODE.INTERNAL_ERROR,"Cannot do reboot now : "+e);
}} 

Resetting a device to factory default

Use the following code to reset a device to factory default.


else if(deviceClient.isFactoryResetAction(request)) {
try {
      //perform Factory Reset
      if(!factoryResetSupported) {
            deviceClient.respondDeviceAction(request,deviceClient.RESPONSECODE.FUNCTION_NOT_SUPPORTED,"Factory reset not supported");
            return;
    }
    console.log("Initiating factory reset...");
    //process.fact_reset(1); 
    console.log("Factory reset complete now...");
//inform the IoT platform know that factory reset is initiated immediately.
deviceClient.respondDeviceAction(request,deviceClient.RESPONSECODE.ACCEPTED, "Factory reset complete");
} catch(e) {
//inform the IoT platform know that factory reset has failed.
deviceClient.respondDeviceAction(request,deviceClient.RESPONSECODE.INTERNAL_ERROR,"Cannot do factory reset now : "+e);
}}}

Updating the firmware for the device

Use the following code to update the firmware for the device.


deviceClient.on('firmwareUpdate', function(request){
  console.log('Action : ' + JSON.stringify(request));

  deviceClient.changeUpdateState(deviceClient.FIRMWAREUPDATESTATE.IN_PROGRESS);

  console.log("Device firmware being updated");
  //Update the firmware

  setTimeout(function(){ 
      deviceClient.changeUpdateState(deviceClient.FIRMWAREUPDATESTATE.SUCCESS);
      deviceClient.changeState(deviceClient.FIRMWARESTATE.IDLE);
  }, 5000);
  
  deviceClient.respondDeviceAction(request,deviceClient.RESPONSECODE.ACCEPTED, "Firmware update complete");

});

Firmware download

When you click Firmware download, a new section opens in which you must enter additional details.

alt

Use the following code to initiate the action to download firmware for the device.



var id = req1.body.dev_id;
var type = req1.body.dev_type;
var action = action = "firmware/download";
var parameters = [{"name": "version","value": req1.body.fw_version},
                    {"name": "name","value": req1.body.fw_name},
                    {"name": "verifier","value": req1.body.fw_verifier},
                    {"name": "uri","value": req1.body.fw_uri}];    
var devices = [{ "typeId": type, "deviceId": id }];
   
appClient.initiateDeviceManagementRequest(action, parameters, devices).then (function onSuccess (response) {
console.log("Success");
console.log(response);
}, function onError (error) {
       console.log("Fail");
    console.log(error);
});
Device side code for firmware download.
deviceClient.on('firmwareDownload', function(request){
  console.log('Action : ' + JSON.stringify(request));

  deviceClient.changeState(deviceClient.FIRMWARESTATE.DOWNLOADING);

  console.log("Device firmware being downloaded");  
  
  setTimeout(function(){ 
      deviceClient.changeState(deviceClient.FIRMWARESTATE.DOWNLOADED);
  }, 5000);
  
  deviceClient.respondDeviceAction(request,deviceClient.RESPONSECODE.ACCEPTED, "Firmware download complete");

});


Decommissioning devices

When the end of service life is reached for a device, which is stage 4 of the IoT device lifecycle, the device should be decommissioned securely. Decommissioning a device includes these steps:

  • Revoking any token or identity that is associated with the device so that it is no longer able to send messages
  • Removing the device and device type from the Watson IoT Platform by using the dashboard or the REST API.

Revoke device identity

Some IoT solutions might use device-specific credentials to validate the device. These credentials can include device-specific certificates or other custom authentication tokens. These credentials that denote the identity of a trusted device must be removed from either Watson IoT Platform or the application device database to disable the device. Any subsequent message from the device will be ignored by the platform.

Delete a device type

An existing device type can be removed permanently from the organization by using this option. A device type can be deleted only if no devices are attached to it, so you should delete the devices first.

alt

Use the following code to delete a device type.


var typetodelete = req8.body.device_types;
console.log("Selected type to delete ‑ " + typetodelete);
appClient.deleteDeviceType(typetodelete).then (function onSuccess (response9) {
        console.log("Success");
        res8.redirect(307,'/refresh‑org');
    }, function onError (error) {
        console.log("Fail");
       res8.redirect(307,'/refresh‑org');
    });
})

Delete a device

Use the following code to delete a device.


appClient.unregisterDevice(selectedType, selectedDevice).then (function onSuccess (response) {
    console.log("Success");
    console.log(response);
}, function onError (error) {
    console.log("Fail");
    console.log(error);
});

Conclusion

Device management is a key part of IoT solution governance. Device management ensures that you can effectively use the devices to generate IoT data and ensures high availability and security for the IoT solution.

Device management is an evolving area in IoT development, with a variety of different technologies or protocols to do IoT device management. As demonstrated in this article, IBM Watson IoT Platform supports a rich set of device management operations that can be used to quickly develop a device management solution for varying needs.

The data that is generated by the IoT devices needs to be managed throughout the lifecycle of the devices to ensure the value and security of the IoT solution. Part 3 of this series will elaborate on a data management approach for governing IoT solutions.

Amitranjan Gantait
Joy Patra
Ayan Mukherjee