Industrial IoT SDK for Node.js – Getting Started¶

Prerequisites to use the Industrial IoT SDK for Node.js¶

• Node.js version 8 or higher
• User authorization token or service credentials with required scopes for Industrial IoT Service APIs

• Environment variable HOST_ENVIRONMENT is set to current region. When hosting an application in Cloud Foundry, the variable must be added to the manifest file:

  env:
    HOST_ENVIRONMENT: eu1
  

  If not specified, HOST_ENVIRONMENT defaults to eu1 in region Europe 1 SDK and to cn1 in region China 1 SDK. * Environment variable HOST_BASEDOMAIN is set optionally if domain is other that '*.mindsphere.io'. When hosting an application in Cloud Foundry, the variable must be added in the manifest file:

  env:
    HOST_BASEDOMAIN: example.orgname.com
  

  Hint

  Service credentials can be set as environment variables so the client can fetch a technical token automatically. Refer to Required Environment Variables for Fetching Technical Tokens for details on parameters to be configured.

  Attention

  You are responsible for keeping the credentials safe. You decide whether it is safe to supply the credentials via environment variables.

Installation Instructions¶

Downloading the Industrial IoT SDK for Node.js¶

Download the Industrial IoT SDK for Node.js from the Siemens Industry Online Support (SIOS) Portal.

Adding Industrial IoT SDK for Node.js Dependency¶

1. Copy the .tgz files into a folder in the root of your project, e.g. repo.

2. Install the mindsphere-sdk-node-core module:

npm install {folder}\mindsphere-sdk-node-core-x.y.z.tgz

npm install repo\mindsphere-sdk-node-core-1.0.0.tgz

3.Install the service modules:

npm install {folder}\{service_name}-sdk-x.y.z.tgz

npm install repo\assetmanagement-sdk-3.9.0.tgz

Further implementation of the SDK libraries has been shown in a sample project that you can download and test in local or on Insights Hub application. Please refer to this repository: industrial-iot-node-sdk-examples.

Service Client and Credentials Configuration¶

The lowest-level building blocks of the service client are ClientConfig and MindsphereCredentials. These objects can be shared between client instances.

Client Configuration¶

The following code block shows an example of how to build a ClientConfig object:

let config = new ClientConfig({ proxy: <proxy_value>, timeout: <timeout_value> });

The ClientConfig can be configured using the following optional parameters:

MindsphereCredentials Configuration¶

MindsphereCredentials has the subclasses UserCredentials, AppCredentials and TenantCredentials. The available configuration parameters for these objects are listed below.

The following configuration parameters can be set programmatically for the UserCredentials object :

The following configuration parameters can be set programmatically for the TenantCredentials object:

The following configuration parameters can be set programmatically for the AppCredentials object:

Refer to Code Samples to create MindsphereCredentials objects for more information.

Service Client Instantiation and Usage¶

A service client instance accepts the ClientConfig and MindsphereCredentials objects as well as its subclasses as optional parameters.

Code sample using the IoT TimeSeries API client, placeholders are indicated by angle brackets < >:

// Require UserCredentials and ClientConfig from `mindsphere-sdk-node-core` module
const ClientConfig = require('mindsphere-sdk-node-core').ClientConfig;
const UserCredentials = require('mindsphere-sdk-node-core').UserCredentials;

// Require TimeseriesClient from `timeseries-sdk` module
const TimeSeriesClient = require('timeseries-sdk').TimeSeriesClient;

// Proxy value can be set in the ClientConfig object
let config = new ClientConfig({ proxy: <proxy_value>, timeout: <timeout_in_seconds> });

// Construct the UserCredentials object
let credentials = new UserCredentials({'authorization': '<user_token>'});

// Construct the TimeSeriesClient object using the config and credentials objects
let time_series_client = new TimeSeriesClient(config, credentials);

try {
  let timeseries_data = await time_series_client.getTimeseries(
    {
      entity: <entity_id>,
      propertysetname: <property_set_name>,
      from: <from_date>,
      to: <to_date>
    }
  );
} catch (err) {
  //Exception Handling
}