Asset Modeler Async API Service - Developer Documentation - Developer Documentation
Skip to content

Asset Modeler Async API Service

Idea

The Asset Modeler Async API provides topics and message structures to create their assets, types, and mappings.

Using this service, devices can send their asset model or can instantiate already stored asset model.

For further information about the Asset Modeler Async API, refer to Asset Modeler Async API Specification.

Info

The Asset Modeler Async API Service is currently available in regions Europe 1 and Europe 2.

Access

For accessing this API, you need to upload your CA Certificate. For more information, refer to Manage MQTT Certificates.

Basics

Broker information

The MQTT devices must authenticate the broker by the help of a certificate. Download the provided certificate and install it on your device.

Environment

You need an environment on Industrial IoT. Within this document, parameter \$TENANT is the name of your environment.

Agent Certificate

An agent can be onboarded using an agent certificate issued by the environment's CA certificate.

To successfully connect, onboard, and communicate with the MQTT broker, each client needs to use a clientId in the following format:

<clientId>=<tenant>_<AgentCertificate.Subject.CommonName>

ClientId

The clientId represents the agent identification. MQTT Client of agents must be unique and exclusive. The ClientId is the key to the session stored in broker, hence exclusiveness is security relevant in a multitenant system. That ClientId is also associated with the thing that represents the client by setting thing's name to ClientId.

Since ClientId selected by connecting(registering) agent, it is possible to have clashes in ids. To avoid clashes client is selection is restricted to format.

<tenantId>_<AgentCertificate.Subject.CommonName>

Then such a relation is enforced:

<thingname> = <clientId> = <tenant>_<AgentCertificate.Subject.CommonName>

Restrictions on customer:

  1. Tenant name must be known prior to issuing device certificates.

  2. Agents needs to be configured with environment name and certificate's CN.

  3. Customer is responsible to assign CNs uniquely for each device.

Models

Models are templates describing asset/aspect types, asset instances, asset hierarchy and mappings from data point ids to variables in aspects. This operation creates own asset model by describing aspect types, asset types, asset instances and data point mappings.

Instantiations

This operation creates a new model with a given asset model in the body. An instantiation job takes a model and creates the items described in the model by creating types, instances, and mappings. A model can be instantiated many times.

Models and instantiations are loosely coupled. A change to model instantiation does not affects model. Also, a change in model does not affect any completed instantiations as well. For example, if a model is deleted, existing instantiations are not affected. Or moving an asset created by an instantiation, does not affect the model.

Instantiation Progress

This operation is used to get instantiation job results for a given instantiation request.

Model Creation Result

Receive model creation results for a previous model request.

Instantiation Progress Result

Receive instantiation job results for a previous instantiation request.

Features

The Asset Modeler Async service exposes its API for realizing the following tasks:

  • Create Asset Model by describing aspect types, asset types, asset instances and data point mappings.

  • Create the instantiation job request of aspect types, asset types and assets and datapoints which are described in asset model.

  • Receive instantiation job results for a previous instantiation request.

Limitations

  • The number of asset model definitions per environment is limited.

  • There are frequency limits per environment and per agent for published and received messages.

  • Maximum size of body is 128 kb.

Example Scenario

The manager of a wind farm wants to collect sensor data of a wind turbine. He wants to collect the data of Rotation Speed, Air Density, Turbulence, Pulse Duration, Pulse Log, and Stator Voltage data to reduce operational risks and improve efficiency.

The developer implements a publisher to create the WindTurbinePowerGenaratorModel, WindTurbune data collection asset instances and data mappings via Asset Modeler Async API.

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

Last update: April 13, 2023