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
  

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

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

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

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:

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:

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