MQTT collector

Basic settings

The collector settings are used to connect to the MQTT broker.

MqttURL

Description: The connection URL for the MQTT broker. Required: yes Example: tcp://localhost:1883

ClientCertificate

Description: Use a client certificate. This is a toggle, not a place to paste a certificate: when enabled the collector reads cert.pem and key.pem from the certificates directory under its base path, and generates a self-signed pair there if either file is missing. Required: no Default: false Options: false | true

Username

Description: Username Required: no

Password

Description: Password Required: no

Topics

Description: Comma separated list of topics to subscribe to. (Wildcards are allowed) Required: yes

QOS

Description: QOS with which to subscribe. Required: yes Default: 1 Options: 0 | 1 | 2

KeepAliveSecs

Description: The keep alive period in seconds, before which the client sends a ping to the mqtt broker (default is 30 seconds). On no response received, the connection is closed. Required: no Default: 30

PersistentSession

Description: If the session is persistent, the broker will store the session information and deliver messages to the client while it is disconnected. Required: no Default: false

A persistent session survives a crash, a network drop or a restart, but not a pause. Pausing the collector clears its session on the broker, which discards everything queued for it, and resuming clears it again before reconnecting. Do not pause a collector expecting the broker to hold its data.

Advanced settings

CACertificate

Description: PEM encoded CA certificate or chain used to verify the broker's TLS certificate. Paste the full certificate, including the BEGIN and END CERTIFICATE lines. Leave empty to use the system trust store. Required: no

InsecureSkipVerify

Description: When enabled, the broker's TLS certificate is not verified. Only use this for testing, or with a broker whose certificate is not RFC 5280 compliant. Required: no Default: false

PingTimeout

Description: The time in seconds to wait for a response to a ping before the connection is regarded as lost. Required: no Default: 30

WriteTimeout

Description: The time in seconds a publish may take before it returns a timeout error. 0 means it never times out. Required: no Default: 0

ConnectionTimeout

Description: The time in seconds to wait when opening a connection to the broker. Required: no Default: 30

MaxReconnectInterval

Description: The maximum time in minutes to wait between reconnection attempts after a disconnection. Required: no Default: 10

ConnectRetryInterval

Description: The time in seconds to wait between attempts while initially connecting. Required: no Default: 30

HandleMessagesAsync

Description: When enabled, incoming messages are handled asynchronously. Required: no Default: true

Configuration

This guide provides comprehensive instructions for setting up and configuring the MQTT collector for Factry Historian. It includes installation steps, connection setup, and best practices for secure and reliable data transmission.

Collector Installation

To install the MQTT collector, follow the steps outlined in the Collector Installation Guide .

Connecting the MQTT Collector to a Broker

To connect the MQTT collector to your broker, ensure the following configurations are properly set up:

Authentication

Provide the username and password required for broker authentication.

Secure Communication (TLS)

Use a CA certificate to validate the broker’s identity.

For mutual TLS, enable ClientCertificate and place cert.pem and key.pem in the certificates directory under the collector's base path. If either file is missing the collector generates a self-signed pair, which the broker has to trust.

While TLS is optional, it is highly recommended for secure environments to ensure encrypted communication and prevent unauthorized access.

Quality of Service (QoS)

MQTT supports three levels of Quality of Service (QoS), each offering different guarantees for message delivery:

Level	Description	Guarantee	Use Case
QoS 0	At most once	No guarantee of delivery	Non-critical data
QoS 1	At least once	Message delivered at least once (may duplicate)	Recommended for most industrial use
QoS 2	Exactly once	Message delivered exactly once	Critical data, higher overhead

Recommendation: Use QoS 1 or QoS 2 to ensure reliable delivery of measurement data.

Topics

MQTT topics are used to route messages. The collector subscribes to specific topics to receive data.

Topics act as filters: the collector only processes messages from subscribed topics.

Measurement configurations can only extract data from these subscribed topics.

Wildcards in Topics

MQTT supports wildcards for flexible topic subscriptions:

Single-Level Wildcard: +

Matches exactly one level of a topic.

Example: factory/+/temperature matches:

factory/machine1/temperature

factory/machine2/temperature

Multi-Level Wildcard: #

Matches multiple levels (including zero) and must be the last character in the topic.

Example: factory/# matches:

factory/machine1

factory/machine1/temperature

factory/machine2/status/online

For more information and best practices, refer to: MQTT Topics Best Practices – HiveMQ

MQTT messages

There are multiple types of messages that can be processed via MQTT:

JSON messages: see JSON Settings

Sparkplug B messages: see Sparkplug B Settings