Skip to content

Creating Data Model from MQTT Agent

Overview

Asset Modeler service defines topics and message structures to create their assets, types and mappings.

Models are templates describing asset/aspect types, asset instances, asset hierarchy and mappings from data point ids to variables in aspects. Instantiations are the realization of the model. 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. Also, moving an asset created by an instantiation does not affect the model.

Limitations

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

  • There are frequency limits per tenant and per client for published and received messages.

  • The maximum size of the body is 128KBs.

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.

MQTTX Create and Instantiate Model

EU1

  1. Agent Connection

    Agent connection should be established before publishing model creation and instantiation messages. Refer to Onboarding Native MQTT Agent.

    Image1

  2. Publish Your Model

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

    Payload: Structure containing models for asset/aspect types, asset instances and mappings from provided keys to variables in the specified model.

    Model Message Example:

        {
            "id": "72609761sdv245248e126814c2dd83a27f",
            "data": {
                "externalId": "SpaceShip",
                "typeModel": {
                    "aspectTypes": [{
                        "id": "<tenantId>.wing",
                        "name": "${aspectTypeName}",
                        "category": "static",
                        "scope": "private",
                        "variables": [{
                            "name": "temperature",
                            "dataType": "STRING",
                            "unit": "C/F",
                            "searchable": true,
                            "length": 5,
                            "qualityCode": true
                        }],
                        "description": "wing aspect type description",
                        "referenceId": "287adc1a086840e0a6721dfd1170e97c"
                    }],
                    "assetTypes": [{
                        "id": "<tenantId>.spaceship",
                        "name": "wingAssetTypeName",
                        "parentTypeId": "core.basicasset",
                        "aspects": [{
                            "name": "wingAspect",
                            "aspectTypeId": "<tenantId>.wing"
                        }],
                        "description": "Hyperspace jump capable space ship",
                        "instantiable": true,
                        "scope": "private",
                        "referenceId": "82a4cc2a69cc42af80c1c6cf5dbefde5"
                    }]
                },
                "instanceModel": {
                    "assets": [{
                        "referenceId": "wingAssetReference",
                        "parentReferenceId": "root",
                        "typeId": "<tenantId>.spaceship",
                        "name": "wingAsset",
                        "description": "The ship of Han Solo and Chewbacca"
                    }]
                },
                "mappingModel": {
                    "mappings": [{
                        "dataPointId": "dp01",
                        "assetReferenceId": "wingAssetReference",
                        "aspectName": "wingAspect",
                        "variableName": "temperature",
                        "referenceId": "19e9048e78f540e7a9ba25e1249fea9b"
                    }]
                }
            }
        }
    

    image2

  3. Get Model Status

    Receive model creation results for a previous model request.

    SUB tc/<tenantId>/<clientId>/i/amo_v3/ms

    Response Message Example:

        {
            "id": "01FQC37FCCASSFT7M0D6W5EB8P",
            "correlationId": "01FQC37FCBG1DWMTEC4DYCZ327",
            "requestId": "72609761sdv245248e126814c2dd83a27f",
            "data": {
                "id": "01FQC37HX2KGP4DR0HNVR3K5B2",
                "externalId": "SpaceShip",
                "status": "Success"
            }
        }
    

    image3

  4. Instantiate your Model

    Create a new model with given asset model in body.

    PUB tc/<tenantId>/<clientId>/o/amo_v3/i

    Payload: Message containing model instantiation request parameters. Model Id can be found in response of Model Status, Id in data object represents modelId.

    Instantiate Message Example:

        {
            "id": "bb9b9d8d6193ddsss45a5w2s7e848fe28c",
            "data": {
                "modelExternalId": "SpaceShip",
                "parameterization": {
                    "values": [{
                        "name": "aspectTypeName",
                        "value": "wingAspectTypeName"
                    }]
                }
            }
        }
    

    image4

  5. Get Instantiate Model Status

    Receive instantiation job results for a previous instantiation request.

    SUB tc/<tenantId>/<clientId>/i/amo_v3/ip

    Response Message Examples:

    Message 1:

        {
            "id": "01FQC37RDJ54CAM75RWNAQV781",
            "correlationId": "01FQC37NKDHM4774NB1R1H7PST",
            "data": {
                "id": "01FQC37NVVFZWET43NSHYZJV4B",
                "modelId": "01FQC37HX2KGP4DR0HNVR3K5B2",
                "modelExternalId": "SpaceShip",
                "message": "25% completed.",
                "status": "InProgress"
            },
            "requestId": "bb9b9d8d6193ddsss45a5w2s7e848fe28c"
        }
    

    Message 2:

        {
            "id": "01FQC37RDJ54CAM75RWNAQV781",
            "correlationId": "01FQC37NKDHM4774NB1R1H7PST",
            "data": {
                "id": "01FQC37NVVFZWET43NSHYZJV4B",
                "modelId": "01FQC37HX2KGP4DR0HNVR3K5B2",
                "modelExternalId": "SpaceShip",
                "message": "50% completed.",
                "status": "InProgress"
            },
            "requestId": "bb9b9d8d6193ddsss45a5w2s7e848fe28c"
        }
    

    Message 3:

        {
            "id": "01FQC37RDJ54CAM75RWNAQV781",
            "correlationId": "01FQC37NKDHM4774NB1R1H7PST",
            "data": {
                "id": "01FQC37NVVFZWET43NSHYZJV4B",
                "modelId": "01FQC37HX2KGP4DR0HNVR3K5B2",
                "modelExternalId": "SpaceShip",
                "message": "75% completed.",
                "status": "InProgress"
            },
            "requestId": "bb9b9d8d6193ddsss45a5w2s7e848fe28c"
        }
    

    Message 4:

        {
            "id": "01FQC37RDJ54CAM75RWNAQV781",
            "correlationId": "01FQC37NKDHM4774NB1R1H7PST",
            "data": {
                "id": "01FQC37NVVFZWET43NSHYZJV4B",
                "modelId": "01FQC37HX2KGP4DR0HNVR3K5B2",
                "modelExternalId": "SpaceShip",
                "message": "100% completed.",
                "status": "Success"
            },
            "requestId": "bb9b9d8d6193ddsss45a5w2s7e848fe28c"
        }
    

    image5

    After instantiation completed successfully, Created resources can be verifed from Asset Manager.

    image6

