Skip to content

Creating V4 Data Model from MQTT Agent

Overview

Asset Modeler service defines topics and message structures to create and maintain the asset model. Its services can also be used for maintaining a suitable asset hierarchy.

Prerequisites

  • To generate certificates, ensure to have the OpenSSL toolkit or an equivalent setup to create certificates.

  • MQTTX is installed on your computer or an equivalent setup.

Preparation

Update the following fields with appropriate values before using the samples given in this section:

  • <requestId>
  • <tenantId>
  • <clientId>

Mqtt Connection

Agent Connection

Agent connection should be established before publishing the model creation and instantiation messages. For more information, refer to Onboarding MindConnect MQTT Agent.

Image0

Create and Instantiate Asset Model

Subscribe to Get Asset Model Instantiation Status

In order to constantly get the status of the model instantiation, we recommend to subscribing to model instantiation progress messages. This will help your agent to asynchronously receive status (success or failure) of model instantiation. Please note that it is optional to subscribe to and should be done only when necessary.

SUB tc/<tenantId>/<clientId>/i/amo_v4/mip
or
SUB tc/<tenantId>/<clientId>/i/amo_v4/#

Response Messages Example:

    {
        "id": "01HFV9RX4YFKA3WHGP1FCJW4AG",
        "correlationId": "01HFV9RNMV43D7Y6FMTQ93YVDF",
        "requestId": "myrequest1",
        "data": {
            "id": "01HFV9RRPZR8YWSSBDZQFVPGX2",
            "modelId": "01HFV9RRADTAQSHAHH91MT7MQ6",
            "message": "20% completed.",
            "status": "InProgress"
        }
    }

image1

Create Asset Model

Trigger the asset model instantiation job to create or update resources defined in the model. The defined resource can be any of the following resource types:

  • aspect types
  • aspect type variables
  • asset types
  • asset type aspects
  • asset instances
  • data point mappings

PUB tc/<tenantId>/<clientId>/o/amo_v4/mi

Model Instantiation Message Example:

