---
title: "Collector MQTT"
slug: "collector-mqtt"
tags: ["DCM", "MQTT ", "Collector", "Data Collection Module"]
updated: 2024-12-17T08:53:39Z
published: 2024-12-17T08:53:39Z
canonical: "kb.secomea.com/collector-mqtt"
stale: true
---

> ## Documentation Index
> Fetch the complete documentation index at: https://kb.secomea.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Collector MQTT

The purpose of this article is to be a reference for the MQTT collector part of the full Data Collection Module documentation.

The MQTT collector can operate in two modes. Client mode; where it acts as a subscriber to an external MQTT broker, and broker mode; where it acts as broker which external publishers can publish to.

          *Note*:

          

Broker mode cannot be used as a general-purpose broker, it allows publishers to connect but does not allow subscriptions.

Example configuration can be found [here](/v1/docs/mqtt-collector-config)

## MQTT Collector main

The Collectors list (mandatory array of objects) contains the following fields

| Function | Type | Importance | Description |
| --- | --- | --- | --- |
| **CollectorName** | string | mandatory | Unique name (within this configuration file) of a device to collect data from. (This is the name used in the agent configuration.) Follows the normal rules for names. |
| **CollectorDescription** | string | optional | Description of this collector. (For your use, no system function). |
| **CollectorIPAddr** | string | optional | Default IP address (or DNS name) for the device to be polled. The agent Target IP address will take precedence over this. If **MQTTCollectorMode** is set to `broker`, this is ignored. |
| **CollectorPortno** | integer > 0 and < 65535 | optional | Default port number for the device to be polled. The agent Target Port number will take precedence over this. If neither **CollectorPortno** nor agent Target Port Number is specified, the appropriate port will be used, depending on the **Protocol** parameter value. If **MQTTCollectorMode** is set to `broker`, this is ignored. |
| **Alias** | string | optional | This is the **CollectorName** of another collector, from which all the parameters (except **CollectorName**, **CollectorDescription**, **CollectorIPAddr** and **CollectorPortno**) are copied. An alias cannot refer to another alias. |
| **Protocol** | string-enum | mandatory | The protocol used to collect data. Currently only `MQTT` is available. |
| **ConnectRetryMin** | integer > 0 | mandatory | The minimum number of seconds before trying to re-establish a connection to the device being sampled. An exponential backoff algorithm is used to retry connection establishment, starting after **ConnectRetryMin** and increasing to **ConnectRetryMax**. |
| **ConnectRetryMax** | integer > 0 | mandatory | The maximum number of seconds before trying to re-establish a connection to the device being sampled. |
| **MQTTAccess** | Object | mandatory | Collection of parameters needed to collect MQTT messages. |
| **SamplePoints** | Array of objects | mandatory | List of samples to be collected, possibly aggregated and stored in the Store and Forward database. |

## MQTT Access object

The **MQTTAccess** object contains the following elements:

| Function | Type | Importance | Description |
| --- | --- | --- | --- |
| **MQTTCollectorMode** | string-enum | mandatory | The collector mode. It can be either `client` or `broker`. |
| **MQTTBrokerConfig** | object | maybe-optional | The broker mode config object containing parameters needed to configure DCM to collect as a broker by allowing external clients/publishers to publish to DCM. Becomes mandatory when “**MQTTCollectorMode**” is set to `broker`. |
| **MQTTClientConfig** | object | maybe-optional | The client mode config object containing parameters needed to configure DCM to collect as a client/subscriber to an external broker. Becomes mandatory when “**MQTTCollectorMode**” is set to `client`. |

## **MQTTClientConfig** object

The **MQTTClientConfig** object contains the following elements:

