Plugin: MQTT Client (GInsMQTTPlugin)

The GInsMQTTPlugin is a controller plugin for enabling edge-to-cloud connectivity using the MQTT protocol.

Introduction

MQTT (Message Queuing Telemetry Transport) is a lightweight, publish-subscribe protocol designed for machine-to-machine communication, ideal for remote condition monitoring in low-bandwidth environments.

With the Gantner Instruments MQTT plugin, the following features are supported:

• Connection to one or more MQTT brokers
• Authentication via username/password and TLS encryption with X.509 certificates
• Publishing variables to a topic as plain text (single variable) or JSON (multiple variables), triggered continuously, periodically, or on value change
• Subscribing to a topic, extracting values from incoming messages, and writing them to controller setpoint variables

Minimum System Requirements

The minimum system requirements for this plugin are:

• Q.station 101 / Q.station X / Q.monixx
• Q.station firmware V2.17.3
• Q.monixx firmware V1.8.3

Plugin Installation

• Download the correct plugin version that matches the controller firmware version from the Gantner public download area.
• For installation instructions please refer to the page: installing a plugin.

General Workflow for Configuring the Plugin

1. The plugin includes a configuration web interface. To access it, open a web browser and enter the following URL: http://[ipaddress]:8090/GInsMQTTPlugin, where [ipaddress] represents the IP address of the controller.

   

2. By default, a single connection is preconfigured with default settings. To establish a connection, enter the Address and Port of the MQTT broker, then click Save. The plugin will attempt to connect to the broker. If successful, the 'Connected to broker' indicator will turn green.

   Other settings like authentication, TLS, last will, and publishing config are optional settings depending on the application and broker requirements.

   To add multiple broker connections, refer to the section Managing connections to an MQTT broker.

   👉 Note: The connection is automatically active when the controller starts, there is no manual start or stop option. If you do not want the controller to connect to a broker immediately, it is recommended to leave the Address field blank.

3. Next, configure the data mapping for publishing and/or subscribing. The MQTT plugin reads data for publishing from the circular buffer and writes subscribed data to the controller’s virtual variables (type: Setpoint), which must be created beforehand.

   For detailed information on how to configure the mapping, refer to either section Publishing options or Subscribing options. When the mapping has been configured, click Save to apply the settings to the current connection.

Managing MQTT Broker Connections

The plugin supports communication with multiple brokers via independent worker threads. Each broker requires a separate connection configuration, including connection details, TLS authentication settings, and mappings for publish and subscribe variables.

• Save: Saves the connection and mapping configuration for the selected connection.

• Append connection: Adds a connection to the configuration with default settings.

• Delete connection: Deletes the selected connection from the configuration.
• Set default: Resets the complete plugin to its default settings, deleting all connections.

Configuring an MQTT Connection

Broker

Authentication

Password-based authentication allows the broker to verify a client's credentials (username and password). This optional method depends on the broker’s configuration and security settings.

• Username: Optional username required for client authentication by the broker. 
• Password: Optional password required for client authentication by the broker. 

Last will

The Last Will is an MQTT feature that lets a client specify a message the broker will automatically publish if the client disconnects unexpectedly. This enhances reliability by notifying other clients and maintaining consistent topic states.

• Enable: Set the last will feature ON or OFF for this connection.
• Set retain: If the retained flag is set to true, the broker stores the Last Will message and its associated QoS level for the topic. This ensures that newly connected clients receive the message immediately upon subscribing.
• Message: Text that will be published in the controller's last will message.
• Topic: Topic of which its subscribers will be informed of the last will message.
• QoS: Quality of Service level for the last will message.

Transport Layer Security (TLS)

TLS establishes a secure, encrypted communication channel between the client and broker. The broker provides an X.509 certificate (commonly known as a CA certificate with a *.crt extension), which must be installed on the controller to authenticate the broker's identity.

