---
title: MQTT collector
slug: mqtt-collector
createdAt: 2025-09-09T09:41:42.339Z
---

## 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
**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 when it reconnects. **So the broker is responsible for caching the messages until the collector is active again**
**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, include the **client certificate** and **private key**.

:::hint{type="info"}
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      |

:::hint{type="info"}
**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](https://www.hivemq.com/blog/mqtt-essentials-part-5-mqtt-topics-best-practices/)



## MQTT messages

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

- JSON messages: see [JSON Settings](docId:89vbWhADQ2gvKMd1bkunK) 
- Sparkplug B messages: see [Sparkplug B Settings](docId\:EgYMCokl3xBS8JPSS-dD2)