Client Libraries & SDKs

Standard SDK 3.0.1

Card Image

Node.js Standard SDK

Version 3.0.1

Updated On 07/22

Sample Code for letest version of SDK

# Date Name Download
1 07/20/2022 Standard SDK Sample v3.0.1 (preview) Download

How to build NodeJS sample code?

Prerequisite tools:

  1. NodeJs : Node.js supported version v10.x and above (Download)
  2. Npm : NPM is compatible to the node version.

Installation 

  1. Extract the “iotconnect-sdk-node-v3.0.1.zip“ (You can download SDK file from here)
  2. To install the required libraries use the below command:
    • Go to SDK directory path using terminal/Command prompt
    • cd iotconnect-sdk-node-v3.0.1/
    • npm install (Install prerequisite nodejs library)

  3. Using terminal/command prompt goto sample folder
    • cd sample
  4. You can take the firmware file from the above location and update the following details
    • Prerequisite input data as explained in the usage section as below
    • Update sensor attributes according to added in IoTConnect cloud platform.
    • If your device is secure then need to configure the x.509 certificate path such as given below in SDK Options otherwise leave it as it is.
  5. Run Firmware File:
    • node iotconnect-sdk-firmware-node-3.0.1.js (dowload from above list)

Public Method and Implementations

To initialize the SDK object need to import below sdk package

var SDKClient = require('iotconnect-sdk');

Prerequisite Configuration

var uniqueId = <<uniqueId>>; 
var cpId = <<CPID>>;
var env = <<env>>;
  • uniqueId : Its device ID which register on IotConnect platform and also its status has Active and Acquired.
  • cpId : It is the company code. It gets from the IoTConnect UI portal “Settings->Key Vault”.
  • env : It is the UI platform environment. It gets from the IoTConnect UI portal “Settings->Key Vault”.

SdkOptions is for the SDK configuration and needs to parse in SDK object initialize call. You need to manage the below configuration as per your device authentication type.

  • If your device has an authentication type “Key” then no need any configuration. SDK will manage itself from device information.
  • To configure the secure SSL/x509 connection follow below step for CA or SelfSiged certificate
  • “sdkOptions” is optional. Mandatory for SSL/x509 device authentication type only.
  • Standard file format for the “sdkOptions” is as below:

var sdkOptions = {
    "certificate" : {
        "SSLKeyPath"	: "<< SystemPath >>/device.key",
        "SSLCertPath"   : "<< SystemPath >>/device.pem",
        "SSLCaPath"     : "<< SystemPath >>/rootCA.pem"
    },
    "offlineStorage": { 
        "disabled": false, //default value = false, false = store data, true = not store data 
        "availSpaceInMb": 1, //size in MB, Default value = unlimited
        "fileCount": 5 // Default value = 1
    }
}
  • certificate : It is indicated to define the path of the certificate file. Mandatory for X.509/SSL device CA signed or self-signed authentication type only.
    • SSLKeyPath : your device key
    • SSLCertPath: your device certificate
    • SSLCaPath : Root CA certificate
  • offlineStorage” : Define the configuration related to the offline data storage.
    • disabled : false = offline data storing, true = not storing offline data
    • availSpaceInMb: Define the file size of offline data which should be in (MB)
    • fileCount : Number of files need to create for offline data

Note: sdkOptions is optional but mandatory for SSL/x509 device authentication type only. Define proper setting or leave it NULL. If you do not provide offline storage, it will set the default settings as per defined above. It may harm your device by storing the large data. Once memory gets full may chance to stop the execution.

To Initialize the SDK object and connect to the cloud

var iotConnectSDK = new SDKClient(cpId, uniqueId, deviceCallback, twinUpdateCallback, sdkOptions, env);

To receive the command from Cloud to Device(C2D)

var callbackMessage = function callbackMessage(data){
    if(data.cmdType == '0x01') { // Device command
        var obj = {
            "ackId": data.ackId,
            "st": 6,
            "msg": "",
            "childId": ""
        }
        var mt = 5;
        if(data.ackId != null)
            iotConnectSDK.sendAck(obj, mt)
    } else if(data.cmdType == '0x02') { // Firmware OTA command
        var obj = {
            "ackId": data.ackId,
            "st": 7,
            "msg": "",
            "childId": ""
        }
        var mt = 11;
        if(data.ackId != null)
            iotConnectSDK.sendAck(obj, mt)
    } else if(data.cmdType == '0x16') { // Firmware OTA command
        if(data.command)
        {
            console.log("Device Connected");
        } else {
            console.log("Device Disconnected");
        }
    }
}

To receive the twin from Cloud to Device(C2D)

var twinUpdateCallback = function twinUpdateCallback(data){
    console.log(data);
}

To get the list of attributes with the respective device.

iotConnectSDK.getAttributes(function(response){
    console.log("Attribute list device wise :: ", response);
});

Note: you can checkout device attribute format with all device type click here

This is the standard data input format for Gateway and non Gateway device to send the data on IoTConnect cloud(D2C)

// For Non Gateway Device 
var data = [{
    "uniqueId": "<< Device UniqueId >>",
    "time" : "<< date >>",
    "data": {}
}];

// For Gateway and multiple child device 
/* var data = [{
    "uniqueId": "<< Gateway Device UniqueId >>", // It should be must first object of the array
    "time": "<< date >>",
    "data": {}
},
{
    "uniqueId":"<< Child DeviceId >>", //Child device
    "time": "<< date >>",
    "data": {}
}]*/
iotConnectSDK.sendData(data);

To update the Twin Property

var key = "<<Desired property key >>"; // Desired proeprty key received from Twin callback message
var value = "<< Desired Property value >>"; // Value of respective desired property
iotConnectSDK.updateTwin(key,value)
  • key : Desired property key received from Twin callback message
  • value : Value of the respective desired property

To send the command acknowledgment from device to cloud.

var obj = {
    "ackId": "",
    "st": "",
    "msg": "",
    "childId": ""
}
var msgType = "";
iotConnectSDK.sendAck(obj, msgType);
  • ackId(*) : Command Acknowledgment GUID which will receive from command payload (data.ackId)
  • st(*) : Acknowledgment status sent to cloud
    4 = Fail
    6 = Device command[0x01]
    7 = Firmware OTA command[0x02])
  • msg : It is used to send your custom message
  • childId : It is used for Gateway’s child device OTA update only
    0x01 : null or “” for Device command
    0x02 : null or “” for Gateway device and mandatory for Gateway child device’s OTA update.
    How to get the “childId”?
    – You will get child uniqueId for child device OTA command from payload “data.urls[~].uniqueId”
  • msgType : Message type
    5 = Device command[0x01]
    11 = Firmware OTA command[0x02]

To disconnect the device from the cloud

iotConnectSDK.dispose()

To get the all twin property Desired and Reported

iotConnectSDK.getAllTwins();