Jabber

Jabber
Zweck / Funktion
	Dieses Modul ermöglicht Fhem, sich mit dem Jabber-Netzwerk zu verbinden, um Nachrichten zu einem Jabber-Server zu senden oder von diesem zu empfangen.
Allgemein
Typ	Gerätemodul
Details
Dokumentation	EN / DE; Thema
Support (Forum)	Unterstuetzende Dienste
Modulname	70_Jabber.pm
Ersteller	BioS (Forum )
	Wichtig: sofern vorhanden, gilt im Zweifel immer die (englische) Beschreibung in der commandref!

Jabber ist eine andere Beschreibung für "XMPP", ein Kommunikationsprotokoll für Nachrichtenorientierte "middleware", basierend auf XML. Fester bestandteil des Protokolls ist die Verschlüsselung zwischen Client und Server. Für den Benutzer ist es ähnlich anderer Chat-Plattformen wie zum Beispiel dem facebook Chat, ICQ oder Google Hangouts - jedoch frei Verfügbar, open Source und normalerweise Verschlüsselt (was Serverabhängig ist).

Seit Version 1.5 kann dieses Modul in Multi-User-Channel (sogenannte MUC) beitreten und Off-the-Record (OTR) Ende-zu-Ende Verschlüsselung benutzen. OTR ist nochmal ein zusätzlicher Sicherheitsrelevater Punkt, da die Kommunikation wirklich von Endgerät zu FHEM verschlüsselt wird und man sich nicht auf die Jabber Server Transportverschlüsselung verlassen muss.

Voraussetzungen

Für dieses Modul brauchst du einen Account auf einem Jabber Server. Kostenlose Accounts und Server findet man unter jabber.org

Auf dem Fhem-Server müssen folgende Perl-Module installiert sein:

Net::Jabber
Net::XMPP
Authen::SASL
XML::Stream
Net::SSLeay
Crypt::OTR (wenn OTR verwendet werden soll)

Definition

define

define <name> Jabber <server> <port> <username> <password> <TLS> <SSL>: Du benötigst natürlich echte Accountdaten.

Beispiel

define JabberClient1 Jabber jabber.org 5222 myusername mypassword 1 0

set

set <name> msg <username> <msg>: Sendet eine Nachricht msg an den Jabberuser username

Beispiel:

set JabberClient1 msg myname@jabber.org It is working!

set <name> msgmuc <channel> <msg>: Sendet eine Nachricht msg an dieJabber-MUC-Gruppe channel; Dabei wird ein eventuell mitgegebener Nickname von "channel" entfernt, so kann man direkt das Reading LastMessageJID benutzen.

Beispiel:

set JabberClient1 msgmuc roomname@jabber.org Woot!

set <name> msgotr <username> <msg>: Sendet eine OTR verschlüsselte Nachricht an den username. Wenn keine aktive OTR Sitzung aufgebaut ist, wird versucht eine aufzubauen.; Wenn der Empfänger OTR nicht versteht, wird die Nachricht verworfen, d.h. sie wird auf keinen Fall im Klartext übertragen.

Beispiel:

set JabberClient1 msgotr myname@jabber.org Wir sehen uns heute um 18:00 Uhr :*

set <name> subscribe <username>: Frägt eine Authorisierung beim username an (normalerweise wird das nicht benötigt)

Beispiel:

set JabberClient1 subscribe myname@jabber.org

Attribute

OnlineStatus available|unavailable: Setzt den Online-status, ob der Client anderen gegenüber Online ist (available) oder Offline erscheint (unavailable); Es ist möglich dass einige Server eingehende Nachrichten trotzdem FHEM zustellen obwohl er "unavailable" ist

Standard: available

ResourceName <name>: In der Jabber-Welt kann ein Client mit einem Usernamen öfter mit einem Server verbunden sein (z.b. Handy, Computer, FHEM).; Der resource name ergibt die finale Jabber-ID und macht die verschiedenen Verbindungen einzigartig (z.B. bios@jabber.org/FHEM).; Hier kannst du den resource name setzen.

Standard: FHEM

PollTimer <seconds>: Dies ist der Intervall in der überprüft wird ob neue Nachrichten zur Verarbeitung beim Jabber Server anstehen.; Ebenfalls wird hiermit die Verbindung zum Server überprüft (Timeouts, DSL Disconnects etc.).; Setze es nicht über 10 Sekunden, die Verbindung kann sonst die ganze Zeit getrennt werden, Sie wird zwar wieder aufgebaut, aber nach 10 Sekunden brechen die meisten Server die Verbindung automatisch ab.

Standard: 2

RecvWhitelist <Regex>: Nur wenn die Jabber-ID einer privaten empfangenen Nachricht auf diese Regex zutrifft, akzeptiert FHEM die Nachricht und gibt sie an Notifys weiter. Alles andere wird verworfen.

Standard: .*

Beispiele:

myname@jabber.org
(myname1@jabber.org|myname2@xmpp.de)

