Allgemein
Das Format der Nutzdaten kann für ausgehende Nachrichten frei gewählt werden (publish data type). Für eingehende Nachrichten sind nur bestimmte Formattypen erlaubt, derzeit nur JSON.
Definition eines Formates
Ein Format wird über eine Vorlagendatei definiert, die über die Weboberfläche hochgeladen werden kann.
Die Datei wird unter /ugw/config/formats gespeichert. Der Name der Vorlage entspricht dem Dateinamen und muss in der Datenpunktdefinition unter "format = template:filename" angegeben werden.
Die Datei selbst enthält Platzhalter, die vom Treiber bei der Erstellung von Payload ersetzt werden.
Zur Identifikation eines Platzhalters werden zwei Zeichen verwendet, die hier PlaceholderBegin und PlaceholderEnd genannt werden. Die Zeichen können in der Treiberkonfiguration eingestellt werden und sind standardmäßig '<' und '>'.
Ein Platzhalter wird immer von diesen beiden Zeichen umschlossen. Innerhalb des Platzhalters befindet sich entweder die Adresse eines anderen Datenpunktes oder ein spezielles Schlüsselwort. Diese Schlüsselwörter beginnen immer mit den Zeichen PlaceHolderSpecial, das ebenfalls gesetzt werden kann und standardmäßig ein '$' ist. Für die genauen Einstellmöglichkeiten sollte die Standardkonfigurationsdatei verwendet werden.
Wenn der Platzhalter der Name eines anderen Datenpunktes ist, wird geprüft, ob dieser Datenpunkt auch ein Template-Format hat. Ist dies der Fall, wird die Vorlage ausgewertet und in das Format eingefügt. Auf diese Weise kann eine einzige Vorlage mehrere Datenpunkte zusammenfassen und gemeinsam senden.
Spezielle Schlüsselwörter
Zunächst gibt es zwei spezielle Schlüsselbegriffe, einmal den Begriff VALUE und den Begriff TIME. Bei VALUE wird der Platzhalter durch den Wert des Datenpunktes und bei TIME durch die aktuelle Uhrzeit ersetzt. Das Format der Zeit kann über die Konfiguration eingestellt werden und entspricht den Formatzeichen von strftime(). Standardmäßig ist das Format ein Zeitformat, das die Zeit nach ISO 8601 ausgibt.
Zusätzlich gibt es den Schlüsselbegriff TIMESTAMP. Mit diesem Schlüsselbegriff kann die Zeit in der Unix-epoch time UTC angegeben werden. Der Schlüsselbegriff ist äquivalent zu TIME mit dem Formatzeichen %s mit dem Unterschied, dass der Wert numerisch ist, was aber nur bei bestimmten Formaten einen Unterschied macht. Der Zeitstempel kann auch in Millisekunden angegeben werden. Dazu muss StampMilliSeconds in der Konfiguration auf "TRUE" gesetzt werden.
Außerdem gibt es jetzt die Schlüsselwörter ADDRESS und NAME. Wie die Namensgebung andeutet, wird entweder die Adresse des mqtt-Datenpunktes oder der Name des Datenpunktes ausgegeben. Ein Adressbeispiel für einen Publish-Datenpunkt wäre:
publish sensor/1
Außerdem gibt es die Schlüsselwörter LASTCHANGED und LASTCHANGEDSTAMP. Beide geben den Zeitpunkt der letzten Wertänderung des Datenpunktes zurück, einmal als formatierte Zeichenkette entsprechend TIME oder als Zeitstempel entsprechend TIMESTAMP. Ist keine Zeit verfügbar, wird "invalid" zurückgegeben.
Die Flags eines Datenpunktes können nun auch gemappt werden. Hierfür gibt es die Platzhalter AUTO, VALID, FAULT, ERROR, LOCAL, AUTO, LOCKED, WARNHIGH, ALARMHIGH, RANGEHIGH, WARNLOW, ALARMLOW, RANGELOW, HISTORY, CHANGED, DEFNEW, DEFDEL, DEFCHG.
Benutzerspezifische Schlüsselbegriffe
Es ist auch möglich, eigene Schlüsselwörter in der Datenpunktdefinition zu definieren. Die Schlüsselwörter können im Formatstring des Datenpunktes im JSON-Format definiert werden:
format = placeholders: {"custom_placeholder": "placeholder_value", "custom_placeholder2": "placeholder_value2"}
Als Wert für die Schlüsselbegriffe sind nur Strings erlaubt. Darüber hinaus können benutzerspezifische Platzhalter ohne PlaceHolderSpecial verwendet werden. In diesem Fall wird davon ausgegangen, dass der Platzhalterwert die Adresse eines Datenpunktes ist. Der Wert dieses Datenpunktes wird dann an der Stelle eingefügt. Andernfalls wird die angegebene Zeichenkette eingefügt.
Beispiele
Mit der Vorlagendatei 'SingleValue.txt'
<$TIME>, <$VALUE>
würde ein Datenpunkt mit den Namen publish sensor/1 und dem Wert 42 die folgende Payload senden:
2021-06-10T10:51:15+0200, 42
Dazu muss die Vorlagendatei hochgeladen und der Datenpunktdefinition unter Format die Angabe "template:SingleValue.txt" hinzugefügt werden. Ein zweiter Datenpunkt mit dem Namen publish sensor/2 und dem Wert 11.2 könnte die gleiche Vorlage verwenden und hätte die Payload:
2021-06-10T10:51:15+0200, 11.2
Es ist auch möglich, eine zweite Formatdatei Values.txt hochzuladen, die dem Datenpunkt publish sensor zugeordnet wird.
name, time, value
sensor 1, <publish sensor/1>
sensor 2, <publish sensor/2>
HINWEIS: Dafür muss der Timer T: (siehe Abschnitt: Periodisches Publish) gesetzt werden, weil sonst kein publish erfolgt.
Dieser Datenpunkt würde dann die folgende Payload senden.
name, time, value
sensor 1, 2021-06-10T10:51:15+0200, 42
sensor 2, 2021-06-10T10:51:15+0200, 11.2
Spezielle Formattypen JSON
JSON-Formate werden besonders unterstützt und haben erweiterte Funktionen. Ob eine Vorlage ein JSON-Format ist, wird durch die Dateierweiterung '.json' bestimmt. Groß- und Kleinschreibung ist dabei unerheblich.
Im Gegensatz zu General können nur JSON-Strings Platzhalter sein. Ein Platzhalter in einem Schlüssel zum Beispiel ist nicht möglich.
Die Zeichenkette wird dann beim Parsen in ein JSON-Objekt umgewandelt. Der Typ des Objekts hängt vom Platzhalter ab. Bezieht sich der Platzhalter auf einen Datenpunkt, dessen Wert eine Fließkommazahl ist, dann ist das JSON-Objekt ebenfalls eine Fließkommazahl.
Wenn der Wert ungültig ist, ist das JSON-Objekt null.
Hinweis
JSON-Formate können nicht nur zum Senden, sondern auch zum Empfangen von Nachrichten verwendet werden.
Beispiel
Das obige Beispiel soll nun in JSON umgewandelt werden.
Zu diesem Zweck wird die Vorlagendatei "SingleValue.txt" durch die Datei "SingleValue.json" ersetzt.
{
"time": "<$TIME>",
"value": "<$VALUE>"
}
Die Datei " Values.txt" wird durch das Beispiel "Values.json" ersetzt.
{
"sensor 1": "<publish sensor/1>",
"sensor 2": "<publish sensor/2>"
}
Der Datenpunkt publish sensors sendet dann folgende Payload:
{"sensor1":{"time":"2021-06-10T10:51:15+0200","value":42},"sensor2":{"time":"2021-06-10T10:51:15+0200","value":11.2}}
Wie zu sehen ist, wird das JSON-Objekt zur Verbesserung der Leistung komprimiert.
In einer strukturierteren Form hätte es die folgende Gestalt:
{
"sensor 1": {
"time": "2021-06-10T10:51:15+0200",
"value": 42
},
"sensor 2": {
"time": "2021-06-10T10:51:15+0200",
"value": 11.2
}
}
In diesem Beispiel ist auch zu sehen, dass die Strings aus der Vorlagendatei durch JSON-Objekte ersetzt werden und keine Strings mehr sind.
Datenpunkt Typ ‘value’
Um Datenpunkte, die nur gebündelt mit anderen Datenpunkten gesendet werden sollen, sinnvoller mit MQTT erstellen zu können, wurde der neue Datentyp 'value' implementiert.
Dieser Datentyp wird nicht veröffentlicht oder abonniert, sondern dient nur dazu, von anderen Publish-Datenpunkten in deren Template verwendet zu werden.
Im obigen Beispiel könnten daher also die Publish Datenpunkte sensor/1 und sensor/2 durch die Wertdatenpunkte 1 und 2 ersetzen.