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 toeu1
. -
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
- On Mac :
-
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
- On Mac :
-
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:
Name | Description | Type | Default value |
---|---|---|---|
connectionTimeoutInSeconds | Connection timeout in seconds | Integer | 100 |
socketTimeoutInSeconds | Socket timeout in seconds | Integer | 100 |
proxyHost | Host address of 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 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:
Name | Description | Type | Mandatory |
---|---|---|---|
authorization | Bearer token, if developer application already generated it. | String | Required for user token |
clientId | Service credential Id | String | Required for user with service credential |
clientSecret | Service credential | String | Required for user with service credential |
tenant | Name of the developer tenant | String | Required 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;
}
Except where otherwise noted, content on this site is licensed under the Development License Agreement.