edit doku

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`.