en:code plugin - Schrolli91/BOSWatch GitHub Wiki

How to Code your own plugin:

More information and a little Tutorial coming soon!

1. Plugin template

1.1 General

You can find a little template plugin file in plugins/template/template.py But you can also take a look in all other plugins.

A plugin must be in an seperate folder with the same name of the .py file

1.2 Plugin Init .onLoad()

This .onLoad() routine is called one time for initialize the plugin

1.3 Plugin call .run()

This .run() routine is called every time an alarm comes in

Here are the information from BOSWatch available. See section 5. Process the data from BOSWatch

2. Use Global Logging

2.1 Init and Use

First you must import the logging module

import logging # Global logger

Now you can send log messages with:

logging.LOGLEVEL("MESSAGE")

You must replace the word LOGLEVEL with one if the following debug, info, warning or error

To use the right loglevel see next section 2.2 Choose right Loglevel

2.2 Choose right Loglevel

debug all messages to find errors and for the internal program flow.

info messages that serve only to inform the user.

warning Warnings are notes and technical errors. Never leads to terminate BOSWatch.

error An error that does not necessarily lead to end of BOSWatch, but an administrator intervention required.

critical errors leading to the end of boswatch immediate - in plugins not allowed (Plugin cannot crash the entire program)

3. Use config file

3.1 Own configuration in config.ini

First you must set a new Section in config.ini A section is between brackets. Its recommended to give the section the same name as the plugin. [SECTION_NAME]

Now you can an set a unlimited number of options with its own value in these format: OPTION = VALUE.

Here is the sample from the template plugin:

[template]
test1 = testString
test2 = 123456

3.2 Read data from config.ini

To read yout configuration data you must import the globalVars.py where the global config-object is located:

from includes import globalVars  # Global variables

Now you can get your configuration data with:

VALUE = globalVars.config.get("SECTION", "OPTION") #Gets any value

or better, use this:

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. Global helper functions

4.1 configHandler.py

First you must include the helper file

from includes.helper import configHandler
4.1.1 .checkConfig(section)

This function read all options from a config section and prints it to the debug log. The return value is true, also the section var is empty. In case of error a false is returned and error printed to log.

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

4.2 timeHandler.py

First you must include the helper file

from includes.helper import timeHandler
4.2.1 .curtime(format)
timeHandler.curtime() # returns a formated datetime string

you can give the function an format string. See https://docs.python.org/2/library/time.html#time.strftime

default (without format parameter) the function returns a date time with this 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

First you must include the helper file

from includes.helper import wildcardHandler
4.3.1 .replaceWildcards(text,data)
wildcardHandler.replaceWildcards(text,data) # replace all standard wildcards

replace all the standard wildcards in the given text the function needs the data[ ] var

defined wildcards:

General:

  • %TIME% = Time (by script)

  • %DATE% = Date (by script)

  • %DESCR% = Description from csv-file

  • %BR% = new line

  • %LPAR% = "("

  • %RPAR% = ")"

FMS:

  • %FMS% = FMS Code
  • %STATUS% = FMS Status
  • %DIR% = Direction of the telegram (0/1)
  • %DIRT% = Direction of the telegram (Text-String)
  • %TSI% = Tactical Short Information (I-IV)

ZVEI:

  • %ZVEI% = ZVEI 5-tone Code

POCSAG:

  • %RIC% = Pocsag RIC
  • %FUNC% = Pocsac function/Subric (1-4)
  • %FUNCCHAR% = Pocsac function/Subric als character (a-d)
  • %FUNCTEXT% = Pocsac function/Subric static massage definded in pocsag section
  • %MSG% = Message of the Pocsag telegram
  • %BITRATE% = Bitrate of the Pocsag telegram

5. Process the data from BOSWatch

Three parameters are passed during the alarm to the .run() method

5.1 typ

Thats the function of the alarm. Possible values are FMS, ZVEI or POC

5.2 freq

The reception frequency of the tuner in Hz

5.3 data[ ]

You can get an information with data["INFO"] In the data map are the folowing informations:

ZVEI:

  • zvei
  • description
  • timestamp

FMS:

  • fms
  • status
  • direction
  • directionText
  • tsi
  • description
  • timestamp

POCSAG:

  • ric
  • function
  • functionChar
  • msg
  • bitrate
  • description
  • timestamp