diff --git a/_info/Changelog.md b/_info/Changelog.md deleted file mode 100644 index e69de29..0000000 diff --git a/_info/packet.md b/_info/packet.md deleted file mode 100644 index 8a0cc99..0000000 --- a/_info/packet.md +++ /dev/null @@ -1,289 +0,0 @@ -## Format of the BOSWatch packets - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
fieldfmspocsagzveimsgwildcarddescription
serverNameXXXX{SNAME}name of the boswatch server instance
serverVersionXXXX{SVERS}in case of new version, server can notify
serverBuildDateXXXX{SDATE}
serverBranchXXXX{SBRCH}
clientNameXXXX{CNAME}name of the boswatch client instance
clientIPXXXX{CIP}
clientVersionXXXX{CVERS}in case of new version, server can notify
clientBuildDateXXXX{CDATE}
clientBranchXXXX{CBRCH}
inputSourceXXXX{INSRC}(stick, audio)
timestampXXXX{TIMES}
frequencyXXXX{FREQ}
modeXXXX{MODE}(fms, pocsag, zvei, msg)
descriptionShortXXX{DESCS}loaded from optional CSV file
descriptionLongXXX{DESCL}loaded from optional CSV file
bitrateX{BIT}
ricX{RIC}
subricX{SRIC}(1, 2, 3, 4)
subricTextX{SRICT}(a, b, c, d)
messageXX{MSG}
toneX{TONE}5-tone sequence
fmsX{FMS}
serviceX{SERV}
countryX{COUNT}
locationX{LOC}
vehicleX{VEHC}
statusX{STAT}
directionX{DIR}
dirextionTextX{DIRT}(Fhz->Lst, Lst->Fhz)
tacticalInfoX{TACI}(I, II, III, IV)
- -

