BOSWatch/BW3-Core
1
0
Fork 0
mirror of https://github.com/BOSWatch/BW3-Core.git synced 2025-12-06 07:12:04 +01:00
Code Issues Actions Packages Projects Releases Wiki Activity

add basic docu

Browse source
This commit is contained in:
Bastian Schroll 2019-09-18 18:38:17 +02:00
parent 438dda48c2
commit e2c8394907
10 changed files with 131 additions and 348 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

0
_info/Changelog.md
View file

289
_info/packet.md
View file

@ -1,289 +0,0 @@
## Format of the BOSWatch packets
<table>
<tr>
<td>field</td>
<td>fms</td>
<td>pocsag</td>
<td>zvei</td>
<td>msg</td>
<td>wildcard</td>
<td>description</td>
</tr>
<tr>
<td>serverName</td>
<td>X</td>
<td>X</td>
<td>X</td>
<td>X</td>
<td>{SNAME}</td>
<td>name of the boswatch server instance</td>
</tr>
<tr>
<td>serverVersion</td>
<td>X</td>
<td>X</td>
<td>X</td>
<td>X</td>
<td>{SVERS}</td>
<td>in case of new version, server can notify</td>
</tr>
<tr>
<td>serverBuildDate</td>
<td>X</td>
<td>X</td>
<td>X</td>
<td>X</td>
<td>{SDATE}</td>
<td></td>
</tr>
<tr>
<td>serverBranch</td>
<td>X</td>
<td>X</td>
<td>X</td>
<td>X</td>
<td>{SBRCH}</td>
<td></td>
</tr>
<tr>
<td>clientName</td>
<td>X</td>
<td>X</td>
<td>X</td>
<td>X</td>
<td>{CNAME}</td>
<td>name of the boswatch client instance</td>
</tr>
<tr>
<td>clientIP</td>
<td>X</td>
<td>X</td>
<td>X</td>
<td>X</td>
<td>{CIP}</td>
<td></td>
</tr>
<tr>
<td>clientVersion</td>
<td>X</td>
<td>X</td>
<td>X</td>
<td>X</td>
<td>{CVERS}</td>
<td>in case of new version, server can notify</td>
</tr>
<tr>
<td>clientBuildDate</td>
<td>X</td>
<td>X</td>
<td>X</td>
<td>X</td>
<td>{CDATE}</td>
<td></td>
</tr>
<tr>
<td>clientBranch</td>
<td>X</td>
<td>X</td>
<td>X</td>
<td>X</td>
<td>{CBRCH}</td>
<td></td>
</tr>
<tr>
<td>inputSource</td>
<td>X</td>
<td>X</td>
<td>X</td>
<td>X</td>
<td>{INSRC}</td>
<td>(stick, audio)</td>
</tr>
<tr>
<td>timestamp</td>
<td>X</td>
<td>X</td>
<td>X</td>
<td>X</td>
<td>{TIMES}</td>
<td></td>
</tr>
<tr>
<td>frequency</td>
<td>X</td>
<td>X</td>
<td>X</td>
<td>X</td>
<td>{FREQ}</td>
<td></td>
</tr>
<tr>
<td>mode</td>
<td>X</td>
<td>X</td>
<td>X</td>
<td>X</td>
<td>{MODE}</td>
<td>(fms, pocsag, zvei, msg)</td>
</tr>
<tr>
<td>descriptionShort</td>
<td>X</td>
<td>X</td>
<td>X</td>
<td></td>
<td>{DESCS}</td>
<td>loaded from optional CSV file</td>
</tr>
<tr>
<td>descriptionLong</td>
<td>X</td>
<td>X</td>
<td>X</td>
<td></td>
<td>{DESCL}</td>
<td>loaded from optional CSV file</td>
</tr>
<tr>
<td>bitrate</td>
<td></td>
<td>X</td>
<td></td>
<td></td>
<td>{BIT}</td>
<td></td>
</tr>
<tr>
<td>ric</td>
<td></td>
<td>X</td>
<td></td>
<td></td>
<td>{RIC}</td>
<td></td>
</tr>
<tr>
<td>subric</td>
<td></td>
<td>X</td>
<td></td>
<td></td>
<td>{SRIC}</td>
<td>(1, 2, 3, 4)</td>
</tr>
<tr>
<td>subricText</td>
<td></td>
<td>X</td>
<td></td>
<td></td>
<td>{SRICT}</td>
<td>(a, b, c, d)</td>
</tr>
<tr>
<td>message</td>
<td></td>
<td>X</td>
<td></td>
<td>X</td>
<td>{MSG}</td>
<td></td>
</tr>
<tr>
<td>tone</td>
<td></td>
<td></td>
<td>X</td>
<td></td>
<td>{TONE}</td>
<td>5-tone sequence</td>
</tr>
<tr>
<td>fms</td>
<td>X</td>
<td></td>
<td></td>
<td></td>
<td>{FMS}</td>
<td></td>
</tr>
<tr>
<td>service</td>
<td>X</td>
<td></td>
<td></td>
<td></td>
<td>{SERV}</td>
<td></td>
</tr>
<tr>
<td>country</td>
<td>X</td>
<td></td>
<td></td>
<td></td>
<td>{COUNT}</td>
<td></td>
</tr>
<tr>
<td>location</td>
<td>X</td>
<td></td>
<td></td>
<td></td>
<td>{LOC}</td>
<td></td>
</tr>
<tr>
<td>vehicle</td>
<td>X</td>
<td></td>
<td></td>
<td></td>
<td>{VEHC}</td>
<td></td>
</tr>
<tr>
<td>status</td>
<td>X</td>
<td></td>
<td></td>
<td></td>
<td>{STAT}</td>
<td></td>
</tr>
<tr>
<td>direction</td>
<td>X</td>
<td></td>
<td></td>
<td></td>
<td>{DIR}</td>
<td></td>
</tr>
<tr>
<td>dirextionText</td>
<td>X</td>
<td></td>
<td></td>
<td></td>
<td>{DIRT}</td>
<td>(Fhz-&gt;Lst, Lst-&gt;Fhz)</td>
</tr>
<tr>
<td>tacticalInfo</td>
<td>X</td>
<td></td>
<td></td>
<td></td>
<td>{TACI}</td>
<td>(I, II, III, IV)</td>
</tr>
</table>
<br><br>
### Other possible wildcards:
- {BR} - Line break (\\r\\n)
- {LPAR} - Left parenthesis (
- {RPAR} - Right parenthesis )
- {TIME} - Actual timestamp

2
boswatch/packet.py
View file

@ -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):

1
docu/docs/changelog.md Normal file
View file

@ -0,0 +1 @@
## Changelog

15
_info/config.md → docu/docs/config.md
View file

@ -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
```
---

74
_info/ownModulePlugin.md → docu/docs/develop/ModulPlugin.md
View file

@ -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.

61
docu/docs/develop/packet.md Normal file
View file

@ -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

BIN
docu/docs/img/bw3.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 35 KiB

18
docu/docs/index.md
View file

@ -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.**

19
docu/mkdocs.yml
View file

@ -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