Übersicht Scriptprogrammierung

Mit diesem Funktionsbaustein können eigene Scripte in Hochsprache programmiert werden. Als Interpreter wird Lua (www.lua.org) eingesetzt. In dieser Beschreibung wird nur auf die Spracherweiterungen eingegangen.


Eingänge

E1-x
 Eingang 1-x
 Eingänge. Diese können im Script über die globalen Variablen E1, E2 usw. angesprochen werden. Zur besseren Übersicht können diesen auch Alias Namen zugeordnet werden.



Ausgänge
A1-Ax
 Ausgang 1-x
 Ausgänge. Diese können im Script über die globalen Variablen A1, A2 usw. angesprochen werden. Zur besseren Übersicht können diesen auch Alias Namen zugeordnet werden.



Parameter
Anzahl Eingänge
 Anzahl der Eingänge
Anzahl Ausgänge
 Anzahl der Ausgänge
Eventfilter
 Standardmäßig werden Events bzw. Telegramme nur an den Funktionsbaustein weiter geleitet wenn die entsprechenden Variablen an den Ein- oder Ausgängen verknüpft sind, durch Ausschalten dieses Filters werden alle Events an den Funktionsbaustein weitergeleitet. Bitte beachten Sie, dass die Bearbeitung aller Events bei großen Projekten mehr Bearbeitungszeit in Anspruch nimmt, der Filter sollte daher nur deaktiviert werden wenn dies nötig ist.
Passwort Optional kann ein Passwort vergeben werden. Das Script kann dann nur mit gültigen Passwort bearbeitet werden. Bitte beachten: Es gibt keine Möglichkeit das Passwort zurückzusetzen.
Bearbeiten
 Klicken Sie auf diesen Button um das Script zu bearbeiten, alternativ kann auch mit der rechten Maustaste auf den Funktionsbaustein geklickt werden.


Bearbeitungsfenster

Mit Klick auf den Parameter Bearbeiten oder mit Klick mit der rechten Maustaste auf den Funktionsbaustein wird der Dialog zur Bearbeitung des Scriptes angezeigt:



Dieser Dialog gliedert sich in folgende drei Bereiche:

  1. Script: Hier wird das Script bearbeitet.
  2. Konsole: In diesem Fenster werden alle Ausgaben des Interpreters angezeigt, beispielsweise Info- und Fehlermeldungen oder Meldungen die über den Funktionsaufruf "sys_debug_print" ausgegeben werden.
  3. Variablen: In diesem Fenster wird der Wert von internen Variablen ausgegeben. Anders als im Fenster Konsole ist die Ausgabe nicht fortlaufend sondern in einer Tabelle. Welche Variablen hier angezeigt werden, wird mit dem Funktionsaufruf "sys_debug_watch" definiert.
Wichtig: Damit Meldungen oder Variablen ausgegeben werden, muss die Play Taste gedrückt sein. Mit Klick auf speichern wird das Script an die Steuerung übertragen und sofort ausgeführt, jedoch nur wenn sich die Play Taste gedrückt ist:




Standardmäßig gibt es nur die Funktion "onInputChanged()" im Script. Diese wird beim Start aufgerufen und wenn sich etwas an den Eingängen geändert hat. Für die meisten Anwendungen ist das auch ausreichend. Über den Menü Button können noch weitere Systemfunktionen hinzugefügt werden. Diese sogenannten Callback Funktionen werden im folgenden beschrieben:

Wichtig:


onCreate()
 Diese Funktion wird einmalig aufgerufen wenn der Funktionsbaustein initialisiert wird. Hier können beispielsweise Initialisierungen von globalen Variablen definiert werden.
onInputChanged()
 Diese Funktion wird aufgerufen wenn die Initialisierung beendet ist (nach onCreate), oder sich die Eingängen geändert haben. Zudem wird diese Funktion bei jedem Telegramm aufgerufen (auch wenn sich die Eingänge nicht geändert haben).
