Creating a configuration file

A JSON configuration file is required to synchronize data to a generic MQTT broker. This file defines the MQTT topic, to which the synchronized data packages will be sent out, and the payload structure of the MQTT packages.

Format of the configuration file

The configuration file should contain the following two fields:

Field	Description
`topic`	The `topic` field defines the MQTT topic to which the packages will be sent out.
`payload`	The `payload` field defines the payload structure. In the payload field, the datapoints definition is mandatory. All other fields need to be of type string and are send as header information with every package. The configuration file must strictly follow this format. A connection will not be established to the MQTT broker if the configuration file has an invalid format.

The code block below shows a sample configuration file for setting up a generic MQTT broker as synchronization destination:

Sample configuration file

{
  "topic": "factory_1/$path/$attributeName",

  "payload": {
    "Topic": "$topic",
    "Name": "$attributeName",
    "Hierarchy": "$path",
    "IED_Model": "IED 427 Factory 1",
    "datapoints": {
      "Measurement": "$value",
      "Time": "$timestamp:ISO8601",
      "Quality_Code": "$qualityCode"
    }
  }
}

`topic` field

The topic field defines the MQTT topic to which the packages will be sent out. The topic must be specified as a string. The topic will be assigned to every attribute individually, i. e., it is possible to send every attribute to a different topic. Since MQTT topics are built relying on hierarchical topics, it is possible to acquire data, e. g., from multiple attributes or a whole entity, by subscribing to the topic at the desired sublevel.

Dynamic attributes can be used as a single topic level in the topic structure. To use a dynamic attribute, append a dollar sign ($) in front of the attribute name. Only one keyword per topic level can be used. The following keywords are supported as dynamic attributes:

$attributeName: This keyword refers to the attribute name (string) that was assigned in IIH Essentials (IIHE). For instance, for the entities overview shown below, when synchronizing the attribute, this keyword would be replaced by the string StressTest1_1.
$path: This keyword refers to the hierarchy to which the attribute belongs. For instance, for the entity overview shown, when synchronizing the attribute, this keyword would be replaced by the string StressTest_grpc/StressTest_1. If the attribute belongs to an entity of type aspect it will also be included in the path.

Note

The base entity, i. e., edge, will not be included in the path. In case this is desired, the entity name can be manually typed into the topic structure.

alt text

Entities overview in IIH Essentials

Further topic guidelines

The following details about the topic should be considered:

The topic must be a JSON string.
Slash (/) is used as the topic level separator.
If an unknown keyword is used along with the dollar sign ($) it will remain as it is.
Keywords that do not start with the dollar sign ($) will be handled as a string in the topic.
The topic should not begin or end with a topic level separator, i. e., it is not necessary to have a topic level separator at the beginning or at the end of the topic.
Spaces will be removed from the MQTT topic.

`payload` field

This object defines the payload structure of each MQTT package. The payload structure is split into two sections: the header elements and the data points.

The header elements will only be contained once per package. The data points element encapsulates an array of objects that will be as long as the amount of data points being sent in the MQTT package. Both objects should contain an object of key-value pairs, where the key refers to an identifier chosen by the user and the value to one of the allowed dynamic attributes or a static keyword.

Note

One MQTT package can only contain data of a single attribute and, therefore, at least one package will be sent out per attribute every Message publish interval.

When header elements are defined in the configuration file, they are sent out one time per MQTT package. If no header elements should not be included in the package, only define the datapoints element. Dynamic attributes can be used as one of the values of the object containing key-value pairs. To use a dynamic value, prepend a dollar sign ($) in front of the json value. Only one keyword per value of the key-value pair can be used. The following keywords are supported as dynamic attributes for the header:

$topic: This keyword refers to the MQTT topic defined in the configuration file. Before sending the value, the keywords are replaced by their respective value and casted as a string.
$attributeName: This keyword refers to the attribute name (string) that was assigned in IIH Essentials. For instance, for the entity overview shown in the picture above, when synchronizing the attribute, this keyword would be replaced by the string StressTest1_1.
$path: This keyword refers to the hierarchy to which the attribute belongs. As an illustration, for the entities overview shown above, when synchronizing the attribute, this keyword would be replaced by the string StressTest_grpc/StressTest_1. If the attribute belongs to an entity of type aspect it will also be included in the path.

Note

The base entity, i.e., edge, will not be included in the path. In case this is desired, the entity name can be manually typed into the topic structure.

Data points

The data points field specifies how each one of the elements of the data points array will look like in the MQTT package. In case no data points are desired in the package, please write the data points as an array containing an empty object. Dynamic keywords can be used as one of the values of the object containing key-value pairs. To use a dynamic keyword, append a dollar sign ($) in front of the keyword name. Only one keyword per value of the key-value pair can be used. The following keywords are supported as dynamic attributes for the data points:

$value: This denotes the value of the data point of the attribute being synchronized. Before sending the value, it is casted as a string.
$timestamp:Format: This denotes the timestamp of the data point of the attribute being synchronized. Before sending the value, it is casted as a string. The timestamp format must be defined along with the keyword. The colon (:) is used as the separator between the timestamp and its format. Three timestamp formats are currently supported:
- $timestamp:LDAP-Filetime: The timestamp is in 18-digit LDAP/FILETIME format.
- $timestamp:ISO8601: The timestamp is in the international ISO8601 standard format.
- $timestamp:Unix: The timestamp is in Unix format (Seconds since Unix epoch).
$topic: This keyword refers to the MQTT topic defined in the configuration file. Before sending the value, the keywords are replaced by their respective value and casted as a string.
$attributeName: This keyword refers to the attribute name (string) that was assigned in IIH Essentials. For instance, for the entities overview shown in the picture above, when synchronizing the attribute, this keyword would be replaced by the string StressTest1_1.
$path: This keyword refers to the hierarchy to which the attribute belongs. For instance, for the entities overview shown above, when synchronizing the attribute, this keyword would be replaced by the string StressTest_grpc/StressTest_1. If the attribute belongs to an entity of type aspect it will also be included in the path.

Note

The base entity, i. e., edge, will not be included in the path. In case this is desired, the entity name can be manually typed into the topic structure.

$qualityCode: This keyword refers to the quality code of the value in IIH Essentials.

Further payload guidelines

The following facts about the payload should be considered:

The key of the key-value pairs can be any string value.
If an unknown keyword is used for the payload along with the dollar sign ($), it will be replaced by unknownPayloadKeyword.
In case an unknown timestamp format is used for the payload keyword, it will be replaced by the default timestamp format ISO8601.
Keywords that do not start with the dollar sign ($) will be handled as a string in the payload. For instance, IED 427 Factory 1 as the IED Model in the sample configuration file shown above.
Bear in mind that the payload structure, in particular, the data points structure, directly affects the amount data traffic from IIH Essentials. As a larger payload entails larger MQTT packages.

In case no header elements are desired in the package, only use the datapoints object, please see the example below.

{
  "topic": "factory_1/$path/$attributeName",
  "payload": {
    "datapoints": {}
  }
}

Result

Once the configuration file has been created and saved as a JSON file, it can be used to add a generic MQTT as a synchronization destination in IIH Essentials.

Except where otherwise noted, content on this site is licensed under the Siemens Inner Source License .

Creating a configuration file

Format of the configuration file

topic field

Further topic guidelines

payload field

Header

Data points

Further payload guidelines

Result

`topic` field

`payload` field