Sending Data from MindConnect MQTT Agent¶
An onboarded MindConnect MQTT agent can send data to Insights Hub 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¶
-
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 overloaded True indicates if the device is overloaded BOOLEAN - true true dataPoint6 readTime Time when the device related data was read TIMESTAMP second true false -
Data Modeling should be completed using the provided Aspect Types and Asset Types .
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:readTimedisplacementrpm
Electrical variables are grouped in
electricalAspectType:overloadedcurrenterrorMessage
Electrical and mechanical aspects are grouped in
electricalAndMechanicalAssetType:mechanicalAspectelectricalAspect
Given below is a sample model message according to the above grouping:
Example
{ "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:
Example
{
"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¶
MindConnect MQTT broker offers below described topics to send time series data.
<clientId> = <tenantId>_<AgentCertificate.Subject.CommonName>
Topic Structure: tc/<tenantId>/<clientId>/o/mc_v3/ts
Check Uploaded Time Series Data From Insights Hub Monitor¶
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 Insights Hub, 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¶
MindConnect MQTT broker which offers below described topics to send event data.
<clientId> = <tenantId>_<AgentCertificate.Subject.CommonName>
Topic: tc/<tenantId>/<clientId>/o/mc_v3/e
Check Uploaded Event Data from Insights Hub Monitor¶
Sending Files¶
Files of up to 75 KB can be uploaded per MQTT request. The files are attached to the corresponding asset, e.g. device log files or complex sensor structures. Files that are uploaded can be referenced by the parent asset in Insights Hub. The content of these files is not parsed by Insights Hub. 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¶
MindConnect MQTT broker offers below described topics for file upload.
<clientId> = <tenantId>_<AgentCertificate.Subject.CommonName>
Topic: tc/<tenantId>/<clientId>/o/mc_v3/f
Check Uploaded File Data from Insights Hub Monitor¶
Related Links¶
Except where otherwise noted, content on this site is licensed under the Development License Agreement.