onEvent(Value,PhysAddress,GroupAddress,Command)
 Diese Funktion wird aufgerufen wenn ein Telegramm empfangen wurde, beispielsweise eine KNX Variable welche am Eingang verknüpft wurde. Standardmäßig werden nur Telegramme an das Script weitergeben welche an den Eingängen verknüpft wurden, dies kann mit dem Parameter "Eventfilter" deaktiviert werden.

Folgende Argumente werden der Funktion übergeben:

  • Value: Wert
  • PhysAddress: Quelladresse im Format "0.0.1"
  • GroupAddress: Zieladresse im Format "0/0/1"
  • Command: Befehle, WRITE, RESPONSE, READ
Wichtig: Diese Funktion sollte nur verwendet werden wenn auch wirklich auf Telegramme reagiert werden muss, beispielsweise KNX Telegramme. Wenn möglich sollte die Funktion onInputChanged verwendet werden. Bei Aktivierung von onEvent werden die Telegramme zum Interpreter weiter geleitet was eine höhere Auslastung der Steuerung bei großen Projekten zur Folge hat.
onTimerEvent100ms() Diese Funktion wird alle 100 ms aufgerufen
onTimerEvent1s()
 Diese Funktion wird 1x pro Sekunde aufgerufen.
onTimerEvent1m()
 Diese Funktion wird 1x pro Minute aufgerufen. Der Aufruf erfolgt immer am Beginn jeder Minute.
onTimerEvent1h()
 Diese Funktion wird 1x pro Stunde aufgerufen. Der Aufruf erfolgt immer am Beginn jeder Stunde.
onGlobalChanged(Id,Value) Diese Funktion wird aufgerufen wenn über sys_set_global_value eine globale Variable verändert wurde.
onOsExecuteFinished(Id,Result) Diese Funktion wird aufgerufen wenn der über sys_os_execute aufgerufene Befehl ausgeführt wurde. Id ist die Id welche von sys_os_execute übergeben wurde, Result ist das Ergebnis, 0=Kein Fehler, ansonsten ein Fehlercode abhängig vom Befehl der aufgerufen wurde.
onNetRead(DataString,SizeString,DataHex,SizeHex) Funktion wird aufgerufen wenn Daten über eine Netzwerkverbindung empfangen wurden. Die Daten werden jeweils als String und Hexadezimal String übergeben.
onNetState( State, Message ) Funktion wird aufgerufen wenn sich der Netzwerk Status ändert:

  • -1: _STATE_CREATE_ERROR
  • -2: _STATE_CONNECT_ERROR
  • -3: _STATE_ERROR_READ
  • 1: _STATE_CREATE_OK
  • 2: _STATE_CONNECT_OK


Systemaufrufe


Folgende Systemaufrufe sind zurzeit integriert.



sys_set_value("0/0/0",Value,Force)
 Schreiben einer beliebigen Variable:

Die Variable wird nu gesendet wenn sich der Wert geändert hat. Dadurch kann die Funktion auch zyklisch aufgerufen werden.

  • Value: Wert
  • Force: Wenn 1 wird die Variable immer gesendet, auch wenn sich der Wert nicht geändert hat, bei 0 nur wenn sich der Wert geändert hat.
sys_get_value("0/0/0")
 Abfrage des Wertes einer Variable

  • Als Argument wird die Adresse in der Form "0/0/0" übergeben.
sys_debug_print("Name: ",Value)
 Ausgabe eines Textes in der Konsole. Bei jedem Aufruf wird eine neue Zeile in der Debug Konsole ausgegeben, dies kann beispielsweise verwendet werden um zu prüfen ob eine Funktion aufgerufen wurde. Der Funktion werden zwei Argumente über geben:

  • Name: Beliebiger Text
  • Value: Beliebige Wert (Texte müssen in Anführungszeichen gesetzt werden)
sys_debug_watch("Name: ",Value)
 Ausgeben des Wertes einer Variable.

