From 27ca31aa8c4cd3568f3851f6bf59f219cde2dc97 Mon Sep 17 00:00:00 2001 From: Bastian Schroll Date: Fri, 1 Mar 2019 17:54:58 +0100 Subject: [PATCH] edit doku --- plugin/readme.md | 83 ++++++++++++++++++++++++++++++++++++------------ 1 file changed, 63 insertions(+), 20 deletions(-) diff --git a/plugin/readme.md b/plugin/readme.md index e8db4b3..b4382a2 100644 --- a/plugin/readme.md +++ b/plugin/readme.md @@ -1,13 +1,19 @@ -## Eigene Plugins schreiben +## Eigene Module und Plugins schreiben -Um ein eigenes Plugin zu schreiben, sollte man sich am besten zuerst einmal das Plugin `template` ansehen. +Um ein eigenes Modul oder Plugin zu schreiben, sollte man sich +am besten zuerst einmal das das `template` im entsprechenden Ordner ansehen. Dies kann als Vorlage für das eigene Plugin genutzt werden. -### 1.) Informationen anpassen +### 1 Informationen anpassen - Dateikopf anpassen -- Namen des Plugins vergeben in der `__init__` Methode `super().__init__("template")` -### 2.) Benötigte Methode überschreiben +### 2 Benötigte Methoden überschreiben +#### 2.1 Modul +Die Modul Basisklasse bietet einige Methoden, welche vom Modul überschrieben werden können. +- `onLoad()` wird direkt beim Import des Moduls ausgeführt +- `doWork(bwPacket)` wird bei der Ausführung aufgerufen +- `onUnload()` wird beim Zerstören der Plugin Modul zum Programmende ausgeführt +#### 2.2 Plugin Die Plugin Basisklasse bietet einige Methoden, welche vom Plugin überschrieben werden können. - `onLoad()` wird direkt beim Import des Plugins ausgeführt - `setup()` wird vor jeder Ausführung gerufen @@ -18,24 +24,61 @@ Die Plugin Basisklasse bietet einige Methoden, welche vom Plugin überschrieben - `teardown()` wird nach jeder Ausführung gerufen - `onUnload()` wird beim Zerstören der Plugin Instanz zum Programmende ausgeführt -### 3.) Zugriff auf Config Datei -Wenn sich im Ordner des Plugins eine ini-Datei befindet, -welche exakt so wie das Plugin heißt, kann deren Inhalt -über die lokale Config-Reader Instanz -- `self.config.getBool(SECTION, KEY)` -- `self.config.getInt(SECTION, KEY)` -- `self.config.getStr(SECTION, KEY)` +### 3 Konfiguration +#### 3.1 Konfiguration anlegen +Jedes Modul oder Plugin wird in einem Router folgendermaßen deklariert: +```yaml +- type: module # oder plugin + name: template_module # Name der Python Datei + config: # config-Sektion + option1: value 1 + option2: value 2 + underOption1: value 21 + underOption2: value 22 + list: + - list 1 + - list 2 +``` -abgerufen werden. +#### 3.2 Konfiguration nutzen +Wird der Instanz eine Konfiguration übergeben wird diese in `self.config` +abgelegt und kann folgendermaßen abgerufen werden: +- `self.config.get("option1")` einzelnes Feld + - liefert `value 1` +- `self.config.get("option2", "underOption1")` verschachteltes Feld (beliebig viele möglich) + - liefert `value 21` +- `self.config.get("notSet", default="defValue")` Es kann ein Default Wert angegeben werden (wenn Eintrag in Config fehlt) + - liefert `defValue` +- `for item in self.config.get(FIELD):` Über Listen kann iteriert werden + - liefert ein Element je Durchgang - hier `list1` und `list2` -### 4.) Daten aus dem BOSWatch Paket lesen -An die Alarm Funktionen FMS, POCSAG und ZVEI wird eine Instanz eines -BOSWatch-Packet Objekts übergeben. +Wird ein End-Wert ausgelesen, wird dieser direkt zurück gegeben. +Sollten weitere Unterelemente oder eine Liste exisitieren +wird erneut ein Element der Klasse `Config()` zurück gegeben -Aus dieser kann mittels `bwPacket.get(FELDNAME)` das entsprechende Feld -ausgelesen werden. Eine Auflistung der bereitgestellten Informationen +### 4 Arbeiten mit dem bwPacket +An das Modul bzw. Plugin wird eine Instanz eines BOSWatch-Packet Objekts übergeben. + +Aus dieser kann mittels `bwPacket.get(FIELDNAME)` das entsprechende Feld +ausgelesen werden. + +Mittels `bwPacket.set(FIELDNAME, VALUE)` kann es hinzugefügt/modifiziert werden. + +Eine Auflistung der bereitgestellten Informationen findet sich im entsprechenden BOSWatch-Packet Dokument. -### 5.) Wildcards parsen +#### 4.1 Zu beachten bei Module +Module können Pakete beliebig verändern. +Diese Änderungen werden im Router entsprechend weitergeleitet. + +Mögliche Rückgabewerte eines Moduls: +- `return bwPacket` gibt das modifizierte bwPacket an den Router zurück +- `return None` Router fährt mit dem unveränderten bwPacket fort (Input = Output) +- `return False` Router stopt sofort die Ausführung (zB. in Filter verwendet) +#### 4.2 Zu beachten bei Plugins +Plugins geben keine Pakete mehr zurück. Sie fungieren ausschließlich als Endpunkt. +Die Plugin Basisklasse liefert intern immer ein `None` an den Router. + +### 5 Wildcards parsen (NUR PLUGIN) Das parsen der Wildcars funktioniert komfortabel über die interne Methode `self.parseWildcards(MSG)`. -Die Platzhalter für die Wildcards findet man in `boswatch/utils/wildcard.py` oder in der `packet.md`- +Die Platzhalter für die Wildcards findet man in `boswatch/utils/wildcard.py` oder in der `packet.md`.