4.4.7.2 Wiregate Plugins - Hinweise, Syntax, etc.

Beschreibung: Auszug aus der Hilfe des Wiregate-Servers zu den Plugins

Kategorie: Logiken, Docker

Link zu diesem Beitrag: Alles auswählen

[url=https://forum.timberwolf.io/app.php/kb/viewarticle?a=103&sid=a00a8a9d81970433e9ed5efee1ac734c]Knowledge Base - 4.4.7.2 Wiregate Plugins - Hinweise, Syntax, etc.[/url]

Funktionsreferenz:
  • Es werden hier nur die gängigsten Befehle beschrieben
  • Parameter in [] sind optinal mit =Defaultwert
knx_write( <Gruppenadresse>,<Wert>,[DPT],[Response])
Beispiel: knx_write("1/2/3","10","5");
-> schreibt Wert 10 als DPT5 auf Gruppenadresse 1/2/3
DPT kann weggelassen werden, falls es in der globalen Konfiguration "eibga.conf" richtig eingetragen/importiert ist.
Wenn Response angebeben ist (1, y, j) wird statt einem A_GroupValue_Write ein A_GroupValue_Response gesendet.

knx_read( <Gruppenadresse> ,<maxAlterInSekunden> ,[DPT] )
Beispiel: knx_read("1/2/3",300,"5.010");
-> liest aus dem Gruppenadressen-Cache den letzten Wert der Gruppenadress 1/2/3 als DPT 5.010
Falls der Wert nicht im Cache ist oder Alter > 0 (in Sekunden) und der Wert im Cache älter als die Angabe, wird ein Lesetelegramm auf den Bus gesendet.
Wenn binnen einer Sekunde eine Antwort eintrifft wird der Wert zurückgegeben, falls nicht, erfolgt bei weiteren Leseversuchen kein erneuter Versand eines Lesetelegramms!
DPT kann weggelassen werden, falls es in der globalen Konfiguration richtig eingetragen/importiert ist.
Wichtig: Niemals zum lesen eines "lokalen" Wertes verwenden (1-Wire Sensor, anderes Plugin), der nicht im Cache ist, da sich das gegenseitig blockiert!

update_rrd("Name","Suffix",Wert,"Wert-Typ") / GAUGE
Beispiel: update_rrd("externe_Temperatur1","",20,"GAUGE");
-> Schreibt den Wert 20 in das RRD mit dem Namen "externe_Temperatur1", falls das RRD nicht existiert wird es als Typ GAUGE angelegt.
(bei einem echten Wert wird man anstelle von 20 natürlich eine soeben gelesene Variable eintragen)
Wichtig: Für interne 1-Wire-Werte ist dies nicht notwendig, die RRD-Dateien werden bereits intern erstellt!
update_rrd("Name","Suffix",Wert,"Wert-Typ","RRD-Steps","RRA-Steps") / COUNTER
Beispiel: update_rrd("Zaehler1","",20,"COUNTER",24,7);
Es gibt auch noch die Typen "COUNTER" (uvm.), der übergebene Typ wird jedoch nur beim initialen anlegen berücksichtigt!
"RRD-Steps" Standart-Wert: 24
"RRA-Steps" Standart-Wert: 7

#COMPILE_PLUGIN
Vorkompilieren von WG-Plugins für höhere Performance.
Detail Beschreibungen finden Sie hier.

Variablen:
  • $plugname ist vorbelegt mit dem Namen des Plugins.
  • %plugin_subscribe
    Anmelden an einer Gruppenadresse:
    $plugin_subscribe{'<Gruppenadresse>'}{$plugname} = 1;
  • %plugin_info
    Hash, dessen Inhalt/Werte dauerhaft im Flash gespeichert wird. z.B. zum Speichern von Zuständen. Folgende Einträge sind u.a. zur Diagnose reserviert
    $plugin_info{$plugname.'_cycle'} : Aufrufzyklus des Plugins
    $plugin_info{$plugname.'_memstart'} : Hilfswert zur Berechung von '_meminc'
    $plugin_info{$plugname.'_meminc'} : Speicherverbrauch in MB
    $plugin_info{$plugname.'_ticks'} : ansteigender Zähler: CPU-Zyklen
    $plugin_info{$plugname.'_timeout_err'} : Anzahl der Abbrüche seit dem letzten Abspeichern des Plugins
    $plugin_info{$plugname.'_lastsaved'} : Zeitpunkt des letzten Abspeichern des Plugins
    $plugin_info{$plugname.'_lastcalled'} : Zeitpunkt vor dem letzten Aufrufs des Plugins
    $plugin_info{$plugname.'_last'} : Zeitpunkt nach dem letzten Aufrufs des Plugins
  • $msg: Hash mit eingetroffenem KNX-Telegramm
Rückgabewerte:
Wenn der Funktion return ein Wert übergeben wird, erfolgt ein Eintrag in der Plugin-Logdatei.
Wenn kein Wert (return;)angegeben wird, erfolgt auch kein Logeintrag.

Die Plugins werden jeweils mit "eval" direkt ausgeführt. Compilerfehler werden ggfs. direkt ausgegeben.

Start/Zyklus/Aufrufverhalten
Der Aufruf eines Plugins erfolgt:
  • Nach jedem Neustart des Daemons (wiregated), also bei reboot, Konfigurationsänderung etc.
  • Sofort nach dem speichern eines Plugins (egal ob per Web oder anders)
  • Nach dem eingestellten Zyklus. Standard: 10s falls nicht anders vom Plugin selbst definiert (_cycle)
  • Beim eintreffen von KNX-Telegrammen soweit "angemeldet" (plugin_subscribe)
  • Beim anliegen von Daten auf einem Socket soweit "angemeldet" (plugin_socket_subscribe). Dazu später mehr..
  • Der Aufruf von Plugins erfolgt max. 1x pro Sekunde
  • Langlaufende Operationen sind zu vermeiden, da sonst alle Aktivitäten blockiert werden. Der Timeout beträgt 10s - länger darf ein einzelnes Plugin nicht laufen.
Timeout Fehler
In dem %plugin_info hash wird für jedes Plugin gezählt, wie oft der WireGate Serverprozess abgebrochen wurde, weil das Plugin zu lange gelaufen ist. Dieser Zähler wird auf 0 gesetzt, wenn das Plugin geändert wird. Da während eines Neustarts des WireGate Serverprozesses Telegramme verloren gehen können, sollten keine langlaufenden Operationen in den Plugins durchgeführt werden.
Auf der Plugin-Seite wird angezeigt, wie oft jedes Plugin seit seiner letzten Änderung den WireGate Serverprozess abgebrochen hat. Kamen solche Abbrüche vor kurzem vor, wird in einer weiteren Tabelle die Anzahl der verursachten Abbrüche innerhalb des angegebenen Zeitsraums angezeigt.

Warnungen loggen
Standardmäßig werden Warnungen bei der Ausführung eines Plugins in die Plugin-Logdatei geschrieben. Um das Loggen abzuschalten, muß 'Warnungen loggen' deaktiviert und anschließend 'speichern' selektiert werden. Der WireGate Serverprozess wird dann neu gestartet und alle Plugins schreiben keine Warnungen mehr in die Plugin-Logdatei.
Wenn 'Warnungen loggen' hier auf aktiv geschaltet ist, können in den einzelnen Plugins durch folgende Zeile die Warnungen aktiviert/deaktiviert werden:
#keine Warnungen
no warnings;
#alle Warnungen
use warnings;

Erklärung zu einigen Warnungen:
Warning: Subroutine ... redefined:
Werden in nicht vorkompilierten Plugins Subroutinen verwendet, wird bei allen Aufrufen, außer dem ersten nach Start des WireGate Serverprozesses, diese Warnung ausgegeben, da das Plugin bei jedem Aufruf evaluiert und die Subroutinen dann neu definiert werden.
In vorkompilierten Plugins wird diese Warnung nach Änderung des Plugins einmal ausgegeben.
Warning: Variable ... is not available
In vorkompilierten Plugins können Subroutinen nicht auf die Variablen des Plugins zugreifen, da das Plugin als anonyme Subroutine aufgerufen wird, die erst zur Laufzeit kompiliert wird. Die Subroutinen werden schon vorher erzeugt. Benötigte Variablen müssen der Subroutine daher als Parameter übergeben werden.
Häufige Fehler&Probleme

Allgemeine Hinweise:
Geeignete Anwendungsfälle:
Einfache Logikfunktionen, Regler etc.
Einbindung von "Sonderfunktionen", speziellen Kundenwünschen.

Eher ungeeignet für:
Komplexe Logikzusammenhänge
Zeit/Resourcenintensive Vorgänge

Am einfachsten dürften die Plugins durch die Betrachtung eines Beispiels zu erlernen sein, Grundwissen in der Programmiersprache Perl ist jedoch notwendig!
Umlaute und Sonderzeichen soweit möglich vermeiden.
Um die Betriebssicherheit zu gewährleisten, werden Plugins nach 10 Sekunden abgebrochen! Passiert dies fünf mal in Folge, wird das Plugin bis zum nächsten Neustart des Dienstes oder speichern nicht mehr aufgerufen.

Wichtig: Niemals sollte man aus einem Plugin etwas aus einem anderen Plugin per knx_read lesen, denn dies führt zu einer Blockade.
(ausser mit Alter 0 aus dem Cache oder - besser - den Wert über die Globale Variable $plugin_info)