Der Funktion werden zwei Argumente über geben:

  • Name: Eindeutige Bezeichnung
  • Value: Beliebige Wert (Texte müssen in Anführungszeichen gesetzt werden)
Alle Aufrufe von z.B. "sys_debug_watch("V1",Value)" werden in einer separaten Zeile im Variablen Fenster ausgegeben. Dies kann dazu verwendet werden um den Wert einer Variable zu überwachen. Bitte beachten Sie, dass die Variable im Variablen Fenster nur aktualisiert wird wenn diese Funktion aufgerufen wird.
sys_alias("E1","Wert_xy")
 Mit dieser Funktion kann einem Ein- oder Ausgang ein symbolischer Name zugewiesen werden. Diese werden dann auch im Fenster für die Verknüpfungen angezeigt.

Wichtig: Alias müssen in der Funktion "onCreate()" definiert werden. Die Alias Namen dürfen keine Leer , Umlaute oder Sonderzeichen enthalten. Wenn einem Ausgang ein Alias Name zugewiesen wurde, muss dieser verwendet werden, Alias Name hat Vorrang vor A1 usw.

  • sys_alias("E1","Außentemperatur"): Weist dem ersten Eingang den Namen "Außentemperatur" zu, dieser kann im folgenden Script dann als "Außentemperatur" angesprochen werden. Beispielweise if ( Außentemperatur > 10 ).
  • sys_alias("A1","Sollwert"): Weist dem Ausgang A1 den Namen "Sollwert" zu, dieser kann im folgenden Script dann am "Sollwert" angesprochen werden. Beispielsweise "Sollwert = 10".
sys_get_addr_in(1)
 Liefert die Adresse der verknüpften Variable eines Einganges im Format "1/2/3" zurück, 1 ist hierbei E1 usw.
sys_get_addr_out(1) Liefert die Adresse der verknüpften Variable eines Ausganges im Format "1/2/3" zurück, 1 ist hierbei A1 usw.


sys_set_persistent_value("Id","Value")
 Mit dieser Funktion können beliebige Daten in den persistenten Bereich der Steuerung gespeichert werden. Anders als die Funktion sys_set_value können mit dieser Funktion beliebige Werte unabhängig vom Datentyp einer Variable gespeichert werden.

Wichtig: Die Steuerung ist mit einem Flash Speicher ausgestattet der nicht beliebig oft beschrieben werden darf. Diese Funktion darf daher nicht zu oft aufgerufen werden. Ständiges speichern persistenter Werte verkürzt die Lebensdauer des Flash Speichers und führt zum Defekt bzw. Datenverlust.
sys_get_persistent_value("Id","DefaultValue") Mit dieser Funktion können die persistenten Werte wieder ausgelesen werden.
sys_set_global_value("Id","Value",force) Setzen einer globalen Variablen. Mit dieser Funktion können globale Variablen verwendet werden. Über diese können mehrere Instanzen des  Interpreters kommunizieren. Beispielsweise mehrere Script Funktionsbausteine ohne Variablen verwenden zu müssen.

Als Parameter wird eine eindeutige Id und der Wert übergeben, optional der Parameter force ( 1 oder 0 ).

Bei Änderung eines Wertes, wird an allen Funktionsbausteinen die Callbackfunktion "onGlobalChanged" aufgerufen, ausgenommen der Baustein der den Wert geändert hat. Ist der Parameter force mit 1 angegeben, wird die Funktion "onGlobalChanged" immer aufgerufen, auch wenn sich der Wert nicht geändert hat.
sys_get_global_value("Id","DefaultValue") Lesen der globalen Variablen.


