MQTT Modul "mqtt"

Beschreibung

Das MQTT Modul dient der Kommunikation mit einem MQTT Broker in beiden Richtungen.

Hierbei können jeweils mehrere smartCORE Kanäle einem MQTT Topic zugeordnet werden, wobei das Modul eine Auswahl mehrerer Topics ermöglicht.

Es können darüberhinaus mehrere Module instantiiert werden, um mit mehreren unterschiedlichen Brokern gleichzeitig kommunizieren zu können.

Bezüglich der Interpretation und Vorbereitung von MQTT Payloads werden sogenannte Payload Hints unterstützt, die der Formatbeschreibung dienen.

In Publikationsrichtung dienen diese dazu, eine Syntaxüberprüfung der Publikationsschablonen, in welche dann konsumierte Kanalwerte eingefügt werden, durchzuführen (z.B. für gänige Formate wie JSON, XML, ...).

Umgekehrt dienen diese Payload Hints in Abbonierungsrichtung (subscribe) dazu, geeignete Datenextraktionsmechanismen für o.g. Formate bereitzustellen, so dass die hiermit extrahierten Werte in entsprechende smartCORE Kanäle produziert werden können.

Verwendete Schnittstellen & Protokolle

• MQTT

JSON-Konfiguration

Im folgenden Abschnitt soll die gesamte JSON-Konfiguration des Moduls beschrieben und die einzelnen Parameter erläutert werden.

Beispielkonfiguration (minimal und typisch)

Im folgenden eine minimale Beispielkonfiguration:

    {
      "module":"MQTT",
      "factory":"mqtt",
      "config":{
        "brokerAddress": "ssl://awe.some.io:8883",
        "brokerUserId": "USER_ID",
        "brokerUserPassword": "USER_PASSWORD",
        "brokerClientId": "CLIENT_ID",
        "topics":[

          <MQTT TOPIC KONFIGURATIONEN>

        ]
      }
    }

Beispielkonfiguration (maximal)

    {
      "module":"MQTT",
      "factory":"mqtt",
      "config":{
        "useLocalBroker":false,
        "enabled":true,
        "pollingIntervalMs":1000,

        "brokerAddress": "ssl://awe.some.io:8883",
        "brokerAuthentication": true,
        "trustStore": "/etc/ssl/certs/ca-certificates.crt",
        "brokerUserId": "USER_ID",
        "brokerUserPassword": "USER_PASSWORD",
        "brokerClientId": "CLIENT_ID",

        "maxBufferedMessages": 10,
        "connectTimeoutS": 10,
        "disconnectTimeoutS": 10,
        "keepaliveIntervalS": 10,
        "completionIntervalS": 10,
        "sendingIntervalS": 10,
        "topics":[

          <MQTT TOPIC KONFIGURATIONEN>

        ]
      }
    }

Beispiele von JSON Objekten zur Topic Konfiguration...

Die folgenden JSON Objekte können in das o.g. Array von topics eingefügt werden.

...in Publikationsrichtung

Hierbei dienen die unter mqttName aufgeführten Strings als Platzhalter, welche 1:1 durch die Werte der unter channelName aufgeführten smartCORE Kanäle ersetzt werden.

{
    "name":"sensor/state",
    "direction":"publish",
    "payload":"{\"voltage\":%BAT_VOLTAGE%,\"current\":%BAT_CURRENT%}",
    "payloadHint":"json",
    "channels":[
        {
            "mqttName":"%BAT_VOLTAGE%",
            "channelName":"PowerSupplyVoltage"
        },
        {
            "mqttName":"%BAT_CURRENT%",
            "channelName":"PowerSupplyCurrent"
        }
    ]
}

...in Subskriptionsrichtung