| Function | Type | Importance | Description |
| --- | --- | --- | --- |
| **ClientId** | string | optional | *MQTT clientid* to use for the MQTT client. If not specified, a default *clientid* of `DCM` will be used. |
| **ClientProtocolVersion** | string-enum | optional | The MQTT protocol version (v3.1, v3.1.1 or v5.0) to use for the client connection. The possible values are: `MQTT_V31`, `MQTT_V311`, `MQTT_V5`. Default: `MQTT_V311`. |
| **ClientKeepAlive** | integer >= 5 and <= 600 | optional | Keep-alive interval to use for the client connection. |
| **ClientPasswordFile** | string | optional | Password file in the format `username:password`. One entry per line. |
| **ClientTLSMode** | string-enum | optional | The possible values are: `TLS-DISABLED`, `TLS-CERT`, `TLS-PSK`. |
| **ClientSSLSecure** | boolean | optional | Whether TLS certificates should be verified. Default: `true`. |
| **ClientCACertificate** | string | maybe-optional | Certificate of the CA who signs the broker to collect from. Required if **ClientTLSMode** is `TLS-CERT`. |
| **ClientCertificate** | string | maybe-optional | Certificate with public key to use for DCM as client. Required if **ClientTLSMode** is `TLS-CERT`. |
| **ClientPrivateKey** | string | maybe-optional | Private key to use for DCM as client. Required if **ClientTLSMode** is `TLS-CERT`. |
| **ClientPSKFile** | string | maybe-optional | File with pre-shared key in the format `identity:key`. Required if **ClientTLSMode** is `TLS-PSK`. |

## **MQTTBrokerConfig** object

The **MQTTBrokerConfig** object contains the following elements:

| Function | Type | Importance | Description |
| --- | --- | --- | --- |
| **BrokerIPAddr** | string | mandatory | The IP address on the SiteManager to bind the broker to. |
| **BrokerPortno** | integer | mandatory | Network portnumber to use for the broker. |
| **BrokerSourceFilteringMode** | string-enum | mandatory | The possible values are: `ALLOW-ANY`, `IP-WHITELIST`, `MAC-WHITELIST`. |
| **BrokerSourceFilteringFile** | string | maybe-optional | File with white-listed (allowed to connect) clients. Must be a list of either IPv4 or MAC addresses, one per line. Required if **BrokerSourceFilteringMode** is different from `ALLOW-ANY`. |
| **BrokerAuthenticationMode** | string-enum | mandatory | Select the authentication mode to use for the broker connection. The possible values are: `ALLOW-ANONYMOUS`, `PASSWORDFILE`. |
| **BrokerPasswordFile** | string | maybe-optional | Password file credentials in the format username:password - one line per. Required if **BrokerAuthenticationMode** is `PASSWORDFILE`. |
| **BrokerTLSMode** | string-enum | mandatory | Select the security type (if any) to use for the transport layer. The possible values are: `TLS-DISABLED`, `TLS-CERT`, `TLS-PSK`. |
| **BrokerSSLSecure** | boolean | optional | Whether TLS certificates should be verified (Default: `true`). |
| **BrokerCACertificate** | string | maybe-optional | Certificate of the CA who signs the clients which will be connecting to the broker. Required if **BrokerTLSMode** is `TLS-CERT`. |
| **BrokerCertificate** | string | maybe-optional | Certificate public key file. Required if **BrokerTLSMode** is `TLS-CERT`. |
| **BrokerPrivateKey** | string | maybe-optional | Private key file. Required if **BrokerTLSMode** is `TLS-CERT`. |
| **BrokerPSKHint** | string | maybe-optional | String to send to clients to aid in authentication. Required if **BrokerTLSMode** is `TLS-PSK`. |
| **BrokerPSKFile** | string | maybe-optional | File with pre-shared keys in the format `identity:key` - one identity per line. Required if **BrokerTLSMode** is `TLS-PSK`. |

## **Samplepoints** object

The **SamplePoints** objects contains the following elements:

