Skip to content

Industrial IoT SDK V2 for Java – Getting Started

Prerequisites to use the Industrial IoT SDK V2 for Java

  • Java 8 is available.
  • Gradle or Maven is used as build tool.
  • User authorization token or service credentials with required scopes for APIs are available.
  • Environment variable HOST_ENVIRONMENT is set to current region. When hosting an application in Cloud Foundry, the variable must be added in 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 token itself.

  • MINDSPHERE_CLIENT_ID
    Specifies service credentials ID

  • MINDSPHERE_CLIENT_SECRET
    Specify service credentials secret

  • MINDSPHERE_TENANT
    Specifies the tenant name

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 V2 for Java

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

com\siemens\mindsphere\mindsphere-sdk-java-core\{x.y.z}\mindsphere-sdk-java-core-{x.y.z}.jar
com\siemens\mindsphere\mindsphere-sdk-java-core\{x.y.z}\mindsphere-sdk-java-core-javadoc.jar
com\siemens\mindsphere\mindsphere-sdk-java-core\{x.y.z}\mindsphere-sdk-java-core.pom
com\siemens\mindsphere\{service_name}-sdk\{x.y}\{service_name}-sdk-{x.y}.jar
com\siemens\mindsphere\{service_name}-sdk\{x.y}\{service_name}-sdk-{x.y}-javadoc.jar
com\siemens\mindsphere\{service_name}-sdk\{x.y}\{service_name}-sdk-{x.y}.pom

Note

  • {x.y.z} is the version number of the Industrial IoT Core SDK for Java (e.g. 2.0.0).The file {service_name}-sdk-{x.y.z}.pom is required for downloading the transitive dependencies of the Industrial IoT Core SDK for Java.
  • {x.y} is the version number of the API Specification (e.g. 3.0). The file {service_name}-sdk-{x.y}.pom is required for downloading the transitive dependencies of the Industrial IoT Service SDK for Java.

Adding Industrial IoT SDK V2 Dependencies

  1. Create the core and service module folder structure as your local Maven repository :
    $PATH\com\siemens\mindsphere\mindsphere-sdk-java-core\{x.y.z}\mindsphere-sdk-java-core-{x.y.z}.jar
    $PATH\com\siemens\mindsphere\mindsphere-sdk-java-core\{x.y.z}\mindsphere-sdk-java-core-javadoc.jar
    $PATH\com\siemens\mindsphere\mindsphere-sdk-java-core\{x.y.z}\mindsphere-sdk-java-core.pom
    $PATH\com\siemens\mindsphere\{service_name}-sdk\{x.y}\{service_name}-sdk-{x.y}.jar
    $PATH\com\siemens\mindsphere\{service_name}-sdk\{x.y}\{service_name}-sdk-{x.y}-javadoc.jar
    $PATH\com\siemens\mindsphere\{service_name}-sdk\{x.y}\{service_name}-sdk-{x.y}.pom

where $PATH is:

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

2.Register the repository and include dependencies in the build config file of your project.

<!-- Modify the following sections of the pom.xml file -->
<!-- 1. Register the repository in the repositories section -->
<repositories>
      <repository>
          <id>maven-repository</id>
          <url>file:///{absolute_path_of_the_repository_folder}</url>
      </repository>
  </repositories>

<!-- 2. Add Core dependency in the dependencies section (optional) -->
<dependency>
    <groupId>com.siemens.mindsphere</groupId>
    <artifactId>mindsphere-sdk-java-core</artifactId>
    <version>{x.y.z}</version>
</dependency>

<!-- 3. Add Service dependency in the dependencies section -->
<dependency>
    <groupId>com.siemens.mindsphere</groupId>
    <artifactId>{service_name}-sdk</artifactId>
    <version>{x.y}</version>
</dependency>

// Modify the following sections of the build.gradle file
// 1. Register the repository in the repositories section
repositories {
        maven {
          url file('{Absolute_path_of_the_created_repository_folder}')
        }
        mavenLocal()
        mavenCentral()
}

// 2. Add Core dependency in the dependencies section (optional)
compile 'com.siemens.mindsphere:mindsphere-sdk-java-core:{x.y.z}'

// 3. Add Service dependency in the dependencies section
compile 'com.siemens.mindsphere:{service_name}-sdk:{x.y}'

Note

All the Industrial IoT service modules have an implicit dependency on the core module, so adding the core module dependency is optional.

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

API Client and Credentials Configuration

The lowest-level building blocks of the API are RestClientConfig and MindsphereCredentials. These objects are instantiated using a builder pattern and shared between client instances.

Client Configuration

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

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

The RestClientConfig can be configured using the following optional parameters:

Name Description Type Default value
connectionTimeoutInSeconds Connection timeout in seconds Integer 100
socketTimeoutInSeconds Socket timeout in seconds Integer 100
proxyHost Host address of the proxy String
proxyPort Proxy port Integer
proxyUsername Username to login to the proxy String
proxyPassword Password to login to the proxy String
hostEnvironment Current Region String eu1
proxySchema Schema used by the proxy String http

Credentials Configuration

The MindsphereCredentials object can be built with a user token or with service credentials to fetch a technical token.

The following configuration parameters are available for the MindsphereCredentials object:

Name Description Type Use Case
authorization Bearer token, if available. String user token
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
clientId Tenant service credentials ID String technical token
clientSecret Tenant service credentials secret String technical token
tenant Tenant String technical token

Refer to the code samples for creating Insights HubCredentials objects for more information.

API Client Instantiation and Usage

An API client instance using RestClientConfig and MindsphereCredentials objects passed as (optional) parameters using a builder pattern.

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

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

    //Construct MindsphereCredentials object
    MindsphereCredentials credentials = MindsphereCredentials.userTokenBuilder()
                                            .authorization(token)
                                            .build();

    //Construct RestClientConfig object
    RestClientConfig config = RestClientConfig.builder()
                                  .connectionTimeoutInSeconds(100)
                                  .proxyHost("my.proxy.host")
                                  .proxyPort("1.2.3.4")
                                  .hostEnvironment("eu1")
                                  .build();

    //Construct TimeSeriesClient object
    TimeSeriesClient timeseries_client = TimeSeriesClient.builder()
                                            .mindsphereCredentials(credentials)
                                            .restClientConfig(config)
                                            .build();

    //Construct GetTimeseriesRequest object
    GetTimeseriesRequest request_object = new GetTimeseriesRequest();
    request_object.setEntity(entity);
    request_object.setPropertysetname(propertySetName);
    request_object.setFrom(<from_time>);
    request_object.setTo(<to_time>);

    List<TimeseriesData> timeseries_data_list = null;
    try {
        timeseries_data_list = timeseries_client.getTimeseries(request_object);
    } catch (MindsphereException e) {
        // Exception handling
    }

    return timeseries_data_list;
}

Last update: February 23, 2024

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