diff --git a/en:code-plugin.md b/en:code-plugin.md new file mode 100644 index 0000000..f42eacc --- /dev/null +++ b/en:code-plugin.md @@ -0,0 +1,199 @@ +## 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 +```python +import logging # Global logger +``` +Now you can send log messages with: + +```python +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: +```python +[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: +```python +from includes import globalVars # Global variables +``` + +Now you can get your configuration data with: +```python +VALUE = globalVars.config.get("SECTION", "OPTION") #Gets any value +``` +or better, use this: +```python +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 +```python +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. +```python +if configHandler.checkConfig("template"): #check config file + ########## User Plugin CODE ########## + pass +``` + + +#### 4.2 timeHandler.py +First you must include the helper file +```python +from includes.helper import timeHandler +``` +##### 4.2.1 `.curtime(format)` +```python +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()` +```python +timeHandler.getDate() # returns the current date in format `%d.%m.%Y` +``` +##### 4.2.3 `.getTime()` +```python +timeHandler.getTime() # returns the current time in format `%H:%M:%S` +``` +##### 4.2.4 `.getTimestamp()` +```python +timeHandler.getTimestamp() # returns the current linux timestamp +``` + +#### 4.3 wildcardHandler.py +First you must include the helper file +```python +from includes.helper import wildcardHandler +``` +##### 4.3.1 `.replaceWildcards(text,data)` +```python +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 \ No newline at end of file