Industrial IoT SDK for Java – Getting started¶

Prerequisites¶

• Java 8
• Gradle or Maven as build tool
• User authorization token or service credentials with required scopes for APIs

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

  env:
    HOST_ENVIRONMENT: {region}
  

  If not specified, HOST_ENVIRONMENT will default to eu1.

• In case you are using service credentials, they can be set as environment variables, so the client can fetch a token itself.

  • MINDSPHERE_CLIENT_ID
    Specify service credential ID

  • MINDSPHERE_CLIENT_SECRET
    Specify service credential

  • MINDSPHERE_TENANT
    Specify tenant name

  Note

  Setting environment variables for service credentials is not mandatory. Service credentials or user tokens can be set as parameters in the MindsphereCredentials object as explained below in API client and credentials configuration.

  Attention

  The developer/customer is responsible for keeping the credentials safe. It is the decision of the developer/customer, whether it is safe enough to supply the credentials via environment variables.

  Requesting service credentials

  For requesting service credentials, see Create Service Credentials.

Installation Instructions¶

Downloading the Industrial IoT SDK¶

Download the Industrial IoT SDK for Java from the Siemens Industry Online Support (SIOS) Portal. The jar and pom files of the downloaded archive have the following structure:

mindsphere\mindsphere-sdk\x.y.z\mindsphere-sdk-x.y.z.jar
mindsphere\mindsphere-sdk\x.y.z\mindsphere-sdk-x.y.z-javadoc.jar
mindsphere\mindsphere-sdk\x.y.z\mindsphere-sdk-x.y.z.pom

com\siemens\mindsphere\mindsphere-sdk\x.y.z\mindsphere-sdk-x.y.z.jar
com\siemens\mindsphere\mindsphere-sdk\x.y.z\mindsphere-sdk-x.y.z-javadoc.jar
com\siemens\mindsphere\mindsphere-sdk\x.y.z\mindsphere-sdk-x.y.z.pom

Adding SDK Dependency for Projects using Maven as a Build Tool¶

• Create SDK folder structure in your local Maven repository:

  $PATH\mindsphere\mindsphere-sdk\x.y.z\mindsphere-sdk-x.y.z.jar
  $PATH\mindsphere\mindsphere-sdk\x.y.z\mindsphere-sdk-x.y.z-javadoc.jar
  $PATH\mindsphere\mindsphere-sdk\x.y.z\mindsphere-sdk-x.y.z.pom
  
  <!-- Version 1.2.0 onwards -->
  $PATH\com\siemens\mindsphere\mindsphere-sdk\x.y.z\mindsphere-sdk-x.y.z.jar
  $PATH\com\siemens\mindsphere\mindsphere-sdk\x.y.z\mindsphere-sdk-x.y.z-javadoc.jar
  $PATH\com\siemens\mindsphere\mindsphere-sdk\x.y.z\mindsphere-sdk-x.y.z.pom
  

  where $PATH is:

  • On Mac : ~/.m2/repository
  • On Windows : C:\Users\{username}\.m2\repository
  • On Linux : /home/{User_Name}/.m2/repository

• Add dependency in pom.xml:

  <dependency>
      <groupId>mindsphere</groupId>
      <artifactId>mindsphere-sdk</artifactId>
      <version>x.y.z</version>
  </dependency>
  
  <!-- Version 1.2.0 onwards -->
  <dependency>
      <groupId>com.siemens.mindsphere</groupId>
      <artifactId>mindsphere-sdk</artifactId>
      <version>x.y.z</version>
  </dependency>
  

Adding SDK Dependency for Projects using Gradle as a Build Tool¶