| Function | Type | Importance | Description |
| --- | --- | --- | --- |
| **SampleName** | string | mandatory | Name of this sampled value (sometimes called a tagname). Follows the normal rules for names. |
| **SampleDescription** | string | optional | A text description of this sample value. |
| **SampleUnit** | string | optional | A description of the unit measurement for this sample. |
| **SampleGroup** | string | optional | Group affiliation. All sample points in the same group (in some datasrvs) should be handled (displayed) together. The DCM system itself places no meaning on this group affiliation. |
| **SamplesSaved** | integer > 0 | optional | Is the number of values collected that is saved in the Store and Forward database even after the values have been sent to all dataservers. When `0` is specified, the value can be used in aggregators, but nothing is sent via dataservers to cloud system. If left unspecified, values are only saved in the Store and Forward database until they have been delivered to all dataservers. |
| **OnlySaveOnChanged** | boolean | optional | Specifies if new sample values should be saved to the Store and Forward database only when the value is different from the last sample value. Default: `false`. |
| **ChangeLimit** | integer/double | optional | Used if **OnlySaveOnChanged** is `true`. Specifies an amount which a sample must be greater than, to count as a changed value. This is a simple hysteresis to filter out inaccurate (jitter) measurements. Default: `0` |
| **SampleDataType** | string-enum | mandatory | The type of data collected. The possible values are: `bool` (1 bit), `sbyte` (8 bit signed), `byte` (8 bit unsigned), `int16` (16 bit signed), `uint16` (16 bit unsigned), `int32` (32 signed), `uint32` (32 bit unsigned), `int64` (64 bit signed), `uint64` (64 bit unsigned), `float` (32 bit), `double` (64 bit), `string` (variable text up to 24575 bytes. Includes terminating NUL), `data` (variable data up to 24575 bytes). |
| **SampleMaxVDataSize** | integer > 0 and <= 24575 | optional | The max size of variable data allowed for this sample. This is only relevant for **SampleDataType** `string` or `data`. If not specified, the value is `1024`. |
| **SampleLowerLimit** | integer/double | optional | The lower limit for the collected data. If the collected data value is less than **SampleLowerLimit** it is evaluated in accordance with **SampleLimitDiscard** and **SampleLimitAlarm**. |
| **SampleUpperLimit** | integer/double | optional | The upper limit for the collected data. If the collected data value is more than **SampleUpperLimit** it is evaluated in accordance with **SampleLimitDiscard** and **SampleLimitAlarm**. |
| **SampleLimitDiscard** | boolean | maybe-optional | Specifies whether samples that violates the sample limit should be discarded. Mandatory if either **SampleLowerLimit** or **SampleUpperLimit** is present. |
| **SampleLimitAlarm** | boolean | maybe-optional | Specifies whether samples that violates the sample limits should generate an alarm. Mandatory if either **SampleLowerLimit** or **SampleUpperLimit** is present. |
| **MQTTSample** | object | mandatory | Specification of the MQTT topic containing this sample value. |

## *MQTTSample* object

The **MQTTSample** object contains the following elements:

| Function | Type | Importance | Description |
| --- | --- | --- | --- |
| **TopicString** | string | mandatory | The MQTT topic to subscribe to. Wildcards ('#', '+') are not allowed. |
| **TopicSubscribeQos** | string-enum | optional | QoS (Quality of Service) to use when subscribing to this topic. Possible values are `qos0`, `qos1`, and `qos2`. |
| **PayloadEndianness** | string-enum | optional | Endianness to use when interpreting binary data in message payload. The possible values are: `big` and `little`. If not specified the default value `big`, corresponding to network byte order, is assumed. |
| **NumberAsString** | boolean | optional | Indicate if numeric data is formatted as a string in the payload - use with appropriate **SampleDataType** to get correct conversion. |
| **PayloadJSONPath** | string | optional | Path to extract sample point from if topic data is a *JSON* string. |
| **PayloadXMLPath** | string | optional | Path to extract sample point from if topic data is an *XML* string. |