• Enable: Set TLS communication ON or OFF for this connection.
• Insecure: This connection option can be useful for testing, as it disables hostname verification against the certificate. However, it should be used with caution, as it increases the risk of man-in-the-middle attacks.
• Content CA: Input field for the CA certificate (the content of the certificate file without "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----"). Alternatively, the CA certificate can be uploaded directly to the controller using FTP.
• Path CA file: The directory path on the controller where the CA certificate is stored. The default path is /gins/fs/config/plugins/GInsMQTTPlugin/ca.crt.
  

Publish config

Global settings for publishing data.

• Max values per message (history):  This setting limits the maximum number of samples per message when using the 'publish history value' option. It is especially useful when the broker was temporarily unavailable, allowing the controller to store additional historical data for later publication.
• Min values per message (history): This parameter determines the frequency of message publication based on the sample rate of the variables when using the 'publish history value' option.
• Timer condition variable: When periodic publishing is selected for online values, a message will be published whenever the variable exceeds 0.5.
• Timer interval (ms): The time duration in milliseconds for publishing a message at fixed intervals when periodic publishing of online values is enabled.

Publishing Options for MQTT

Publish online value

Using the 'publish online value' option, the current value of a variable is published using one of the following publishing modes:

1. Periodically: Messages are published at fixed time intervals using the Timer interval (ms) setting or at random intervals using the Timer condition variable.
2. On Change: Messages are published each time a value has changed.
3. Continuous Data Transfer: Messages are published as quickly as possible. The publish rate (messages per second) depends heavily on the number of variables, as well as network speed and broker capacity.

By default, the message contains a variable list in JSON format without a timestamp. The timestamp can be included as a separate variable in the message.

{
    "VariableName_1":54.014,
    "VariableName_2":42
}

Publish history value

Enabling the Publish History Value feature stores data in a buffer on the controller and continuously publishes it from there. The number of samples per message depends on the variable's sample rate and the Min. values per message (history) setting.

For example, if a variable is sampled at 1 Hz and the minimum values per message is set to 10, a message will be published every 10 seconds, containing 10 values.

If the MQTT connection is temporarily unavailable, data continues to be buffered on the controller. Once the connection is restored, the buffered data is published based on the Max. values per message (history) setting.

The message contains a variable list as JSON structure. The timestamp is in nanoseconds since 01/01/2000.

{
"FirstTimestamp":728059579000000136,
"Timestamp":[
  728059579000000136,
  728059579100000139,
  728059579200000135,
  728059579300000129,
  728059579400000144
],
"VirtualVars_1":[ 5, 2, 7, 5, 3 ]
}

Quality of Service (QoS)

QoS is indicated by a number that ranges from 0 to 2. Each level provides a different level of reliability and assurance for message delivery.

• QoS 0 (at most once): This level provides no guarantee that a message will be delivered. The message is sent once, and if it is lost or not received by the recipient, it will not be resent.
• QoS 1 (at least once): This level ensures that a message is delivered at least once, but it may be delivered multiple times in the case of network issues or failures.
• QoS 2 (exactly once): This level provides the highest assurance for message delivery. The message is guaranteed to be delivered exactly once, but it requires more communication between the client and broker, potentially increasing latency and network traffic.

Additional settings

• Set retain: If the retained flag is set to true, the broker stores the last retained message and its corresponding QoS for the topic. Retained messages ensure that newly connected clients receive the message immediately, without the need for extended waiting periods.

• Publish metadata: Publishes a retained message with general information to Topic/MetaData.

• Publish as pure value: The variable is published as a plain text value, not as a JSON structure (this option is available only with 'publish online value').

Subscribing Options for MQTT

Subscribe from a JSON

To extract the numeric value, the path of the desired element in the JSON must be specified. This path can be built using "/" for sub-members and "%[0-9]" for array elements. For example, consider the following JSON:

{  
   "store":{     
      "book":[  
         {  
            "category":"reference",
            "author":"Nigel Rees",
            "title":"Sayings of the Century",
            "price":8.95
         },
         {
            "category":"fiction",
            "author":"J. R. R. Tolkien",
            "title":"The Lord of the Rings",
            "isbn":"0-395-19395-8",
            "price":22.99
         }
      ]
   }
}

The path to the price of "The Lord of the Rings" would be:

store/book/%1/price