Skip to content

Sending Data from MindConnect MQTT Agent

An onboarded MindConnect MQTT agent can send data to MindSphere using the MindConnect Async API. The steps shown here assumes that this is already accomplished:

  • Time Series
  • File
  • Event

Prerequisite

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

  • <requestId>
  • <tenantId>
  • <clientId>
  • <AgentCertificate.Subject.CommonName>

Sending Time Series Data

  1. The agent in this example uses 6 data points. The following table provides the particulars of the data points.

    Data Point Variable Description DataType Unit QualityCode Searchable
    dataPoint1 current Current consumed by the device DOUBLE A true true
    dataPoint2 displacement Displacement from the center INT cm true true
    dataPoint3 rpm Rotations per minute of the motor LONG - true true
    dataPoint4 errorMessage Error Message of the device STRING - true true
    dataPoint5 overloade True indicates if the device is overloaded BOOLEAN - true true
    dataPoint6 readTime Time when the device related data was read TIMESTAMP second true false
  2. Data Modeling should be completed using Aspect Types and Asset Types provided by MindSphere.

    Aspect Types: An Aspect Type is a template for creating multiple aspects with the same variables. Aspects are a data modeling mechanism for assets. Aspects group-related data points based on their logical association. An aspect can consist of several variables.

    Asset Types: An Asset Type is a pre-configured template for creating multiple assets with the same variables. Assets take on the properties of the type on which they are based. Within the type, you can define which aspects are integrated into the template. You can use a type in various assets and built several interconnections between a type and assets.

    Mechanical variables are grouped in mechanicalAspectType:

    • readTime
    • displacement
    • rpm

    Electrical variables are grouped in electricalAspectType:

    • overloaded
    • current
    • errorMessage

    Electrical and mechanical aspects are grouped in electricalAndMechanicalAssetType:

    • mechanicalAspect
    • electricalAspect

    Given below is a sample model message according to the above grouping:

    {
        "id": "<requestId>",
        "data": {
            "externalId": "ElectricMechanicalDeviceModel",
            "typeModel": {
                "aspectTypes": [{
                        "id": "<tenantId>.mechanicalAspectType",
                        "name": "mechanicalAspectType",
                        "category": "dynamic",
                        "scope": "private",
                        "variables": [{
                                "name": "readTime",
                                "dataType": "TIMESTAMP",
                                "unit": "second",
                                "searchable": false,
                                "qualityCode": true
                            },
                            {
                                "name": "displacement",
                                "dataType": "INT",
                                "unit": "cm",
                                "searchable": true,
                                "qualityCode": true
                            },
                            {
                                "name": "rpm",
                                "dataType": "LONG",
                                "searchable": true,
                                "qualityCode": true
                            }
                        ],
                        "description": "Mechanical properties of an device"
                    },
                    {
                        "id": "<tenantId>.electricalAspectType",
                        "name": "electricalAspectType",
                        "category": "dynamic",
                        "scope": "private",
                        "variables": [{
                                "name": "overloaded",
                                "dataType": "BOOLEAN",
                                "searchable": true,
                                "qualityCode": true
                            },
                            {
                                "name": "current",
                                "dataType": "DOUBLE",
                                "unit": "A",
                                "searchable": true,
                                "qualityCode": true
                            },
                            {
                                "name": "errorMessage",
                                "dataType": "STRING",
                                "length": 255,
                                "searchable": true,
                                "qualityCode": true
                            }
                        ],
                        "description": "Electrical properties of an device"
                    }
                ],
                "assetTypes": [{
                    "id": "<tenantId>.electricalAndMechanicalAssetType",
                    "name": "electricalAndMechanicalAssetType",
                    "parentTypeId": "core.basicasset",
                    "aspects": [{
                            "name": "electricalAspect",
                            "aspectTypeId": "<tenantId>.electricalAspectType"
                        },
                        {
                            "name": "mechanicalAspect",
                            "aspectTypeId": "<tenantId>.mechanicalAspectType"
                        }
                    ],
                    "description": "Asset Type with electrical and mechanical properties",
                    "instantiable": true,
                    "scope": "private"
                }]
            },
            "instanceModel": {
                "assets": [{
                    "referenceId": "electricalAndMechanicalAssetReference1",
                    "parentReferenceId": "root",
                    "typeId": "<tenantId>.electricalAndMechanicalAssetType",
                    "name": "electricalAndMechanicalAsset",
                    "description": "Asset with electrical and mechanical properties"
                }]
            },
            "mappingModel": {
                "mappings": [{
                        "dataPointId": "dataPoint1",
                        "assetReferenceId": "electricalAndMechanicalAssetReference1",
                        "aspectName": "electricalAspect",
                        "variableName": "current"
                    },
                    {
                        "dataPointId": "dataPoint2",
                        "assetReferenceId": "electricalAndMechanicalAssetReference1",
                        "aspectName": "mechanicalAspect",
                        "variableName": "displacement"
                    },
                    {
                        "dataPointId": "dataPoint3",
                        "assetReferenceId": "electricalAndMechanicalAssetReference1",
                        "aspectName": "mechanicalAspect",
                        "variableName": "rpm"
                    },
                    {
                        "dataPointId": "dataPoint4",
                        "assetReferenceId": "electricalAndMechanicalAssetReference1",
                        "aspectName": "electricalAspect",
                        "variableName": "errorMessage"
                    },
                    {
                        "dataPointId": "dataPoint5",
                        "assetReferenceId": "electricalAndMechanicalAssetReference1",
                        "aspectName": "electricalAspect",
                        "variableName": "overloaded"
                    },
                    {
                        "dataPointId": "dataPoint6",
                        "assetReferenceId": "electricalAndMechanicalAssetReference1",
                        "aspectName": "mechanicalAspect",
                        "variableName": "readTime"
                    }
                ]
            }
        }
    }
    

    Here is a sample instantiate message for the this model:

    {
        "id": "ElectricMechanicalDeviceInstantiationRequest",
        "data": {
            "modelExternalId": "ElectricMechanicalDeviceModel",
            "parameterization": {
                "values": []
            }
        }
    }
    

    Define the above model and instantiate it via Creating Data Model from MQTT Agent.