-### Other possible wildcards: -- {BR} - Line break (\\r\\n) -- {LPAR} - Left parenthesis ( -- {RPAR} - Right parenthesis ) -- {TIME} - Actual timestamp diff --git a/boswatch/packet.py b/boswatch/packet.py index 185bed7..a0fcce8 100644 --- a/boswatch/packet.py +++ b/boswatch/packet.py @@ -73,7 +73,7 @@ class Packet: self.set("clientVersion", version.client) self.set("clientBuildDate", version.date) self.set("clientBranch", version.branch) - self.set("inputSource", config.get("client", "inoutSource")) + self.set("inputSource", config.get("client", "inputSource")) self.set("frequency", config.get("inputSource", "sdr", "frequency")) def addServerData(self, config): diff --git a/docu/docs/changelog.md b/docu/docs/changelog.md new file mode 100644 index 0000000..132c88c --- /dev/null +++ b/docu/docs/changelog.md @@ -0,0 +1 @@ +## Changelog \ No newline at end of file diff --git a/_info/config.md b/docu/docs/config.md similarity index 91% rename from _info/config.md rename to docu/docs/config.md index 7c00dbc..707860d 100644 --- a/_info/config.md +++ b/docu/docs/config.md @@ -1,6 +1,6 @@ ## Konfiguration -Die Konfiguration von BOSWatch 3 ist im YAML Format abgelegt und wird nachfolgend beschrieben. +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. @@ -12,11 +12,12 @@ Nachfolgend alle Paramater der Client Konfiguration |Feld|Beschreibung|Default| |----|------------|-------| |name|Name zur Identifizierung der Client Instanz|| -|inoutSource|Art der zu nutzenden Input Quelle (aktuell nur `sdr`)|| +|inputSource|Art der zu nutzenden Input Quelle (aktuell nur `sdr`)|| |useBroadcast|Verbindungsdaten per Broadcast beziehen|no| #### `server:` -Der Abschnitt `server:` wird nur genutzt, wenn `useBroadcast: no` gesetzt ist. +Der Abschnitt `server:` wird nur genutzt, wenn `useBroadcast: no` gesetzt ist. +Ansonsten wird versucht die Verbindungsdaten per Broadcast Paket direkt vom Server zu beziehen. |Feld|Beschreibung|Default| |----|------------|-------| @@ -72,8 +73,8 @@ Enthält eine Liste der Router Namen, welche bei einem Alarm direkt gestartet we Bsp: ```yaml alarmRouter: -- Name des Routers -- ein weiter Router + - Name des Routers + - ein weiter Router ``` #### `router:` @@ -118,8 +119,8 @@ Bsp: ```yaml config: allowed: - - fms - - zvei + - fms + - zvei ``` --- diff --git a/_info/ownModulePlugin.md b/docu/docs/develop/ModulPlugin.md similarity index 60% rename from _info/ownModulePlugin.md rename to docu/docs/develop/ModulPlugin.md index 55bb5be..be80245 100644 --- a/_info/ownModulePlugin.md +++ b/docu/docs/develop/ModulPlugin.md @@ -1,21 +1,21 @@ -## Eigene Module und Plugins 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 Plugin genutzt werden. +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. -### 1 Informationen anpassen +### Informationen anpassen - Dateikopf anpassen -### 2 Benötigte Methoden überschreiben -#### 2.1 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 -#### 2.2 Plugin +#### 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 @@ -25,12 +25,12 @@ 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 Konfiguration -#### 3.1 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 +- type: module # oder 'plugin' + name: template_module # Name der Python Datei (ohne .py) config: # config-Sektion option1: value 1 option2: value 2 @@ -40,49 +40,47 @@ Jedes Modul oder Plugin wird in einem Router folgendermaßen deklariert: - list 1 - list 2 ``` -Eine entsprechende Dokumentation der Parameter ist in der Config-Readme zu hinterlegen. +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: -#### 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` +> `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` +> 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 Durchgang - hier `list1` und `list2` +> 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 Element der Klasse `Config()` zurück gegeben +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. -### 4 Arbeiten mit dem bwPacket -An das Modul bzw. Plugin wird eine Instanz eines BOSWatch-Packet Objekts übergeben. +### 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. +Aus dieser kann mittels `bwPacket.get(FIELDNAME)` das entsprechende Feld ausgelesen werden. -Mittels `bwPacket.set(FIELDNAME, VALUE)` kann es hinzugefügt/modifiziert werden. +Mittels `bwPacket.set(FIELDNAME, VALUE)` kann es hinzugefügt/modifiziert werden. -Eine Auflistung der bereitgestellten Informationen -findet sich im entsprechenden BOSWatch-Packet Dokument. +Eine Auflistung der bereitgestellten Informationen findet sich im entsprechenden [BOSWatch Paket](packet.md) Dokumentation. -#### 4.1 Zu beachten bei Module -Module können Pakete beliebig verändern. +#### 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) -#### 4.2 Zu beachten bei Plugins -Plugins geben keine Pakete mehr zurück. Sie fungieren ausschließlich als Endpunkt. +#### 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. -### 5 Wildcards parsen (NUR IN 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`. +### 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 new file mode 100644 index 0000000..4a301d4 --- /dev/null +++ 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 diff --git a/docu/docs/img/bw3.png b/docu/docs/img/bw3.png new file mode 100644 index 0000000..b229bbf Binary files /dev/null and b/docu/docs/img/bw3.png differ diff --git a/docu/docs/index.md b/docu/docs/index.md index d388039..b953b18 100644 --- a/docu/docs/index.md +++ b/docu/docs/index.md @@ -1,17 +1,11 @@ -# Welcome to MkDocs +# BOSWatch 3 -For full documentation visit [mkdocs.org](https://mkdocs.org). +![BOSWatch](img/bw3.png "BOSWatch 3 Logo") -## Commands -* `mkdocs new [dir-name]` - Create a new project. -* `mkdocs serve` - Start the live-reloading docs server. -* `mkdocs build` - Build the documentation site. -* `mkdocs help` - Print this help message. +**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)_ -## Project layout +*** - mkdocs.yml # The configuration file. - docs/ - index.md # The documentation homepage. - ... # Other markdown pages, images and other files. +**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 diff --git a/docu/mkdocs.yml b/docu/mkdocs.yml index c97182f..f075849 100644 --- a/docu/mkdocs.yml +++ b/docu/mkdocs.yml @@ -1 +1,18 @@ -site_name: My Docs +site_name: BOSWatch3 Core +site_author: Bastian Schroll & BW3 Dev team + +nav: + # - BW3: index.md + - Quick Start Guide: config.md + # - Module: index.md + # - Plugins: index.md + - Entwickler: + - Eigenes Modul/Plugin: develop/ModulPlugin.md + - BOSWatch Packet Format: develop/packet.md +# - BW3 Source Docu: /api/index.html + - Changelog: changelog.md + +theme: + name: mkdocs + highlightjs: true + hljs_style: github \ No newline at end of file