add basic docu

2026-04-05 14:25:45 +00:00 · 2019-09-18 18:38:17 +02:00 · 2019-09-18 18:38:17 +02:00 · e2c8394907
commit e2c8394907
parent 438dda48c2
10 changed files with 131 additions and 348 deletions
--- a/docu/docs/develop/ModulPlugin.md
+++ b/docu/docs/develop/ModulPlugin.md
@ -0,0 +1,86 @@
+## Eigenes Modul/Plugin schreiben
+
+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 Modul oder Plugin genutzt werden.
+
+### Informationen anpassen
+- Dateikopf anpassen
+
+### Benötigte Methoden überschreiben
+#### 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
+
+#### 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
+- `fms(bwPacket)` wird bei einem FMS Paket ausgeführt
+- `pocsag(bwPacket)` wird bei einem POCSAG Paket ausgeführt
+- `zvei(bwPacket)` wird bei einem ZVEI Packet ausgeführt
+- `msg(bwPacket)` wird bei einem Nachrichten Packet ausgeführt
+- `teardown()` wird nach jeder Ausführung gerufen
+- `onUnload()` wird beim Zerstören der Plugin Instanz zum Programmende ausgeführt
+
+### Konfiguration
+#### 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 (ohne .py)
+    config:                 # config-Sektion
+      option1: value 1
+      option2: value 2
+        underOption1: value 21
+        underOption2: value 22
+      list:
+      - list 1
+      - list 2
+```
+Eine entsprechende Dokumentation der Parameter ist in der Dokumentation der [Konfiguration](../config.md) zu hinterlegen.
+
+#### Konfiguration verwenden
+Wird der Instanz eine Konfiguration übergeben wird diese in `self.config` abgelegt und kann folgendermaßen abgerufen werden:
+
+- `self.config.get("option1")` einzelnes Feld
+> `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
+> liefert `defValue`
+- `for item in self.config.get(FIELD):` Über Listen kann iteriert werden
+> liefert ein Element je Iteration - hier `list 1` und `list 2`
+
+Wird ein End-Wert ausgelesen, wird dieser direkt zurück gegeben.  
+Sollten weitere Unterelemente oder eine Liste exisitieren wird erneut ein Objekt der Klasse `Config()` zurück gegeben, auf welches wiederum nach obigem Schema zugegriffen werden kann.
+
+### 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 Paket](packet.md) Dokumentation.
+
+#### 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 Filtern verwendet)
+
+#### 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 zurück,
+was zur weiteren Ausführung des Routers führt.
+ 
+### Wildcards parsen (Plugin only)
+Das parsen der Wildcars funktioniert komfortabel über die interne Methode `self.parseWildcards(MSG)`.  
+Die Platzhalter der Wildcards findet man in der [BOSWatch Paket](packet.md) Dokumentation.
--- a/docu/docs/develop/packet.md
+++ b/docu/docs/develop/packet.md
@ -0,0 +1,61 @@
+## BOSWatch Packet Format
+
+Ein BOSWatch Datenpaket wird in einem Python Dict abgebildet. In der nachfolgenden Tabelle sind die genutzten Felder abgebildet.
+
+### Allgemeine Informationen
+
+|Feldname|FMS|POCSAG|ZVEI|MSG|Wildcard|Beschreibung|
+|--------|:-:|:----:|:--:|:-:|--------|------------|
+|serverName|X|X|X|X|`{SNAME}`|Name der BOSWatch Server Instanz|
+|serverVersion|X|X|X|X|`{SVERS}`||
+|serverBuildDate|X|X|X|X|`{SDATE}`||
+|serverBranch|X|X|X|X|`{SBRCH}`||
+|clientName|X|X|X|X|`{CNAME}`|Name der BOSWatch Client Instanz|
+|clientIP|X|X|X|X|`{CIP}`||
+|clientVersion|X|X|X|X|`{CVERS}`||
+|clientBuildDate|X|X|X|X|`{CDATE}`||
+|clientBranch|X|X|X|X|`{CBRCH}`||
+|inputSource|X|X|X|X|`{INSRC}`|(sdr, audio)|
+|timestamp|X|X|X|X|`{TIMES}`||
+|frequency|X|X|X|X|`{FREQ}`||
+|mode|X|X|X|X|`{MODE}`|(fms, pocsag, zvei, msg)|
+|descriptionShort|X|X|X||`{DESCS}`|Kann aus optinalem CSV File geladen werden|
+|descriptionLong|X|X|X||`{DESCL}`|Kann aus optinalem CSV File geladen werden|
+
+### Speziell für POCSAG
+
+|Feldname|FMS|POCSAG|ZVEI|MSG|Wildcard|Beschreibung|
+|--------|:-:|:----:|:--:|:-:|--------|------------|
+|bitrate||X|||`{BIT}`||
+|ric||X|||`{RIC}`||
+|subric||X|||`{SRIC}`|(1, 2, 3, 4)|
+|subricText||X|||`{SRICT}`|(a, b, c, d)|
+|message||X||X|`{MSG}`|Kann außerdem für ein Message Paket genutzt werden|
+
+### Speziell für ZVEI
+
+|Feldname|FMS|POCSAG|ZVEI|MSG|Wildcard|Beschreibung|
+|--------|:-:|:----:|:--:|:-:|--------|------------|
+|tone|||X||`{TONE}`|5-Ton Sequenz nach ZVEI|
+
+### Speziell für FMS
+
+|Feldname|FMS|POCSAG|ZVEI|MSG|Wildcard|Beschreibung|
+|--------|:-:|:----:|:--:|:-:|--------|------------|
+|fms|X||||`{FMS}`||
+|service|X||||`{SERV}`||
+|country|X||||`{COUNT}`||
+|location|X||||`{LOC}`||
+|vehicle|X||||`{VEC}`||
+|status|X||||`{STAT}`||
+|direction|X||||`{DIR}`||
+|dirextionText|X||||`{DIRT}`|(Fhz->Lst, Lst->Fhz)|
+|vehicle|X||||`{VEC}`||
+|vehicle|X||||`{VEC}`||
+|tacticalInfo|X||||`{TACI}`|(I, II, III, IV)|
+
+### Weitere Wildcards
+- `{BR}` - Zeilenumbruch `\r\n`
+- `{LPAR}` - öffnende Klammer `(`
+- `{RPAR}` - schließende Klammer `)`
+- `{TIME}` - Aktueller zeitstempel