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): Defines the maximum number of historical samples included in a single MQTT message when using Publish History Value. This is particularly useful after a temporary broker connection loss, when accumulated historical data must be published after the connection is restored.

• Min Values per Message (History): Defines the minimum number of historical samples collected before an MQTT message is published when using Publish History Value. Together with the variable sample rate, this determines the effective publishing frequency.

• Timer Condition Variable: When periodic publishing of online values is enabled, a message is published when the specified variable has a value greater than 0.5.

• Timer Interval (ms): Defines the time interval, in milliseconds, between MQTT messages when periodic publishing of online values is enabled.

Publishing Measurement Data via MQTT

Publishing Real-Time Measurement Data

Using the Publish Online Value option, the latest value of a variable can be published using one of the following modes:

• Periodically: Publishes messages at fixed intervals defined by Timer Interval (ms), or conditionally when the Timer Condition Variable exceeds the configured threshold.

• On Change: Publishes a message whenever the value of a configured variable changes.

• Continuous Data Transfer: Publishes messages as quickly as possible. The achievable publishing rate depends on factors such as the number of variables, network performance, and MQTT broker capacity.

By default, multiple variables are published as a JSON-formatted variable list without a timestamp. If required, a timestamp can be added as a separate variable to the published message.

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

Publishing Historical Measurement Data

Enabling Publish History Value stores measurement data in a buffer on the controller and publishes the buffered data continuously to the MQTT broker. The number of samples included in each message is determined by the variable’s sample rate and the Min. Values per Message (History) setting.

For example, if a variable is sampled at 1 Hz and Min. Values per Message (History) is set to 10, an MQTT message is published every 10 seconds containing 10 samples.

If the MQTT connection is temporarily unavailable, measurement data continues to be stored in the controller buffer. Once the connection is restored, the accumulated data is published in batches, with the maximum number of samples per message determined by the Max. Values per Message (History) setting.

The message contains the variable data as a JSON-formatted list. Each sample includes a timestamp expressed in nanoseconds since 1 January 2000.

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

MQTT Quality of Service (QoS 0, 1 and 2)

Quality of Service (QoS) defines the level of assurance for MQTT message delivery and can be set from 0 to 2:

• QoS 0 - At most once: The message is sent once without acknowledgement. Delivery is not guaranteed, and lost messages are not retransmitted.

• QoS 1 - At least once: The message is delivered at least once. Retransmission may occur if an acknowledgement is not received, which can result in duplicate messages.

• QoS 2 – Exactly once: The message is delivered exactly once using an additional acknowledgement process. This provides the highest delivery assurance but requires more communication between the client and broker, increasing protocol overhead and potentially latency.

MQTT Retained Messages, Metadata and Payload Settings

• Set Retain: When enabled, the broker stores the most recently retained message and its associated QoS level for the topic. New subscribers receive the retained message immediately upon subscribing.
• Publish Metadata: Publishes general variable information as a retained message to Topic/MetaData.
• Publish as Pure Value: Publishes the variable value as plain text instead of a JSON structure. This option is available only when using Publish Online Value.

Subscribing to MQTT Data with Q.station

Extracting Values from MQTT JSON Messages

To extract a numeric value from an incoming JSON message, specify the path to the required JSON element. Use “/” to navigate through nested members and “%[0-9]” to select an array element. For example, consider the following JSON structure:

{  
   "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