From 5394bceedfd058b7316395ae0f312fc91b8fbad8 Mon Sep 17 00:00:00 2001 From: Schrolli Date: Wed, 27 May 2015 07:48:24 +0200 Subject: [PATCH] insert a Lots of Docu in includes --- includes/alarmHandler.py | 29 ++++++++++++++-- includes/decoder.py | 19 +++++++++++ includes/decoders/fms.py | 21 ++++++++++++ includes/decoders/poc.py | 35 +++++++++++++++++-- includes/decoders/zvei.py | 30 ++++++++++++++++ includes/filter.py | 37 ++++++++++++++++++++ includes/globals.py | 7 ++++ includes/pluginLoader.py | 35 +++++++++++++++++++ includes/shellHeader.py | 72 +++++++++++++++++++++++++-------------- 9 files changed, 255 insertions(+), 30 deletions(-) diff --git a/includes/alarmHandler.py b/includes/alarmHandler.py index 51536a7..bbcc24f 100644 --- a/includes/alarmHandler.py +++ b/includes/alarmHandler.py @@ -1,13 +1,38 @@ #!/usr/bin/python # -*- coding: cp1252 -*- -import logging +""" +Handler for the Filter and Plugins at an Alarm + +@author: Bastian Schroll + +@requires: none +""" + +import logging # Global logger from includes import globals # Global variables + def processAlarm(typ,freq,data): + """ + Function to process Filters and Plugins at Alarm + + @type typ: string (FMS|ZVEI|POC) + @param typ: Typ of the dataset + @type freq: string + @param freq: frequency of the SDR Stick + @type data: map of data (structure see interface.txt) + @param data: Contains the parameter + + @requires: active Plugins in pluginList + + @return: nothing + @exception: Exception if Alarm processing failed + """ try: logging.debug("[ ALARM ]") + #Go to all Plugins in pluginList for pluginName, plugin in globals.pluginList.items(): #if enabled use RegEx-Filter @@ -18,7 +43,7 @@ def processAlarm(typ,freq,data): plugin.run(typ,freq,data) logging.debug("return from: %s", pluginName) - else: + else: #RegEX Filter off - Call Plugin direct logging.debug("call Plugin: %s", pluginName) plugin.run(typ,freq,data) logging.debug("return from: %s", pluginName) diff --git a/includes/decoder.py b/includes/decoder.py index 680f803..0fcfd41 100644 --- a/includes/decoder.py +++ b/includes/decoder.py @@ -1,9 +1,28 @@ #!/usr/bin/python # -*- coding: cp1252 -*- +""" +Search for decode String and call the right decoder Funtion + +@author: Jens Herrmann + +@requires: none +""" + import logging def decode(freq, decoded): + """ + Search for decode String and call the right decoder Function + + @type freq: string + @param freq: frequency of the SDR Stick + @type decoded: string + @param decoded: RAW Information from Multimon-NG + + @return: nothing + @exception: Exception if decoder File call failed + """ try: #FMS Decoder Section #check FMS: -> check CRC -> validate -> check double alarm -> log diff --git a/includes/decoders/fms.py b/includes/decoders/fms.py index 934c7da..7ad12fa 100644 --- a/includes/decoders/fms.py +++ b/includes/decoders/fms.py @@ -1,6 +1,14 @@ #!/usr/bin/python # -*- coding: cp1252 -*- +""" +FMS Decoder + +@author: Bastian Schroll + +@requires: Configuration has to be set in the config.ini +""" + import logging import time #timestamp for doublealarm import re #Regex for validation @@ -10,6 +18,19 @@ from includes import globals # Global variables #FMS Decoder Function #validate -> check double alarm -> log def decode(freq, decoded): + """ + Export FMS Information from Multimon-NG RAW String and call alarmHandler.processAlarm() + + @type freq: string + @param freq: frequency of the SDR Stick + @type decoded: string + @param decoded: RAW Information from Multimon-NG + + @requires: Configuration has to be set in the config.ini + + @return: nothing + @exception: Exception if FMS decode failed + """ timestamp = int(time.time())#Get Timestamp fms_service = decoded[19] #Organisation diff --git a/includes/decoders/poc.py b/includes/decoders/poc.py index 593bd95..b58c8ca 100644 --- a/includes/decoders/poc.py +++ b/includes/decoders/poc.py @@ -1,6 +1,15 @@ #!/usr/bin/python # -*- coding: cp1252 -*- +""" +POCSAG Decoder + +@author: Bastian Schroll +@author: Jens Hermann + +@requires: Configuration has to be set in the config.ini +""" + import logging import time #timestamp for doublealarm import re #Regex for validation @@ -9,7 +18,17 @@ from includes import globals # Global variables # Simple Filter def isAllowed(poc_id): - """Simple filter for POCSAG""" + """ + Simple Filter Functions (Allowed ,Denied and Range) + + @type poc_id: string + @param poc_id: POCSAG Ric + + @requires: Configuration has to be set in the config.ini + + @return: True if the Ric is allows, other False + @exception: none + """ # 1.) If allowed RICs is set, only they will path, # If RIC is the right one return True, else False if globals.config.get("POC", "allow_ric"): @@ -36,7 +55,19 @@ def isAllowed(poc_id): #POCSAG Decoder Function #validate -> check double alarm -> log def decode(freq, decoded): - """Decode for structure of typ POCSAG""" + """ + Export POCSAG Information from Multimon-NG RAW String and call alarmHandler.processAlarm() + + @type freq: string + @param freq: frequency of the SDR Stick + @type decoded: string + @param decoded: RAW Information from Multimon-NG + + @requires: Configuration has to be set in the config.ini + + @return: nothing + @exception: Exception if POCSAG decode failed + """ bitrate = 0 timestamp = int(time.time())#Get Timestamp diff --git a/includes/decoders/zvei.py b/includes/decoders/zvei.py index 0c5688e..28f9255 100644 --- a/includes/decoders/zvei.py +++ b/includes/decoders/zvei.py @@ -1,6 +1,14 @@ #!/usr/bin/python # -*- coding: cp1252 -*- +""" +ZVEI Decoder + +@author: Bastian Schroll + +@requires: Configuration has to be set in the config.ini +""" + import logging import time #timestamp for doublealarm import re #Regex for validation @@ -10,6 +18,19 @@ from includes import globals # Global variables #ZVEI Decoder Function #validate -> check double alarm -> log def decode(freq, decoded): + """ + Export ZVEI Information from Multimon-NG RAW String and call alarmHandler.processAlarm() + + @type freq: string + @param freq: frequency of the SDR Stick + @type decoded: string + @param decoded: RAW Information from Multimon-NG + + @requires: Configuration has to be set in the config.ini + + @return: nothing + @exception: Exception if ZVEI decode failed + """ timestamp = int(time.time())#Get Timestamp zvei_id = decoded[7:12] #ZVEI Code @@ -31,6 +52,15 @@ def decode(freq, decoded): def removeF(zvei): + """ + Resolve the F from the repeat Tone + + @type zvei: string + @param zvei: ZVEI Information + + @return: ZVEI without F + @exception: none + """ if "F" in zvei: zvei_old = zvei for i in range(1, 5): diff --git a/includes/filter.py b/includes/filter.py index 7de49c4..63ee3b6 100644 --- a/includes/filter.py +++ b/includes/filter.py @@ -1,6 +1,14 @@ #!/usr/bin/python # -*- coding: cp1252 -*- +""" +Functions for the RegEX Filter + +@author: Bastian Schroll + +@requires: Configuration has to be set in the config.ini +""" + import logging # Global logger import re #Regex for Filter Check @@ -9,25 +17,54 @@ from includes import globals # Global variables def loadFilters(): + """ + load all Filters from the config.ini into globals.filterList + + @requires: Configuration has to be set in the config.ini + + @return: nothing + @exception: Exception if Filter loading failed + """ try: logging.debug("loading filters") + #For each entry in config.ini [Filters] Section for key,val in globals.config.items("Filters"): logging.debug(" - %s = %s", key, val) filter = val.split(";") + #insert splitet Data into globals.filterList globals.filterList.append({"name": key, "typ": filter[0], "dataField": filter[1], "plugin": filter[2], "regex": filter[3]}) except: logging.exception("cannot read config file") def checkFilters(data,typ,plugin): + """ + Check the Typ/Plugin combination with the RegEX Filter + If no Filter for the combination is found, Function returns True. + + @type data: map of data (structure see interface.txt) + @param data: Contains the parameter + @type typ: string (FMS|ZVEI|POC) + @param typ: Typ of the dataset + @type plugin: string + @param plugin: Name of the Plugin to checked + + @requires: all Filters in the filterList + + @return: nothing + @exception: Exception if Filter check failed + """ try: logging.debug("search Filter for %s to %s", typ, plugin) foundFilter = False + #go to all Filter in globals.filterList for i in globals.filterList: + #if Typ/Plugin combination is found if i["typ"] == typ and i["plugin"] == plugin: foundFilter = True logging.debug("found Filter: %s = %s", i["name"], i["regex"]) + #Check the RegEX if re.search(i["regex"], data[i["dataField"]]): logging.debug("Filter passed: %s", i["name"]) return True diff --git a/includes/globals.py b/includes/globals.py index f4af170..1169b29 100644 --- a/includes/globals.py +++ b/includes/globals.py @@ -1,6 +1,13 @@ #!/usr/bin/python # -*- coding: cp1252 -*- +""" +Global variables + +@author: Jens Hermann +@author: Bastian Schroll +""" + #Global variables config = 0 script_path = "" diff --git a/includes/pluginLoader.py b/includes/pluginLoader.py index 2818143..7e7134b 100644 --- a/includes/pluginLoader.py +++ b/includes/pluginLoader.py @@ -1,6 +1,14 @@ #!/usr/bin/python # -*- coding: cp1252 -*- +""" +Functions to Load and import the Plugins + +@author: Bastian Schroll + +@requires: Configuration has to be set in the config.ini +""" + import logging # Global logger import imp import os @@ -8,23 +16,40 @@ import os from includes import globals # Global variables def loadPlugins(): + """ + Load all Plugins into globals.pluginList + + @return: nothing + @exception: Exception if insert into globals.pluginList failed + """ try: logging.debug("loading plugins") + #go to all Plugins from getPlugins() for i in getPlugins(): + #call for each Plugin the loadPlugin() Methode plugin = loadPlugin(i) + #Add it to globals.pluginList globals.pluginList[i["name"]] = plugin except: logging.exception("cannot load Plugins") def getPlugins(): + """ + get a Python Dict of all activeated Plugins + + @return: Plugins as Python Dict + @exception: Exception if Plugin search failed + """ try: logging.debug("Search in Plugin Folder") PluginFolder = globals.script_path+"/plugins" plugins = [] + #Go to all Folders in the Plugin-Dir for i in os.listdir(PluginFolder): location = os.path.join(PluginFolder, i) + #Skip if Path.isdir() or no File DIR_NAME.py is found if not os.path.isdir(location) or not i + ".py" in os.listdir(location): continue @@ -45,6 +70,16 @@ def getPlugins(): def loadPlugin(plugin): + """ + Imports a single Plugin + + @type plugin: Plugin Data + @param plugin: Contains the information to import a Plugin + + + @return: nothing + @exception: Exception if Plugin import failed + """ try: logging.debug("load Plugin: %s", plugin["name"]) return imp.load_module(plugin["name"], *plugin["info"]) diff --git a/includes/shellHeader.py b/includes/shellHeader.py index 4387a6f..7f5e468 100644 --- a/includes/shellHeader.py +++ b/includes/shellHeader.py @@ -1,32 +1,52 @@ #!/usr/bin/python # -*- coding: cp1252 -*- +""" +Shows the Header in Shell if quiet Mode is not active + +@author: Bastian Schroll +@author: Jens Hermann + +@requires: none +""" def printHeader(args): - print " ____ ____ ______ __ __ __ " - print " / __ )/ __ \/ ___/ | / /___ _/ /______/ /_ b" - print " / __ / / / /\__ \| | /| / / __ `/ __/ ___/ __ \ e" - print " / /_/ / /_/ /___/ /| |/ |/ / /_/ / /_/ /__/ / / / t" - print " /_____/\____//____/ |__/|__/\__,_/\__/\___/_/ /_/ a" - print " German BOS Information Script " - print " by Bastian Schroll " - print "" + """ + Prints the Header to the Shell - print "Frequency: "+args.freq - print "Device-ID: "+str(args.device) - print "Error in PPM: "+str(args.error) - print "Active Demods: "+str(len(args.demod)) - if "FMS" in args.demod: - print "- FMS" - if "ZVEI" in args.demod: - print "- ZVEI" - if "POC512" in args.demod: - print "- POC512" - if "POC1200" in args.demod: - print "- POC1200" - if "POC2400" in args.demod: - print "- POC2400" - print "Squelch: "+str(args.squelch) - if args.verbose: - print "Verbose Mode!" - print "" \ No newline at end of file + @type args: Array + @param args: All given Arguments from argsparser + + @return: nothing + @exception: Exception if display of the Shell Header failed + """ + try: + print " ____ ____ ______ __ __ __ " + print " / __ )/ __ \/ ___/ | / /___ _/ /______/ /_ b" + print " / __ / / / /\__ \| | /| / / __ `/ __/ ___/ __ \ e" + print " / /_/ / /_/ /___/ /| |/ |/ / /_/ / /_/ /__/ / / / t" + print " /_____/\____//____/ |__/|__/\__,_/\__/\___/_/ /_/ a" + print " German BOS Information Script " + print " by Bastian Schroll " + print "" + + print "Frequency: "+args.freq + print "Device-ID: "+str(args.device) + print "Error in PPM: "+str(args.error) + print "Active Demods: "+str(len(args.demod)) + if "FMS" in args.demod: + print "- FMS" + if "ZVEI" in args.demod: + print "- ZVEI" + if "POC512" in args.demod: + print "- POC512" + if "POC1200" in args.demod: + print "- POC1200" + if "POC2400" in args.demod: + print "- POC2400" + print "Squelch: "+str(args.squelch) + if args.verbose: + print "Verbose Mode!" + print "" + except: + logging.exception("cannot display shell header") \ No newline at end of file