Skip to content

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

Note

{x.y.z} is the version number of the Industrial IoT Core or Service SDK for Node.js (e.g. 1.0.0).

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:

Name Description Type Default value
proxy Complete proxy URL String
timeout Connection timeout in ms Integer 10000
hostEnvironment - String eu1

Default value for region China 1

For region China 1 SDK, default value for hostEnvironment is cn1.

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 :

Name Description Type Use Case
authorization Bearer token, if available. String user token

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

Name Description Type Use Case
clientId Tenant service credential ID String technical token
clientSecret Tenant service credential ID String technical token
tenant Tenant service credential ID String technical token

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

Name Description Type Use Case
keyStoreClientId App service credential ID String technical token
keyStoreClientSecret App service credential secret String technical token
appName Application name String technical token
appVersion Application version String technical token
hostTenant Host tenant String technical token
userTenant User tenant String technical token

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

Note

If the service credentials are set via environment variables, there is no need to build the MindsphereCredentials object.

Service Client Instantiation and Usage

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

Note

UserCredentials, AppCredentials and TenantCredentials are subclasses of MindsphereCredentials. Developers may pass objects of these subclasses to clients, if the respective credentials are set programmatically.

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
}

Last update: February 23, 2024

Except where otherwise noted, content on this site is licensed under the Development License Agreement.