id = sys_os_execute() Aufruf eines externen Programms. Dieser Aufruf ist ähnlich dem Lua Befehl "os.execute", jedoch wird der Befehl im Hintergrund ausgeführt und blockiert das Script nicht. Nach der Ausführung wird die Callback Funktion onOsExecuteFinished aufgrufen.
sys_send_mail() Senden einer Mail

  1. Empfänger. mehrere Empfänger können mit Semikolon getrennt angegeben werden
  2. Betreff
  3. Inhalt
  4. Anhang. Optionaler Anhang, mehrere Dateinamen können mit Semikolon getrennt angegeben werden. Der Pfad muss vollständig angegeben werden.

id = sys_timer_create() Erzeugt einen Timer. Bevor Timer verwendet werden können, müssen diese zuerst initialisiert werden. Diese Funktion gibt eine ID zurück, welche für alle weiteren Funktionen als Parameter verwendet wird.
sys_timer_start(id,timeMs) Startet den Timer.
sys_timer_stop(id) Stoppt den Timer.
sys_timer_elapsed(id) Gibt die Zeit seit dem Start des Timers in Millisekunden zurück.
sys_timer_finished(id) Gibt 1 zurück wenn die Zeit welche mit "sys_timer_start" angegeben wurde abgelaufen ist.



sys_comm_open("/dev/ttyONBOARD-232","115200","8","1","N") Mit dieser Funktion wird die serielle Schnittstelle initialisiert.

  1. Name der Schnittstelle. /dev/ttyONBOARD-232 = RS232, /dev/ttyONBOARD-485 = RS485
  2. Baudrate
  3. Datenbit, 7 oder 8
  4. Stopbits, 1 oder 2
  5. Parity, N=ohne, E=even, O=odd
Rückgabe 1 wenn erfolgreich, 0 bei Fehler.
sys_comm_close() Port wird geschlossen.
len,dataString = sys_comm_read(len,timeout,"_ASCII") Liest Daten von der Schnittstelle

  1. Anzahl der Bytes die gelesen werden sollen
  2. Timeout in Millisekunden
  3. Format. _ASCII als String, _HEX in hexadezimaler Schreibweise (bei binären Daten).
Rückgabe

  1. len = Anzahl der Datenbytes
  2. dataString = Daten als String
Wichtig: Diese Funktion blockiert solange bis die Anzahl der Bytes empfangen wurde oder das Timeout eintritt.
sys_comm_write(len,data,"_ASCII") Sendet Daten zur Schnittstelle

  1. Länge der Daten die an der Schnittstelle ausgegeben werden. Normalerweise ist dies die Länge des Strings. Wird _HEX verwendet ist dies die Hälfte da zwei Zeichen ein Datenbyte darstellen.
  2. Daten
  3. Format, _ASCII als String, _HEX in hexadezimaler Schreibweise (bei binären Daten).
Rückgabe

  1. Anzahl der gesendeten Bytes



Id = sys_net_create("_TCP",IPAddress,IPPort,Timeout) Initialisiert die Netzwerk Verbindung. Diese Funktion ist nicht blockierend. Die Verbindung wird im Hintergrund aufgebaut, der Status wird in der Callback Funktion "onNetState" zurückgegeben.
  1. Typ. "_TCP" oder "_UDP" (UDP noch Vorbereitung)
  2. IP Adresse
  3. Portnummer
  4. Timout in Millisekunden.
Rückgabe

  1. ID der Verbindung. Zurzeit ist nur eine Verbindung pro Scriptbaustein möglich. -1 bei Fehler (beispielsweise wenn Verbindung schon hergestellt).


Siehe Callback Funktionen "onNetState( State, Message )", "onNetRead( Data, Size )"
sys_net_write(Data,"_STRING") Sendet Daten zum Verbundenen Netzwerkgerät

  1. Daten. Zu sendende Daten
  2. Format, _ASCII als String, _HEX in hexadezimaler Schreibweise (bei binären Daten).

Rückgabe

  1. -1 bei Fehler, ansonsten die Länge der gesendeten Daten.
sys_net_close(Id) Schließt die Verbindung.



Siehe auch allgemeine Parameter aller Funktionsbausteine.