Logikbausteine (allgemein)***r-0Entwicklung von Logikbausteinen***r-0-0Quelltext

Das Grundgerüst eines LBS besteht aus 4 Abschnitten (die Reihenfolge der einzelnen Abschnitte ist unerheblich):

Abschnitt [DEF]

Hier wird der Name des LBS definiert, sowie seine Ein- und Ausgänge und ggf. seine Variablen: Beispiel:
###[DEF]###
[name = UND-Gatter 2xEingänge]

[e#1 = A]
[e#2 = B #init=0]
...

[a#1 = Ausgang]
[a#2 = 0/1]
...

[v#1 = 123]
[v#2 = 0]
...
###[/DEF]###
Ein LBS kann beliebig viele Eingänge, Ausgänge und Variablen enthalten. "Whitespace" (Leerzeichen) innerhalb der Deklaration wird ignoriert - [name=(Name)] führt zum gleichen Ergebnis wie [ name = (Name) ]. Im Anschluss an eine Deklaration kann bei Bedarf ein Hilfetext angegeben werden:
###[DEF]###
...
[e#1 = A] Hinweis: Dies ist Eingang A
...
###[/DEF]###
Der Hinweistext darf keine eckigen Klammern enthalten! Variablen beziehen sich auf genau eine LBS-Instanz, d.h. mehrere LBS gleichen Typs beeinflussen sich nicht hinsichtlich deren Variablen. Die Variablen halten einen Wert solange, bis EDOMI beendet bzw. neu gestartet wird. Variablen und Initialwerte vom Typ String werden genau wie Zahlen ohne(!) Anführungszeichen deklariert (Zeichenketten und Zahlen werden intern nicht unterschieden). Wichtig: Eine Deklaration darf keine eckigen Klammern oder HTML-Tags enthalten, z.B. wäre [e#1 = [Test]] keine gültige Deklaration, [e#1 = Test] wäre hingegen gültig. Bei Bedarf müssen HTML-Entities/Unicode-Symbole verwendet werden.

Besonderheiten bei der Deklaration von Eingängen

Eingänge können ggf. mit einem Initial- bzw. Fixwert vorbelegt werden:
[e#1 = Eingang1 #init=EDOMI]
Zudem können Eingänge individuell farblich kodiert werden, der Eingang wird dann im Logikeditor entsprechend farblich hervorgehoben:
[e#1 trigger|option|important = Eingang1]
Standardmäßig werden Eingänge in weiß dargestellt. Die Option "trigger" stellt den Eingang in grün dar, "option" führt zu einer Darstellung in grau, "important" stellt den Eingang in orange dar. Wichtig: Die Farbkodierung hat keinerlei Einfluss auf die Funktionsweise des Logikbausteins, sondern dient lediglich einer besseren Übersichtlichkeit im Logikeditor.

Abschnitt [HELP]

Hier sollte der LBS kurz beschrieben werden, sowie die Bedeutungen der Ein- und Ausgänge erläutert werden. Der Hilfetext kann HTML-Tags enthalten (z.B. Tabellen oder Listen). Beispiel:
###[HELP]###
(Hilfetext)
###[/HELP]###

Abschnitt [LBS]

In diesem Abschnitt wird die Funktionalität des LBS implementiert. Hier kann prinzipiell beliebiger PHP-Code verwendet werden. Wichtig: Es ist unbedingt zu bedenken, dass dieser Code im Kontext des EDOMI-Hauptprozesses ausgeführt wird und daher die gesamte Logik-Engine während der Ausführung des LBS-Codes blockiert ist. Der Code ist daher so effizient und "zeitsparend" wie möglich zu implementieren. Funktionen, die eine gewisse Latenz aufweisen (z.B. eine HTTP-Abfrage), müssen daher auf eine besondere Art und Weise implementiert werden (siehe Abschnitt [EXEC]). Die Funktionalität z.B. eines Timers darf nicht(!) in Form einer Warteschleife implementiert werden, sondern muss mittels LBS-Variablen und entsprechenden Zeitvergleichen bereitgestellt werden. Das Grundgerüst muss stets diese Hauptfunktion bilden: function LB_LBSID($id) {...} Beispiel:
###[LBS]###

###[/LBS]###
$id repräsentiert nicht(!) die LBS-ID (Dateiname), sondern die interne ID der LBS-Instanz(!). Diese Funktion muss den gesamten Code des LBS beinhalten. Zusätzlich(!) können bei Bedarf weitere Hilfsfunktionen deklariert werden, außerdem können auch isolierte PHP-Scripte erzeugt werden (siehe Abschnitt [EXEC]). Innerhalb des Abschnitts [LBS] können bei Bedarf lokale (nur für diesen LBS gültige) Hilfsfunktionen deklariert werden. Eine solche Hilfsfunktion muss diesem Namensschema folgen:
function LB_LBSID_FUNKTIONSNAME($id,...) {...}
Die LBS-Instanz-ID $id sollte stets übergeben werden, damit die Hilfsfunktion ggf. auf die globalen LBS-Funktionen zugreifen kann. Der Aufruf der Hilfsfunktion erfolgt dann mit:
LB_LBSID_FUNKTIONSNAME($id,...)
Als nächstes wird i.d.R. die aktuelle Belegung der Eingänge des LBS in ein Array übergeben:
if ($E=logic_getInputs($id)) {...}
Das (2-dimensionale) Array $E[Eingangs-ID][Wert] enthält nun u.a. folgende Einträge (hier am Beispiel des Eingangs Nr. 1):
$E[1]['value']: der aktuelle Wert am Eingang
$E[1]['refresh']: 1=der Eingang wurde refreshed, 0=der Eingang wurde nicht refreshed
Damit ein LBS überhaupt "startet", muss mindestens ein Eingang des LBS getriggert werden. $E[1]['refresh']=1 bedeutet, dass (mindestens) dieser Eingang durch ein Ereignis (z.B. ein eintreffendes Telegramm eines KOs) getriggert worden ist.

Abschnitt [EXEC]

Bei Bedarf kann zusätzlich zum normalen LBS-Code ein PHP-Script erstellt werden, das vom LBS als eigener Prozess gestartet werden kann. Dies ist sinnvoll, um z.B. eine HTTP-Abfrage zu implementieren (Ausführungszeit) oder um externe Programme auszuführen. Beispiel:
###[EXEC]###

###[/EXEC]###
Es können alle grundlegenden Funktionen genutzt werden, die auch im Abschnitt [LBS] zu Verfügung stehen. Eigene deklarierte Hilfsfunktionen im Abschnitt [LBS] können jedoch nicht(!) genutzt werden, da diese nur lokal für den Abschnitt [LBS] zu Verfügung stehen. Achtung: Die o.g. Funktionen greifen intern auf eine mySQL-Datenbank zu. Die mySQL-Engine trennt jedoch die Verbindung, sobald länger als 8 Stunden keinerlei Zugriff erfolgt - der Aufruf der o.g. Funktionen wird dann scheitern! Es ist daher ggf. dafür zu sorgen, dass z.B. stündlich ein mySQL-Zugriff erfolgt, um die Verbindung aufrecht zu erhalten. Die kann z.B. durch einen zyklischen Aufruf (z.B. alle 60 Minuten) der Funktion setLogicKeepAlive()***r-0-3 erfolgen. Wichtig: Die LBS-Instanz-ID $id steht auch im Abschnitt [EXEC] zu Verfügung. Hinweis: Das EXEC-Script wird als eigene PHP-Instanz ausgeführt. Der LBS-Code im Abschnitt [LBS] hat nach dem Aufruf keine(!) Kontrolle mehr über das EXEC-Script, d.h. der Code des EXEC-Scripts muss sich selbst verwalten. Wenn EDOMI beendet oder neu gestartet wird, werden alle laufenden EXEC-Scripte unmittelbar beendet (die Prozesse werden abgebrochen).