Defining Time Series Data Message for Sample Use Case

The message contains an array of sampled data. Each sample consists of a timestamp and an array of value objects. Each value object consists of data point id, value, and quality code.

According to the sample use case, the MQTT agent sends data every 10 seconds for the first three data points (dataPoint1, dataPoint2, dataPoint3) and sends data every 20 seconds for others (dataPoint4, dataPoint5, dataPoint6).

Given below is a sample time series message for this use case:

{
  "timeseries":[
    {
      "timestamp":"2022-03-17T02:05:00.000Z",
      "values":[
        {
          "dataPointId":"dataPoint1",
          "value":20.1,
          "qualityCode":"0"
        },
        {
          "dataPointId":"dataPoint2",
          "value":555,
          "qualityCode":"0"
        },
        {
          "dataPointId":"dataPoint3",
          "value":2147483648,
          "qualityCode":"0"
        },
        {
          "dataPointId":"dataPoint4",
          "value":"error",
          "qualityCode":"0"
        },
        {
          "dataPointId":"dataPoint5",
          "value":"true",
          "qualityCode":"0"
        },
        {
          "dataPointId":"dataPoint6",
          "value":"2022-02-10T01:05:20.020Z",
          "qualityCode":"0"
        }
      ]
    },
    {
      "timestamp":"2022-03-17T02:05:10.000Z",
      "values":[
        {
          "dataPointId":"dataPoint1",
          "value":34.14,
          "qualityCode":"0"
        },
        {
          "dataPointId":"dataPoint2",
          "value":654,
          "qualityCode":"0"
        },
        {
          "dataPointId":"dataPoint3",
          "value":4294967296,
          "qualityCode":"0"
        }
      ]
    },
    {
      "timestamp":"2022-03-17T02:05:20.000Z",
      "values":[
        {
          "dataPointId":"dataPoint1",
          "value":80.6,
          "qualityCode":"0"
        },
        {
          "dataPointId":"dataPoint2",
          "value":565,
          "qualityCode":"0"
        },
        {
          "dataPointId":"dataPoint3",
          "value":8589934592,
          "qualityCode":"0"
        },
        {
          "dataPointId":"dataPoint4",
          "value":"error",
          "qualityCode":"0"
        },
        {
          "dataPointId":"dataPoint5",
          "value":"true",
          "qualityCode":"0"
        },
        {
          "dataPointId":"dataPoint6",
          "value":"2022-02-10T01:10:20.020Z",
          "qualityCode":"0"
        }
      ]
    },
    {
      "timestamp":"2022-03-17T02:05:30.000Z",
      "values":[
        {
          "dataPointId":"dataPoint1",
          "value":43.13,
          "qualityCode":"0"
        },
        {
          "dataPointId":"dataPoint2",
          "value":456,
          "qualityCode":"0"
        },
        {
          "dataPointId":"dataPoint3",
          "value":8589934595,
          "qualityCode":"0"
        }
      ]
    }
  ]
}

