Skip to content

Setting up a generic MQTT broker as a synchronization destination

A generic MQTT broker can be configured as a data destination in IIH Essentials to synchronize live and historical data. In this section, the procedure to add an MQTT broker as a data destination, some particularities and limitations to take into consideration are shown.

Data prioritization

IIH Essentials synchronizes data for an attribute in chronological order. This means it starts with the oldest but not yet synchronized data and continues until all data up to the current timestamp is synchronized.

Attribute-based synchronization

The outgoing MQTT packages from IIH Essentials only contain data from a single attribute. It is not possible to send data from multiple attributes within the same MQTT package. The synchronization only starts once at least an attribute has been added to the entity. If the synchronization is started for an entity without attributes, no MQTT packages will be sent out.

Synchronization without model

In contrast to the data synchronization to Senseye or Insights Hub, the synchronization to a generic MQTT broker is done without a model synchronization. This means that the model hierarchy will not be synchronized to the data destination. Instead, the hierarchy path of the attribute being synchronized can be sent as part of the topic or payload.

Payload

The payload structure can be specified using the configuration file, please see the section Creating a configuration file for further details on how to create a configuration file. While creating the synchronization destination through IIH Essential's UI it is possible to indicate further parameters linked to the payload of the MQTT packages. As a whole, the following values were taken as upper limits for the payload:

  • Maximum 10 MB for payload size per package (including headers).

Note

The payload size strongly depends on how the payload structure specified in the configuration file looks like.

Unidirectional synchronization

Data is always synchronized in one direction – from IIH Essentials to the generic MQTT broker. For this synchronization with a generic MQTT broker, IIH Essentials is set up as an MQTT client.

Procedure

To set up a generic MQTT broker as a synchronization destination, follow these steps:

  1. Create a new data destination and select Generic MQTT Broker as the destination type.

    alt text

    Adding a generic MQTT broker as synchronization destination in IIH Essentials

  2. Enter the relevant information.

    • Name: Identifier for the synchronization destination. This name must be unique. It will be used for creating synchronization of entities or attributes.
    • MQTT Protocol: Which protocol should be used for establishing the connection to the broker.
      • TCP/MQTT: The broker's URL will be built using tcp://
      • SSL/TLS/MQTTS: The broker's URL will be built using ssl://
      • WebSocket: The broker's URL will be built using ws://
      • WebSocket Secure: The broker's URL will be built using wss://
    • MQTT Host: Host address of the MQTT broker to which the data should be sent.

    • MQTT Port: Port through which the MQTT broker will receive the data published from IIH Essentials.

      Note

      This port should be open in the proxy settings, in case that the application is running in an Industrial Edge Device.

    • MQTT Path: Which connection path should be appended to the broker's URL when connecting. For instance, /mqtt.

      Note

      That is an optional field and is only available when WebSocket or WebSocket Secure are chosen as MQTT protocols.

    • Message Publishing Interval in Seconds: How often the data of the attributes should be sent out. This interval will define the time span of an attribute contained within a single MQTT package. Since one MQTT package is sent out per attribute it is recommended to have relatively large message publish interval. Depending on the amount of values being synchronized, value ranges between 1-10 minutes would be beneficial.

    • QOS for Time Series Data: MQTT Quality of Service.

    • Maximum MQTT Packages per Second: Amount of single MQTT packages containing data of a single attribute that can be sent within a second. If the maximum quota is reached, it will waited until the next period of one second starts.
    • Maximum MQTT Package Size in KB: The maximum size of an MQTT package after the payload has been created based on the configuration file. This size includes the headers needed for MQTT as well. The maximum package size was set to 10 MB.

  3. Create the configuration file following the steps portrayed in Creating a configuration file, save it as a JSON file and upload it into IIH Essentials.

  4. Choose the desired authentication method to establish a connection with the MQTT broker.

    Please make sure to select the MQTT protocol (using the selector MQTT Protocol) that matches the authentication method chosen here and the configuration of the MQTT broker.

    Four authentication methods are supported:

    alt text

    Authentication methods of a generic MQTT broker as synchronization destination in IIH Essentials

    • No authentication: Neither username nor certificates will be used to establish the connection to the MQTT broker.
    • User Credentials: The given username and password will be used to connect to the MQTT broker.
    • Client Certificate: X.509 certificates based authentication will be used to connect to the MQTT broker.
    • User Credentials with Client Certificate: X.509 certificates based authentication will be combined with user credentials to connect to the MQTT broker.

  5. More advanced settings can be accessed by activating the Advanced Settings option.

    alt text

    Advanced settings of a generic MQTT broker as synchronization destination in IIH Essentials

    The advanced settings will always be used for establishing a connection to the MQTT broker. With the slider the user can decide whether he prefers to use the default values or specify them through the UI. The following default values are used then the slider is set to inactive:

    • Retained Flag for Time Series Data: Active
    • Clean Session Flag: Inactive
    • Keep Alive Interval: 60 seconds
    • MQTT Connection Timeout: 15 seconds
    • Last Will and Testament: Inactive. Therefore, the last will topic, last will message, QoS for last will message and the retained flag for last will message are left empty/inactive.

    When the advanced settings are active it is possible to leave some optional fields empty and fill out those of interest. The optional values that were left empty will be replaced by the default values that were portrayed above. Mandatory values are represented using an asterisk right after the property name.

  6. Enable the data destination.

  7. Click Save.

Result

The added MQTT broker is now available as a data destination and can be specified as the storage location.

alt text

Status of a Generic MQTT Broker as synchronization destination in IIH Essentials

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