MQTT Plugin

The MQTT plugin allows sending the collected messages via MQTT and MQTT over websockets to a remote system. Proxy-support is on board as well as local message caching/persisting and data compression.

File location:

configs/configurations/OutputPlugins/MqttNet/MqttSettings.xml

Configuration

Mandatory settings

Two settings are mandatory for running the MQTT-plugin and connecting to the Senseforce MQTT broker. All the other settings are for advanced use-cases (see the section below).

Setting	Description
Username/Password	Enter the username and password for connecting with the remote broker. Contact Senseforce for getting your credentials.
Topic	The topic identifies your machine in the Senseforce cloud. The following format is required: tenant/machineIdentifier. If your company is called MyCompany at Senseforce and your machine is called Machine1, use the following topic: MyCompany/Machine1

The topic setting identifies the data sent to the Senseforce cloud and correlates them to a specific machine identifier. Renaming a machine identifier is not possible.

Sample configuration

A sample MQTT plugin configuration is illustrated below

<?xml version="1.0" encoding="utf-8" ?>
<MqttConfiguration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                   xsi:schemaLocation="https://senseforce.io/ ..\..\Schemas\mqttnetsettings.xsd" >
  <Broker>
    <Host>luna.senseforce.io</Host>
    <Port>8883</Port>
    <Secure>true</Secure>
    <AllowAnonymous>false</AllowAnonymous>
    <Username>username</Username>
    <Password>password</Password>
    <!-- Allowed settings for ProtocolVersion: NONE, Version_3_1_0, Version_3_1_1 (default), Version_5_0_0-->
    <ProtocolVersion>Version_3_1_1</ProtocolVersion>
    <!-- Allowed settings for TlsVersion: NONE, SSL3, TLS_1_0, TLS_1_1, TLS_1_2-->
    <TlsVersion>TLS_1_2</TlsVersion>
    <!-- by default tcp mqtt server is used. Set UseWebsockets to true, to enable communication via websockets-->
    <!-- Use the Host-setting above to give the fully qualified websocket address (like luna.senseforce.io:443/mqtt). The Port-setting is ignored for websockets.
         Define the port directly in the Host-entry.-->
    <UseWebsockets>false</UseWebsockets>
    <!--<Proxy>
      <Address>http://myproxy:23500</Address>
      <Domain></Domain> <!-- Proxy server domain -->
  		<Username></Username> <!-- Proxy server user name -->
  		<Password></Password> <!-- Proxy server password -->
    </Proxy>-->
  </Broker>
  <Compression>LZ4</Compression>
  <!--Currently implemented: LZ4, Disabled-->

  <!--Messages arriving from ingress plugins are batched until the NumberOfMessagesToCombine is reached or the MessageCombineCounterMs are elapsed. Then they are sent.-->
  <NumberOfMessagesToCombine>500</NumberOfMessagesToCombine>
  <MessageCombineCounterMs>5000</MessageCombineCounterMs>

  <Topic>tenant/test</Topic>

  <PersistMessagesOnFileSystem>true</PersistMessagesOnFileSystem>
  <PersistencePath>$(LunaAppDataPath)configurations/OutputPlugins/MqttNet/Persistence</PersistencePath>

  <!-- If EnableServerCertAuth is set to false, all server certificates are trusted-->
  <EnableServerCertAuth>true</EnableServerCertAuth>
  <CaFilePath>$(RuntimePath)data/certs/ca.pem</CaFilePath>

  <!-- Set to true, if the oldest message should be deleted in case of the MaxReconnectBuffer is hit. Otherwise, the newest incoming messages are removed -->
  <DropOldestIfOverflow>true</DropOldestIfOverflow>
  <MaxReconnectBuffer>100000</MaxReconnectBuffer>

  <!-- Maximum and minimum reconnect time. A random time interval between these two values is waited after a connection loss to wait for reconnect.-->
  <MinReconnectTimeSeconds>20</MinReconnectTimeSeconds>
  <MaxReconnectTimeSeconds>1200</MaxReconnectTimeSeconds>

  <Logger>
    <FilePath>$(LunaAppDataPath)Logs</FilePath>
    <FileName>mqttnet.log</FileName>
    <!--LogLevel: Debug,Information,Warning,Error,Critical,None-->
    <LogLevel>Information</LogLevel>
  </Logger>
</MqttConfiguration>

Advanced Settings

The following settings are available: (Note: the corresponding line in the above sample file is provided in brackets).

Setting	Description
Host	Define the MQTT broker endpoint address. If using websockets (Setting UseWebsockets = true), the fully qualified websocket address needs to be entered (eg. luna.senseforce.io:443/mqtt). Otherwise, only the hostname is required (eg. luna.senseforce.io) Senseforce default: luna.senseforce.io
Port	Port of the remote broker. Make sure, your firewall supports outgoing connections on this port. Senseforce default: 8883 (also available: 443)
Secure	If set to true, a TLS-encrypted connection is used. To connect with Senseforce, this setting needs to be true
AllowAnonymous	Determines, whether anonymous clients (without username and password) can connect to the remote broker. Not allowed when connecting to Senseforce
ProtocolVersion	Specify the MQTT protocol version. Allowed settings are: NONE, Version_3_1_0, Version_3_1_1 (default), Version_5_0_0
TlsVersion	Defines the TLS-Version to use. Allowed settings are: NONE, SSL3, TLS_1_0, TLS_1_1, TLS_1_2
UseWebsockets	Allows enabling MQTT over websockets, enabling to communicate the messages over websocket technology. This setting might be advantageous to circumvent strict firewall rules, as this kind of traffic is often allowed. Furthermore, websockets allow enabling Proxy-Support (see below). Use the Host-setting to give the fully qualified websocket address (like luna.senseforce.io:443/mqtt). The Port-setting is ignored for websockets. Define the port directly in the Host-entry.
Proxy	Definition of a proxy-server. Define proxy server address, optional domain, username, and password.
Compression	Allows enabling LZ4 compression. Alternatively, DISABLE the compression. If compression is enabled, the topic is automatically extended as follows: [topic]/LZ4
NumberOfMessagesToCombine MessageCombineCounterMs	Messages arriving from ingress plugins are batched until the NumberOfMessagesToCombine is reached or the MessageCombineCounterMs (milliseconds) are elapsed. Then they are sent. Setting higher values reduces bandwidth if the transmitted messages are compressed.
PersistMessagesOnFileSystem PersistencePath	Specify whether and where to persist incoming messages on the file system. Highly suggested as this setting allows to overcome extensive periods without being connected to the internet and without losing messages.
EnableServerCertAuth CaFilePath	Define if the MQTT plugin should verify the remote server certificate. It is highly suggested to activate this setting to prevent from connecting to unknown servers. CaFilePath specifies where to find the certificate which was used to sign the remote server certificate (and therefore is used for the verification process)
DropOldestIfOverflow	Set this setting to true to remove the oldest message from the internal message queue if it is full. If set to false, the newest incoming messages are dropped.
MaxReconnectBuffer	Defines the size of the internal message queue - how many messages can be locally stored while not connected to the remote server.
MinReconnectTimeSeconds MaxReconnectTimeSeconds	Maximum and minimum reconnection time. A random time interval between these two values is waited after a connection loss to wait for reconnecting.

Sample file

3KB

MqttSettings.xml