Topic structure for sending time series

EU1
MindConnect MQTT broker for MindSphere which offers below described topics to send time series data.
<clientId> = <tenantId>_<AgentCertificate.Subject.CommonName>
Topic Structure: tc/<tenantId>/<clientId>/o/mc_v3/ts

EU2
MindConnect MQTT broker for MindSphere which offers below described topics to send time series data.
The actual IoTHub Broker URL is provided by DPS, during the onboarding flow.
<clientId> = <AgentCertificate.Subject.CommonName>
Topic Structure: devices/<clientId>/messages/events/mc_v3=ts

Check Uploaded Time Series Data From Operations Insight

image1

Sending Events

Events are based on machine events, for example, emergency stops or machine failures. However, this mechanism can also be used to upload custom notifications, for example, if you do on-site threshold monitoring and want to report a broken threshold.

MQTT Agents can upload events into MindSphere, where they are stored in the respective asset. The events must be of an event type derived from type AgentBaseEvent. The following rules apply for Sending events:

  • Event id must be sent as id in the payload.
  • The event type must exist in Event Management. Otherwise, the event is dropped.
  • The severity is optional, but events with invalid severity values are dropped. Allowed integer values are: 20 (ERROR), 30 (WARNING), 40 (INFORMATION)

Given below is a sample custom event type which is derived from AgentBaseEvent:

{
    "name": "FileUploadCompletedEvent",
    "parentId": "core.connectivity.event.type.AgentBaseEvent",
    "ttl": 35,
    "scope": "LOCAL",
    "fields": [{
            "name": "fileNumber",
            "filterable": true,
            "required": false,
            "updatable": true,
            "type": "INTEGER"
        },
        {
            "name": "fileSize",
            "filterable": true,
            "required": false,
            "updatable": true,
            "type": "DOUBLE"
        },
        {
            "name": "fileName",
            "filterable": true,
            "required": true,
            "updatable": true,
            "type": "STRING"
        },
        {
            "name": "isValid",
            "filterable": true,
            "required": false,
            "updatable": true,
            "type": "BOOLEAN"
        }
    ]
}
Given below is a sample event message for this event type:

{
  "events":[
    {
      "id":"e6e31c6f-7963-4f62-92a9-46b1b8b0649",
      "correlationId":"eventCorrelationId",
      "timestamp":"2022-03-17T15:45:02.302Z",
      "severity":20,
      "type":"FileUploadCompletedEvent",
      "description":"File upload test event",
      "details":{
        "fileName":"test2",
        "fileSize":11.2,
        "isValid":"true",
        "fileNumber":15
      }
    }
  ]
}

Topic structure for sending event

EU1
MindConnect MQTT broker for MindSphere which offers below described topics to send event data.
<clientId> = <tenantId>_<AgentCertificate.Subject.CommonName>
Topic: tc/<tenantId>/<clientId>/o/mc_v3/e

EU2
MindConnect MQTT broker for MindSphere which offers below described topics to send event data.
The actual IoTHub Broker URL is provided by DPS, during the onboarding flow.
<clientId> = <AgentCertificate.Subject.CommonName>
Topic: devices/<clientId>/messages/events/mc_v3=e

Check Uploaded Event Data From Operations Insight

image2

Sending Files

Files of up to 75 KB can be uploaded per MQTT request. The files are attached to the corresponding (virtual) asset, e.g. device log files or complex sensor structures. Files that are uploaded can be referenced by the parent (virtual) asset in MindSphere. The content of these files is not parsed by MindSphere. It requires custom applications or analytical tools to interpret and visualize the data.

Note

File content must Base64 encoded. The content size is limited to 75 KB.

Here is a sample message for sending file:

{
  "file":{
    "name":"samplefile",
    "creationDate":"2022-03-17T15:46:02.302Z",
    "content":"U2FtcGxlIEZpbGUgQ29udGVudA=="
  }
}

Topic structure for file upload

EU1
MindConnect MQTT broker for MindSphere which offers below described topics for file upload.
<clientId> = <tenantId>_<AgentCertificate.Subject.CommonName>
Topic: tc/<tenantId>/<clientId>/o/mc_v3/f

EU2
MindConnect MQTT broker for MindSphere which offers below described topics for file upload.
The actual IoTHub Broker URL is provided by DPS, during the onboarding flow.
<clientId> = <AgentCertificate.Subject.CommonName>
Topic: devices/<clientId>/messages/events/mc_v3=f

Check Uploaded File Data From Operations Insight

image3

Any questions left?

Ask the community


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


Last update: August 30, 2022