DevIo
An dieser Seite wird momentan noch gearbeitet. |
DevIo | |
---|---|
Zweck / Funktion | |
Hilfsfunktionen für die Kommunikation per serieller Schnittstelle (USB/RS232), TCP/IP-Verbindung oder UNIX-Socket | |
Allgemein | |
Typ | Hilfsmodul |
Details | |
Dokumentation | EN / DE |
Support (Forum) | FHEM Development |
Modulname | DevIo.pm |
Ersteller | rudolfkoenig (Forum / Wiki) |
Wichtig: sofern vorhanden, gilt im Zweifel immer die (englische) Beschreibung in der commandref! |
Das Modul DevIo(.pm) ist für Modulentwickler gedacht, um Daten zwischen einem FHEM-Modul und bspw. einer seriellen Schnittstelle, einer TCP/IP-Verbindung oder einem UNIX-Socket auszutauschen. Es übernimmt dabei die gesamte Verbindungsverwaltung und Aufrechterhaltung innerhalb von FHEM und nimmt dem Modulentwickler daher die gesamte Verbindungsverwaltung (Aufbau, Initialisierung, Neu-Verbindung bei Abbruch, etc.) ab. Es berücksichtigt dabei Besonderheiten zwischen Unix-basierten Betriebssystemen und Windows.
Es dient dabei lediglich dem Zweck einen Kommunikationskanal für eine Definition in FHEM zu etablieren und Daten darüber auszutauschen. Die Interpretation der empfangenen Daten obliegt dem Modul, welches die Verbindung via DevIo geöffnet hat. Die ausgetauschten Daten werden durch DevIo nicht verändert.
Allgemeine Funktionsweise
DevIo hat das Ziel eine besonders einfache Möglichkeit für Modulentwickler zu schaffen, um einen dauerhaften Kommunikationskanal zu etablieren. Um eine Verbindung aufzubauen muss zunächst die Gegenstelle bekannt sein. Dazu muss vor dem Verbindungsaufbau in dem Internal $hash->{DeviceName}
der jeweiligen Definition das Ziel hinterlegt werden. Dies kann bspw. eine serielle Schnittstelle sein (z.B. "/dev/ttyUSB0" oder "COM1" unter Windows) oder eine TCP/IP-Gegenstelle (z.B. "192.168.1.100:1012") sein. Eine detaillierte Aufstellung der möglichen Verbindungsarten und deren Angabe in $hash->{DeviceName}
gibt es im folgenden Kapitel Unterstützte Verbindungsarten.
Die Funktion DevIo_OpenDev() baut dabei die entsprechende Verbindung für eine einzelne Definition in Form eines Filedeskriptors auf und registriert diesen in dem globalen Hash %selectlist
[1]. Sobald die Verbindung erfolgreich aufgebaut wurde, kann beim eine durch den Modulautor mitgelieferte Initialisierungs-Funktion ausgeführt werden, um die Kommunikation zu initialiseren (bspw. das Senden einer Authentifizierungs-/Loginsequenz oder aktivieren der Hardware, etc.).
FHEM (respektive fhem.pl) prüft nun regelmäßig, ob Daten zum Lesen bereitstehen (also Daten empfangen wurden). Ist dies der Fall, so wird die X_Read()-Funktion des zugehörigen Moduls für die hinterlegte Definition aufgerufen. Hier können die Daten durch den Aufruf von DevIo_SimpleRead() nun eingelesen und verarbeitet werden. Das Senden von Daten ist durch den Aufruf von DevIo_SimpleWrite() sehr einfach möglich.
Sollte die Verbindung zusammenbrechen (USB-Gerät abgezogen, Gerät per Netzwerk nicht mehr erreichbar, etc.), so erkennt dies fhem.pl und führt die X_Ready()-Funktion des zugehörigen Moduls aus um zu prüfen, ob die Verbindung wieder aufgebaut werden kann. Hier wird nun erneut DevIo_OpenDev() ausgeführt um die Verbindung wieder herzustellen.
Sobald die Verbindung nicht mehr benötigt wird, oder FHEM bspw. beendet wird, kann die Verbindung via DevIo_Close() sauber geschlossen werden.
Unterstützte Verbindungsarten
Die folgenden Verbindungsarten können via DevIo realisiert werden.
Verbindungsart | Beispielangabe in$hash->{DeviceName} |
Beschreibung |
---|---|---|
Serielle Schnittstelle |
|
Durch Angabe eines Geräts in Form eines Gerätepfad (UNIX-basierte Betriebssysteme) oder der Schnittstellenbezeichnung aus Windows kann eine serielle Verbindung geöffnet werden. Der Gerätename kann zusätzliche Angaben zu Baudrate, Datenbits, Parität und Stoppbits enthalten um die Verbindung entsprechend zu konfiguieren. Diese Angaben sind durch ein "@" getrennt an die Gerätebezeichnung angehangen: Schematische Syntax:
Wenn man unter Unix-basierten Betriebssystemen die Schnittstelle nicht explizit konfiguriert öffnen möchte, sondern das Gerät direkt öffnen möchte (und damit die OS-Einstellungen verwendet), kann man durch Angabe von Bsp: Unter Windows verwendet man als Gerätename die entsprechende Schnittstellenbezeichung wie bspw. |
TCP/IP-Verbindung |
|
Durch Angabe eines Hostnamen oder IP-Adresse und einem Port, kann eine TCP-Verbindung aufgebaut werden. Dazu muss Hostname/IP-Adresse und Port in folgendem Schema angegeben werden: Schematische Syntax:
Die Verbindung kann optional verschlüsselt via SSL/TLS aufgebaut werden. Dazu muss das Internal |
UNIX-Socket |
|
TODO |
FHEM IO-Modul |
|
TODO: Beschreibung nach Thema |
Die Funktionen
DevIo_OpenDev
$error = DevIo_OpenDev($hash, $reopen, $initfn, $callback);
Die Funktion DevIo_OpenDev() öffnet eine Verbindung zu dem Endpunkt der in $hash->{DeviceName}
hinterlegt ist. Sobald die Verbindung erfolgreich hergestellt wurde, wird die Funktion $initfn
ausgeführt, sofern gesetzt, um die Verbindung zu initialisieren. Sofern eine TCP/IP-Verbindung hergestellt wird, kann eine optionale Callback-Funktion $callback
übergeben werden um den Verbindungsaufbau non-blocking durchzuführen.
Der Rückgabewert enthält im Fehlerfall eine entsprechende Fehlermeldung. Im Erfolgsfall wird undef
zurückgegeben. Sofern eine TCP/IP-Verbindung hergestellt wird und eine Callback-Funktion $callback
übergeben wurde, wird immer undef
zurückgegeben, da ein evtl. Fehler an diese Callback-Funktion nach dem erfolgten Verbindungsversuch mitgeteilt wird.
Parameter:
Parameter | Bedeutung |
---|---|
$hash
mandatory |
Die Hash-Referenz der Definition, für die eine Verbindung geöffnet werden soll |
$reopen
mandatory |
Flag (0 oder 1), ob es sich um einen erneuten Verbindungsversuch handelt (im Rahmen der X_Ready()-Funktion). Sollte es der erste Verbindungsversuch sein, so muss dieser Parameter den Wert 0 besitzen. |
$initfn
mandatory |
Der Name (als Zeichenkette) oder die Referenz auf eine Modulfunktion, welche optional nach dem erfolgreichen Aufbau/Wiederaufbau der Verbindung ausgeführt werden soll. Im Rahmen dieser Funktion kann weiterführende Kommunikation über die aufgebaute Verbindung erfolgen um zum Beispiel eine Loginsequenz oder eine Konfiguration der Gegenseite vorzunehmen, bevor die Verbindung allgemein benutzt werden kann.
Die Funktion welche in $ret = MYMODULE_InitFn($hash)
Wenn der Rückgabewert Beispiel:
|
$callback
optional |
Der Name (als Zeichenkette) oder die Referenz auf eine Modulfunktion, welche aufgerufen werden soll um evtl. Fehlermeldungen beim Verbindungsaufbau einer TCP/IP-Verbindung an das Modul zurückzuliefern. Wenn eine Callback-Funktion gesetzt ist, erfolgt der Verbindungsaufbau non-blocking. Andernfalls wartet DevIo_OpenDev() bis die Verbindung steht bzw. ein Fehler auftritt (z.B. Timeout).
Die Funktion welche in MYMODULE_ConnectCallbackFn($hash, $error)
Das Argument Beispiel:
|
Rückgabewert:
Rückgabe | Bedeutung |
---|---|
$error |
Eine Fehlermeldung als Zeichenkette, sollte der Verbindungsaufbau fehlschlagen. Im Erfolgsfall wird undef zurückgegeben.
Wenn es sich um eine TCP/IP-Verbindung handelt und eine Callback-Funktion als Parameter |
DevIo_SimpleRead
TBD
DevIo_SimpleReadWithTimeout
TBD
DevIo_SimpleWrite
TBD
DevIo_Expect
TBD
DevIo_Close
TBD
Beispiel
TBD
Referenzen
- ↑ Development Module Introduction - Wichtige globale Variablen aus fhem.pl