insert a Lots of Docu in includes

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)

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

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

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                  
 	

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

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

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 = ""

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"])

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 "" 
+	@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")