Skip to content

Importing and Using High Frequency Simulation Data

Introduction

This guide describes how to use high frequency simulation data.

Simulation is widely used to test and analyze new products in a virtual environment in order to get early measurements and predictions on the expected behavior of the physical product during its life cycle. On the other hand, IoT data can be used as input for optimized simulation runs and both data sets can be used to predict possible weak spots of machines and thus enable better upfront designs and use cases like predictive maintenance.

Prerequisites

Creating a Simulation Asset

Simulation data can only be imported to simulation assets. These simulation assets do not represent an actual device importing data, but instead are completely virtual. However, they also require an aspect type that maps the imported simulation data. For details on how to create aspect types and asset types, follow the instructions on Modeling Assets.

Simulation assets cannot be derived from basic agents (e.g. Nanobox, IoT2040), subtenant assettypes and hierarchical assets.

Asset Manager

For creating a simulation asset using the Asset Manager, follow the steps below:

  1. Open the Asset Manager from the Launchpad.
  2. On the Types tab select BasicDevice from the list.
  3. Click on the plus symbol to create a custom asset type that is derived from core.basicdevice.

    Create Custom Asset Type

  4. Switch to the Assets tab click on the plus symbol to create a new asset.
    The screen for selecting the asset type is displayed.

  5. Choose the custom asset type derived from core.basicdevice.
  6. Enter all relevant information for your asset and enable the simulation checkbox as shown below:

    Attention

    The classification of an asset can only be set upon creation. There's no possibility to change this value afterwards.

    Create Simulation Asset

For further information regarding the Asset Manager, refer to the Asset Manager documentation.

Asset Management API

For creating a simulation asset using the Asset Management Service, use the optional parameter twinType. Valid values for this property are performance and simulation. In this case, use simulation, e.g.:

POST /api/assetmanagement/v3/assets HTTP/1.1
Host: gateway.{region}.{mindsphere-domain}
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}
{
    "name": "SimulationAsset",
    "description": "Asset for simulated data",
    "typeId": "{core.basicdevice}",
    "parentId": "{parentAssetId}",
    "twinType": "simulation"
}

Preparing Simulation Data

Simulation data must be provided in files. The content must be in JSON format with the following structure:

[
    {
        "_time": "2018-11-01T10:00:00.050000Z",
        "pressure": "382.12638",
        "temperature": "52.785329",
        "humidity": "80.89459",
    },
    ...
]

A single file can contain multiple time series records, ordered by timestamp in ascending order. Data for a one-hour-interval can be distributed across up to 10 files, where time periods must not overlap. The Time Series Bulk Import Service works hourly aligned and requires that a single import job only contains data where the start and end time are within the same hour. I.e., the hour part of all timestamps within one file must be equal.

Uploading Simulation Data to Insights Hub

Files with simulation data are uploaded to Insights Hub using the IoT File Service, e.g.:

PUT /api/iotfile/v3/files/978528e7a124458f87c8f1d38fd9400f/simulationData.json HTTP/1.1
Host: gateway.{region}.{mindsphere-domain}
Content-Type: application/octet-stream
Accept: application/octet-stream
Authorization: Bearer {token}

After successful upload, the service returns HTTP 201.

Importing Data

Import simulation data from the IoT File Service to an asset using the IoT Time Series Bulk Service. A single import job can take up to 10 input files that contain up to one hour of data as described above. For each input file, the relative path from the IoT File Service and the very first and last timestamps in the file must be specified. The following request imports the simulation data from two files into the aspect tireMonitor of an asset.

POST /api/iottsbulk/v3/importJobs HTTP/1.1
Host: gateway.{region}.{mindsphere-domain}
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}
{
  "data": [
    {
      "entity": "978528e7a124458f87c8f1d38fd9400f",
      "propertySetName": "tireMonitor",
      "timeseriesFiles": [
        {
          "filePath": "Demo/SampleFile1.json",
          "from": "2018-09-21T15:00:01.787000Z",
          "to": "2018-09-21T15:05:50.633015Z"
        },
        {
          "filePath": "Demo/SampleFile2.json",
          "from": "2018-09-21T15:07:00.795015Z",
          "to": "2018-09-21T15:11:40.417015Z"
        }
      ]
    }
  ]
}

The import of multiple files for the same hour can be divided into multiple import requests. This enables importing files with overlapping time periods. Be aware that this service does not process data from multiple import requests for the same hour in parallel. Import requests for a specific hour are handled sequentially in the order they are received.

Retrieving Simulation Data

To retrieve the simulation data of a specific aspect for a specific time range, use the IoT Time Series Bulk Service, e.g.:

GET /api/iottimeseries/v3/iottsbulk/978528e7a124458f87c8f1d38fd9400f/tireMonitor?from=2018-11-01T10:00:00.050000Z&to=2018-11-01T10:00:05.000000Z&select=pressure,temperature HTTP/1.1
Host: gateway.{region}.{mindsphere-domain}
Accept: application/json
Authorization: Bearer {token}

Last update: March 17, 2023

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