mirror of
https://github.com/BOSWatch/BW3-Core.git
synced 2026-04-05 14:25:45 +00:00
improve documentation
This commit is contained in:
Bastian Schroll
parent
dc5c0dab5e
commit
6d688acfac
8 changed files with 133 additions and 82 deletions
|
|
@ -1,19 +1,21 @@
|
|||
## Eigenes Modul/Plugin schreiben
|
||||
|
||||
# <center>Eigenes Modul/Plugin schreiben</center>
|
||||
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
|
||||
---
|
||||
## Informationen anpassen
|
||||
- Dateikopf anpassen
|
||||
|
||||
### Benötigte Methoden überschreiben
|
||||
#### Modul
|
||||
---
|
||||
## 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
|
||||
---
|
||||
### Plugin
|
||||
Die Plugin Basisklasse bietet einige Methoden, welche vom Plugin überschrieben werden können.
|
||||
|
||||
- `onLoad()` wird direkt beim Import des Plugins ausgeführt
|
||||
|
|
@ -25,50 +27,57 @@ 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
|
||||
|
||||
### Konfiguration
|
||||
#### Konfiguration anlegen
|
||||
---
|
||||
## 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:
|
||||
name: template_module # Name der Python Datei (ohne .py)
|
||||
config: # config-Sektion
|
||||
option1: value 1
|
||||
option2:
|
||||
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:
|
||||
### Konfiguration verwenden
|
||||
Wird der Instanz eine Konfiguration übergeben wird diese in `self.config` abgelegt und kann wie folgt abgerufen werden:
|
||||
(Dies Ergebnisse beziehen sich auf das Konfigurationsbeispiel oben)
|
||||
|
||||
- `self.config.get("option1")` einzelnes Feld
|
||||
> `value 1`
|
||||
- `self.config.get("option2", "underOption1")` verschachteltes Feld (beliebig viele möglich)
|
||||
- Einzelnes Feld auslesen
|
||||
`self.config.get("option1")`
|
||||
> liefert `value 1`
|
||||
|
||||
- Verschachteltes Feld auslesen (beliebige tiefe möglich)
|
||||
`self.config.get("option2", "underOption1")`
|
||||
> liefert `value 21`
|
||||
- `self.config.get("notSet", default="defValue")` Es kann ein Default Wert angegeben werden
|
||||
|
||||
- Es kann ein Default Wert angegeben werden
|
||||
`self.config.get("notSet", default="defValue")`
|
||||
> liefert `defValue`
|
||||
- `for item in self.config.get(FIELD):` Über Listen kann iteriert werden
|
||||
|
||||
- Über Listen kann einfach iteriert werden
|
||||
`for item in self.config.get(FIELD):`
|
||||
> 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
|
||||
---
|
||||
## 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 ein Wert hinzugefügt oder modifiziert werden.
|
||||
Eine Auflistung der bereitgestellten Informationen findet sich im entsprechenden [BOSWatch Paket](packet.md) Dokumentation.
|
||||
Selbst vom Modul hinzugefügte Informationen müssen dokumentiert werden.
|
||||
|
||||
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.
|
||||
### Zu beachten bei Module
|
||||
Module können Pakete beliebig verändern. Diese Änderungen werden im Router entsprechend weitergeleitet.
|
||||
|
||||
Mögliche Rückgabewerte eines Moduls:
|
||||
|
||||
|
|
@ -76,11 +85,12 @@ Mögliche Rückgabewerte eines Moduls:
|
|||
- `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
|
||||
### 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.
|
||||
was zur weiteren Ausführung des Routers mit dem original Paket führt. Daher macht es in Plugins keinen Sinn ein Paket zu modifizieren.
|
||||
|
||||
### Wildcards parsen (Plugin only)
|
||||
---
|
||||
## 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.
|
||||
|
|
|
|||
|
|
@ -1,9 +1,9 @@
|
|||
## BOSWatch Packet Format
|
||||
# <center>BOSWatch Packet Format</center>
|
||||
|
||||
Ein BOSWatch Datenpaket wird in einem Python Dict abgebildet. In der nachfolgenden Tabelle sind die genutzten Felder abgebildet.
|
||||
|
||||
### Allgemeine Informationen
|
||||
|
||||
---
|
||||
## Allgemeine Informationen
|
||||
|Feldname|FMS|POCSAG|ZVEI|MSG|Wildcard|Beschreibung|
|
||||
|--------|:-:|:----:|:--:|:-:|--------|------------|
|
||||
|serverName|X|X|X|X|`{SNAME}`|Name der BOSWatch Server Instanz|
|
||||
|
|
@ -22,8 +22,8 @@ Ein BOSWatch Datenpaket wird in einem Python Dict abgebildet. In der nachfolgend
|
|||
|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
|
||||
|
||||
---
|
||||
## Speziell für POCSAG
|
||||
|Feldname|FMS|POCSAG|ZVEI|MSG|Wildcard|Beschreibung|
|
||||
|--------|:-:|:----:|:--:|:-:|--------|------------|
|
||||
|bitrate||X|||`{BIT}`||
|
||||
|
|
@ -32,14 +32,14 @@ Ein BOSWatch Datenpaket wird in einem Python Dict abgebildet. In der nachfolgend
|
|||
|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
|
||||
|
||||
---
|
||||
## Speziell für ZVEI
|
||||
|Feldname|FMS|POCSAG|ZVEI|MSG|Wildcard|Beschreibung|
|
||||
|--------|:-:|:----:|:--:|:-:|--------|------------|
|
||||
|tone|||X||`{TONE}`|5-Ton Sequenz nach ZVEI|
|
||||
|
||||
### Speziell für FMS
|
||||
|
||||
---
|
||||
## Speziell für FMS
|
||||
|Feldname|FMS|POCSAG|ZVEI|MSG|Wildcard|Beschreibung|
|
||||
|--------|:-:|:----:|:--:|:-:|--------|------------|
|
||||
|fms|X||||`{FMS}`||
|
||||
|
|
@ -54,7 +54,8 @@ Ein BOSWatch Datenpaket wird in einem Python Dict abgebildet. In der nachfolgend
|
|||
|vehicle|X||||`{VEC}`||
|
||||
|tacticalInfo|X||||`{TACI}`|(I, II, III, IV)|
|
||||
|
||||
### Weitere Wildcards
|
||||
---
|
||||
## Weitere Wildcards
|
||||
- `{BR}` - Zeilenumbruch `\r\n`
|
||||
- `{LPAR}` - öffnende Klammer `(`
|
||||
- `{RPAR}` - schließende Klammer `)`
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue