mirror of
https://github.com/BOSWatch/BW3-Core.git
synced 2026-04-06 14:53:53 +00:00
add basic docu
This commit is contained in:
Bastian Schroll
parent
438dda48c2
commit
e2c8394907
10 changed files with 131 additions and 348 deletions
127
_info/config.md
127
_info/config.md
|
|
@ -1,127 +0,0 @@
|
|||
## 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
|
||||
Nachfolgend alle Paramater der Client Konfiguration
|
||||
|
||||
#### `client:`
|
||||
|Feld|Beschreibung|Default|
|
||||
|----|------------|-------|
|
||||
|name|Name zur Identifizierung der Client Instanz||
|
||||
|inoutSource|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.
|
||||
|
||||
|Feld|Beschreibung|Default|
|
||||
|----|------------|-------|
|
||||
|ip|IP Adresse des Servers|127.0.0.1|
|
||||
|port|Port des Sever|8080|
|
||||
|
||||
#### `inputSource:`
|
||||
Aktuell gibt es nur `sdr:` als Input Quelle
|
||||
|
||||
##### `sdr:`
|
||||
|Feld|Beschreibung|Default|
|
||||
|----|------------|-------|
|
||||
|device|rtl_fm Device ID|0|
|
||||
|frequency|Frequenz des Empfängers||
|
||||
|error|Frequenz Abweichung in ppm|0|
|
||||
|squelch|Einstellung der Rauschsperre|0|
|
||||
|gain|Verstärkung des Eingangssignals|100|
|
||||
|
||||
Bsp:
|
||||
```yaml
|
||||
inputSource:
|
||||
sdr:
|
||||
device: 0
|
||||
frequency: 85.000M
|
||||
error: 0
|
||||
squelch: 0
|
||||
gain: 100
|
||||
```
|
||||
|
||||
#### `decoder:`
|
||||
|Feld|Beschreibung|Default|
|
||||
|----|------------|-------|
|
||||
|fms|FMS Decoder|no|
|
||||
|zvei|ZVEI Decoder|no|
|
||||
|poc512|POCSAG Decoder (Bitrate 512)|no|
|
||||
|poc1200|POCSAG Decoder (Bitrate 1200)|no|
|
||||
|poc2400|POCSAG Decoder (Bitrate 2400)|no|
|
||||
|
||||
---
|
||||
### Server
|
||||
Nachfolgend alle Paramater der Server Konfiguration
|
||||
|
||||
#### `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:`
|
||||
Enthält eine Liste der Router Namen, welche bei einem Alarm direkt gestartet werden sollen.
|
||||
|
||||
Bsp:
|
||||
```yaml
|
||||
alarmRouter:
|
||||
- Name des Routers
|
||||
- ein weiter Router
|
||||
```
|
||||
|
||||
#### `router:`
|
||||
Mit den Routern kann der Verarbeitungsweg eines Alarm-Paketes festgelegt werden.
|
||||
Diese werden als Liste angegeben
|
||||
|
||||
|Feld|Beschreibung|Default|
|
||||
|----|------------|-------|
|
||||
|name|Name des Routers||
|
||||
|route|Definiten des Routenverlaufs
|
||||
|
||||
Die einzelnen Routen werden wie folgt definiert
|
||||
|
||||
|Feld|Beschreibung|Default|
|
||||
|----|------------|-------|
|
||||
|type|Art des Routenpunktes (module, plugin, router)||
|
||||
|name|Zu ladende Resource (vollständige Liste siehe !!!TBD!!!)||
|
||||
|config|Konfigurationseinstellungen des Routenpunktes||
|
||||
|
||||
Bsp:
|
||||
```yaml
|
||||
router:
|
||||
- name: Router 1
|
||||
route:
|
||||
- type: module
|
||||
name: filter.modeFilter
|
||||
config:
|
||||
allowed:
|
||||
- fms
|
||||
```
|
||||
|
||||
---
|
||||
### Module
|
||||
Nachfolgend alle Paramater der Modul Konfigurationen
|
||||
#### `filter.modeFilter`
|
||||
|
||||
|Feld|Beschreibung|Default|
|
||||
|----|------------|-------|
|
||||
|allowed|Liste der erlaubten Paket Typen `fms` `zvei` `pocsag`||
|
||||
|
||||
Bsp:
|
||||
```yaml
|
||||
config:
|
||||
allowed:
|
||||
- fms
|
||||
- zvei
|
||||
```
|
||||
|
||||
---
|
||||
### Plugins
|
||||
Nachfolgend alle Paramater der Plugin Konfigurationen
|
||||
|
|
@ -1,88 +0,0 @@
|
|||
## Eigene Module und Plugins 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.
|
||||
|
||||
### 1 Informationen anpassen
|
||||
- Dateikopf anpassen
|
||||
|
||||
### 2 Benötigte Methoden überschreiben
|
||||
#### 2.1 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
|
||||
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
|
||||
- `pocsag(bwPacket)` wird bei einem POCSAG Paket ausgeführt
|
||||
- `zvei(bwPacket)` wird bei einem ZVEI Packet ausgeführt
|
||||
- `msg(bwPacket)` wird bei einem Nachrichten Packet ausgeführt
|
||||
- `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
|
||||
Jedes Modul oder Plugin wird in einem Router folgendermaßen deklariert:
|
||||
```yaml
|
||||
- type: module # oder plugin
|
||||
name: template_module # Name der Python Datei
|
||||
config: # config-Sektion
|
||||
option1: value 1
|
||||
option2: value 2
|
||||
underOption1: value 21
|
||||
underOption2: value 22
|
||||
list:
|
||||
- list 1
|
||||
- list 2
|
||||
```
|
||||
Eine entsprechende Dokumentation der Parameter ist in der Config-Readme zu hinterlegen.
|
||||
|
||||
#### 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`
|
||||
- `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`
|
||||
- `for item in self.config.get(FIELD):` Über Listen kann iteriert werden
|
||||
- liefert ein Element je Durchgang - hier `list1` und `list2`
|
||||
|
||||
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
|
||||
|
||||
### 4 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 es hinzugefügt/modifiziert werden.
|
||||
|
||||
Eine Auflistung der bereitgestellten Informationen
|
||||
findet sich im entsprechenden BOSWatch-Packet Dokument.
|
||||
|
||||
#### 4.1 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.
|
||||
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`.
|
||||
289
_info/packet.md
289
_info/packet.md
|
|
@ -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->Lst, Lst->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
|
||||
Loading…
Add table
Add a link
Reference in a new issue