From 6d688acfacfad88fa1306d8b60fb85a8c6749800 Mon Sep 17 00:00:00 2001 From: Bastian Schroll Date: Thu, 19 Sep 2019 14:46:18 +0200 Subject: [PATCH] improve documentation --- docu/docs/changelog.md | 4 +- docu/docs/config.md | 56 +++++++++++++--------- docu/docs/develop/ModulPlugin.md | 80 ++++++++++++++++++-------------- docu/docs/develop/packet.md | 21 +++++---- docu/docs/index.md | 9 ++-- docu/docs/modul/mode_filter.md | 3 ++ docu/docs/tbd.md | 5 ++ docu/mkdocs.yml | 37 +++++++++++---- 8 files changed, 133 insertions(+), 82 deletions(-) create mode 100644 docu/docs/modul/mode_filter.md create mode 100644 docu/docs/tbd.md diff --git a/docu/docs/changelog.md b/docu/docs/changelog.md index 132c88c..2af6dec 100644 --- a/docu/docs/changelog.md +++ b/docu/docs/changelog.md @@ -1 +1,3 @@ -## Changelog \ No newline at end of file +#
Changelog
+ +--- diff --git a/docu/docs/config.md b/docu/docs/config.md index 707860d..5debcad 100644 --- a/docu/docs/config.md +++ b/docu/docs/config.md @@ -1,21 +1,22 @@ -## Konfiguration +#
Konfiguration
Die Konfiguration von BOSWatch 3 ist im YAML Format abgelegt und wird nachfolgend beschrieben. Immer wenn für eine Einstellung ein **Default** Wert angegeben ist, muss diese Einstellung nicht zwingend in die Konfiguration eingetragen werden. +--- +## Client -### Client -Nachfolgend alle Paramater der Client Konfiguration -#### `client:` +### `client:` |Feld|Beschreibung|Default| |----|------------|-------| |name|Name zur Identifizierung der Client Instanz|| |inputSource|Art der zu nutzenden Input Quelle (aktuell nur `sdr`)|| |useBroadcast|Verbindungsdaten per Broadcast beziehen|no| -#### `server:` +--- +### `server:` Der Abschnitt `server:` wird nur genutzt, wenn `useBroadcast: no` gesetzt ist. Ansonsten wird versucht die Verbindungsdaten per Broadcast Paket direkt vom Server zu beziehen. @@ -24,10 +25,17 @@ Ansonsten wird versucht die Verbindungsdaten per Broadcast Paket direkt vom Serv |ip|IP Adresse des Servers|127.0.0.1| |port|Port des Sever|8080| -#### `inputSource:` +Bsp: +```yaml +server: + ip: 10.10.10.2 + port: 9123 +``` +--- +### `inputSource:` Aktuell gibt es nur `sdr:` als Input Quelle -##### `sdr:` +#### `sdr:` |Feld|Beschreibung|Default| |----|------------|-------| |device|rtl_fm Device ID|0| @@ -47,7 +55,8 @@ inputSource: gain: 100 ``` -#### `decoder:` +--- +### `decoder:` |Feld|Beschreibung|Default| |----|------------|-------| |fms|FMS Decoder|no| @@ -57,17 +66,18 @@ inputSource: |poc2400|POCSAG Decoder (Bitrate 2400)|no| --- -### Server +## Server Nachfolgend alle Paramater der Server Konfiguration -#### `server:` +### `server:` |Feld|Beschreibung|Default| |----|------------|-------| |port|Port auf dem der Server lauscht|8080 |name|Name zur Identifizierung der Server Instanz|| |useBroadcast|Verbindungsdaten per Broadcast Server bereitstellen|no| -#### `alarmRouter:` +--- +### `alarmRouter:` Enthält eine Liste der Router Namen, welche bei einem Alarm direkt gestartet werden sollen. Bsp: @@ -77,22 +87,24 @@ alarmRouter: - ein weiter Router ``` -#### `router:` -Mit den Routern kann der Verarbeitungsweg eines Alarm-Paketes festgelegt werden. -Diese werden als Liste angegeben +--- +### `router:` +Mit den Routern kann der Verarbeitungsweg eines Alarm-Paketes festgelegt werden. DEs können beliebig viele Router in Form einer Liste angegeben werden. |Feld|Beschreibung|Default| |----|------------|-------| |name|Name des Routers|| |route|Definiten des Routenverlaufs -Die einzelnen Routen werden wie folgt definiert +#### `route:` + +Jeder Router kann eine beliebige Anzahl einzelner Routenpunkte enthalten. Diese werden innerhalb des Routers sequentiel abgearbeitet. Mögliche Typen der Routenpunkte sind dabei ein Modul, ein Plugin oder ein anderer Router. Sie werden ebenfalls in Form einer Liste definiert. |Feld|Beschreibung|Default| |----|------------|-------| |type|Art des Routenpunktes (module, plugin, router)|| -|name|Zu ladende Resource (vollständige Liste siehe !!!TBD!!!)|| -|config|Konfigurationseinstellungen des Routenpunktes|| +|name|Zu ladende Resource (Siehe weiter unten)|| +|config|Konfigurationseinstellungen des Routenpunktes (Siehe weiter unten)|| Bsp: ```yaml @@ -107,9 +119,10 @@ router: ``` --- -### Module +## Module Nachfolgend alle Paramater der Modul Konfigurationen -#### `filter.modeFilter` + +### `filter.modeFilter` |Feld|Beschreibung|Default| |----|------------|-------| @@ -124,5 +137,6 @@ config: ``` --- -### Plugins -Nachfolgend alle Paramater der Plugin Konfigurationen \ No newline at end of file +## Plugins +Nachfolgend alle Paramater der Plugin Konfigurationen + diff --git a/docu/docs/develop/ModulPlugin.md b/docu/docs/develop/ModulPlugin.md index be80245..614e8d9 100644 --- a/docu/docs/develop/ModulPlugin.md +++ b/docu/docs/develop/ModulPlugin.md @@ -1,19 +1,21 @@ -## Eigenes Modul/Plugin schreiben - +#
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 +--- +## 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. diff --git a/docu/docs/develop/packet.md b/docu/docs/develop/packet.md index 4a301d4..1995db0 100644 --- a/docu/docs/develop/packet.md +++ b/docu/docs/develop/packet.md @@ -1,9 +1,9 @@ -## BOSWatch Packet Format +#
BOSWatch Packet Format
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 `)` diff --git a/docu/docs/index.md b/docu/docs/index.md index b953b18..d757638 100644 --- a/docu/docs/index.md +++ b/docu/docs/index.md @@ -1,11 +1,10 @@ -# BOSWatch 3 - -![BOSWatch](img/bw3.png "BOSWatch 3 Logo") +#
BOSWatch 3
+
![BOSWatch](img/bw3.png "BOSWatch 3 Logo")
**Es wird darauf hingewiesen, dass für die Teilnahme am BOS-Funk nur nach den Technischen Richtlinien der BOS zugelassene Funkanlagen verwendet werden dürfen.** **Der BOS-Funk ist ein nichtöffentlicher mobiler Landfunk. Privatpersonen gehören nicht zum Kreis der berechtigten Funkteilnehmer.** _(Quelle: TR-BOS)_ -*** +--- -**The intercept of the German BOS radio is strictly prohibited and will be prosecuted. The use is only permitted for authorized personnel.** \ No newline at end of file +**The intercept of the German BOS radio is strictly prohibited and will be prosecuted. The use is only permitted for authorized personnel.** diff --git a/docu/docs/modul/mode_filter.md b/docu/docs/modul/mode_filter.md new file mode 100644 index 0000000..2376578 --- /dev/null +++ b/docu/docs/modul/mode_filter.md @@ -0,0 +1,3 @@ +#
Mode Filter
+ +Mit diesem Modul ist es Möglich, die Pakete auf bestimmte Modes (FMS, POCSAG, ZVEI) zu Filtern. Je nach Konfiguration werden Pakete eines bestimmten Modes im aktuellen Router weitergeleitet oder verworfen. diff --git a/docu/docs/tbd.md b/docu/docs/tbd.md new file mode 100644 index 0000000..61a8220 --- /dev/null +++ b/docu/docs/tbd.md @@ -0,0 +1,5 @@ +#
To be done ...
+ +--- + +Hier existiert noch kein Inhalt, gerne kannst du uns aber Helfen die Dokumentation zu vervollständigen. diff --git a/docu/mkdocs.yml b/docu/mkdocs.yml index f075849..37c107d 100644 --- a/docu/mkdocs.yml +++ b/docu/mkdocs.yml @@ -1,18 +1,35 @@ site_name: BOSWatch3 Core site_author: Bastian Schroll & BW3 Dev team +repo_url: https://github.com/BOSWatch/BW3-Core +edit_uri: edit/develop/docu/docs/ + nav: - # - BW3: index.md - - Quick Start Guide: config.md - # - Module: index.md - # - Plugins: index.md + # - BW3: index.md + - Quick Start Guide: +# - Installation: tbd.md + - Konfiguration: config.md +# - BOSWatch nutzen: tbd.md +# - BOSWatch als Service: tbd.md +# - Informationen: +# - Server/Cient Prinzip: tbd.md +# - Broadcast Funktion: tbd.md +# - Modul/Plugin Konzept: tbd.md +# - Routing Mechanismus: tbd.md + - Module: + - Mode Filter: modul/mode_filter.md +# - Plugins: tbd.md - Entwickler: - - Eigenes Modul/Plugin: develop/ModulPlugin.md - - BOSWatch Packet Format: develop/packet.md -# - BW3 Source Docu: /api/index.html + - Eigenes Modul/Plugin: develop/ModulPlugin.md + - BOSWatch Packet Format: develop/packet.md + - BW3 Source Docu: /api/index.html - Changelog: changelog.md +use_directory_urls: false + theme: - name: mkdocs - highlightjs: true - hljs_style: github \ No newline at end of file + name: mkdocs + highlightjs: true + hljs_style: github + +