EU2

  1. Agent Connection

    Already connected agent via Native MQTT. Refer to Onboarding Native MQTT Agent.

  2. Publish Your Model

    PUB devices/<clientId>/messages/events/amo_v3=m

    Payload: Structure containing models for asset/aspect types, asset instances and mappings from provided keys to variables in the specified model.

    Model Message Example:

        {
            "id": "72609761sdv245248e126814c2dd83a27f",
            "data": {
                "externalId": "SpaceShip",
                "typeModel": {
                    "aspectTypes": [{
                        "id": "<tenantId>.wing",
                        "name": "${aspectTypeName}",
                        "category": "static",
                        "scope": "private",
                        "variables": [{
                            "name": "temperature",
                            "dataType": "STRING",
                            "unit": "C/F",
                            "searchable": true,
                            "length": 5,
                            "qualityCode": true
                        }],
                        "description": "wing aspect type description",
                        "referenceId": "287adc1a086840e0a6721dfd1170e97c"
                    }],
                    "assetTypes": [{
                        "id": "<tenantId>.spaceship",
                        "name": "wingAssetTypeName",
                        "parentTypeId": "core.basicasset",
                        "aspects": [{
                            "name": "wingAspect",
                            "aspectTypeId": "<tenantId>.wing"
                        }],
                        "description": "Hyperspace jump capable space ship",
                        "instantiable": true,
                        "scope": "private",
                        "referenceId": "82a4cc2a69cc42af80c1c6cf5dbefde5"
                    }]
                },
                "instanceModel": {
                    "assets": [{
                        "referenceId": "wingAssetReference",
                        "parentReferenceId": "root",
                        "typeId": "<tenantId>.spaceship",
                        "name": "wingAsset",
                        "description": "The ship of Han Solo and Chewbacca"
                    }]
                },
                "mappingModel": {
                    "mappings": [{
                        "dataPointId": "dp01",
                        "assetReferenceId": "wingAssetReference",
                        "aspectName": "wingAspect",
                        "variableName": "temperature",
                        "referenceId": "19e9048e78f540e7a9ba25e1249fea9b"
                    }]
                }
            }
        }
    

    image7

  3. Get Model Status

    Receive model creation results for a previous model request.

    SUB devices/<clientId>/messages/devicebound/#

    Receive model creation results for a previous model request.

    Response Message Example:

        {
            "id": "01FQC37FCCASSFT7M0D6W5EB8P",
            "correlationId": "01FQC37FCBG1DWMTEC4DYCZ327",
            "requestId": "72609761sdv245248e126814c2dd83a27f",
            "data": {
                "id": "01FQC37HX2KGP4DR0HNVR3K5B2",
                "externalId": "SpaceShip",
                "status": "Success"
            }
        }
    

    image8

  4. Instantiate your Model

    Create a new model with given asset model in body.

    Topic Name: PUB devices/<clientId>/messages/events/amo_v3=i

    Payload: Message containing model instantiation request parameters. Model Id can be found in response of Model Status, Id in data object represents modelId.

    Instantiate Message Example:

        {
            "id": "bb9b9d8d6193ddsss45a5w2s7e848fe28c",
            "data": {
                "modelExternalId": "SpaceShip",
                "parameterization": {
                    "values": [{
                        "name": "aspectTypeName",
                        "value": "wingAspectTypeName"
                    }]
                }
            }
        }
    

    image10

  5. Get Instantiate Model Status

    Receive instantiation job results for a previous instantiation request.

    SUB devices/{clientId}/messages/devicebound/#

    Response Message Examples:

    Message 1:

        {
            "id": "01FQC37RDJ54CAM75RWNAQV781",
            "correlationId": "01FQC37NKDHM4774NB1R1H7PST",
            "data": {
                "id": "01FQC37NVVFZWET43NSHYZJV4B",
                "modelId": "01FQC37HX2KGP4DR0HNVR3K5B2",
                "modelExternalId": "SpaceShip",
                "message": "25% completed.",
                "status": "InProgress"
            },
            "requestId": "bb9b9d8d6193ddsss45a5w2s7e848fe28c"
        }
    

    Message 2:

        {
            "id": "01FQC37RDJ54CAM75RWNAQV781",
            "correlationId": "01FQC37NKDHM4774NB1R1H7PST",
            "data": {
                "id": "01FQC37NVVFZWET43NSHYZJV4B",
                "modelId": "01FQC37HX2KGP4DR0HNVR3K5B2",
                "modelExternalId": "SpaceShip",
                "message": "50% completed.",
                "status": "InProgress"
            },
            "requestId": "bb9b9d8d6193ddsss45a5w2s7e848fe28c"
        }
    

    Message 3:

        {
            "id": "01FQC37RDJ54CAM75RWNAQV781",
            "correlationId": "01FQC37NKDHM4774NB1R1H7PST",
            "data": {
                "id": "01FQC37NVVFZWET43NSHYZJV4B",
                "modelId": "01FQC37HX2KGP4DR0HNVR3K5B2",
                "modelExternalId": "SpaceShip",
                "message": "75% completed.",
                "status": "InProgress"
            },
            "requestId": "bb9b9d8d6193ddsss45a5w2s7e848fe28c"
        }
    

    Message 4:

        {
            "id": "01FQC37RDJ54CAM75RWNAQV781",
            "correlationId": "01FQC37NKDHM4774NB1R1H7PST",
            "data": {
                "id": "01FQC37NVVFZWET43NSHYZJV4B",
                "modelId": "01FQC37HX2KGP4DR0HNVR3K5B2",
                "modelExternalId": "SpaceShip",
                "message": "100% completed.",
                "status": "Success"
            },
            "requestId": "bb9b9d8d6193ddsss45a5w2s7e848fe28c"
        }
    

    image11

    After instantiation completed successfully, Created resources can be verifed from Asset Manager.

    image6

Any questions left?

Ask the community


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


Last update: December 22, 2021