BW3-Core/develop/ModulPlugin.html

416 lines
20 KiB
HTML
Raw Normal View History

<!DOCTYPE html>
<html lang="en" data-bs-theme="light">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="author" content="Bastian Schroll & BW3 Dev team">
<link rel="shortcut icon" href="../img/favicon.ico">
<title>Eigenes Modul/Plugin schreiben - BOSWatch3 Core</title>
<link href="../css/bootstrap.min.css" rel="stylesheet">
<link href="../css/fontawesome.min.css" rel="stylesheet">
<link href="../css/brands.min.css" rel="stylesheet">
<link href="../css/solid.min.css" rel="stylesheet">
<link href="../css/v4-font-face.min.css" rel="stylesheet">
<link href="../css/base.css" rel="stylesheet">
<link id="hljs-light" rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/styles/github.min.css" >
<link id="hljs-dark" rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/styles/github-dark.min.css" disabled>
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/highlight.min.js"></script>
<script>hljs.highlightAll();</script>
</head>
<body>
<div class="navbar fixed-top navbar-expand-lg navbar-dark bg-primary">
<div class="container">
<a class="navbar-brand" href="..">BOSWatch3 Core</a>
<!-- Expander button -->
<button type="button" class="navbar-toggler" data-bs-toggle="collapse" data-bs-target="#navbar-collapse" aria-controls="navbar-collapse" aria-expanded="false" aria-label="Toggle navigation">
<span class="navbar-toggler-icon"></span>
</button>
<!-- Expanded navigation -->
<div id="navbar-collapse" class="navbar-collapse collapse">
<!-- Main navigation -->
<ul class="nav navbar-nav">
<li class="nav-item dropdown">
<a href="#" class="nav-link dropdown-toggle" role="button" data-bs-toggle="dropdown" aria-expanded="false">Quick Start</a>
<ul class="dropdown-menu">
<li>
<a href="../tbd.html" class="dropdown-item">Installation</a>
</li>
<li>
<a href="../config.html" class="dropdown-item">Konfiguration</a>
</li>
</ul>
</li>
<li class="nav-item dropdown">
<a href="#" class="nav-link dropdown-toggle" role="button" data-bs-toggle="dropdown" aria-expanded="false">Informationen</a>
<ul class="dropdown-menu">
<li>
<a href="../information/serverclient.html" class="dropdown-item">Server/Cient Prinzip</a>
</li>
<li>
<a href="../information/broadcast.html" class="dropdown-item">Broadcast Service</a>
</li>
<li>
<a href="../information/router.html" class="dropdown-item">Routing Mechanismus</a>
</li>
<li>
<a href="../changelog.html" class="dropdown-item">Changelog</a>
</li>
</ul>
</li>
<li class="nav-item dropdown">
<a href="#" class="nav-link dropdown-toggle" role="button" data-bs-toggle="dropdown" aria-expanded="false">Module</a>
<ul class="dropdown-menu">
<li>
<a href="../modul/descriptor.html" class="dropdown-item">Descriptor</a>
</li>
<li>
<a href="../modul/geocoding.html" class="dropdown-item">Geocoding</a>
</li>
<li>
<a href="../modul/mode_filter.html" class="dropdown-item">Mode Filter</a>
</li>
<li>
<a href="../modul/regex_filter.html" class="dropdown-item">Regex Filter</a>
</li>
<li>
<a href="../modul/double_filter.html" class="dropdown-item">Double Filter</a>
</li>
</ul>
</li>
<li class="nav-item dropdown">
<a href="#" class="nav-link dropdown-toggle" role="button" data-bs-toggle="dropdown" aria-expanded="false">Plugins</a>
<ul class="dropdown-menu">
<li>
<a href="../plugin/http.html" class="dropdown-item">Http</a>
</li>
<li>
<a href="../plugin/telegram.html" class="dropdown-item">Telegram</a>
</li>
<li>
<a href="../plugin/divera.html" class="dropdown-item">Divera</a>
</li>
<li>
<a href="../plugin/mysql.html" class="dropdown-item">MySQL</a>
</li>
</ul>
</li>
<li class="nav-item dropdown">
<a href="#" class="nav-link dropdown-toggle active" aria-current="page" role="button" data-bs-toggle="dropdown" aria-expanded="false">Entwickler</a>
<ul class="dropdown-menu">
<li>
<a href="ModulPlugin.html" class="dropdown-item active" aria-current="page">Eigenes Modul/Plugin schreiben</a>
</li>
<li>
<a href="packet.html" class="dropdown-item">BOSWatch Alarmpaket Format</a>
</li>
<li>
<a href="../api/html/index.html" class="dropdown-item">BW3 Quellcode Dokumentation</a>
</li>
</ul>
</li>
</ul>
<ul class="nav navbar-nav ms-md-auto">
<li class="nav-item">
<a href="#" class="nav-link" data-bs-toggle="modal" data-bs-target="#mkdocs_search_modal">
<i class="fa fa-search"></i> Search
</a>
</li>
<li class="nav-item">
<a rel="prev" href="../plugin/mysql.html" class="nav-link">
<i class="fa fa-arrow-left"></i> Previous
</a>
</li>
<li class="nav-item">
<a rel="next" href="packet.html" class="nav-link">
Next <i class="fa fa-arrow-right"></i>
</a>
</li>
<li class="nav-item">
<a href="https://github.com/BOSWatch/BW3-Core/edit/develop/docu/docs/develop/ModulPlugin.md" class="nav-link"><i class="fa-brands fa-github"></i> Edit on GitHub</a>
</li>
</ul>
</div>
</div>
</div>
<div class="container">
<div class="row">
<div class="col-md-3"><div class="navbar-expand-md bs-sidebar hidden-print affix" role="complementary">
<div class="navbar-header">
<button type="button" class="navbar-toggler collapsed" data-bs-toggle="collapse" data-bs-target="#toc-collapse" title="Table of Contents">
<span class="fa fa-angle-down"></span>
</button>
</div>
<div id="toc-collapse" class="navbar-collapse collapse card bg-body-tertiary">
<ul class="nav flex-column">
<li class="nav-item" data-bs-level="1"><a href="#eigenes-modulplugin-schreiben" class="nav-link">Eigenes Modul/Plugin schreiben</a>
<ul class="nav flex-column">
<li class="nav-item" data-bs-level="2"><a href="#allgemeine-informationen" class="nav-link">Allgemeine Informationen</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-bs-level="2"><a href="#benotigte-methoden-uberschreiben" class="nav-link">Benötigte Methoden überschreiben</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-bs-level="2"><a href="#konfiguration" class="nav-link">Konfiguration</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-bs-level="2"><a href="#arbeiten-mit-dem-bwpacket" class="nav-link">Arbeiten mit dem bwPacket</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-bs-level="2"><a href="#nutzung-der-wildcards" class="nav-link">Nutzung der Wildcards</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-bs-level="2"><a href="#richtiges-logging" class="nav-link">Richtiges Logging</a>
<ul class="nav flex-column">
</ul>
</li>
</ul>
</li>
</ul>
</div>
</div></div>
<div class="col-md-9" role="main">
<h1 id="eigenes-modulplugin-schreiben"><center>Eigenes Modul/Plugin schreiben</center></h1>
<p>Um ein eigenes Modul oder Plugin zu schreiben, sollte man sich am besten zuerst einmal das das <code>template</code> im entsprechenden Ordner ansehen. Dies kann als Vorlage für das eigene Modul oder Plugin genutzt werden.</p>
<hr />
<h2 id="allgemeine-informationen">Allgemeine Informationen</h2>
<p>Im ersten Schritt sollte eine Kopie des jeweiligen Templates (Modul oder Plugin) erstellt werden. Nun sollten im Dateikopf die Angaben angepasst werden.</p>
<hr />
<h2 id="benotigte-methoden-uberschreiben">Benötigte Methoden überschreiben</h2>
<h3 id="modul">Modul</h3>
<p>Die Modul Basisklasse bietet einige Methoden, welche vom Modul überschrieben werden können.</p>
<ul>
<li><code>onLoad()</code> wird direkt beim Import des Moduls ausgeführt</li>
<li><code>doWork(bwPacket)</code> wird bei der Ausführung aufgerufen</li>
<li><code>onUnload()</code> wird beim Zerstören der Plugin Modul zum Programmende ausgeführt</li>
</ul>
<h3 id="plugin">Plugin</h3>
<p>Die Plugin Basisklasse bietet einige Methoden, welche vom Plugin überschrieben werden können.</p>
<ul>
<li><code>onLoad()</code> wird direkt beim Import des Plugins ausgeführt</li>
<li><code>setup()</code> wird vor jeder Ausführung gerufen</li>
<li><code>fms(bwPacket)</code> wird bei einem FMS Paket ausgeführt</li>
<li><code>pocsag(bwPacket)</code> wird bei einem POCSAG Paket ausgeführt</li>
<li><code>zvei(bwPacket)</code> wird bei einem ZVEI Packet ausgeführt</li>
<li><code>msg(bwPacket)</code> wird bei einem Nachrichten Packet ausgeführt</li>
<li><code>teardown()</code> wird nach jeder Ausführung gerufen</li>
<li><code>onUnload()</code> wird beim Zerstören der Plugin Instanz zum Programmende ausgeführt</li>
</ul>
<hr />
<h2 id="konfiguration">Konfiguration</h2>
<h3 id="konfiguration-anlegen">Konfiguration anlegen</h3>
<p>Jedes Modul oder Plugin wird in einem Router folgendermaßen deklariert:</p>
<pre><code class="language-yaml">- type: module # oder 'plugin'
res: template_module # Name der Python Datei (ohne .py)
name: Mein Modul # optionaler Name
config: # config-Sektion
option1: value 1
option2:
underOption1: value 21
underOption2: value 22
list:
- list 1
- list 2
</code></pre>
<p>Eine entsprechende Dokumentation der Parameter <strong>muss</strong> in der Dokumentation des jeweiligen Moduls oder Plugins hinterleget werden.</p>
<h3 id="konfiguration-verwenden">Konfiguration verwenden</h3>
<p>Wird der Instanz eine Konfiguration übergeben wird diese in <code>self.config</code> abgelegt und kann wie folgt abgerufen werden:<br />
(Dies Ergebnisse beziehen sich auf das Konfigurationsbeispiel oben)</p>
<ul>
<li>
<p>Einzelnes Feld auslesen<br />
<code>self.config.get("option1")</code></p>
<blockquote>
<p>liefert <code>value 1</code></p>
</blockquote>
</li>
<li>
<p>Verschachteltes Feld auslesen (beliebige tiefe möglich)<br />
<code>self.config.get("option2", "underOption1")</code></p>
<blockquote>
<p>liefert <code>value 21</code></p>
</blockquote>
</li>
<li>
<p>Es kann ein Default Wert angegeben werden (falls entsprechender Eintrag fehlt)<br />
<code>self.config.get("notSet", default="defValue")</code> </p>
<blockquote>
<p>liefert <code>defValue</code></p>
</blockquote>
</li>
<li>
<p>Über Listen kann einfach iteriert werden<br />
<code>for item in self.config.get(FIELD):</code></p>
<blockquote>
<p>liefert ein Element je Iteration - hier <code>list 1</code> und <code>list 2</code></p>
</blockquote>
</li>
</ul>
<p>Wird ein End-Wert ausgelesen, wird dieser direkt zurück gegeben.<br />
Sollten weitere Unterelemente oder eine Liste exisitieren wird erneut ein Objekt der Klasse <code>Config()</code> zurück gegeben, auf welches wiederum nach obigem Schema zugegriffen werden kann.</p>
<hr />
<h2 id="arbeiten-mit-dem-bwpacket">Arbeiten mit dem bwPacket</h2>
<p>An das Modul bzw. Plugin wird eine Instanz eines BOSWatch-Paket Objekts übergeben.<br />
Aus dieser kann mittels <code>bwPacket.get(FIELDNAME)</code> das entsprechende Feld ausgelesen werden.<br />
Mittels <code>bwPacket.set(FIELDNAME, VALUE)</code> kann ein Wert hinzugefügt oder modifiziert werden.<br />
Eine Auflistung der bereitgestellten Informationen findet sich im entsprechenden <a href="packet.html">BOSWatch Paket</a> Dokumentation.</p>
<p><strong>Bitte beachten:</strong></p>
<ul>
<li>Selbst vom Modul hinzugefügte Felder <strong>müssen</strong> in der Modul Dokumentation unter <code>Paket Modifikation</code> aufgeführt werden.</li>
<li>Sollte ein Modul oder Plugin Felder benutzen, welche in einem anderen Modul erstellt werden, <strong>muss</strong> dies im Punkt <code>Abhänigkeiten</code> des jeweiligen Moduls oder Plugins dokumentiert werden.</li>
</ul>
<h3 id="ruckgabewert-bei-modulen">Rückgabewert bei Modulen</h3>
<p>Module können Pakete beliebig verändern. Diese Änderungen werden im Router entsprechend weitergeleitet.</p>
<p>Mögliche Rückgabewerte eines Moduls:</p>
<ul>
<li><code>return bwPacket</code> Gibt das modifizierte bwPacket an den Router zurück (Paket Modifikation)</li>
<li><code>return None</code> Der Router fährt mit dem unveränderten bwPacket fort (Input = Output)</li>
<li><code>return False</code> Der Router stopt sofort die Ausführung (zB. in Filtern verwendet)</li>
</ul>
<h3 id="ruckgabewert-bei-plugins">Rückgabewert bei Plugins</h3>
<p>Plugins geben keine Pakete mehr zurück. Sie fungieren ausschließlich als Endpunkt.<br />
Die Plugin Basisklasse liefert intern immer ein <code>None</code> an den Router zurück,
was zur weiteren Ausführung des Routers mit dem original Paket führt. Daher macht es in Plugins keinen Sinn ein Paket zu modifizieren.</p>
<hr />
<h2 id="nutzung-der-wildcards">Nutzung der Wildcards</h2>
<p>Es gibt einige vordefinierte Wildcards welche in der <a href="packet.html">BOSWatch Paket</a> Dokumentation zu finden sind.</p>
<p>Außerdem sind die folgenden allgemeinen Wildcards definiert:</p>
<ul>
<li><code>{BR}</code> - Zeilenumbruch <code>\r\n</code></li>
<li><code>{LPAR}</code> - öffnende Klammer <code>(</code></li>
<li><code>{RPAR}</code> - schließende Klammer <code>)</code></li>
<li><code>{TIME}</code> - Aktueller Zeitstempel im Format <code>%d.%m.%Y %H:%M:%S</code></li>
</ul>
<h3 id="wildcards-registrieren-module">Wildcards registrieren [Module]</h3>
<p>Module können zusätzliche Wildcards registrieren welche anschließend in den Plugins ebenfalls geparst werden können.
Dies kann über die interne Methode <code>self.registerWildcard(newWildcard, bwPacketField)</code> gemacht werden.</p>
<ul>
<li><code>newWildcard</code> muss im folgenden Format angegeben werden: <code>{WILDCARD}</code></li>
<li><code>bwPacketField</code> ist der Name des Feldes im bwPacket - gestezt per <code>bwPacket.set(FIELDNAME, VALUE)</code></li>
</ul>
<p><strong>Bitte beachten:</strong></p>
<ul>
<li>Selbst vom Modul registrierte Wildcards <strong>müssen</strong> in der Modul Dokumentation unter <code>Zusätzliche Wildcards</code> aufgeführt werden.</li>
</ul>
<h3 id="wildcards-parsen-plugins">Wildcards parsen [Plugins]</h3>
<p>Das parsen der Wildcars funktioniert komfortabel über die interne Methode <code>msg = self.parseWildcards(msg)</code>.</p>
<ul>
<li><code>msg</code> enstrpicht dabei dem String in welchem die Wildcards ersetzt werden sollen</li>
</ul>
<p>Die Platzhalter der Wildcards findet man in der <a href="packet.html">BOSWatch Paket</a> Dokumentation.</p>
<p>Sollten Module zusätzliche Wildcards registrieren, findet man Informationen dazu in der jeweiligen Modul Dokumentation</p>
<hr />
<h2 id="richtiges-logging">Richtiges Logging</h2>
<p>tbd ... </p></div>
</div>
</div>
<footer class="col-md-12">
<hr>
<p>Documentation built with <a href="https://www.mkdocs.org/">MkDocs</a>.</p>
</footer>
<script src="../js/bootstrap.bundle.min.js"></script>
<script>
var base_url = "..",
shortcuts = {"help": 191, "next": 78, "previous": 80, "search": 83};
</script>
<script src="../js/base.js"></script>
<script src="../search/main.js"></script>
<div class="modal" id="mkdocs_search_modal" tabindex="-1" role="dialog" aria-labelledby="searchModalLabel" aria-hidden="true">
<div class="modal-dialog modal-lg">
<div class="modal-content">
<div class="modal-header">
<h4 class="modal-title" id="searchModalLabel">Search</h4>
<button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
</div>
<div class="modal-body">
<p>From here you can search these documents. Enter your search terms below.</p>
<form>
<div class="form-group">
<input type="search" class="form-control" placeholder="Search..." id="mkdocs-search-query" title="Type search term here">
</div>
</form>
<div id="mkdocs-search-results" data-no-results-text="No results found"></div>
</div>
<div class="modal-footer">
</div>
</div>
</div>
</div><div class="modal" id="mkdocs_keyboard_modal" tabindex="-1" role="dialog" aria-labelledby="keyboardModalLabel" aria-hidden="true">
<div class="modal-dialog">
<div class="modal-content">
<div class="modal-header">
<h4 class="modal-title" id="keyboardModalLabel">Keyboard Shortcuts</h4>
<button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
</div>
<div class="modal-body">
<table class="table">
<thead>
<tr>
<th style="width: 20%;">Keys</th>
<th>Action</th>
</tr>
</thead>
<tbody>
<tr>
<td class="help shortcut"><kbd>?</kbd></td>
<td>Open this help</td>
</tr>
<tr>
<td class="next shortcut"><kbd>n</kbd></td>
<td>Next page</td>
</tr>
<tr>
<td class="prev shortcut"><kbd>p</kbd></td>
<td>Previous page</td>
</tr>
<tr>
<td class="search shortcut"><kbd>s</kbd></td>
<td>Search</td>
</tr>
</tbody>
</table>
</div>
<div class="modal-footer">
</div>
</div>
</div>
</div>
</body>
</html>