We've updated our file storage system, so some links may no longer work. If you need a file, just email us at support@secomea.com—we’re happy to help!

Dataserver Generic MQTT

  • Updated on Mar 27, 2025
  • Published on Sep 25, 2024
  • 6 minute(s) read
  • SE
  • PL
 Prev Next

The purpose of this article is to serve as a reference guide for using a generic MQTT broker as data server in the Data Collection Module.

This guide is part of the complete documentation for the Data Collection Module feature in SiteManager.

The Generic MQTT dataserver is used to send collected samples (data points) to a TLS encryption enabled MQTT broker.

Supported SiteManager Models:

The MQTT Dataserver is supported by the following SiteManager models:
15XX & 35XX

Configuration

The data server's (array of objects, mandatory) list elements contain the following fields:

Function Type Importance Description
DatasrvName string mandatory Unique name (within this configuration file) for each data server this SiteManager delivers data to. Follows the normal rules for names.
DatasrvDesription string optional A description of this data server. For your future reference.
SampleList array of strings optional This array contains the list of sampleref this data server will deliver data for. If it is not present, all sample values in this configuration will be delivered. Since this object is not a Collector object, the CollectorName part of the sampleref field is mandatory. If the SampleName part of the sampleref is left blank, all samples from that collector are delivered.
IOPin boolean optional If set to true, the Output I/O pins configured to follow DCM data loss will be controlled by this datasrv. If multiple data servers control the I/O pins, then the value will be the logical OR of all data servers in data loss state. (I.e. If any data server is in data loss, the I/O pins will be in logical high). If not set, the value is false.
DatasrvProtocol string-enum mandatory Designates the protocol used to deliver data from the Store and Forward database to data servers, aka Cloud Systems. For Generic MQTT use GENERIC/MQTT. Other possible values (for other dataservers) are: C8Y/REST, AWS/MQTT, AZURE/IOTHUB, SCI/SPD, C8Y/REST, AVEVA/REST and SIMULATOR/NONE.
ConnectRetryMin integer > 0 mandatory Minimum number of seconds before trying to reestablish a connection to the data server for data delivery. An exponential back-off algorithm is used to retry connection establishment, starting after ConnectRetryMin and increasing to ConnectRetryMax.
ConnectRetryMax integer > 0 mandatory Maximum number of seconds before trying to reestablish a connection to the data server for data delivery.
MQTTParams object mandatory for MQTT Contains all the parameters needed to deliver (publish) data to a generic MQTT broker. Mandatory if DatasrvProtocol has the value GENERIC/MQTT.

MQTTParams object

The MQTTParams object contains the following fields:

Function Type Importance Description
BrokerAddr string mandatory The DNS name/IP address of the external generic MQTT broker where data from the Store and Forward database is delivered to.
BrokerPort integer > 0 and < 65535 mandatory The TCP port to use for the connection from the SiteManager to the MQTT broker.
KeepAlive integer >= 5 and <= 600 optional Keep-alive interval in seconds to use for the client connection. If not specified, the value 60 is used.
ProtocolVersion string-enum optional The MQTT protocol version (v3.1, v3.1.1, or v5.0) to use for the MQTT connection. The possible values are: MQTT_V31, MQTT_V311, MQTT_V5. If not specified, the value MQTT_V311 is used.
ClientIdFormat string optional This string describes the format used for the MQTT clientid. The format is printf-like and accepts the same formats as PayloadFormat, except only %m, %M, %N and %% are supported. If not specified, a clientid of DCM will be used.
PasswordFile string optional The certname of the password-file used for password based authentication. The file should be formatted as username:password. If no file is specified, the DCM client will connect anonymously to the broker.
TLSMode string-enum mandatory Select the TLS security type to use for the MQTT connection. The possible values are: TLS-CERT, TLS-PSK.
SSLSecure boolean optional Whether TLS certificates should be verified. If not specified, the default value true is used.
RootCA string optional The certname of the RootCA certificate file to use for the TLS encryption. Only relevant if TLSMode has the value TLS-CERT.
DeviceCert string optional The certname of the Device Certificate file to use for the TLS encryption. In this context, device refers to the SiteManager. Only relevant if TLSMode has the value TLS-CERT.
DevicePrivKey string optional The certname of the Device Private Key file to use for the TLS encryption. In this context, device refers to the SiteManager. Only relevant if TLSMode has the value TLS-CERT.
DevicePSKFile string maybe optional The certname of the Device PSKfile with pre-shared key. In this context, device refers to the SiteManager. The file should be formatted as identity:key. Mandatory if TLSMode has the value TLS-PSK.
PublishQos string string-enum The QOS (Quality Of Service) used to publish messages to the MQTT broker. The possible values are: qos0, qos1, qos2. If not specified, the value qos0 is used.
Retain boolean optional Whether to set the retain flag for all published samplepoints. If not specified, the value false is used.
PayloadFormat string optional This string describes the format of the payload reported over MQTT. The format is printf-like with % formats described in the PayloadFormat list below.
LastWill object optional Object specifying the MQTT client Last Will and Testament (LWT) settings. If not specified, Last Will and Testament will not be set.
PublishInterval integer >= 0 mandatory The interval in seconds between each delivery of new data from the Store and Forward database. The value 0 means that data is delivered as fast as possible.
BulkElementFormat string optional This string describes the format of the element used by the %b format used in the PayloadFormat and is therefore mandatory if PayloadFormat contains a %b format. The BulkElementFormat is printf-like with the same specifiers as for PayloadFormat except %b is not allowed. If not specified the format is { "ts" : %t, "%jd:%js" : %jv }.

