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:

NameDescriptionTypeDefault value
connectionTimeoutInSecondsConnection timeout in secondsInteger100
socketTimeoutInSecondsSocket timeout in secondsInteger100
proxyHostHost address of the 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 with a user token or with service credentials to fetch a technical token.

The following configuration parameters are available for the MindsphereCredentials object:

NameDescriptionTypeUse Case
authorizationBearer token, if available.Stringuser token
keyStoreClientIdApp service credential IDStringtechnical token
keyStoreClientSecretApp service credential secretStringtechnical token
appNameApplication nameStringtechnical token
appVersionApplication versionStringtechnical token
hostTenantHost tenantStringtechnical token
userTenantUser tenantStringtechnical token
clientIdTenant service credentials IDStringtechnical token
clientSecretTenant service credentials secretStringtechnical token
tenantTenantStringtechnical 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;
}