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. Sobald die Verbindung erfolgreich aufgebaut wurde, kann 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 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	/dev/ttyUSB0 /dev/ttyUSB0@9600 /dev/ttyUSB0@9600,7,E,2 /dev/ttyUSB0@directio COM1@9600	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: <Gerät>@<Baudrate>,<Datenbits>,<Parität>,<Stopbits> <Baudrate> - Eine gültige Taktfrequenz (Symbole pro Sekunde) mit der die Schnittstelle geöffnet werden soll (Beispiel: 9600, 14400, 115200, ...) <Datenbits> - Die Anzahl an Datenbits (7 oder 8 Datenbits). Standardwert sofern nicht angegeben sind 8 Datenbits. <Parität> - Die zu verwendende Parität, sofern benötigt. Dabei bedeutet der Wert N keine Parität, O bedeutet ungleiche Parität (odd) und E bedeutet gleiche Parität (even) Standardwert sofern nicht angegeben ist N (keine Parität). <Stopbits> - Die Anzahl an zu verwendenden Stopbits (0, 1 oder 2 Stopbits). Standardwert sofern nicht angegeben sind 0 Stopbits. 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 @directio die Konfiguration der Schnittstelle umgehen und das Gerät direkt öffnen: Bsp: /dev/ttyUSB0@directio Unter Windows verwendet man als Gerätename die entsprechende Schnittstellenbezeichung wie bspw. COM1, COM2, usw.
TCP/IP-Verbindung	192.168.1.2:1012 raspberry:5000	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: <Hostname/IP-Adresse>:<Port> <Hostname/IP-Adresse> - Der Hostname oder die IP-Adresse des zu verbindenden Gerätes/Server. <Port> - Der Zielport zu dem sich verbunden werden soll (0-65535). Die Verbindung kann optional verschlüsselt via SSL/TLS aufgebaut werden. Dazu muss das Internal $hash->{SSL} auf 1 gesetzt werden.
UNIX-Socket	UNIX:SEQPACKET:/var/tmp/me_avm_home_external.ctl UNIX:STREAM:/var/socket/con	TODO
FHEM IO-Modul	FHEM:DEVIO:Firmata_SerielleSchnittstelle@9600	TODO: Beschreibung nach Thema

Die Funktionen

DevIo_OpenDev

TBD

DevIo_SimpleRead

TBD

DevIo_SimpleReadWithTimeout

TBD

DevIo_SimpleWrite

TBD

DevIo_Expect

TBD

DevIo_Close

TBD

Beispiel

TBD