PayloadFormat

  • m - SiteManager Unique address. (This is NOT the MAC address, but the EdgeID)
  • M - SiteManager Unique MAC address.
  • N - SiteManager Name. (GateManager Appliance Name).
  • V - Configuration version ID.
  • d - Collector name.
  • s - Sample name.
  • u - Sample unit. If undefined, an empty string.
  • g - Sample group name. If undefined, the sample name will be used.
  • t - Timestamp value as an integer. (64bit Win32 FILETIME Epoch in 100 nanosecond resolution)
  • T - Timestamp as ISO-8601 time string. (2018-11-12T14:04:46.114)
  • e - Timestamp as an integer. (32bit Unix Epoch in 1 second resolution)
  • E - Timestamp as an integer. (64bit Unix Epoch in 1 millisecond resolution)
  • v - Sample value as a string. (binary data as hex byte string)
  • b - Multiple values are delivered (in bulk) as an array, described in the BulkElementFormat.
  • % - A percent character.
  • 0 - Additionally, the GENERIC/MQTT dataserver implements the special format specifier 0 which returns the resulting MQTT clientid for the dataserver instance.

LastWill object

The LastWill object contains the following fields:

Function Type Importance Description
TopicFormat string optional This string describes the format of the topic used over MQTT. The format is printf-like and accepts the same formats as PayloadFormat, except that only %m, %M, %N, %V, %d, %s, %g, %0 and %% are supported. If not specified, Last Will and Testament will not be set.
MessageFormat string optional The message format to use for the LWT message. The format is printf-like and accepts the same formats as PayloadFormat.
PublishQos string-enum optional The quality of service to use when publishing the LWT message. The possible values are: qos0, qos1, qos2. If not specified, the value qos0 is used.
Retain boolean optional Specify whether or not the retain flag should be set for the LWT message. If not specified, the value false is used.

Example configuration

{
    "ConfigName": "mqtt_dataserver_password_tlscert_all_certs",
    "ConfigDescription": "DCM MQTT dataserver with passwordfile authorisation and certificate based TLS",
    "Collectors":
    [
      ...
    ],
    "DataServers":
    [
        {
            "DatasrvName": "Secomea_DCM_GenericMQTT_Example",
            "DatasrvProtocol": "GENERIC/MQTT",
            "ConnectRetryMin": 10,
            "ConnectRetryMax": 100,
            "MQTTParams":
            {
                "BrokerAddr": "10.11.12.13",
                "BrokerPort": 8883,
                "KeepAlive": 60,
                "ProtocolVersion": "MQTT_V311",
                "ClientIdFormat": "secomea_dcm",
                "PasswordFile": "dataserver_passwordfile.pw",
                "TLSMode": "TLS-CERT",
                "SSLSecure": true,
                "RootCA": "dataserver_rootca.crt",
                "DeviceCert": "dataserver.crt",
                "DevicePrivKey": "dataserver.key",
                "PublishQos": "qos0",
                "Retain": false,
                "PublishInterval": 60,
                "TopicFormat": "%0/%s",
                "PayloadFormat": "{ \"v\" : [ %jb ] }",
                "BulkElementFormat": "{ \"ts\" : %t, \"%jd:%js\" : %jv },",
                "LastWill": {
                    "TopicFormat": "%0/will",
                    "MessageFormat": "Goodbye",
                    "PublishQos": "qos0",
                    "Retain": false
                }
            }
        }
    ]
}
© 2024 Secomea A/S. All Rights Reserved