{
  "id": "<requestId>",
  "data": {
    "typeModel": {
      "aspectTypes": [
        {
          "id": "<tenantId>.mechanicalAspectType",
          "name": "mechanicalAspectType",
          "description": "Mechanical properties of an device",
          "category": "dynamic",
          "referenceId": "AspectType1ReferenceId",
          "variables": [
            {
              "name": "readTime",
              "dataType": "TIMESTAMP",
              "qualityCode": true,
              "unit": "second",
              "searchable": false,
              "referenceId": "readTimeReferenceId"
            },
            {
              "name": "displacement",
              "dataType": "INT",
              "qualityCode": true,
              "unit": "cm",
              "searchable": true,
              "referenceId": "displacementReferenceId"
            },
            {
              "name": "rpm",
              "dataType": "LONG",
              "qualityCode": true,
              "searchable": true,
              "referenceId": "rpmReferenceId"
            }
          ]
        },
        {
          "id": "<tenantId>.electricalAspectType",
          "name": "electricalAspectType",
          "description": "Electrical properties of an device",
          "category": "dynamic",
          "referenceId": "AspectType2ReferenceId",
          "variables": [
            {
              "name": "overloaded",
              "dataType": "BOOLEAN",
              "qualityCode": true,
              "searchable": true,
              "referenceId": "overloadedReferenceId"
            },
            {
              "name": "current",
              "dataType": "DOUBLE",
              "qualityCode": true,
              "unit": "A",
              "searchable": true,
              "referenceId": "currentReferenceId"
            },
            {
              "name": "errorMessage",
              "dataType": "STRING",
              "qualityCode": true,
              "searchable": true,
              "length": 255,
              "referenceId": "errorMessageReferenceId"
            }
          ]
        }
      ],
      "assetTypes": [
        {
          "id": "<tenantId>.electricalAndMechanicalAssetType",
          "name": "electricalAndMechanicalAssetType",
          "description": "Asset Type with electrical and mechanical properties",
          "parentTypeId": "core.basicasset",
          "variables": [],
          "referenceId": "AssetType1ReferenceId",
          "aspects": [
            {
              "name": "electricalAspect",
              "aspectTypeId": "<tenantId>.electricalAspectType",
              "referenceId": "electricalAspectReferenceId"
            },
            {
              "name": "mechanicalAspect",
              "aspectTypeId": "<tenantId>.mechanicalAspectType",
              "referenceId": "mechanicalAspectReferenceId"
            }
          ]
        }
      ]
    },
    "instanceModel": {
      "assets": [
        {
          "name": "electricalAndMechanicalAsset",
          "typeId": "<tenantId>.electricalAndMechanicalAssetType",
          "parentReferenceId": "root",
          "description": "Asset with electrical and mechanical properties",
          "referenceId": "Asset1ReferenceId"
        }
      ]
    },
    "mappingModel": {
      "mappings": [
        {
          "aspectName": "electricalAspect",
          "variableName": "current",
          "dataPointId": "dataPoint1",
          "assetReferenceId": "Asset1ReferenceId",
          "referenceId": "dataPoint1ReferenceId"
        },
        {
          "aspectName": "mechanicalAspect",
          "variableName": "displacement",
          "dataPointId": "dataPoint2",
          "assetReferenceId": "Asset1ReferenceId",
          "referenceId": "dataPoint2ReferenceId"
        },
        {
          "aspectName": "mechanicalAspect",
          "variableName": "rpm",
          "dataPointId": "dataPoint3",
          "assetReferenceId": "Asset1ReferenceId",
          "referenceId": "dataPoint3ReferenceId"
        },
        {
          "aspectName": "electricalAspect",
          "variableName": "errorMessage",
          "dataPointId": "dataPoint4",
          "assetReferenceId": "Asset1ReferenceId",
          "referenceId": "dataPoint4ReferenceId"
        },
        {
          "aspectName": "electricalAspect",
          "variableName": "overloaded",
          "dataPointId": "dataPoint5",
          "assetReferenceId": "Asset1ReferenceId",
          "referenceId": "dataPoint5ReferenceId"
        },
        {
          "aspectName": "mechanicalAspect",
          "variableName": "readTime",
          "dataPointId": "dataPoint6",
          "assetReferenceId": "Asset1ReferenceId",
          "referenceId": "dataPoint6ReferenceId"
        }
      ]
    }
  }
}

image2

After the model instantiation is completed successfully, the created resources can be verified from Asset Manager.

image3

Get Instantiated Model

Subscribe to Get Instantiated Model

Subscribe to following topic to get the already created asset model. In response message, a pre-sign bucket url is available. Ensure to download your model from this link within one day.

SUB tc/<tenantId>/<clientId>/i/amo_v4/m
or
SUB tc/<tenantId>/<clientId>/i/amo_v4/#

Response Message Example:

    {
    "id": "01HFVCJYNARR56BPHBEA8Y90QE",
    "correlationId": "01HFVCJYN9WDFXT9N6PDWTPPN5",
    "requestId": "myModelGetRequest",
    "data": {
        "content": "https://your-bucket-name.s3.amazonaws.com/path/to/your/object/file.json?AWSAccessKeyId=YOUR_ACCESS_KEY_ID&Expires=EXPIRATION_TIMESTAMP&Signature=SIGNATURE",       
        "status": "Success"
    }
    }

image4

Send Message to Get Instantiated Models**

Request the entire asset model with all the resource definitions.

PUB tc/<tenantId>/<clientId>/o/amo_v4/m

Get Instantiated Model Message Example:

    {
    "id": "<requestId>"
    }

image5

Get Resource with Reference Id

Subscribe to Get Specific Resource Definition with Reference Id

Receive specific resource definition of asset model for a given referenceId.

SUB tc/{tenantId}/{clientId}/i/amo_v4/m/{referenceId}
or
SUB tc/<tenantId>/<clientId>/i/amo_v4/#

Response Message Example:

    {
    "id": "01HFVE3NRY46NKWPMBQ21T7CWT",
    "correlationId": "01HFVE3NRY9FGCRCJ360PP5Q7B",
    "requestId": "myResourceGetRequestWithRefId",
    "data": {
        "status": "Success",
        "AssetType1ReferenceId": {
            "id": "<tenantId>.electricalAndMechanicalAssetType",
            "name": "electricalAndMechanicalAssetType",
            "description": "Asset Type with electrical and mechanical properties",
            "parentTypeId": "core.basicasset",
            "variables": [],
            "referenceId": "AssetType1ReferenceId"
        }
    }
    }