MucJoin: Tritt dem MUC mit dem spezifizierten Nickname und dem optionalem Passwort bei.

Standard: nicht definiert

Beispiele:

Einen Raum betreten: channel1@server.com/mynick
Mehrere Räume betreten: channel1@server.com/mynick,channel2@server.com/myothernick
Einen Raum mit Passwort betreten: channel1@server.com/mynick:password

MucRecvWhitelist <Regex>: Selbe funktion wie RecvWhitelist, aber für Gruppenräume: Nur wenn die Regex zutrifft, wird die Nachricht verarbeitet. Alles andere wird ignoriert.

Standard: nicht definiert (keine Nachricht wird akzeptiert)

Beispiele:

Alle Nachrichten aller betretenen Räume erlauben: .*
Alle Nachrichten bestimmter betretenen Räume erlauben: mychannel@jabber.org
Nur bestimmte User in bestimmten betretenen Räumen erlauben: mychannel@jabber.org/NickOfFriend

OTREnable 1|0: Schaltet die Verschlüsselungsfunktionen von Crypt::OTR für sichere Ende-zu-Ende Kummunikation in FHEM an oder aus.; Es muss zwangsläufig dafür Crypt::OTR installiert sein.; Ein Privater Schlüssel wird bei Erstbenutzung generiert, das kann mehr als 2 Stunden dauern! Dafür ist das eine einmalige Sache und FHEM wird dadurch nicht blockiert. Im Device sieht man im OTR_STATE wenn der Private Schlüssel fertig ist. Erst danach ist OTR aktiv.

Standard: nicht definiert (OTR deaktiviert)

OTRSharedSecret aSecretKeyiOnlyKnow@@*: Optionales geheimes Passwort, dass man vom Endgerät an FHEM schicken kann um zu beweisen, dass es sich tatsächlich um FHEM handelt und nicht um einen Hacker der sich (z.b. bei dem Internetprovider) zwischengeschaltet hat. Normalerweise bekommt das Endgerät eine Warnung wenn sich an einer bereits verifizierten Verbindung etwas geändert hat.; Diese Warnung sollte man dann sehr ernst nehmen.

Standard: nicht definiert, setze hier dein geheimes Passwort.

Generierte Readings/Events

Privat Nachrichten
- Message - Komplette Nachricht inkl. JID und Text
- LastMessage - Nur der Textteil der Nachricht
- LastSenderJID - Nur die Sender-JID der Nachricht

Verschlüsselte Private Nachrichten (wenn OTREnable=1)
- OTRMessage - Komplette entschlüsselte Nachricht inkl. JID und Text
- OTRLastMessage - Nur der Textteil der Nachricht
- OTRLastSenderJID - Nur die Sender-JID der Nachricht

MUC Raum Nachrichten (wenn MUCJoin gesetzt ist)
- MucMessage - Komplette Nachricht (Raumname/Nickname und Text)
- MucLastMessage - Nur der Textteil der Nachricht
- MucLastSenderJID - Nur die Sender-JID der Nachricht

Beispiele

Mit folgendem Notify-Beispiel kannst du auf eingehende Nachrichten reagieren, dieses Beispiel schickt das Reading "Temperatur" des Sensors "BU_Temperatur" bei jeder ankommenden Nachricht an den Sender zurück:

define Jabber_Notify notify JabberClient1:Message.* {
      my $lastsender=ReadingsVal("JabberClient1","LastSenderJID","0");
      my $lastmsg=ReadingsVal("JabberClient1","LastMessage","0");
      my $temperature=ReadingsVal("BU_Temperatur","temperature","0");
      fhem("set JabberClient1 msg ". $lastsender . " Temp: ".$temperature);
}

Auf MUC Nachrichten lässt sich folgend reagieren, Augenmerk darauf legen dass der Nickname aus $lastsender in der msgmuc Funktion entfernt wird, damit die Nachricht an den Raum geht

define Jabber_Notify notify JabberClient1:MucMessage.* {
      my $lastsender=ReadingsVal("JabberClient1","LastSenderJID","0");
      my $lastmsg=ReadingsVal("JabberClient1","LastMessage","0");
      my $temperature=ReadingsVal("BU_Temperatur","temperature","0");
      fhem("set JabberClient1 msgmuc ". $lastsender . " Temp: ".$temperature);
}

Auf OTR Nachrichten wird reagiert, wie auf normale private Nachrichten auch, jedoch wird mit der msgotr Funktion geantwortet:

define Jabber_Notify notify JabberClient1:OTRMessage.* {
      my $lastsender=ReadingsVal("JabberClient1","LastSenderJID","0");
      my $lastmsg=ReadingsVal("JabberClient1","LastMessage","0");
      my $temperature=ReadingsVal("BU_Temperatur","temperature","0");
      fhem("set JabberClient1 msgotr ". $lastsender . " Temp: ".$temperature);
}

Weblinks