Skip to content

IoT Time Series Service

Idea

The IoT Time Series Service is used to create, read, update, and delete time series data. Time series data is stored against an asset (entity) instance and an aspect (property set). Within the IoT Time Series Service you can store and query time series data with a precision of 1 millisecond.

Prerequisites

Depending on the usage scenario, prerequisites might be different.

  • Ingesting time series data from a field device: An onboarded asset (entity) is connected to MindSphere and produces time series data. A valid mapping must exist from device data points to asset variables.
  • Ingesting time series data from an application: An asset (entity) with respective variables must exist

Access

The following permissions are required for interacting with the IoT Time Series Service:

  • Reading time series: iot.tim.r
  • Writing/updating time series: iot.tim.w
  • Deleting time series: iot.tim.d

A user can only read data within his tenant and subtenants.

Basics

A time series record consists of a timestamp, one or more values, and an optional quality indicator for each value, as defined in the aspect type definition. If there are multiple variables in the aspect, they are expected to arrive in the same payload. Writing a time series record with the same timestamp, asset (entity) instance, and aspect as a record will completely overwrite the old record. There is no versioning of data.

The time stamp may be specified with millisecond precision. Measurement values must match the type that was defined in the aspect type. Time series data can be of type int, long, double, boolean, string, big_string (blobs), or timestamp. The maximum sizes of strings and big strings are defined in the aspect type, and can be up to 255 and 100,000 respectively.

In the aspect type definition, there is a "qualitycode" field that indicates whether quality code data will accompany the time series data. If the "qualitycode" value is true for a variable (property), the quality code property name is the same as the variable (property) name but with a "_qc" suffix. For example, the quality code property for the "temperature" variable (property) would be "temperature_qc".

Multiple records for an asset (entity) instance and aspect can be written in one call to the service. Records can be read and deleted by identifying the asset (entity) instance, aspect (property set), and time range.

When writing or deleting data, the default behavior of the service is to queue the incoming request and perform the physical writes to the underlying data store asynchronously. In this mode, if a user writes time series data and immediately tries to read it back, it may not yet be present in the data store and it won't be returned. If a user deletes data and then reads that time range, the data may not have been physically deleted yet, and could be returned in the response. Requests for an asset (entity) sent in queued mode will be processed in the order they were received.

Features

The IoT Time Series Service exposes its API for realizing the following tasks:

  • Read time series data for a single asset (entity) and aspect (property set).
  • Returns data for a specified time range.
  • Returns the latest value if no range is provided.
  • Write or update time series data for a single asset (entity) and aspect (property set).
  • Overwrite existing time series data.
  • Delete time series data for a single asset (entity) and aspect (property set) within a given time range.

Limits & Restrictions

  • The maximum size of a write payload to the Time Series PUT endpoint is 1 megabyte.
  • Writes for an individual asset and aspect are throttled to 100 kbytes per second, with each record in the payload consuming at least 1 kbyte.

To get the current list of known restrictions go to release notes and choose the latest date. From there goto "MindAccess Developer Plan Subscribers and MindAccess Operator Plan Subscribers" and pick the IoT service you are interested in.

Example Scenario

A windmill is connected to MindSphere. The wind wheel is moving with a constantly changing speed. The sensor catches the speed data and sends the data via MindConnect to MindSphere.

The IoT Time Series Service API allows you to collect the speed data of the wind wheel.

Requirements

  • The windmill is connected to MindSphere.

API Specification

Download OpenAPI Specification

Any questions left?

Ask the community


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