Plugin: MQTT Client (GInsMQTTPlugin)

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

Introduction

MQTT (MQ Telemetry Transport) is a publish-subscribe, machine-to-machine communication protocol primarily developed to fulfill the requirements of the Internet of Things. Designed as an extremely lightweight publish/subscribe message protocol, MQTT is ideal for scenarios requiring remote condition monitoring with minimal data bandwidth.

With the Gantner Instruments MQTT plugin, the following functions are available:

• Connection to one or more brokers.
• Authentication with username/password and TLS encryption with X.509 certificate.
• Publishing one or more variables to a topic as plain text for a single variable or as a JSON structure for a list of variables. Messages can be sent continuously, periodically, or on value change.
• Subscribing to a topic on the broker, extracting the value from the message, and writing it into a controller setpoint variable.

Minimum system requirements

The minimum system requirements for this plugin are:

• Q.station 101 / Q.station X / Q.monixx
• Q.station firmware V2.16.0
• Q.monixx firmware V1.9.0

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. To access the web interface, open a web browser and enter http://[ipaddress]:8090/GInsMQTTPlugin, where [ipaddress] represents the IP address of the controller.
   
   
   
   

2. By default, one connection is provided with default settings. Enter the Address and Port of the MQTT broker and click Save. The plugin will now try to establish a connection to the broker. If successful, the 'Connected to broker' LED 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'.

   👉 Please be aware that the connection is always active when the controller is started. There is no manual start or stop option for the connection. If you do not want to connect to a broker immediately, it is recommended to leave the address field blank.

3. Next, configure the mapping for publishin and/or subscribing data. The MQTT plugin can read and write data to the controller's virtual variables.

   The controller virtual variables must be created first before configuring the plugin. The virtual variables should be configured as Setpoint and the Data direction should be Input to publish data or Output for subscribing to data.

   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 connections to an MQTT broker

The plugin supports communication with multiple brokers by using workers in independent threads. A connection must be configured for each broker with the required information. This information includes the connection and TLS authorization settings, as well as the mapping of 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 a connection

Broker

• Address: The address of the MQTT broker, either an IP address or URL.

• Port: The port number for communication with the MQTT broker. The two most commonly used ports are 1883 and 8883. Port 1883 is the default unencrypted port for MQTT and is usually used for communication over a local network or a secure network, such as a VPN. Port 8883 is exclusively reserved for MQTT over TLS.

• Client ID: A unique identification for the controller (client). Every MQTT connection needs a unique client ID. With this unique client ID, the broker can recognize when a client reconnects and can close an old, potentially half-open TCP connection for the client.

• Keep alive time: Defines a time interval in seconds (default = 60s) during which a client shall notify a broker that the connection is alive by sending a PINGREQ message. If the client is not sending a message, the broker becomes attentive to it and disconnects the client after another half of the specified interval. In this case, other clients connected to the broker will receive the last will message if this was enabled when establishing the connection.

Authentication

Authentication based on passwords enables the broker to validate that the client possesses accurate connection credentials, including a username, client ID, and password. The broker has the flexibility to verify either the username or client ID against the provided password. Password-based authentication is optional and depends on the broker's requirements.

• 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 a powerful functionality in MQTT, enabling a client to define a message automatically published by the broker in the event of an unexpected disconnection. It provides a reliable means of communication and ensures that clients can gracefully handle disconnections without leaving topics in an inconsistent state.

• 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 the corresponding QoS for that topic. A retained message guarantees that newly connected clients receive the last will message instantly.
• 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 and encrypted communication channel between the client and broker. The broker issues an X.509 certificate, commonly referred to as a CA certificate (*.crt), which needs to be installed on the controller to validate the identity of the broker.

• Enable: Set TLS communication ON or OFF for this connection.
• Insecure: This option in the connection can be useful for testing the system. In this case, the hostname of the broker is not compared to the name in the certificate. However, it's important to note that this setting opens the possibility of man-in-the-middle attacks and should, therefore, be used with caution.
• 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 restricts the maximum number of samples per message when using the 'publish history value' option. This is particularly useful, for instance, when the broker was temporarily unavailable, and additional historical data is stored on the controller for later publication.
• Min values per message (history): This parameter, depending on the sample rate of the variables, determines the frequency at which messages are published when using the 'publish history value' option.
• Timer condition variable: In the case of choosing periodic publishing for online values, a message will be published whenever this variable exceeds 0.5.
• Timer interval (ms): The time duration in milliseconds for publishing a message at a fixed interval when periodic publishing of online values is selected.

Publishing options

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 fast as possible. The publish rate (messages/second) strongly depends on the number of variables. Furthermore, network speed and broker capacity impact the publish rate.

By default, the message contains a variable list as a JSON structure without a timestamp. The timestamp can be added to the message as a separate variable.

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

Publish history value

By opting for the 'publish history value' feature, data is stored in a buffer on the controller and subsequently published continually from that buffer. The number of samples per message depends on the sample rate setting of that variable and the Min values per message (history). 

Example: If a variable is sampled with 1 Hz on the controller, and the minimal values per message are set to 10, then a message will be published every 10 seconds containing 10 values.

In case the connection to MQTT is temporarily not available, measurement data will be buffered on the controller. Once the connection is available again, buffered data will be published using 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 level of assurance for message delivery. The message is guaranteed to be delivered exactly once, but this level requires more communication between the client and broker, which can increase latency and network traffic.

Additional settings

• Set retain: If the retained flag is set to true, the broker stores the last retained message and the corresponding QoS for that topic. Retained messages guarantee that newly connected clients receive messages instantly, eliminating 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

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