Skip to content

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

Note

The group id for the Industrial IoT SDK for Java artifact is changed from mindsphere to com.siemens.mindsphere from version 1.2.0. Update the archive structure as follows:

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

Note

x.y.z is the version number of the Industrial IoT SDK for Java (e.g. 1.0.0).

The file mindsphere-sdk-x.y.z.pom is required for downloading the transitive dependencies of the Industrial IoT SDK for Java.

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:

NameDescriptionTypeDefault value
connectionTimeoutInSecondsConnection timeout in secondsInteger100
socketTimeoutInSecondsSocket timeout in secondsInteger100
proxyHostHost address of proxyString
proxyPortProxy portInteger
proxyUsernameUsername to login to the proxyString
proxyPasswordPassword to login to the proxyString
hostEnvironmentCurrent RegionStringeu1
proxySchemaSchema used by the proxyStringhttp

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:

NameDescriptionTypeMandatory
authorizationBearer token, if developer application already generated it.StringRequired for user token
clientIdService credential IdStringRequired for user with service credential
clientSecretService credentialStringRequired for user with service credential
tenantName of the developer tenantStringRequired for user with service credential

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;
}