Hierbei wird durch die unter mqttName aufgeführten Strings beschrieben, wie Kanaldaten aus dem MQTT Payload zu extrahieren sind, was auf unterschiedliche Art und Weise möglich ist (siehe unten).

  {
    "name":"sensor/status/switch:0",
    "direction":"subscribe",
    "payloadHint":"json",
    "channels":[
      {
        "mqttName":"power",
        "channelName":"Power",
        "dataType":"float"
      },
      {
        "mqttName":"current",
        "channelName":"Current",
        "dataType":"float"
      },
      {
        "mqttName":"temperature/tC",
        "channelName":"TemperatureTC",
        "dataType":"float"
      }
    ]
  }

Modulparameter

Parametername	Erforderlich	Datentyp	sinnvoller Wertebereich	Default	Beschreibung
useLocalBroker	Nein	BOOL	true, false	false	Starte MQTT Broker auf dem Gerät und kommuniziere mit diesem
enabled	Nein	BOOL	true, false	true	Aktivität der Kommunikation zum Broker
pollingIntervalMs	Nein	INT	1 -	1000	Modulbezogenes Verarbeitungsintervall [ms]
brokerAddress	Nein	STRING	gültige Broker URL		"ssl://awe.some.io:8883" , "tcp://awe.some.io:1883" (nicht empfohlen)
brokerAuthentication	Nein	BOOL	true, false	true	Broker-Authentifizierung
trustStore	Nein	STRING		/etc/ssl/certs/ca-certificates.crt	Trust Store für Broker-Authentifizierung
brokerUserId	Nein	STRING			Broker-Benutzerkennung
brokerUserPassword	Nein	STRING			Broker-Benutzerpasswort
brokerClientId	Nein	STRING			Broker-Client-/Gerätekennung
maxBufferedMessages	Nein	INT	1 -	10	Maximale Anzahl gepufferter MQTT Botschaften innerhalb des MQTT Clients
connectTimeoutS	Nein	INT	1 -	10	Timeout bzgl. Verbindungsherstellung
disconnectTimeoutS	Nein	INT	1 -	10	Timeout bzgl. Verbindungstrennung nach Aufforderung
keepaliveIntervalS	Nein	INT	1 -	10	Timeout bzgl. Detektion einer getrennten Verbindung
completionIntervalS	Nein	INT	1 -	10	Timeout bzgl. Quittierungsempfang nach Versand einer MQTT Botschaft
sendingIntervalS	Nein	INT	1 -	10	Timeout bzgl. Versand einer MQTT Botschaft
topics	JA	JSON Array			siehe MQTT Topic Konfiguration

MQTT Topic Konfiguration "topics"

Man unterscheidet hierbei zwischen zu publizierenden (published) und zu abbonierenden (subscribed) Topics.

Zu publizierende Topics (published topics)

Ein zu publizierendes Topic, welches i.A. eine Auswahl von smartCORE Kanälen beinhaltet, wird hierbei als JSON Objekt, das folgende Parameter enthält, konfiguriert.

Parametername	Erforderlich	Datentyp	sinnvoller Wertebereich	Default	Beschreibung
name	JA	STRING			Name/Pfad des Topics auf dem Broker
direction	JA	STRING	"publish"		für ein zu publizierendes Topic auf "publish" zu setzen
payload	JA	STRING			Payload-Schablone
payloadHint	JA	STRING	"plain", "json"	"json"	Auswahl des zu übertragenen Payload-Formats bzgl. dessen eine Syntaxprüfung der Payload-Schablone erfolgt, falls dies möglich ist
channels	JA	JSON Array			siehe unten

Die Kanalkonfiguration zu publizierender Kanäle erfolgt in Form eines JSON Arrays, das JSON Objekte mit folgenden Parametern enthält.

Parametername	Erforderlich	Datentyp	sinnvoller Wertebereich	Default	Beschreibung
channelName	JA	STRING			Name des zu konsumierenden smartCORE Kanals
mqttName	JA	STRING			Teilstring innerhalb der Payload-Schablone, der mit einer Stringrepräsentation des aktuellen Kanalwertes ersetzt wird.
format	NEIN	STRING			Formatierungsanweisung bzgl. Konvertierung des Kanalwertes nach String
translateFalse	NEIN	STRING		"false"	Stringrepräsentation des Booleschen Wertes für falsch
translateTrue	NEIN	STRING		"true"	Stringrepräsentation des Booleschen Wertes für wahr

