Collector MQTT
  • 26 Sep 2024
  • 7 Minutes to read
  • Contributors
  • Dark
    Light
  • PDF

Collector MQTT

  • Dark
    Light
  • PDF

Article summary

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

MQTT Collector main

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

FunctionTypeImportanceDescription
CollectorNamestringmandatoryUnique 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.
CollectorDescriptionstringoptionalDescription of this collector. (For your use, no system function).
CollectorIPAddrstringoptionalDefault 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.
CollectorPortnointeger >0 and <65535optionalDefault 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.
AliasstringoptionalThis 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.
Protocolstring-enummandatoryThe protocol used to collect data. Currently only MQTT is available.
ConnectRetryMininteger >0mandatoryThe 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.
ConnectRetryMaxinteger >0mandatoryThe maximum number of seconds before trying to re-establish a connection to the device being sampled.
MQTTAccessObjectmandatoryCollection of parameters needed to collect MQTT messages.
SamplePointsArray of objectsmandatoryList of samples to be collected, possibly aggregated and stored in the Store'n'Forward database.

MQTT Access object

The MQTTAccess object contains the following elements:

FunctionTypeImportanceDescription
MQTTCollectorModestring-enummandatoryThe collector mode. It can be either client or broker.
MQTTBrokerConfigobjectmaybe-optionalThe 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.
MQTTClientConfigobjectmaybe-optionalThe 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:

FunctionTypeImportanceDescription
ClientIdstringoptionalMQTT clientid to use for the MQTT client. If not specified, a default clientid of DCM will be used.
ClientProtocolVersionstring-enumoptionalThe 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
ClientKeepAliveinteger >= 5 and <= 600optionalKeep-alive interval to use for the client connection.
ClientPasswordFilestringoptionalPassword file in the format username:password. One entry per line.
ClientTLSModestring-enumoptionalThe possible values are: TLS-DISABLED, TLS-CERT, TLS-PSK.
ClientSSLSecurebooleanoptionalWhether TLS certificates should be verified. Default: true.
ClientCACertificatestringmaybe-optionalCertificate of the CA who signs the broker to collect from. Required if ClientTLSMode is TLS-CERT.
ClientCertificatestringmaybe-optionalCertificate with public key to use for DCM as client. Required if ClientTLSMode is TLS-CERT.
ClientPrivateKeystringmaybe-optionalPrivate key to use for DCM as client. Required if ClientTLSMode is TLS-CERT.
ClientPSKFilestringmaybe-optionalFile with pre-shared key in the format identity:key. Required if ClientTLSMode is TLS-PSK.

MQTTBrokerConfig object

The MQTTBrokerConfig object contains the following elements:

FunctionTypeImportanceDescription
BrokerIPAddrstringmandatoryThe IP address on the SiteManager to bind the broker to.
BrokerPortnointegermandatoryNetwork portnumber to use for the broker.
BrokerSourceFilteringModestring-enummandatoryThe possible values are: ALLOW-ANY, IP-WHITELIST, MAC-WHITELIST.
BrokerSourceFilteringFilestringmaybe-optionalFile 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.
BrokerAuthenticationModestring-enummandatorySelect the authentication mode to use for the broker connection. The possible values are: ALLOW-ANONYMOUS, PASSWORDFILE.
BrokerPasswordFilestringmaybe-optionalPassword file credentials in the format username:password - one line per. Required if BrokerAuthenticationMode is PASSWORDFILE.
BrokerTLSModestring-enummandatorySelect the security type (if any) to use for the transport layer. The possible values are: TLS-DISABLED, TLS-CERT, TLS-PSK.
BrokerSSLSecurebooleanoptionalWhether TLS certificates should be verified (Default: true).
BrokerCACertificatestringmaybe-optionalCertificate of the CA who signs the clients which will be connecting to the broker. Required if BrokerTLSMode is TLS-CERT.
BrokerCertificatestringmaybe-optionalCertificate public key file. Required if BrokerTLSMode is TLS-CERT.
BrokerPrivateKeystringmaybe-optionalPrivate key file. Required if BrokerTLSMode is TLS-CERT.
BrokerPSKHintstringmaybe-optionalString to send to clients to aid in authentication. Required if BrokerTLSMode is TLS-PSK.
BrokerPSKFilestringmaybe-optionalFile with pre-shared keys in the format identity:key - one identity per line. Required if BrokerTLSMode is TLS-PSK.

Samplepoint object

The SamplePoints objects contains the following elements:

FunctionTypeImportanceDescription
SampleNamestringmandatoryName of this sampled value (sometimes called a tagname). Follows the normal rules for names.
SampleDescriptionstringoptionalA text description of this sample value.
SampleUnitstringoptionalA description of the unit measurement for this sample.
SampleGroupstringoptionalGroup 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.
SamplesSavedinteger > 0optionalThe number of collected values that are saved in the Store'n'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 will be sent via dataservers. If left unspecified, values are only saved in the Store'n'Forward database until they have been delivered to all dataservers
OnlySaveOnChangedbooleanoptionalSpecifies 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.
ChangeLimitinteger/doubleoptionalUsed 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
SampleDataTypestring-enummandatoryThe 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).
SampleMaxVDataSizeinteger > 0 and <= 24575optionalThe 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.
SampleLowerLimitinteger/doubleoptionalThe lower limit for the collected data. If the collected data value is less than SampleLowerLimit it is evaluated in accordance with SampleLimitDiscard and SampleLimitAlarm.
SampleUpperLimitinteger/doubleoptionalThe upper limit for the collected data. If the collected data value is more than SampleUpperLimit it is evaluated in accordance with SampleLimitDiscard and SampleLimitAlarm.
SampleLimitDiscardbooleanmaybe-optionalSpecifies whether samples that violates the sample limit should be discarded. Mandatory if either SampleLowerLimit or SampleUpperLimit is present.
SampleLimitAlarmbooleanmaybe-optionalSpecifies whether samples that violates the sample limits should generate an alarm. Mandatory if either SampleLowerLimit or SampleUpperLimit is present.
MQTTSampleobjectmandatorySpecification of the MQTT topic containing this sample value.

MQTTSample object

The MQTTSample object contains the following elements:

FunctionTypeImportanceDescription
TopicStringstringmandatoryThe MQTT topic to subscribe to. Wildcards ('#', '+') are not allowed.
TopicSubscribeQosstring-enumoptionalQoS (Quality of Service) to use when subscribing to this topic. Possible values are qos0, qos1, and qos2
PayloadEndiannessstring-enumoptionalEndianness 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.
NumberAsStringbooleanoptionalIndicate if numeric data is formatted as a string in the payload - use with appropriate SampleDataType to get correct conversion.
PayloadJSONPathstringoptionalPath to extract sample point from if topic data is a JSON string.
PayloadXMLPathstringoptionalPath to extract sample point from if topic data is an XML string.

Was this article helpful?