de:Plugin entwickeln - Schrolli91/BOSWatch GitHub Wiki

Wie programmiere ich mein eigenes Plugin:

Weitere Informationen sowie ein kleines Tutorial folgen!

1. Plugin-Template

1.1 Allgemeines

Im Ordner plugins/template/template.py ist ein kleines Beispiel-Template gespeichert. Da alle Plugins ähnlich funktionieren, ist es durchaus möglich, in allen anderen Plugins nachzusehen.

Ein neues Plugin muss in einem separaten Ordner gespeichert werden, dessen Name dem Dateinamen der *.py-Datei entspricht.

1.2 Initialisierung des Plugins `.onLoad()`

Die .onLoad()-Routine wird einmalig zur Initialisierung des Plugins aufgerufen.

1.2 Aufruf des Plugins `.run()`

Die .run() Routine wird immer aufgerufen, wen nein Alarm empfangen und decodiert wurde. Die Informationen, die BOSWatch decodiert hat sind hier verfügbar. Siehe Kapitel 5: Verarbeiten der Daten aus BOSWatch

2. Benutzen der globalen Log-Funktion

2.1 Initialisierung und Benutzung

Zuerst muss das Logging-Modul importiert werden: import logging # Global logger

Mit logging.LOGLEVEL("MESSAGE") können jetzt Log-Meldungen gesendet warden.

Dazu wird LOGLEVEL durch DEBUG, INFO, WARNING oder ERROR ersetzt.

Die richtige Benutzung der Loglevel wird im Kapitel 2.2 Auswählen des richtigen Loglevels verdeutlicht.

2.2 Auswahl des richtigen Loglevels

debug Alle Nachrichten aus dem Programmablauf, Verwendung um Fehler im Programmablauf zu finden

info Nachrichten, die rein zur Information des Benutzers dienen

warning Warnungen und technische Fehler. Führt niemals zum Beenden von BOSWatch

error Fehler, die nicht zwangsweise zum Beenden von BOSWatch führen, wo jedoch ein Eingriff eines Administrators erforderlich ist.

critical Fehler die zur sofortigen Beendigung von BOSWatch führen – Option in Plugins nicht erlaubt (Ein Plugin kann keinen Crash des gesamten Programms herbeiführen)

3. Benutzung der Config-Datei

3.1 Erstellung einer eigenen Konfiguration in der Datei config.ini

Zuerst muss eine neue Sektion in der config.ini erstellt warden. Eine Sektion wird definiert durch eckige Klammern. Es empfiehlt sich, denselben Namen wie für das Plugin zu verwenden. [SECTION_NAME] Hiernach werden beliebig viele Optionen definiert, folgendes Format ist vorgeschrieben: OPTION = VALUE.

Hier das Beispiel aus dem Template-Plugin: [template] test1 = testString test2 = 123456

3.2 Lesen der Daten aus der config.ini

Um die Konfigurationsdaten lesen zu können, muss die globalVars.py importiert werden, da sich dort das globale Konfigurations-Objekt befindet: from includes import globalVars # Global variables

Jetzt können die Daten folgendermaßen gelesen werden: VALUE = globalVars.config.get("SECTION", "OPTION") #Gets any value

Die Bessere Variante:

VALUE = globalVars.config.getint("SECTION", "OPTION") #Value must be an Integer

VALUE = globalVars.config.getfloat("SECTION", "OPTION") #Value must be an Float

VALUE = globalVars.config.getboolean("SECTION", "OPTION") #Value must be an Boolean

4. Globale Hilfs-Funktionen

4.1 configHandler.py

Zuerst muss die Hilfs-Funktions-Datei importiert werden. from includes.helper import configHandler

4.1.1 .checkConfig(section)

Die Funktion liest alle Optionen einer Kofigurations-Sektion und schreibt diese in den Debug-Log. Ist die Konfiguration lesbar, so ergibt die Funktion true, auch, wenn die Konfiguration leer ist. Tritt beim Lesen der Konfiguration ein Fehler auf, so ergibt die Funktion false und schreibt eine Error-Nachricht in den Log.

if configHandler.checkConfig("template"): #check config file ########## User Plugin CODE ########## pass

4.2 timeHandler.py

Zuerst muss die Hilfs-Datei importiert werden: from includes.helper import timeHandler

4.2.1 .curtime(format)

timeHandler.curtime() # returns a formated datetime string Weiter Informationen hier Ohne weitere Parameter ergibt die Funktion ein Datum/Uhrzeit im folgenden Format: %d.%m.%Y %H:%M:%S

4.2.2 .getDate()

timeHandler.getDate() # returns the current date in format %d.%m.%Y``

4.2.3 .getTime()

timeHandler.getTime() # returns the current time in format %H:%M:%S``

4.2.4 .getTimestamp()

timeHandler.getTimestamp() # returns the current linux timestamp

4.3 wildcardHandler.py

Zuerst muss die Hilfsdatei importiert werden: from includes.helper import wildcardHandler

4.3.1 .replaceWildcards(text,data)

wildcardHandler.replaceWildcards(text,data) # replace all standard wildcards Um die Standart-Wildcards zu ersetzen, benötigt die Funktion die in der data[] definierten Standart-Wildcards.

Allgemein:

%TIME% = Uhrzeit (Aus dem Script)
%DATE% = Datum (Aus dem Script)
%DESCR% = Beschreibung aus den CSV-Files
%BR% = „Neue Zeile“
%LPAR% = "("
%RPAR% = ")"

FMS:

%FMS% = FMS Code
%STATUS% = FMS Status
%DIR% = Richtung des Telegramms (0/1)
%DIRT% = Richtung des Telegramms (Text-String)
%TSI% = Taktische Kurzinformation / Teilung (I-IV)
ZVEI:
%ZVEI% = ZVEI 5-Ton Code

POCSAG:

%RIC% = Pocsag RIC
%FUNC% = Pocsac Funktion/Subric (1-4)
%FUNCCHAR% = Pocsac Funktion/Subric als Buchstabe (a-d)
%FUNCTEXT% = Pocsac Funktion/Subric als Statische Nachricht, definiert in der config.ini unter [POCSAG]
%MSG% = Nachricht des POCSAG-Telegramms
%BITRATE% = Bitrate des POCSAG-Telegramms

5. Verarbeiten der Daten von BOSWatch

Drei Parameter werden während die .run()-Funktion läuft, weitergegeben:

5.1 typ

Die Art des Alarms, Möglich sind FMS, ZVEI oder POC

5.2 freq

Die Empfangsfrequenz des Alarms

5.3 data[ ]

Informationen können aus dem Array ausgelesen werden mittels data["INFO"]. Im Datenfeld befinden sich folgende Informationen:

ZVEI:

zvei
description
timestamp