GInsMQTTPlugin: MQTT Integration with Gantner controller

What is MQTT?

MQTT (Message Queuing Telemetry Transport) is a lightweight messaging protocol designed for reliable data exchange between connected devices, sensors, cloud platforms, and IoT applications. Using a publish/subscribe model, MQTT enables efficient real-time communication with minimal bandwidth and power consumption, making it ideal for IoT, industrial monitoring, remote sensing, and machine-to-machine communication.

MQTT Data Acquisition with GInsMQTTPlugin 

The Gantner Instruments MQTT Plugin provides MQTT communication between a Q.series controller and one or more MQTT brokers. The plugin supports:

• Multiple broker connections – Connect to one or more MQTT brokers simultaneously.

• Secure communication – Authenticate using a username and password and secure connections using TLS encryption with X.509 certificates.

• Publishing measurement data – Publish a single variable as plain text or multiple variables as a JSON message.

• Flexible publishing triggers – Publish data continuously, periodically, or when a value changes.

• Subscribing to MQTT topics – Subscribe to topics and receive data from external MQTT clients.

• Writing received data to the controller – Extract values from incoming MQTT messages and write them to controller setpoint variables.

GInsMQTTPlugin 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

Installing the GInsMQTTPlugin

For installation instructions please refer to the page: installing a plugin.

 Configuring the GInsMQTTPlugin: General Workflow

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 Multiple MQTT Broker Connections

The plugin supports simultaneous communication with multiple MQTT brokers, with each broker connection handled independently. Each broker requires a separate configuration containing the connection parameters, TLS and authentication settings, and variable mappings for publishing and subscribing.

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

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

• Delete Connection: Removes the selected connection from the plugin configuration.

• Set Default: Resets the entire plugin configuration to its default settings and deletes all configured connections.

Configuring an MQTT Broker Connection

MQTT Broker and Client Settings

MQTT Broker Authentication

Username/password authentication allows the MQTT broker to verify the client’s credentials before establishing a connection. This authentication method is optional and must be supported and enabled in the broker’s security configuration.

• Username: Optional username used to authenticate the client with the MQTT broker.
• Password: Optional password used to authenticate the client with the MQTT broker.

MQTT Last Will and Testament (LWT)

The Last Will is an MQTT feature that allows the broker to automatically publish a predefined message if the client disconnects unexpectedly, enabling other clients to detect the connection loss and maintain consistent topic states.

• Enable: Enables or disables the Last Will feature for the selected connection.

• Set retain: When enabled, the broker stores the Last Will message and its associated QoS level as the retained message for the topic. New clients subscribing to the topic will immediately receive the retained message.

• Message: The text that the broker publishes as the controller’s Last Will message if the connection is lost unexpectedly.

• Topic: The MQTT topic to which the Last Will message is published, allowing subscribers to be notified if the controller disconnects unexpectedly.

• QoS: The Quality of Service level used when publishing the Last Will message. 

MQTT Security with TLS and X.509 Certificates

TLS establishes a secure, encrypted communication channel between the controller and the MQTT broker. The broker presents an X.509 certificate, which the controller validates against a trusted CA certificate (typically a .crt file) installed on the controller to verify the broker’s identity.

• Enable: Enables or disables TLS-secured communication for the selected MQTT connection.

• Insecure: Disables verification of the broker’s hostname against its TLS certificate. This option can be useful for testing and troubleshooting, but should not be used in production environments because it reduces connection security and increases the risk of man-in-the-middle attacks.

• Content CA: Enter the content of the CA certificate, excluding the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines. Alternatively, the CA certificate file can be uploaded directly to the controller via FTP.

• Path CA file: The file path on the controller where the CA certificate is stored. The default path is /gins/fs/config/plugins/GInsMQTTPlugin/ca.crt.
  

MQTT Publishing Configuration

Global settings that define how data is published to the MQTT broker.

• 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 latest value of a variable can be 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