Created de:Plugin entwickeln (markdown)

de:Plugin-entwickeln.md

@@ -0,0 +1,166 @@
+##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](https://docs.python.org/2/library/time.html#time.strftime)
+ 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
+
+**FMS:**
+* fms
+* status
+* direction
+* directionText
+* tsi
+* description
+* timestamp
+
+**POCSAG:**
+* ric
+* function
+* functionChar
+* msg
+* bitrate
+* description
+* timestamp