Merge remote-tracking branch 'origin/develop' into cleanup

2025-12-06 07:12:04 +01:00 · 2019-09-19 17:05:49 +02:00 · 2019-09-19 17:05:49 +02:00 · 642595fb9a
parent 4508d4dfb8 6d688acfac
commit 642595fb9a
8 changed files with 130 additions and 79 deletions
--- a/docu/docs/changelog.md
+++ b/docu/docs/changelog.md
@ -1 +1,3 @@
-## Changelog
+# <center>Changelog</center>
+
+---
--- a/docu/docs/config.md
+++ b/docu/docs/config.md
@ -1,21 +1,22 @@
-## Konfiguration
+# <center>Konfiguration</center>

 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
+## Plugins
+Nachfolgend alle Paramater der Plugin Konfigurationen
+
--- a/docu/docs/develop/ModulPlugin.md
+++ b/docu/docs/develop/ModulPlugin.md
@ -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.
--- a/docu/docs/develop/packet.md
+++ b/docu/docs/develop/packet.md
@ -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 `)`
--- a/docu/docs/index.md
+++ b/docu/docs/index.md
@ -1,11 +1,10 @@
-# BOSWatch 3
-
-![BOSWatch](img/bw3.png "BOSWatch 3 Logo")
+# <center>BOSWatch 3</center>

+<center>![BOSWatch](img/bw3.png "BOSWatch 3 Logo")</center>

 **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.**
+**The intercept of the German BOS radio is strictly prohibited and will be prosecuted. The use is only permitted for authorized personnel.**
--- a/docu/docs/modul/mode_filter.md
+++ b/docu/docs/modul/mode_filter.md
@ -0,0 +1,3 @@
+# <center>Mode Filter</center> 
+
+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.
--- a/docu/docs/tbd.md
+++ b/docu/docs/tbd.md
@ -0,0 +1,5 @@
+# <center>To be done ...</center>
+
+---
+
+Hier existiert noch kein Inhalt, gerne kannst du uns aber Helfen die Dokumentation zu vervollständigen.
--- 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/html/index.html
  - Changelog: changelog.md

+use_directory_urls: false
+
 theme:
-    name: mkdocs
-    highlightjs: true
-    hljs_style: github
+  name: mkdocs
+  highlightjs: true
+  hljs_style: github
+
+