image6

Send Message to Get Specific Resource Definition with Reference Id

Request the entire asset model with all resource definitions.

PUB tc/{tenantId}/{clientId}/o/amo_v4/m/{referenceId}

Get Specific Resource Definition with Reference Id Message Example:

    {
    "id": "<requestId>"
    }

image7

Update Resources Defined in the Model

Send Message to Update Resources Defined in the Model

Trigger the asset model instantiation job to update the resources defined in the model. The defined resource can be any of the following resource types:

  • aspect types
  • aspect type variables
  • asset types
  • asset type aspects
  • asset instances
  • data point mappings

Only adding new variable to aspect type and adding new aspect to asset type is allowed.

Info

To get the update request related results, subscribe totc/<tenantId>/<clientId>/i/amo_v4/mip or tc/<tenantId>/<clientId>/i/amo_v4/#

PUB tc/{tenantId}/{clientId}/o/amo_v4/mi/u

Update Resources Message Example:

    {
    "id": "<requestId>",
    "data": {
        "overloadedReferenceId": {
            "name": "overloadedUpdatedName"
        },
        "Asset1ReferenceId": {
            "name": "electricalAndMechanicalAssetUpdatedName",
            "description": "New description for asset."
        }
    }
    }

image8

After updating the resources successfully, the updated resources can be verified from Asset Manager.

image9

Delete Resources with Reference Id

Send Message to Delete Specific Resource with Reference Id

Trigger the asset model instantiation job to delete the resource by referenceId defined in the model. The defined resource can be any of the following resource types:

  • aspect types
  • aspect type variables
  • asset types
  • asset type aspects
  • asset instances
  • data point mappings

Info

To get the delete request related results, subscribe totc/<tenantId>/<clientId>/i/amo_v4/mip or tc/<tenantId>/<clientId>/i/amo_v4/#

PUB tc/{tenantId}/{clientId}/o/amo_v4/mi/d/{referenceId}

Delete Resources Message Example:

    {
    "id": "<requestId>"
    }

image10

Add New Mapping and Variable

Send Message to Add New Variable and Mapping**

Trigger the asset model instantiation job to add new resource in the model. The new resource to be added can be any of the following resource types:

  • aspect types
  • aspect type variables
  • asset types
  • asset type aspects
  • asset instances
  • data point mappings

Info

To get the add request related results, subscribe to tc/<tenantId>/<clientId>/i/amo_v4/mip or tc/<tenantId>/<clientId>/i/amo_v4/#

Instead of re-sending the entire model, it is only required to send the new resources to be added within the model.

PUB tc/{tenantId}/{clientId}/o/amo_v4/mi

Add New Variable and Mapping Message Example:

    {
    "id": "<requestId>",
    "data": {
        "typeModel": {
            "aspectTypes": [
                {
                    "id": "<tenantId>.mechanicalAspectType",
                    "name": "mechanicalAspectType",
                    "description": "Mechanical properties of an device",
                    "category": "dynamic",
                    "referenceId": "AspectType1ReferenceId",
                    "variables": [
                        {
                            "name": "newAddedVariable",
                            "dataType": "DOUBLE",
                            "qualityCode": true,
                            "unit": "A",
                            "searchable": false,
                            "referenceId": "newAddedVariableReferenceId"
                        }
                    ]
                }
            ],
            "assetTypes": []
        },
        "instanceModel": {
            "assets": []
        },
        "mappingModel": {
            "mappings": [
                {
                    "aspectName": "mechanicalAspect",
                    "variableName": "newAddedVariable",
                    "dataPointId": "dataPoint7",
                    "assetReferenceId": "Asset1ReferenceId",
                    "referenceId": "dataPoint7ReferenceId"
                }
                ]
        }
    }
    }

image11

After adding the resources successfully, the added resources can be verified from Asset Manager.

image12

Limitations

  • One-to-one relation exists between the client and the asset model.
  • The maximum size of the body is 128KBs.
Last update: December 12, 2023

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