MQTT Connector

• Overview
• Configuration Modes
• General Settings
• Connection Settings
  • Connection to Broker
  • Security
    • Anonymous
    • Basic
    • Certificates
• Data Mapping
  • Data Conversion
  • Attributes and Time Series
• Requests Mapping
  • Connect Request
  • Disconnect Request
  • Attribute Requests
  • Attribute Updates
  • Server Side RPC Commands
• Additional Information
  • Wildcard Usage
  • Converter Types
• Next Steps

Overview

This documentation will help you set up the MQTT connector for the IndustryOS IoT Gateway. We’ll explain the configuration parameters in simple terms to make it easy for you to understand and follow. The MQTT (Message Queuing Telemetry Transport) is a lightweight publish-subscribe, machine-to-machine network protocol that is widely used for connections with remote locations with devices that have resource constraints or network transfer rate.

The connector can be configured via the user interface form, which helps you set up a connection to an MQTT broker and read/write data by subscribing/publishing to MQTT topics, that can be defined statically or generated on the fly.

Configuration Modes

The MQTT connector can be configured in two modes: Basic and Advanced.

• Basic mode is designed for users who are new to IndustryOS IoT Gateway and want to quickly set up the connector with minimal configuration. It provides a simplified interface with essential settings.
• Advanced mode is intended for experienced users who need more control over the configuration. It offers additional options and flexibility for advanced use cases.

If you are new to IoT Gateway, use the “Basic” configuration mode. If you are familiar with configuring IoT Gateway, you can use the “Advanced” configuration mode.

General Settings

This configuration section contains general connector settings:

• Name - connector name used for logs and saving to persistent devices
• Logs configuration - settings for local and remote logging:
  • Enable remote logging - enables remote logging for the connector
  • Logging level - logging level for local and remote logs: NONE, ERROR, CRITICAL, WARNING, INFO, DEBUG, TRACE
• Report strategy - strategy for sending data to IndustryOS:
  • Report period - period for sending data to IndustryOS in milliseconds
  • Type - type of the report strategy:
    • On report period - sends data to IndustryOS after the report period
    • On value change - sends data to IndustryOS when the value changes
    • On value change or report period - sends data to IndustryOS when the value changes or after the report period
    • On received - sends data to IndustryOS after receiving data from the device (default strategy)

Additional information about the report strategy can be found in the Report Strategy documentation.

Connection Settings

Connection to Broker

This subsection specifies the target MQTT broker and how the gateway interacts with it. It includes the broker’s host, port, MQTT version protocol and client ID.

Configuration parameters:

• Host - MQTT broker hostname or IP address
• Port - listening port on the MQTT broker that will be used for establishing connection
• MQTT version - MQTT protocol version (3.1, 3.11, or 5)
• Client ID - Unique identifier for each client’s session on the broker
• Security - configuration for client authorisation at MQTT Broker (anonymous, basic, or certificates)

Note: The broker (or broker cluster) does not allow two simultaneous sessions with the same Client ID. If a second connection uses that ID, the broker closes the existing session and accepts the new one (session takeover).

Security

MQTT broker connections offer three distinct security types:

Anonymous

Anonymous is the simplest option: no credentials are required to publish/subscribe on the MQTT broker. It can be useful for testing (e.g., public test brokers), but not recommended for production because it allows unattended access.

Basic

Basic authentication option uses a username and password configured on the MQTT broker. It’s a good default for most setups - just use strong, unique credentials.

Configuration parameters:

• Username - username for establishing connection with MQTT broker
• Password - password for establishing connection with MQTT broker

Certificates

Certificate-based authentication uses TLS certificates so the gateway and broker verify each other. The safest authentication mode, requiring the broker’s TLS port (typically 8883) for encrypted, production-grade security.

Configuration parameters:

• Path to CA Certificate - path to your CA certificate
• Path to Private Key - path to the private key
• Path to Client Certificate - path to the certificate that identifies the gateway to the MQTT broker

Data Mapping

Data Mapping lets you configure the topic/topics the gateway subscribes to for device creation and incoming data handling. You can generate topic/topics and device names on the fly, and choose what data is sent as device attributes or telemetry.

Configuration parameters:

• Topic filter - the topic/topics the gateway will subscribe to for data feed. Supports wildcards: ‘#’ and ‘+’
• QoS - MQTT Quality of Service (0-At most once, 1-At least once, 2-Exactly once)
• Payload type - the incoming data type (JSON, Bytes, Custom)

Data Conversion

• Device Name - the name of the device in IndustryOS. Can be parsed from Message, Topic, or Constant
• Device Profile name - the device profile in IndustryOS. Can be parsed from Message, Topic, or Constant

Attributes and Time Series

Configuration parameters for device data:

• Key - the key of the attribute/time series in IndustryOS
• Type - the type of attribute/time series field (string, boolean, integer, double, or Raw)
• Value - the value that will be sent to the platform device

Each time series or attribute can have a specific report strategy configured.

Requests Mapping

The Requests mapping section allows you to configure how the IndustryOS platform instance will interact with the devices.

Connect Request

Connect request is used for sending a message to the Gateway indicating that a device has connected, so the device can be marked as online on the platform.

Disconnect Request

Disconnect request is used for sending a message to the Gateway indicating that a device has disconnected, so the device can be marked as offline on the platform.

Attribute Requests

Attribute requests are used for requesting the values of client-side or shared attributes from IndustryOS via the Gateway.

Attribute Updates

Attribute updates are used for provisioning or updating client-side or shared attributes on IndustryOS through the Gateway. You can treat this as a remote configuration for devices.

Server Side RPC Commands

Server side RPC commands are used for delivering remote procedure call (RPC) commands from IndustryOS to a device connected via the Gateway. RPC commands can be:

• Two Way - expects response from a topic
• One Way - does not expect response from a topic

Additional Information

Wildcard Usage

Wildcards let the gateway subscribe to many topics with one pattern:

• # wildcard - matches this level and all following levels. Put it only at the end.
  • Example: sensor/data/# matches sensor/data/room1, sensor/data/room1/temp
• + wildcard - matches exactly one level, may be used anywhere at the topic level.
  • Example: sensor/+/data matches sensor/A/data, sensor/B/data

Converter Types

• JSON - use for JSON formatted data
• BYTES - use for sequence of bytes
• CUSTOM - use for custom formats; implement your own converter

Next Steps

Explore guides related to main IndustryOS features:

• Data Visualisation - how to visualise collected data
• Device attributes - how to use device attributes
• Telemetry data collection - how to collect telemetry data
• Using RPC capabilities - how to send commands to/from devices
• Pipeline - how to use pipeline to analyse data from devices