Das Grundgerüst jeder Custom-Logik ist ein JSON-Objekt mit den vier Schlüsseln
Level (Deklaration in der Custom-Logik verwendeten Variablen),
Module (die eigentlichen Handlungsanweisungen, d.h. eine Abfolge Logikbausteinen),
Input (Definition der Eingänge und Zuordnung der Variablen) und
Output (Definition der Eingänge und Zuordnung der Variablen).
Jeder dieser vier Schlüssel hat einen Array als Wert. Somit hat das JSON-Objekt einer Custom-Logik folgenden Aufbau:
{ "Level": [] , "Module": [], "Input": [], "Output": [] }
In welcher Reihenfolge die vier Schlüssel im JSON-Objekt erwähnt werden, spielt keine Rolle und ist Geschmackssache des jeweiligen Anwenders. Einige Anwender stellen bspw. Input und Output an den Anfang; andere stellen die Module vorab, weil dort die meisten Änderungen gemacht werden müssen und sie auf diese Weise nicht lange scrollen müssen.
Grundsätzliches zur JSON-Datenstruktur und -Notation
Um Logikmodule zu erstellen, ist es nicht erforderlich, sich vertieft in die JSON-Notation einzuarbeiten. Grundlegende Informationen zu JSON findet sich bspw. unter https://wiki.selfhtml.org/wiki/JSON oder https://de.wikipedia.org/wiki/JavaScript_Object_Notation.
Hier sollen im Moment nur folgende Besonderheiten erläutert werden:
Alle Eigenschaftsnamen in einem Objekt müssen in doppelten Anführungszeichen (
" ") notiert werden.Folgende Typen können verwendet werden:
Null, ----------- Trifft dies zu? -----------------
Boolean (
bool; zulässige Schlüsselwörter: true und false)Ganzzahl (
integer; zulässiger Wertebereich von --------------------- bis ----------------)Fliesszahl (
float; zulässiger Wertebereich von --------------------- bis ---------------- ). Wichtiger Hinweis: Die Werte müssen immer einen Punkt enthaltenZeichenkette (
string; zulässige Zeichen sind alle Buchstaben, alle Ziffern und folgende Sonderzeichen: ------------- Welche? -----------Array: Ein Array schliesst beliebig viele durch Kommas getrennte Werte in eckigen Klammern (
[ ]) ein; jeder Eintrag kann einen beliebigen für JSON zugelassenen Typ annehmen.Objekt: Ein Objekt wird in geschweiften Klammern (
{}) eingeschlossen. --------- Objekte werden bei der Erstellung von eigenem Code nicht benötigt. ----------
Variablen werden über einen String, der mit einem
$beginnt, bezeichnet. Über den Variablenname kann man sich innerhalb von “Module”, “Input” und “Output” auf den Wert dieser Variable beziehen.Spezialfall bei den Variablen: Damit bei der Kodierung die Zahl der Eingangsvariablen offengehalten werden kann, kann eine ------Multivariable------ definiert werden. Auf diese Weise kann in der grafischen Oberfläche durch Klick auf + (mehrfach) mehrere Variablen von diesem Typ als Eingang hinzugefügt werden.
Bei der Definition einer ----- Multivariablen----- gibt es zwei Varianten:$VAR<name?>: Mehrfache, aber optionale Verwendung (0 .. n), d.h. die Variable kann auch weggelassen werden.$VAR<name!>: Mindestens einmalige, optional mehrfache Verwendung (1 .. n).
…..
- Die mit ------- gekennzeichneten Textstellen prüfen, resp. Fehlendes ergänzen Stefan Werner
Kommentare
Um die Lesbarkeit des Codes zu verbessern, empfiehlt es sich, Kommentare zu verwenden. Um Text als Kommentar zu kennzeichnen, stehen in JSON verschiedene Möglichkeiten offen:
Am Ende einer Zeile: Kommentar mit "//" beginnen
["Comparator", "$Zaehler", "$Test", "$Endwert"], // Prüfen, ob Zaheler über Endwert liegt
Innerhalb einer Zeile oder über mehrere Zeilen hinweg: Kommentar mit "/*" und "*/" eingrenzen
/* * Dieses Logik-Modul stellt eine Beleuchtungssteuerung zur Verfügung. */ ["Latch","$Start","$Zaehler","-$Test"/* Wichtig: Negation */,0],
Wie in anderen Programmiersprachen kann über Kommentar-Kennzeichnungen nicht nur der Code erläutert werden, sondern es können auch Code-Zeilen (vorübergehend) “ausgeschaltet” werden. Dies kann die Fehlersuche erleichtern.
Level-Array:
Der Level-Array dient der Deklaration von Variablen. Es müssen hier sämtliche Variablen deklariert werden, die im Logikmodul angewendet.
Variable dienen vor allem folgenden Zwecken:
Austausch von Informationen zwischen den Modulen, In-und Output;
Ablaufsteuerung innerhalb des Moduls, indem einer Variable abhängig vom erfüllen einer Bedingung einen bestimmten Wert zugewiesen wird (Beispiele siehe ….)
Verwendung als Konstante, um bestimmte fixe Werte in den Modulen zu verwenden.
- Verlinkung mit Beispielen Diego Clavadetscher
Es gilt folgende Syntax:
"Level": [ [<Variablenname>, <Typ>, <Init value>], ... ]
Zu den einzelnen Syntax-Elementen:
Variablenname: String, der mit einem
$beginnt.Typ: Zulässig sind
bool,float,integeroderstringInit value: Weist der Variablen ein Default-Wert zu, der bis zum ersten Beschreiben der Variable gültig ist. Der Wert muss zum Typ passen!
Modul-Array:
Im Modul-Array werden die Variablen mit den Ein- und Ausgängen der Modulbausteinen verknüpft und so die eigentliche(n) Funktion(en) des Logiksmoduls definiert.
Es gilt folgende Syntax:
Modul": [ [<Basis-Modul>, <spezifische Parameter des Basis-Moduls> ], ... ]
Zu den einzelnen Syntax-Elementen:
Basis-Modul: Bezeichnung des Modulbausteins, die Auswahl hängt von der Software-Version des TWS ab. Die Liste der vorhandenen Befehle findet sich hier .
Spezifische Parameter des Basis-Moduls: siehe
Die Basis-Module sind vorgegebene (kompilierte) Funktionen . Die Auswahl hängt von der Software-Version des TWS ab.
Die genaue Beschreibung jedes einzelnen Basis-Moduls und dessen Parameter erfolgen in einem eigenen Abschnitt.Unter: app.php/kb/viewarticle?a=115 sind die wichtigsten Standardbausteine mit einer exemplarischen Modul-Definition aufgeführt.
Variablen können vorangestellten Minus bei der Übergabe in ein Modul direkt invertiert werden. Beim Typ boolean verhält sich das Minuszeichen wie ein NOT, und bei float und integer wie ein *(-1).
Achtung: Diese Syntax ist nur bei den Referenzen im "Modul"-Block erlaubt (nicht bei "Input" oder "Output)!CODE:
"Module":[ ["And",["$In","-$Limit_ON"],"$Delayed_ON"], ],Hinweis:
In den Funktionen sind aktuell nur Variablen, die im Abschnitt Level definiert wurden erlaubt. Es können keine Parameter als Zahl eingeben werden!
Ausnahme ist, wenn ein Ausgangswert nicht weiter verwendet wird. Dann kann anstelle eines Verweises (String beginnend mit $) auf den Level auch der Zahlenwert 0 eingesetzt werden; man spart sich so eine Definition in den Levels. Beispiel:
Statt: ["Statistic",["$VAR<Helligkeit!>"],"$Stat_Min","$Stat_Max","$Stat_Mean","$Stat_Median"]
So: ["Statistic",["$VAR<Helligkeit!>"], 0,"$Stat_Max","$Stat_Mean","$Stat_Median"]Alle Module (mit Ausnahme des Moduls "Break") werden in der Reihenfolge, wie sie in der Liste stehen, ausgeführt.
Das Modul "Break" nimmt eine Sonderstellung ein. Es wertet seine 0..n Eingänge aus und bricht die weitere Abarbeitung der Logikzelle ab, falls einer der Eingänge true ist. Auch das Senden der Outputs wird unterdrückt. Break ist daher nicht geeignet, wenn beim Sperren ein definierter Zustand zB schließen eines Ventils gewünscht ist!
Input-Array:
Im Abschnitt Input werden die Variablen mit den Eingängen der Custom-Logikzelle verknüft.Es gilt folgende Syntax:
"Input": [ [<Name>, <Beschreibung>, <Variablenname>, <Trigger-Option> ], ... ]Der Name ist ein String, mit dem der Eingang in der GUI angezeigt wird.
Die Beschreibung wird bei "Mouse over" angezeigt.
Der Variablenname bestimmt, welche Variable mit den Eingang verknüpft ist.
Die Trigger-Optionen bestimmen, wann ein Signal am Eingang die Berechnung der Logikzelle anstößt. Mögliche Optionen:"a": jedesmal (always)
"c": nur bei Wertänderung (on change)
"u": kein Trigger, nur Wertübernahme nach Level (update only)
Output-Array:
Im Abschnitt Output werden die Variablen mit den Ausgängen der Custom-Logikzelle verknüft.Es gilt folgende Syntax:
"Output": [ [<Name>, <Beschreibung>, <Variablenname>, <Sende-Option> ], ... ]Der Name ist ein String, mit dem der Ausgang in der GUI angzeigt wird.
Die Beschreibung wird bei "Mouse over" angezeigt.
Der Variablenname bestimmt, welcher Variable mit den Ausgang verknüpft ist.
Die Sende-Optionen bestimmen, wann ein Wert am Ausgang gesendet wird. Mögliche Optionen:"a": jedesmal (always)
"c": nur bei Wertänderung (on change)
"t": wenn ein Timer abgelaufen ist (on timer)
0 Kommentare