Zu abbonierende Topics (subscribed topics)

Ein zu abbonierendes Topic, welches i.A. eine Auswahl von smartCORE Kanälen bereitstellt, wird hierbei als JSON Objekt, das folgende Parameter beinhaltet, konfiguriert.

Parametername	Erforderlich	Datentyp	sinnvoller Wertebereich	Default	Beschreibung
name	JA	STRING			Name/Pfad des Topics auf dem Broker
direction	JA	STRING	"subscribe"		für ein zu abbonierendes Topic auf "subscribe" zu setzen
payloadHint	JA	STRING	"plain", "json"	"json"	Auswahl des zu empfangenen Payload-Formats bzgl. dessen eine Datenextraktion in konfigurierte Kanäle erfolgt.
channels	JA	JSON Array			siehe unten

Die Kanalkonfiguration zu publizierender Kanäle erfolgt in Form eines JSON Arrays, das JSON Objekte mit folgenden Parametern enthält.

Parametername	Erforderlich	Datentyp	sinnvoller Wertebereich	Default	Beschreibung
channelName	JA	STRING			Name des zu produzierenden smartCORE Kanals
dataType	JA	STRING	gültiger smartCORE Datentyp		Datentyp des Kanals
bufferSize	NEIN	INT	1 -	1024	Puffergröße des Kanals
physicalUnit	NEIN	STRING			Physikalische Einheit des Kanals
mqttName	JA	STRING			String, der eine Anweisung zur Extraktion einzelner Kanalwerte aus einem Payload beschreibt (z.B. eine Pfadangabe für JSON Payloads)
translateFalse	NEIN	STRING		"false"	Stringrepräsentation des Booleschen Wertes für falsch
translateTrue	NEIN	STRING		"true"	Stringrepräsentation des Booleschen Wertes für wahr

Payload-Inhalt-bezogene Besonderheiten

Direkte 1:1 Datenextraktion (payloadHint "plain")

Hierbei wird in Abbonierungsrichtung (subscribe) der gesamte Inhalt des Payloads vollständig als Kanalwert verwendet. Es erfolgt hierbei eine automatische fehlertolerante Konvertierung in den Zieldatentyp, soweit diese möglich ist. Umgekehrt erfolgt keine Syntaxprüfung in Publikationsrichtung.

JSON (payloadHint "json")

Um Kanaldaten aus einem abbonierten Topic mit JSON-formattiertem Payload zu extrahieren, kann als "mqttName" Parameter eine Pfadangabe benutzt werden.

Beispiel: Beinhaltet der empfangene Payload folgendes JSON Objekt.

{
  "someObject":{
    "someSubObject/with/slash":{
      "someKey": 42
    }
  }
  "someArray":[
    1,
    2,
    3
  ]
}

so extrahiert "mqttName":"someObject/someSubObject\/with\/slash/someKey" den Wert 42, welcher dann in den als "channelName" definierten Kanal produziert wird (d.h. es ist erforderlich, das Trennzeichen "/" zu escapen).

Entsprechend extrahiert "mqttName":"someArray/1" den Wert 2 aus o.g. JSON Objekt (d.h. im Fall eines JSON Arrays wird die Pfadkomponente als Index verwendet).

Werden mehrere Trennzeichen "/" hintereinander spezifiziert, so werden diese als einzelnes Trennzeichen betrachtet.

Wird ein ungültiger Pfad spezifiziert, erfolgt in jedem Fall keine Produktion von Kanaldaten.

Modul-Informationen

Information	Wert
Autoren	optiMEAS Measurement and Automation Systems GmbH
seit smartCORE	2.6
Modultyp	wahlweise Consumer, Producer oder beides
Abhängigkeiten	vorhandener MQTT-Broker