• Create SDK folder structure in your local Maven repository or create a similar folder structure anywhere in your system:

  $PATH\mindsphere\mindsphere-sdk\x.y.z\mindsphere-sdk-x.y.z.jar
  $PATH\mindsphere\mindsphere-sdk\x.y.z\mindsphere-sdk-x.y.z-javadoc.jar
  $PATH\mindsphere\mindsphere-sdk\x.y.z\mindsphere-sdk-x.y.z.pom
  
  <!-- Version 1.2.0 onwards -->
  $PATH\com\siemens\mindsphere\mindsphere-sdk\x.y.z\mindsphere-sdk-x.y.z.jar
  $PATH\com\siemens\mindsphere\mindsphere-sdk\x.y.z\mindsphere-sdk-x.y.z-javadoc.jar
  $PATH\com\siemens\mindsphere\mindsphere-sdk\x.y.z\mindsphere-sdk-x.y.z.pom
  

  where $PATH is:

  • On Mac : ~/.m2/repository
  • On Windows : C:\Users\{username}\.m2\repository
  • On Linux : /home/{User_Name}/.m2/repository

• Advice gradle to look at the local Maven repository in build.gradle of your project as follows:

  repositories {
      mavenLocal()
      mavenCentral()
  
      // Use this if SDK jars are not placed in local maven repository.
      maven {
          url file('{Absolute path of the created repository folder}')
      }
  }
  

• Add dependency in build.gradle:

      compile 'mindsphere:mindsphere-sdk:x.y.z'
  
      <!-- Version 1.2.0 onwards -->
      compile 'com.siemens.mindsphere:mindsphere-sdk:x.y.z'
  

Once the build is complete, all transitive dependencies of the Industrial IoT SDK for Java are downloaded to your application.

API Client and Credentials Configuration¶

The lowest-level building blocks of the API are RestClientConfig and MindsphereCredentials. These objects will be created and shared between client instances. A builder pattern is used to instantiate them.

Client Configuration¶

The RestClientConfig object can be built using configuration parameters. Currently all parameters are optional.

RestClientConfig config = RestClientConfig.builder()
                              .connectionTimeoutInSeconds(100)
                              .proxyHost("host")
                              .proxyPort(8080)
                              .build();

The following parameters can be configured for the RestClientConfig object:

Credentials Configuration¶

The MindsphereCredentials object can be built directly with the user token or with the technical token credentials. If credentials are set via environment variables, there is no need to build the MindsphereCredentials object.

A code sample with user authorization token:

MindsphereCredentials credentials = MindsphereCredentials.builder()
                                        .authorization("usertokenFromRequestHeader")
                                        .build();

A code sample with service credentials:

MindsphereCredentials credentials = MindsphereCredentials.builder()
                                        .clientId("ClientId")
                                        .clientSecret("ClientSecret")
                                        .tenant("TenantName")
                                        .build();

The following parameters can be configured for the MindsphereCredentials object:

API client instantiation and usage¶

An API client instance requires a RestClientConfig and a MindsphereCredentials instance passed as parameters using a builder pattern.

A code sample using the IoT Time Series API client:

@RequestMapping(method = RequestMethod.GET, value = "/{entity}/{propertySetName}")
public TimeseriesData getTimeSeriesAsObject(@PathVariable("entity") String entity,
    @PathVariable("propertySetName") String propertySetName,
    @RequestHeader("Authorization") String token) throws MindsphereException
{

    MindsphereCredentials credentials = MindsphereCredentials.builder()
                                            .authorization(token)
                                            .build();

    RestClientConfig config = RestClientConfig.builder()
                                  .connectionTimeoutInSeconds(100)
                                  .proxyHost("host")
                                  .proxyPort(portnumber)
                                  .hostEnvironment("host-environment")
                                  .build();

    TimeseriesClient timeseriesClient = TimeseriesClient.builder()
                                            .mindsphereCredentials(credentials)
                                            .restClientConfig(config)
                                            .build();

    TimeseriesData timeseriesData = null;
    try {
      timeseriesData = timeseriesClient.getLatestTimeseries(entity, propertySetName);
    } catch (MindsphereException e) {
      // Exception handling
    }

    return timeseriesData;
}