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:
-
Tenant name must be known prior to issuing device certificates.
-
Agents needs to be configured with environment name and certificate's CN.
-
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.
Related Links¶
Except where otherwise noted, content on this site is licensed under the Development License Agreement.