Asset Modeler Async API Service¶

Idea¶

One of the significant hurdles after connecting your agents to the cloud is to represent their data points in the asset model accurately along with desired asset structure and its hierarchy. Allowing the user to perform this operation manually can often lead to a subpar experience due to its susceptibility to errors and the extensive time it demands. It requires a skilled person to spend their quality time. This becomes very expensive even if you want to maintain a simple asset hierarchy along with countable number of data points.
It would be helpful if the agent could automatically construct and maintain the entire asset model and its hierarchy for the users. This allows the users to quickly realize the value of the data collected by your agent. By using Asset Modeler services, your agent can efficiently create and maintain the entire asset model from your agent. The user then can refrain from manually creating and maintaining the asset model. This will enable the user to focus on the data gathered by the agents.

You can use Asset Modeler Async services to create and maintain the asset model. These services provide you with topics and message structures for this purpose. It can also be used for maintaining a suitable asset hierarchy.

Features¶

Asset Modeler services can be used to create the asset model in either of the following ways:

• Create all elements of the asset model
• Create only portions of the asset model as per the requirement

Asset Modeler Async services allows the agents to perform the following operations:

• Create an entire asset model by describing aspect types, asset types, asset instances and data point mappings. In this case, every element of the asset model is created by the Asset Modeler services.
• Reuse the portions of asset model to create a new one or update an existing asset model. In this case, only the new definition of the asset model is created.
• Instantiate already defined asset model to quickly create its components
• Update only portion of the model to modify the model that is already existing
• Delete the portion of the model that is no longer needed
• Subscribe to the changes to the model from Insights Hub either partially or fully

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

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 with the help of a certificate. You need to 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.

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 multi-tenant system. That ClientId is also associated with the thing that represents the client by setting thing's name to ClientId.

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

<tenantId>_<AgentCertificate.Subject.CommonName>

Then, such a relation is enforced:

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

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 an 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 affect the model. Also, a change in the 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.

Limitations¶

• In Asset Modeler V3, it is possible to upload models to Insights Hub. However, retrieval of these models is not supported, and neither deletion nor updating of resources is permitted. The model is not updated after a change made through Asset Manager.
• There are frequency limits per environment and per agent for published and received messages.
• Maximum size of the body is 128 KB.
• One-to-one relation exists between the client and the asset model for Asset Modeler V4.
• The enablement of Asset Modeler V4 API may take up to 15 minutes after the device is connected.

Example Scenario¶

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

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

Related Links¶

• MindConnect Async API

• MindConnect MQTT Broker

• Manage MQTT Certificates

• Asset Modeler How To

• Creating V4 Data Model from MQTT Agent

• Creating V3 Data Model from MQTT Agent

• Transition to V4 Model