FHEMWiki - Benutzerbeiträge [de]

HomeConnect

2019-10-24T13:33:04Z

Hoppel118: Neues Kapitel "Fehler während der Installation" ergänzt

{{Infobox Modul
|ModPurpose=Anbindung von Hausgeräten mit Home Connect Schnittstelle
|ModType=d
|ModForumArea=Home Connect
|ModTechName=48_HomeConnectConnection.pm 48_HomeConnect.pm
|ModOwner=swhome
}}
==Übersicht==
Mit den beiden Modulen HomeConnectConnection und HomeConnect können in FHEM Devices für [http://www.home-connect.com/de/de/ Home Connect Hausgeräte] angelegt werden, die an einem Home Connect Account angemeldet sind. Mögliche Hausgeräte sind aktuell Backöfen, Spülmaschinen, Kühlschränke, Waschmaschinen, Wäschetrockner und Kaffeemaschinen der Marken Bosch, Siemens und Neff.

Wann verwendet man HomeConnectConnection, wann HomeConnect?

Das Modul HomeConnectConnection verwaltet die Verbindung zwischen FHEM und einem Home Connect Account. Es legt die HomeConnect Devices für die einzelnen Hausgeräte an.

==Aktueller Status des Moduls==
Die beiden Module befinden sich aktuell im Betatest. Jeder Tester muss sich bei Home Connect als Entwickler anmelden und den Login-Namen seines Home Connect App Accounts hinterlegen. Was jeder auch ohne eigene Geräte probieren kann ist der Hausgeräte-Simulator. Allerdings kann man damit in der Praxis nicht viel anfangen...

==Definition von FHEM Devices==
===Modul-Installation===
Zur Installation (oder zum Update) einfach diesen Befehl in der FHEM Kommandozeile eingeben:

<pre>
update all https://raw.githubusercontent.com/sw-home/FHEM-HomeConnect/master/controls_homeconnect.txt
</pre>

Danach FHEM neu starten.

Damit das Modul auch bei einem normale "update check" mit geprüft wird, muss folgendes ergänzt werden
<pre>
update add https://raw.githubusercontent.com/sw-home/FHEM-HomeConnect/master/controls_homeconnect.txt
</pre>

===Basisdefinition===
Um mit dem Simulator zu testen, braucht Ihr einen [https://developer.home-connect.com/ Entwickleraccount bei HomeConnect]

Man braucht zwingend einen Advanced Account um Geräte fernstarten zu dürfen. Das kostet nichts, es wird jedoch eine Namensverifikation durchgeführt.

Im Entwickleraccount muss eine Applikation generiert werden, als „Company Name“ im Home Connect Developer Portal bitte “FHEM Betatester“ angeben. Die wichtigste Einstellung der Applikation ist die Redirect URL. Diese URL muss den Host enthalten, den Ihr in Eurer Umgebung für den Zugriff auf FHEM verwendet, also localhost oder 192.168.x.y, und sie muss ein Kommando in dem definierten HomeConnectConnection Modul aufrufen. Die URL sieht dann z.B. so aus:

<pre>
http://localhost:8083/fhem?cmd.Test=set%20hcconn%20auth%20
</pre>

Die identische URL muss sowohl auf der Home Connect Seite in der Applikation angegeben werden, als auch bei der Definition in FHEM. Dazu kommen noch der generierte API Key und das Client Secret:

<pre>
define hcconn HomeConnectConnection API-KEY REDIRECT-URL simulator CLIENT-SECRET
</pre>

Also zum Beispiel

<pre>
define hcconn HomeConnectConnection D239EBCABC99994D239EBCABC999B3D2393204
http://localhost:8083/fhem?cmd.Test=set%20hcconn%20auth%20 simulator 994D239EBCABCBCABC999B3D
</pre>

Danach findet Ihr in dem neuen Device hcconn einen Link namens Home Connect Login. Diesen klicken und die Anmeldung wird durchgeführt. Danach im hcconn-Device noch scanDevices ausführen und Ihr solltet eine stattliche Anzahl Hausgeräte finden.

Um mit echten Geräten zu arbeiten, muss das Wort simulator in der Definition entfernt werden.

====Fehler während der Installation====

Kam es beim vorangegangenen define zu folgender Fehlermeldung:

<pre>
Cannot load module HomeConnectConnection
</pre>

dann ist die Perl-Bibliothek "libswitch-perl" zu installieren:

<pre>
apt-get install libswitch-perl
</pre>

==Sicherheitsfunktion csrfToken in FHEM==
Neueste Versionen von FHEM verwenden eine [[csrfToken-HowTo|XSRF Schutzfunktion]]. Wer diese benutzen möchte, muss ein statisches Token definieren:
<pre>
attr WEB csrfToken myToken123
</pre>
und muss dann an seine redirectURL noch diesen Teil anhängen:
<pre>
&fwcsrf=myToken123
</pre>
Beispiel:
<pre>
define hcconn HomeConnectConnection D239EBCABC99994D239EBCABC999B3D2393204
http://localhost:8083/fhem?cmd.Test=set%20hcconn%20auth%20&fwcsrf=myToken123 simulator
</pre>
Wichtig wie immer: Die Redirect URL muss sowohl im Home Connect Developer Program als auch in der Definition des FHEM HomeConnectConnection devices geändert werden.

==Problembehandlung==
Frage: Wenn ich Zuhause bin, erreiche ich meinen FHEM-Server unter: https:// 192.168.x.x:8083/fhem.
Aus dem Internet erreiche ich FHEM über eine statische IP und Port-forwarding. Funktioniert das dann auch?

Antwort: Es muss kein Zugriff aus dem Internet auf den lokalen Server freigeschaltet werden, der Redirect passiert im eigenen Browser.
Aktuell ist nur eine redirect URL möglich, daher müsstest Du dich beim Home Connect Login für eine Variante entscheiden. Man muss sich ja nicht ständig neu einloggen. Ich habe aber gehört dass zukünftig mal eine Liste von URL's hinterlegt werden kann.

Frage: Ich bekomme '''vor''' dem Home Connect Login eine Fehlermeldung, sofort nach dem Klick auf "Home Connect Login"

Antwort: Entweder ist der API Key falsch oder die Redirect URL. Letztere muss den korrekten Hostnamen und Port enthalten, und auch den Namen des HomeConnectConnection device in der FHEM Installation. Diese URL muss identisch in der Home Connect App Definition und in der FHEM Definition eingetragen werden.

Frage: Ich bekomme '''nach''' dem Home Connect Login "Error" als Meldung in FHEM

Antwort: Dann hat Deine Redirect URL gestimmt und es ist was faul mit dem Api Key.

- Inspiziere mal genau die URL der Seite wo "Error" steht, vielleicht findest Du dort noch eine Fehlermeldung.

- Hast Du das Wort simulator in der Definition mit angegeben? Nur freigeschaltete Betatester können echte Hausgeräte steuern.

- Hast Du einen Advanced Account? Wenn nicht, können die Rechte von FHEM so eingeschränkt werden:
<pre>
attr hcconn accessScope IdentifyAppliance Monitor
</pre>

Frage: Die Geräte werden angelegt, aber das einzige, was ich angeboten bekomme ist: StartProgram RemoteProgramNotEnabled

Antwort: Du musst den Fernstart der Spülmaschine aktivieren, erst danach darf FHEM sie starten.

Frage: Nach dem Erlauben des Zugriffs bei HomeConnect erscheint nur ein weißer Bildschirm.

Antwort: Du musst das Attribut csrfToken deines FHEMWEB auf none setzen (oder wie oben beschrieben ein statisches Token installieren)
<pre>
attr WEB csrfToken none
</pre>

==Unterstützte Geräte==
Grundsätzlich funktionieren alle Home Connect Geräte, d.h. sie werden zumindest in FHEM angelegt und ihr Status wird sichtbar. Steuern kann man sie aktuell jedoch noch nicht alle.
===Backofen===
Steuerung aktuell nicht möglich, aber der Status wird angezeigt
===Geschirrspüler===
Steuerung möglich, Status wird angezeigt. Die Programmoption BSH.Common.Option.StartInRelative kann vor dem Programmstart auf eine Anzahl Sekunden gesetzt werden, um die der Start verzögert werden soll.

[[Kategorie:Other Components]]

HomeConnect

2019-10-24T13:29:58Z

Hoppel118: Paket "libswitch-perl" aus Kapitel "Modul-Installation" entfernt und in "Basisdefinition" hinzugefügt

{{Infobox Modul
|ModPurpose=Anbindung von Hausgeräten mit Home Connect Schnittstelle
|ModType=d
|ModForumArea=Home Connect
|ModTechName=48_HomeConnectConnection.pm 48_HomeConnect.pm
|ModOwner=swhome
}}
==Übersicht==
Mit den beiden Modulen HomeConnectConnection und HomeConnect können in FHEM Devices für [http://www.home-connect.com/de/de/ Home Connect Hausgeräte] angelegt werden, die an einem Home Connect Account angemeldet sind. Mögliche Hausgeräte sind aktuell Backöfen, Spülmaschinen, Kühlschränke, Waschmaschinen, Wäschetrockner und Kaffeemaschinen der Marken Bosch, Siemens und Neff.

Wann verwendet man HomeConnectConnection, wann HomeConnect?

Das Modul HomeConnectConnection verwaltet die Verbindung zwischen FHEM und einem Home Connect Account. Es legt die HomeConnect Devices für die einzelnen Hausgeräte an.

==Aktueller Status des Moduls==
Die beiden Module befinden sich aktuell im Betatest. Jeder Tester muss sich bei Home Connect als Entwickler anmelden und den Login-Namen seines Home Connect App Accounts hinterlegen. Was jeder auch ohne eigene Geräte probieren kann ist der Hausgeräte-Simulator. Allerdings kann man damit in der Praxis nicht viel anfangen...

==Definition von FHEM Devices==
===Modul-Installation===
Zur Installation (oder zum Update) einfach diesen Befehl in der FHEM Kommandozeile eingeben:

<pre>
update all https://raw.githubusercontent.com/sw-home/FHEM-HomeConnect/master/controls_homeconnect.txt
</pre>

Danach FHEM neu starten.

Damit das Modul auch bei einem normale "update check" mit geprüft wird, muss folgendes ergänzt werden
<pre>
update add https://raw.githubusercontent.com/sw-home/FHEM-HomeConnect/master/controls_homeconnect.txt
</pre>

===Basisdefinition===
Um mit dem Simulator zu testen, braucht Ihr einen [https://developer.home-connect.com/ Entwickleraccount bei HomeConnect]

Man braucht zwingend einen Advanced Account um Geräte fernstarten zu dürfen. Das kostet nichts, es wird jedoch eine Namensverifikation durchgeführt.

Im Entwickleraccount muss eine Applikation generiert werden, als „Company Name“ im Home Connect Developer Portal bitte “FHEM Betatester“ angeben. Die wichtigste Einstellung der Applikation ist die Redirect URL. Diese URL muss den Host enthalten, den Ihr in Eurer Umgebung für den Zugriff auf FHEM verwendet, also localhost oder 192.168.x.y, und sie muss ein Kommando in dem definierten HomeConnectConnection Modul aufrufen. Die URL sieht dann z.B. so aus:

<pre>
http://localhost:8083/fhem?cmd.Test=set%20hcconn%20auth%20
</pre>

Die identische URL muss sowohl auf der Home Connect Seite in der Applikation angegeben werden, als auch bei der Definition in FHEM. Dazu kommen noch der generierte API Key und das Client Secret:

<pre>
define hcconn HomeConnectConnection API-KEY REDIRECT-URL simulator CLIENT-SECRET
</pre>

Also zum Beispiel

<pre>
define hcconn HomeConnectConnection D239EBCABC99994D239EBCABC999B3D2393204
http://localhost:8083/fhem?cmd.Test=set%20hcconn%20auth%20 simulator 994D239EBCABCBCABC999B3D
</pre>

Danach findet Ihr in dem neuen Device hcconn einen Link namens Home Connect Login. Diesen klicken und die Anmeldung wird durchgeführt. Danach im hcconn-Device noch scanDevices ausführen und Ihr solltet eine stattliche Anzahl Hausgeräte finden.

Kam es beim vorangegangenen define zu folgender Fehlermeldung:

<pre>
Cannot load module HomeConnectConnection
</pre>

dann ist die Perl-Bibliothek "libswitch-perl" zu installieren:

<pre>
apt-get install libswitch-perl
</pre>

Um mit echten Geräten zu arbeiten, muss das Wort simulator in der Definition entfernt werden.

==Sicherheitsfunktion csrfToken in FHEM==
Neueste Versionen von FHEM verwenden eine [[csrfToken-HowTo|XSRF Schutzfunktion]]. Wer diese benutzen möchte, muss ein statisches Token definieren:
<pre>
attr WEB csrfToken myToken123
</pre>
und muss dann an seine redirectURL noch diesen Teil anhängen:
<pre>
&fwcsrf=myToken123
</pre>
Beispiel:
<pre>
define hcconn HomeConnectConnection D239EBCABC99994D239EBCABC999B3D2393204
http://localhost:8083/fhem?cmd.Test=set%20hcconn%20auth%20&fwcsrf=myToken123 simulator
</pre>
Wichtig wie immer: Die Redirect URL muss sowohl im Home Connect Developer Program als auch in der Definition des FHEM HomeConnectConnection devices geändert werden.

==Problembehandlung==
Frage: Wenn ich Zuhause bin, erreiche ich meinen FHEM-Server unter: https:// 192.168.x.x:8083/fhem.
Aus dem Internet erreiche ich FHEM über eine statische IP und Port-forwarding. Funktioniert das dann auch?

Antwort: Es muss kein Zugriff aus dem Internet auf den lokalen Server freigeschaltet werden, der Redirect passiert im eigenen Browser.
Aktuell ist nur eine redirect URL möglich, daher müsstest Du dich beim Home Connect Login für eine Variante entscheiden. Man muss sich ja nicht ständig neu einloggen. Ich habe aber gehört dass zukünftig mal eine Liste von URL's hinterlegt werden kann.

Frage: Ich bekomme '''vor''' dem Home Connect Login eine Fehlermeldung, sofort nach dem Klick auf "Home Connect Login"

Antwort: Entweder ist der API Key falsch oder die Redirect URL. Letztere muss den korrekten Hostnamen und Port enthalten, und auch den Namen des HomeConnectConnection device in der FHEM Installation. Diese URL muss identisch in der Home Connect App Definition und in der FHEM Definition eingetragen werden.

Frage: Ich bekomme '''nach''' dem Home Connect Login "Error" als Meldung in FHEM

Antwort: Dann hat Deine Redirect URL gestimmt und es ist was faul mit dem Api Key.

- Inspiziere mal genau die URL der Seite wo "Error" steht, vielleicht findest Du dort noch eine Fehlermeldung.

- Hast Du das Wort simulator in der Definition mit angegeben? Nur freigeschaltete Betatester können echte Hausgeräte steuern.

- Hast Du einen Advanced Account? Wenn nicht, können die Rechte von FHEM so eingeschränkt werden:
<pre>
attr hcconn accessScope IdentifyAppliance Monitor
</pre>

Frage: Die Geräte werden angelegt, aber das einzige, was ich angeboten bekomme ist: StartProgram RemoteProgramNotEnabled

Antwort: Du musst den Fernstart der Spülmaschine aktivieren, erst danach darf FHEM sie starten.

Frage: Nach dem Erlauben des Zugriffs bei HomeConnect erscheint nur ein weißer Bildschirm.

Antwort: Du musst das Attribut csrfToken deines FHEMWEB auf none setzen (oder wie oben beschrieben ein statisches Token installieren)
<pre>
attr WEB csrfToken none
</pre>

==Unterstützte Geräte==
Grundsätzlich funktionieren alle Home Connect Geräte, d.h. sie werden zumindest in FHEM angelegt und ihr Status wird sichtbar. Steuern kann man sie aktuell jedoch noch nicht alle.
===Backofen===
Steuerung aktuell nicht möglich, aber der Status wird angezeigt
===Geschirrspüler===
Steuerung möglich, Status wird angezeigt. Die Programmoption BSH.Common.Option.StartInRelative kann vor dem Programmstart auf eine Anzahl Sekunden gesetzt werden, um die der Start verzögert werden soll.

[[Kategorie:Other Components]]

FHEM Connector für Amazon Alexa

2019-08-05T07:12:05Z

Hoppel118: Kapitel "Fehler bei Aktivierung" neu strukturiert und "Permission denied" ergänzt

{{Baustelle}}
'''Alexa FHEMlazy''' war historisch ein Fork des Original [[Alexa-Fhem|alexa-fhem]], der im Januar 2019 mit dem Original zusammengeführt wurde und nun als '''FHEM Connector''' verfügbar ist.

Er ermöglicht innerhalb von Minuten die Verknüpfung von FHEM mit einem Amazon Echo Gerät. Auch Geräte anderer Hersteller mit verbauten Mikrofonen und Alexa-Sprachassistenten-Unterstützung sollten problemlos funktionieren. Für folgende Geräte ist dies bspw. der Fall (Falls Ihr andere/weitere Gerätemodelle bzw. Hersteller in Verwendung habt, bitte hier pflegen):

* SONOS Beam und SONOS One

Gegenüber dem klassischen Ansatz ergeben sich Einschränkungen, so läuft die Software normalerweise unter dem gleichen Benutzer wie FHEM auf dem gleichen Server, und es wird z.Zt. nur der Smarthome-Skill unterstützt (die Variante, bei der die Möglichkeiten der Interaktion von Amazon festgelegt wurden).
Dafür ist weder ein Developer-Account bei Amazon, eigene Lambda- und Skillfunktionen, noch das Öffnen eines eingehenden Ports aus dem Internet nötig.
* Die Software integriert einen Installer, der die Erstkonfiguration und Anmeldung übernimmt
* Die Kommunikation zur Software auf dem heimischen Rechner und dann zu FHEM verläuft über SSH und einen vom FHEM-Verein gehosteten Server
* Funktioniert mit IPv4, IPv6, echtem Dual Stack und DS-Lite
* Als Skill bei Amazon wird der Skill "FHEM Connector" verwendet.

Der Thread im Forum zur Software ist hier: {{Link2Forum|Topic=94817}}.

{{Infobox Modul
|ModPurpose=Einfache Anbindung von FHEM an Amazon Assistent Alexa
|ModType=h
|ModCmdRef=alexa
|ModTechName=39_alexa.pm / alexa-fhem
|ModForumArea=Frontends/Sprachsteuerung
|ModOwner=gvzdus, André/ justme1968 ({{Link2FU|430|Forum}} / [[Benutzer Diskussion:Justme|Wiki]])
}}

==Einführung==

===Arbeitsweise und Datenfluss===
Vorläufig ist alexa-fhem im "FHEM Connector-Modus" ein reiner [https://developer.amazon.com/de/docs/smarthome/understand-the-smart-home-skill-api.html SmartHome-Skill].
SmartHome-Skills erhalten weder die Sprachdaten selber noch das, was Amazon in Textform verstanden hat, sondern vielmehr extrahiert Amazon aus dem verstandenen Text Anweisungen und Abfragen für Geräte, die dann an den Skill übermittelt werden. Charmant ist dabei, dass unmittelbar gefragt werden kann "Alexa, wie ist die Temperatur im Wohnzimmer?", während andere Skills zunächst explizit angesprochen werden müssen ("Alexa, frage FHEM nach der Temperatur im Wohnzimmer"). Außerdem kann der Nutzer mehrere Smarthome-Skills installieren, und die Geräte werden zu einer Gesamtmenge zusammengefasst.

Gehen wir den Datenfluss bei der konkreten Frage "Wie ist die Temperatur im Wohnzimmer?" durch:
* Alexa hat bei der Skillinstallation gelernt, dass "FHEM Connector" bei Dir einen Thermostaten im Raum Wohnzimmer kennt. Dadurch wird bei der Sprachanalyse von "Alexa Voice Service" in der Cloud erkannt, dass eine Abfrage an "FHEM Connector" erfolgversprechend ist.
* Zunächst wird die zentrale "Lambda-Funktion" von "FHEM Connector" aufgerufen. Die Funktion leitet aber im Kern nur den Request unverändert an den vom Verein bereitgestellten Server weiter. Im Request enthalten ist ein Token, das sogenannte "Bearer-Token".
* Der "Vereinsserver" prüft anhand dieses Tokens, ob es überhaupt bekannt ist, und zu welchem Nutzer es gehört. Ist dieser Nutzer verbunden, wird der Request wiederum quasi unverändert an den Nutzer weitergeleitet.
* Diese Weiterleitung passiert über einen sogenannten SSH-Reverse-Tunnel, der von Deiner Seite und der Software auf dem FHEM-Tunnel automatisch aufgebaut wird.
* Auf Deiner Seite läuft die eigentliche Software, und zwar unter nodeJS. nodeJS ist ein Javascript ausführender Miniserver, der lokal auf Port 3000 auf Requests "lauscht". In der Original-Version [[Alexa-Fhem|Alexa FHEM]] kommen die Requests aus dem Internet (hoffentlich von der eigenen Lambda-Funktion), hier bei "FHEM Connector" kommen sie ausschließlich aus dem SSH-Tunnel von lokal.
* Die Software validiert nun diesen Request anhand des Bearer-Tokens. Konkret wird dabei das bei der Installation generierte Token, dass bei der Skill-Aktivierung an Amazon übertragen wurde, mit dem lokal gespeicherten Wert verglichen. Stimmt das Token, wird der Befehl verarbeitet, üblicherweise wird hierbei ein Aufruf an die Webschnittstelle von FHEM abgesetzt.
* FHEM führt den Befehl aus

Hört sich langsam und kompliziert an? Kompliziert: Okay. Langsam eher nicht, in etlichen Fällen liegt die Gesamtantwortszeit unter 200 ms.

Soweit ein erster Überblick über die Datenflüsse. Im Abschnitt Sicherheit ist das Konzept der Absicherung deutlich genauer und ausführlicher beschrieben.

==Installation==

Du wirst bei der Installation zuerst auf der Kommandozeile auf Deinem Raspberry (o.ä.) unterwegs sein, anschließend im Webfrontend von FHEM, und zum Schluss auf der Alexa-Konsole im Web.

===node.js installieren===

Bei Jessy liegt NodeJS bereits in einer ausreichend aktuellen Version vor. Mit

<syntaxhighlight lang="bash" style="width:50%;">
sudo apt-get install nodejs npm
</syntaxhighlight>

kannst Du es installieren. Mit
<syntaxhighlight lang="bash" style="width:50%;">
node --version
</syntaxhighlight>

erfährst Du die aktuelle Version - wenn hier etwas mit "8" vorneweg erscheint, ist alles gut.
Ansonsten suche Dir bitte eine Anleitung im Web, wie Du NodeJS auf Deinem System auf einen aktuellen Stand bringen kannst.

=== Alexa-FHEM installieren ===

Nun installieren wir Alexa-fhem aus dem offiziellen Repository:

<syntaxhighlight lang="bash" style="width:50%;">
sudo npm install -g alexa-fhem
</syntaxhighlight>

Der Vorgang benötigt etwas Zeit.

=== Alexa-FHEM aktivieren ===

Wechsele jetzt in FHEM-Web!

Wichtig ist, dass das Alexa-Modul in der Version ab 14. Januar 2019 vorliegt. Dafür bitte einmal FHEM aktualisieren:
Speichern der Config nicht vergessen, und

<syntaxhighlight lang="bash" style="width:50%;">
update
shutdown restart
</syntaxhighlight>

Alles, was jetzt noch nötig ist, ist das Anlegen eines Alexa-Devices. Gib dafür in der FHEM-Web-Kommandozeile

<syntaxhighlight lang="bash" style="width:50%;">
define alexa alexa
</syntaxhighlight>

an. Nun läuft, während Du bereits das neu angelegte Alexa-Devices siehst, ein komplexer Prozess im Hintergrund:

* Falls noch kein SSH-Key für den Benutzer, unter dem FHEM läuft, existiert, wird einer generiert
* Es wird ein Secret-Key im Prozess generiert, dass den Server nicht verlässt, und der Skillanmeldung dient.
* Du wirst auf dem Server "va-fhem.fhem.de" des FHEM-Vereins mit dem SSH-Key angemeldet, und der Hash-Wert Deines Secret-Key dort abgelegt.

Und wenn Du diese Sätze gelesen hast, sollte inzwischen sich das Alexa-Device in FHEM-Web aktualisiert haben, und
ungefähr so aussehen:

[[Datei:Alexa-Device-2.png|800px]]

Neben dem Status für alexa-fhem und der Proxyverbindung ist wichtig, dass diese beiden Zeilen beim Reload aufgetaucht sind:

<syntaxhighlight lang="bash" style="width:90%;">
alexaFHEM.bearerToken crypt:...
alexaFHEM.skillRegKey crypt:...
</syntaxhighlight>

Ja, und diesen Schlüssel benötigst Du wirklich! Also am besten schon einmal mit

<syntaxhighlight lang="bash" style="width:90%;">
get <alexa> proxyKey
</syntaxhighlight>

in Klartext anzeigen lassen und in ein Editor-Fenster dauerhaft wegsichern.

Jetzt solltest Du Dein Alexa-Device nicht mehr löschen, denn das im Reading angezeigte "bearerToken" zu löschen bedeutet, dass die Software die Zugriffe von nicht mehr überprüfen kann und keine Kommandos mehr funktionieren. In diesem Fall hilft nur die Neuinstallation des Skills.

==== Fehler bei der Aktivierung ====

Während kompliziertere Fehlerfälle im Abschnitt "Mögliche Probleme und Lösungen" behandelt werden, hier häufige Fälle, warum die kryptischen Zeilen nicht auftauchen:

* Zuerst bitte einfach einmal die Seite neu laden.

===== 401: Authorization Required =====

Wenn Du FHEM-Web mit einem User/Passwort-Schutz versehen hast, wirst du folgende Fehlermeldung sehen:

<syntaxhighlight lang="bash" style="width:90%;">
alexaFHEM stopped; failed to connect to fhem: 401: Authorization Required
</syntaxhighlight>

In der Regel musst du die Angaben User/Passwort noch einmal explizit setzen. Im Attribute-Abschnitt "alexaFHEM-auth" auswählen, User/Passwort mit ":" getrennt angeben und "attr" anklicken. alexa-fhem wird automatisch neu gestartet. Hier das Ganze in der Text-Variante:

<syntaxhighlight lang="bash" style="width:90%;">
attr alexa alexaFHEM-auth user:pass
</syntaxhighlight>

===== Permission denied =====

Wenn du folgende Fehlermeldungen im Alexa Logfile siehst, wurde das Verzeichnis "/opt/fhem/.ssh/" von dir bei der Arbeit mit "root" oder "sudo" mit den falschen Berechtigungen versehen:

<syntaxhighlight lang="bash" style="width:90%;">
[2019-7-25 11:59:12] sshautoconf: aborted with ssh-keygen returned error - key_save_private: Permission denied
[2019-7-25 11:59:12] *** SSH: proxy configuration failed: ssh-keygen returned error - key_save_private: Permission denied
</syntaxhighlight>

Prüfen kannst du die Berechtigungen mit folgendem Befehl auf der Shell-Konsole:

<syntaxhighlight lang="bash" style="width:90%;">
ls -l /opt/fhem/.ssh
</syntaxhighlight>

Du solltest dann folgende Ausgabe erhalten:

<syntaxhighlight lang="bash" style="width:90%;">
insgesamt 12
-rw------- 1 fhem dialout 1675 Jul 12 13:10 id_rsa
-rw-r--r-- 1 fhem dialout 391 Jul 12 13:10 id_rsa.pub
-rw-r--r-- 1 fhem dialout 884 Jul 12 13:10 known_hosts
</syntaxhighlight>

Steht in der Ausgabe nicht "fhem dialout" (dein fhem User), sondern bspw. "root root", dann bspw. mit folgendem Befehl an deinen fhem User anpassen:

<syntaxhighlight lang="bash" style="width:90%;">
chown fhem:dialout /opt/fhem/.ssh
</syntaxhighlight>

Mit dem ersten Befehl "ls -l ..." kannst du dann nochmal prüfen, ob die Berechtigungen korrekt übernommen wurden.

===== weitere Prüfungen =====

Hast Du noch die Shell-Konsole offen? Dann prüfe bitte noch einmal auf der Konsole, ob nun zwei Prozesse laufen:

<syntaxhighlight lang="bash" style="width:50%;">
ps -ef | egrep '(alexa|ssh)'
</syntaxhighlight>

sollte Dir idealerweise so etwas anzeigen:
<syntaxhighlight lang="bash" style="width:90%;">
fhem 31322 1 99 13:56 ? 00:00:03 alexa
fhem 31332 31322 8 13:56 ? 00:00:00 /usr/bin/ssh -R 1234:127.0.0.1:<zufälliger port> -oServerAliveInterval=90 -p 58824 fhem-va.fhem.de
</syntaxhighlight>

"alexa" ist dabei der Node-JS-Prozess, der ssh-Prozess ist die aufgebaute Verbindung zum Vereinsserver.

Wenn Du diese Prozesse '''nicht''' siehst oder das Alexa-Device keinen Registrierungskey anzeigt, dann ist leider der Start nicht glatt verlaufen.

Im Logfile (über den link <code>Logfile</code> in der Detail-Ansicht über <code>set</Code>, oder über den Namen bei <it>currentlogfile</it> in den Internals) findest Du idealerweise selber Hinweise, wo es hakt, oder kannst im Forum nachfragen.

=== Geräte im FHEM-Webfrontend zuweisen ===
Um das Aha-Erlebnis zu vergrößern, ist jetzt ein guter Zeitpunkt, 1 oder besser mind. 2 Geräte für den Alexa-Dienst zuzuweisen. Von Haus aus wird keines Deiner FHEM-Geräte automatisch Alexa zugewiesen!

Wähle die Geräte aus, rufe sie auf und setze das Attribut "alexaName". Hierbei in Kürze nur der Hinweis:
* Keine Angst vor Leerzeichen und Umlauten, funktioniert.
* Große Angst vor Rechtschreibfehlern (Terrasse, Rollladen) oder komplizierten Wörtern "handgebastelte Martinslaterne im Kinderzimmer Iphigenie-Chantal".
* Das Attribut "alexaRoom" ist NUR FÜR DEN CUSTOM SKILL relevant. Ausnahme: structure und LightScene Devices, siehe: [[FHEM_Connector_f%C3%BCr_Amazon_Alexa#Was_geht_alles_.3F]].

Lade die Geräte neu in die Software, indem Du <code>set <alexa> restart</code> ausführst!

== Finale: Skill verknüpfen ==
Suche im WebFrontend oder der Alexa-App den Skill "FHEM Connector". Für nicht-Mac/iOS Anwerder empfiehlt das WebFrontend (https://alexa.amazon.de) statt die App, damit Du den Anmeldeschlüssel auch bequem kopieren kannst.

Wenn du noch nicht bei Amazon angemeldet bist, erwartet Amazon zunächst, dass Du Dich normal bei Amazon anmeldest.

Sobald Du "FHEM Connector" aktivierst, öffnet sich ein Browser-Tab mit folgender Maske: 
[[Datei:FHEMlazy_login.png|240px]]

Hier kopierst Du Deinen Anmeldeschlüssel (im Klartext!) hinein und klickst auf Check. Als glücklicher Mensch ist auf der folgenden Statusseite alles grün: 
[[Datei:FHEMlazy_check.png|240px]]

Im Einzelnen wird hier geprüft, ob Du per SSH verbunden bist (und auch Deine IP zur Sicherheit angezeigt), ob der Reverse-Tunnel steht, ob nodeJS erreichbar ist und wie viele Geräte Alexa gleich finden sollte (in meinem Fall 22).

Sollte etwas nicht grün sein und Du eine Idee zum Fixen haben, kannst Du mit "Retry" neue Versuche auslösen.

Ist alles okay, klicke rechts den Button "Activate Skill". Du springst damit wieder zurück zu Amazon, die Dir hoffentlich zur erfolgreichen Verknüpfung gratulieren.

Amazon möchte nun unmittelbar die Gerätesuche starten, und unter SmartHome-Geräte sollten diese nun auftauchen.

== Was geht alles ? ==

* Geräte, die sich ein- und ausschalten lassen:
** Automatisch: Müssen <code>set on</code> und <code>set off</code> Kommandos haben
** dummys müssen <code>setList</code> mit on und off haben
** Über <code>genericDeviceType</code> switch bzw. light kann bestimmt werden ob es in alexa als Schalter oder Licht behandelt wird.
** Wenn die Set-Kommandos im FHEM Device anders benannt sind: hombridgeMapping On:cmdOn=<ein>,CmdOff=<aus> setzen
** Kommandos:
***Alexa, schalte <name> ein/aus
***Alexa, Licht an/aus
***Alexa, schalte <gruppe> ein/aus

* Geräte, die eine Temperatur messen
** Automatisch: Es muss ein Reading temperature geben
** Über <code>genericDeviceType</code> thermometer
** Sonst: hombridgeMapping CurrentTemperature:reading=<reading>

* Geräte, deren Helligkeit sich ändern lässt
** Automatisch: wenn <code>dim</code> oder <code>pct</code> Kommandos erkannt werden
** Über <code>genericDeviceType</code> light
** Über homebridgeMapping: Wenn <code>helligkeit</code> das Reading für die aktuelle Helligkeit enthält und die Helligkeit mit <code>set <device> prozent xxx</code> gesetzt wird, sieht das homebridgeMapping wie folgt aus:
*** homebridgeMapping Brightness=helligkeit::prozent,minValue=0,maxValue=<maximalwert>

**Kommandos:
***Alexa, mache <name> heller/dunkler
***Alexa, Licht heller/dunkler

* Geräte, deren Farbe sich ändern lässt
** ...

* Geräte, deren Farbtemperatur sich ändern lässt
** ...

* Geräte, bei denen sich eine Lautstärke einstellen lässt
** ...

* Geräte, bei denen sich ein prozentualer Wert einstellen lässt
** Automatisch: wenn <code>dim</code> oder <code>pct</code> Kommandos erkannt werden
** ...

* elektrische Türschlösser
** <code>genericDeviceType</code>: lock
** hombridgeMapping mit LockCurrentState und LockTargetState

* Thermostate
** Über <code>genericDeviceType</code> thermostate
** ...

* structure Devices aus FHEM (ab alexa-fhem version 0.5.7)
** können mit <code>genericDeviceType</code> scene als Szene eingebunden werden
** über <code>alexaRoom</code> kann der name um einen Ort ergänzt werden
** Szenen aus einer structure lassen sich ein- und ausschalten
** Wichtig:
*** Ein Skill darf nur 12 Szenen automatisch erkennen und einbinden.

* LightScene Devices aus FHEM (ab alexa-fhem version 0.5.8)
** können mit <code>genericDeviceType</code> scene als Szenen eingebunden werden
** über <code>alexaRoom</code> kann der name um einen Ort ergänzt werden
** Szenen aus einer LightScene lassen sich nur einschalten
** Wichtig:
*** Ein Skill darf nur 12 Szenen automatisch erkennen und einbinden.

* Geräte, deren Kanal sich umschalten lässt (ab alexa-fhem version 0.5.13)
** Über <code>genericDeviceType</code> media
** hombridgeMapping ChannelController:reading=<reading>,cmd=<cmd>
** Erlaubte Werte siehe hier: https://developer.amazon.com/de/docs/device-apis/alexa-channelcontroller.html#changechannel
** ...

* Geräte, deren Playback status sich schalten lässt (ab alexa-fhem version 0.5.13)
** Über <code>genericDeviceType</code> media
** hombridgeMapping PlaybackController:playback,values=Play;Pause;Stop;Previous;Next
** Erlaubte Werte siehe hier: https://developer.amazon.com/de/docs/device-apis/alexa-playbackcontroller.html#discovery
** ...

* Geräte, deren Eingang sich umschalten lässt (ab alexa-fhem version 0.5.13)
** Über <code>genericDeviceType</code> media
** hombridgeMapping InputController:reading=<reading>,cmd=<cmd>,values=HDMI+1;HDMI+2;XBOX
** Erlaubte Werte siehe hier: https://developer.amazon.com/de/docs/device-apis/alexa-property-schemas.html#input
** ...

* Kontaktsensoren (ab alexa-fhem version 0.5.15)
** Über <code>genericDeviceType</code> contact
** hombridgeMapping ContactSensorState:reading=<reading> oder CurrentDoorState:reading=<reading>
** Die Anzeige in der Alexa-App funktioniert sofort, die Abfrage per Sprache erst ab Version 0.5.27.

* Geräte, deren Lautstärke sich ändern lässt (ab alexa-fhem version 0.5.24)
** Über <code>genericDeviceType</code> speaker
** Automatisch: es muss ein Reading <code>volume</code> und/oder <code>mute</code> geben
** hombridgeMapping Volume:reading=<reading>,cmd=<cmd> Mute:reading=<reading>,cmd=<cmd>
** ...

* Geräte, die sich ein- (und optional) ausschalten lassen als Szene (ab alexa-fhem version 0.5.26)
** Über <code>genericDeviceType</code> scene
** Automatisch: Müssen <code>set on</code> und <code>set off</code> Kommandos haben
** hombridgeMapping On:reading=<reading>,cmdOn=<cmd>[,cmdOff=<cmd>]
** Hinweis: Fehlende Kommandos lassen sich mit cmdalias erzeugen
** Wichtig:
*** Ein Skill darf nur 12 Szenen automatisch erkennen und einbinden.

Es werden noch einige andere häufig verwendete Geräte (Homematic, hue,...) automatisch erkannt.

to be continued ...

In der [https://developer.amazon.com/docs/device-apis/list-of-interfaces.html List of Capability Interfaces] bei Amazon kann man sehen, welche Möglichkeiten das Smart Home Skill API aktuell in einzelnen Ländern bietet. Leider ohne die jeweiligen landessprachlichen Kommandos.

== Mögliche Probleme und Lösungen ==

Es kann vorkommen, dass Geräte zwar korrekt erkannt werden, aber das durch Alexa erkannte Kommando nicht richtig umgesetzt wird (Beispiel - mittlerweile behoben: {{Link2Forum|Topic=96766}}). Neben dem FHEM-Log gibt es noch das Logfile, welches von alexa-fhem angelegt wird.

=== Fehlersuche über die FHEM-Oberfläche ===

* alexa-fhem Logfile anschauen (Detail-Ansicht des <alexa>-Device aufrufen, klick auf '''Logfile''' oben)
* alexa-fhem im Debug-Modus aufrufen:
** -D zum alexaFHEM-params attribut hinzufügen
** Alexa-Befehl auslösen
** -D aus dem alexaFHEM-params attribut entfernen
* Die notwendigen Informationen finden sich in dem alexa-Logfile (siehe oben)

=== Fehlersuche über Kommandozeile (lies: Shell) + FHEM-Oberfläche ===

:* set <alexa> stop (FHEM-Oberfläche)
:* Auf der Kommandozeile <code>alexa-fhem -D -c /opt/fhem/alexa-fhem.cfg > debug.log</code> starten (dadurch wird die Datei debug.log erzeugt im aktuellen Verzeichnis)
:* Alexa-Befehl auslösen
:* alexa-fhem auf der Kommandozeile wieder stoppen (CTRL-C)
:* set <alexa> start (FHEM-Oberfläche)

Die Datei debug.log sollte Hinweise enthalten, wie das Problem zu lösen ist oder Dich zumindest in die richtige Richtung schieben.

Im Beispiel aus dem Forum fand sich in dem Logfile der Hinweis darauf, dass das Device mit falschen min/max-Werten unterwegs war.

=== Registrierungskey vergessen, Registrierung zurücksetzen ===

Auf der Kommandoshell:

<syntaxhighlight lang="bash" style="width:90%;">
pi@raspberrypi:~# sudo -u fhem ssh -p 58824 fhem-va.fhem.de status
Registered.
Registered on 2019-01-13T15:38:13Z.
</syntaxhighlight>

heisst, das der Vereinsserver eigentlich alles hat, was er will. Es wird kein neuer Schlüssel generiert.
Wenn Du die Situation zurücksetzen möchtest, wäre die hässliche Methode, Deinen SSH-Key zu löschen. Eleganter ist, die Registrierung auf Vereinsseite zu löschen:

<syntaxhighlight lang="bash" style="width:90%;">
pi@raspberrypi:~# sudo -u fhem ssh -p 58824 fhem-va.fhem.de unregister
Your registration has been removed
</syntaxhighlight>

löscht Deinen Schlüssel mitsamt allen dort gespeicherten Daten auf Vereinsseite. Bei Restart von alexa-fhem in FHEM-WEB wird jetzt ein neuer Registrierungskey angefordert.

== Sicherheitskonzept und Secrets ==

Um diesen Abschnitt zu verstehen, solltest Du den Abschnitt "Arbeitsweise" im Kopf haben. Einerseits ist Dir vermutlich einleuchtend, dass ein Server, der per SSH rückwärts nur ausgewählte Kommandos in den Tunnel, den Du aufgebaut hast, leitet, "irgendwie sicherer" ist. Andererseits möchte man nicht blind vertrauen.

=== SSH ===
==== SSH - macht das nichts Gefährliches? ====
SSH ist ein Veteran des Internet und entstand, um sich sicher (verschlüsselt) und schnell auf Servern einzuloggen. Schon früh wurde dabei der sogenannte "Reverse-Tunnel" implementiert: Also der vom Client (Deinem Rechner) geäußerte Wunsch: "Bitte leite mir Requests, die bei Dir, Server, auf Port xy eingehen, an meinen lokalen Port yz weiter.". Dieses Verfahren implementiert der Reverseproxy, wobei tatsächlich auf dem Server für Dich kein echter Port geöffnet wird.

Wie Dir ggf. sicher der Unix-Guru Deines Vertrauens bestätigen wird: Die Kombination
<syntaxhighlight lang="bash" style="width:50%;">
ssh -R 1234:localhost:<zufälliger port> zielserver
</syntaxhighlight>
erlaubt keine Ausführung von Shell-Kommandos auf Deinem Server, sondern einzig, dass vom SSH-Programm Verbindungen zu einem lokalen Port auf Deinem Server auf dem alexa-fhem lauscht aufgebaut werden. Du kannst also z.B. mit einem
<syntaxhighlight lang="bash" style="width:50%;">
sudo /usr/sbin/tcpdump -X -s 0 -i lo port <zufälliger port>
</syntaxhighlight>
vollständig überwachen (oder ggf. permanent aufzeichen), was auf Deinem Server von außen gesteuert passiert.

==== Wie wird bei SSH verschlüsselt? ====
Im Prinzip wie im Web auf SSL-Seiten, teils mit den gleichen Verschlüsselungsverfahren. Allerdings arbeitet SSH eher wie das im Web recht seltene Verfahren: Bei jeder Verbindung übermitteln sowohl Server wie auch Client den öffentlichen Teil ihres Schlüssels. Anders als im Web wird der Schlüssel aber nicht von einer öffentlichen Zertifizierungsstelle wie "LetsEncrypt" unterschrieben. Stattdessen entscheiden Server wie Client beim ersten Verbindungsaufbau typischerweise per manueller Frage: "Willst Du jetzt und künftig diesem Schlüssel vertrauen?" Bei der Installation wird diese Frage für Deine Seite bejaht, und fortan wird der öffentliche Schlüssel des FHEM-Servers auf Deinem Rechner gespeichert. Ab da bist Du z.B. davor sicher, dass jemand den DNS-Eintrag verbiegt oder sich in den Datenfluss Deines Providers einhängt: Ein geänderter Serverschlüssel würde bemerkt werden.
 
Soweit klar? Aus Deinem öffentlichen Schlüssel wiederum leitet der Server her: "Das ist definitiv wieder derjenige, der sich damals "registriert" hat". Und an dieser Stelle kann ich auch den ersten Teil des 3-teiligen Registrierungskeys erläutern: Die typischerweise 6-stellige Hex-Zahl am Anfang ist der Java-Hashcode Deines öffentlichen Schlüssel. Sie ist damit sozusagen Deine aus Deinem öffentlichen Schlüssel abgeleitete Benutzer-ID.

=== Die Rolle der Secrets ===
Wenn jetzt klar ist, dass die Verbindung zum Vereinsserver sicher und vertauschungsfrei funktioniert, bleiben noch 2 Probleme zu lösen:
1) Im Web bei der Skill-Aktivierung musst Du beweisen, dass Du der Mensch am Browser bist, dem der SSH-Tunnel von IP xy mit dem öffentlichen Schlüssel X gehört. Bei der automatischen Registrierung werden lokal auf Deinem Rechner zwei 64-Bit-Secrets generiert:
* Das Anmelde-Secret
* Das Bearer-Token
Beim Anmelden des SSH-Keys auf dem öffentlichen Server wird nun der Hashwert des ersten Secrets übertragen und dort in Verbindung mit Deinem öffentlichen Schlüssel gespeichert. Ein Hashwert bedeutet, dass (sofern das Verfahren, hier SHA256, funktioniert), niemand aus dem Hash das Secret zurückrechnen kann. Ein Datenbankklau auf dem Server gefährdet also nicht die Sicherheit Deines Passwortes.

Wenn Du nun beim Skill-Aktivieren den Registrierungskey eingibst, dann "sieht" der Server zum ersten Mal Dein ausgewürfeltes Secret, vergleicht es mit dem Hashwert und wird es anschließend wieder umgehend vergessen. Anhand des Hashwertes kann der Server aber entscheiden, dass Du der legitime Nutzer zum öffentlichen Schlüssel XY bist.

2) Das zweite Problem ist: Wie soll Amazon "beweisen", dass sie der legitime Aufrufer sind? Amazon erhält binnen wenigen Sekunden nach dem Klick auf "Activate Skill" den dritten Teil des Registrierungskeys als sogenanntes Bearer-Token. Zwar läuft er durch den Registrierungsserver, er wird dort, auf dem Registrierungs/Vereinsserver aber nicht gespeichert. Das Bearer-Token wird von Amazon bei allen Requests zu Deinem Server mitgesendet. Da es am Anfang zusätzlich Deine "User-ID" enthält, weiß der Vereinsserver, zu welchem SSH-Tunnel der Request zu senden ist. Aber lokal auf Deinem Rechner wird ausgewertet, ob das Token "stimmt".

== alexa-fhem Updaten ==
* alexa-fhem über FHEM anhalten:
:<syntaxhighlight lang="perl" style="width:50%;">set alexa stop</syntaxhighlight>

*Auf der Konsole wie anfangs bei der Installation:
:<syntaxhighlight lang="bash" style="width:50%;">sudo npm update -g alexa-fhem</syntaxhighlight>

:Manchmal hat npm Probleme mit einem Update. Dann einfach die aktuelle Version noch mal drüber Installieren:

:<syntaxhighlight lang="bash" style="width:50%;">sudo npm install -g alexa-fhem</syntaxhighlight>

*alexa-fhem über FHEM wieder starten:
:<syntaxhighlight lang="perl" style="width:50%;">set alexa start</syntaxhighlight>

== Bug- und Wunschliste ==
* Ist beim Start keine Internetverbindung vorhanden, erfolgt kein Retry -- alexa-fhem muss restartet werden (ssh_autoconfig wertet keine temporären Fehler aus)

==Weitergehende Informationen==
*[[Alexa_und_Mappings]]
*[[Alexa_Tipps_und_Kniffe]]
[[Kategorie:HOWTOS]]
[[Kategorie:Sprachsteuerung]]

FHEM Connector für Amazon Alexa

2019-07-31T11:11:03Z

Hoppel118: Hinweis zu alexaRoom in Kapitel "Geräte im FHEM-Webfrontend zuweisen" ergänzt

{{Baustelle}}
'''Alexa FHEMlazy''' war historisch ein Fork des Original [[Alexa-Fhem|alexa-fhem]], der im Januar 2019 mit dem Original zusammengeführt wurde und nun als '''FHEM Connector''' verfügbar ist.

Er ermöglicht innerhalb von Minuten die Verknüpfung von FHEM mit einem Amazon Echo Gerät. Auch Geräte anderer Hersteller mit verbauten Mikrofonen und Alexa-Sprachassistenten-Unterstützung sollten problemlos funktionieren. Für folgende Geräte ist dies bspw. der Fall (Falls Ihr andere/weitere Gerätemodelle bzw. Hersteller in Verwendung habt, bitte hier pflegen):

* SONOS Beam und SONOS One

Gegenüber dem klassischen Ansatz ergeben sich Einschränkungen, so läuft die Software normalerweise unter dem gleichen Benutzer wie FHEM auf dem gleichen Server, und es wird z.Zt. nur der Smarthome-Skill unterstützt (die Variante, bei der die Möglichkeiten der Interaktion von Amazon festgelegt wurden).
Dafür ist weder ein Developer-Account bei Amazon, eigene Lambda- und Skillfunktionen, noch das Öffnen eines eingehenden Ports aus dem Internet nötig.
* Die Software integriert einen Installer, der die Erstkonfiguration und Anmeldung übernimmt
* Die Kommunikation zur Software auf dem heimischen Rechner und dann zu FHEM verläuft über SSH und einen vom FHEM-Verein gehosteten Server
* Funktioniert mit IPv4, IPv6, echtem Dual Stack und DS-Lite
* Als Skill bei Amazon wird der Skill "FHEM Connector" verwendet.

Der Thread im Forum zur Software ist hier: {{Link2Forum|Topic=94817}}.

{{Infobox Modul
|ModPurpose=Einfache Anbindung von FHEM an Amazon Assistent Alexa
|ModType=h
|ModCmdRef=alexa
|ModTechName=39_alexa.pm / alexa-fhem
|ModForumArea=Frontends/Sprachsteuerung
|ModOwner=gvzdus, André/ justme1968 ({{Link2FU|430|Forum}} / [[Benutzer Diskussion:Justme|Wiki]])
}}

==Einführung==

===Arbeitsweise und Datenfluss===
Vorläufig ist alexa-fhem im "FHEM Connector-Modus" ein reiner [https://developer.amazon.com/de/docs/smarthome/understand-the-smart-home-skill-api.html SmartHome-Skill].
SmartHome-Skills erhalten weder die Sprachdaten selber noch das, was Amazon in Textform verstanden hat, sondern vielmehr extrahiert Amazon aus dem verstandenen Text Anweisungen und Abfragen für Geräte, die dann an den Skill übermittelt werden. Charmant ist dabei, dass unmittelbar gefragt werden kann "Alexa, wie ist die Temperatur im Wohnzimmer?", während andere Skills zunächst explizit angesprochen werden müssen ("Alexa, frage FHEM nach der Temperatur im Wohnzimmer"). Außerdem kann der Nutzer mehrere Smarthome-Skills installieren, und die Geräte werden zu einer Gesamtmenge zusammengefasst.

Gehen wir den Datenfluss bei der konkreten Frage "Wie ist die Temperatur im Wohnzimmer?" durch:
* Alexa hat bei der Skillinstallation gelernt, dass "FHEM Connector" bei Dir einen Thermostaten im Raum Wohnzimmer kennt. Dadurch wird bei der Sprachanalyse von "Alexa Voice Service" in der Cloud erkannt, dass eine Abfrage an "FHEM Connector" erfolgversprechend ist.
* Zunächst wird die zentrale "Lambda-Funktion" von "FHEM Connector" aufgerufen. Die Funktion leitet aber im Kern nur den Request unverändert an den vom Verein bereitgestellten Server weiter. Im Request enthalten ist ein Token, das sogenannte "Bearer-Token".
* Der "Vereinsserver" prüft anhand dieses Tokens, ob es überhaupt bekannt ist, und zu welchem Nutzer es gehört. Ist dieser Nutzer verbunden, wird der Request wiederum quasi unverändert an den Nutzer weitergeleitet.
* Diese Weiterleitung passiert über einen sogenannten SSH-Reverse-Tunnel, der von Deiner Seite und der Software auf dem FHEM-Tunnel automatisch aufgebaut wird.
* Auf Deiner Seite läuft die eigentliche Software, und zwar unter nodeJS. nodeJS ist ein Javascript ausführender Miniserver, der lokal auf Port 3000 auf Requests "lauscht". In der Original-Version [[Alexa-Fhem|Alexa FHEM]] kommen die Requests aus dem Internet (hoffentlich von der eigenen Lambda-Funktion), hier bei "FHEM Connector" kommen sie ausschließlich aus dem SSH-Tunnel von lokal.
* Die Software validiert nun diesen Request anhand des Bearer-Tokens. Konkret wird dabei das bei der Installation generierte Token, dass bei der Skill-Aktivierung an Amazon übertragen wurde, mit dem lokal gespeicherten Wert verglichen. Stimmt das Token, wird der Befehl verarbeitet, üblicherweise wird hierbei ein Aufruf an die Webschnittstelle von FHEM abgesetzt.
* FHEM führt den Befehl aus

Hört sich langsam und kompliziert an? Kompliziert: Okay. Langsam eher nicht, in etlichen Fällen liegt die Gesamtantwortszeit unter 200 ms.

Soweit ein erster Überblick über die Datenflüsse. Im Abschnitt Sicherheit ist das Konzept der Absicherung deutlich genauer und ausführlicher beschrieben.

==Installation==

Du wirst bei der Installation zuerst auf der Kommandozeile auf Deinem Raspberry (o.ä.) unterwegs sein, anschließend im Webfrontend von FHEM, und zum Schluss auf der Alexa-Konsole im Web.

===node.js installieren===

Bei Jessy liegt NodeJS bereits in einer ausreichend aktuellen Version vor. Mit

<syntaxhighlight lang="bash" style="width:50%;">
sudo apt-get install nodejs npm
</syntaxhighlight>

kannst Du es installieren. Mit
<syntaxhighlight lang="bash" style="width:50%;">
node --version
</syntaxhighlight>

erfährst Du die aktuelle Version - wenn hier etwas mit "8" vorneweg erscheint, ist alles gut.
Ansonsten suche Dir bitte eine Anleitung im Web, wie Du NodeJS auf Deinem System auf einen aktuellen Stand bringen kannst.

=== Alexa-FHEM installieren ===

Nun installieren wir Alexa-fhem aus dem offiziellen Repository:

<syntaxhighlight lang="bash" style="width:50%;">
sudo npm install -g alexa-fhem
</syntaxhighlight>

Der Vorgang benötigt etwas Zeit.

=== Alexa-FHEM aktivieren ===

Wechsele jetzt in FHEM-Web!

Wichtig ist, dass das Alexa-Modul in der Version ab 14. Januar 2019 vorliegt. Dafür bitte einmal FHEM aktualisieren:
Speichern der Config nicht vergessen, und

<syntaxhighlight lang="bash" style="width:50%;">
update
shutdown restart
</syntaxhighlight>

Alles, was jetzt noch nötig ist, ist das Anlegen eines Alexa-Devices. Gib dafür in der FHEM-Web-Kommandozeile

<syntaxhighlight lang="bash" style="width:50%;">
define alexa alexa
</syntaxhighlight>

an. Nun läuft, während Du bereits das neu angelegte Alexa-Devices siehst, ein komplexer Prozess im Hintergrund:

* Falls noch kein SSH-Key für den Benutzer, unter dem FHEM läuft, existiert, wird einer generiert
* Es wird ein Secret-Key im Prozess generiert, dass den Server nicht verlässt, und der Skillanmeldung dient.
* Du wirst auf dem Server "va-fhem.fhem.de" des FHEM-Vereins mit dem SSH-Key angemeldet, und der Hash-Wert Deines Secret-Key dort abgelegt.

Und wenn Du diese Sätze gelesen hast, sollte inzwischen sich das Alexa-Device in FHEM-Web aktualisiert haben, und
ungefähr so aussehen:

[[Datei:Alexa-Device-2.png|800px]]

Neben dem Status für alexa-fhem und der Proxyverbindung ist wichtig, dass diese beiden Zeilen beim Reload aufgetaucht sind:

<syntaxhighlight lang="bash" style="width:90%;">
alexaFHEM.bearerToken crypt:...
alexaFHEM.skillRegKey crypt:...
</syntaxhighlight>

Ja, und diesen Schlüssel benötigst Du wirklich! Also am besten schon einmal mit

<syntaxhighlight lang="bash" style="width:90%;">
get <alexa> proxyKey
</syntaxhighlight>

in Klartext anzeigen lassen und in ein Editor-Fenster dauerhaft wegsichern.

==== Fehler bei der Aktivierung ====

Während kompliziertere Fehlerfälle im Abschnitt "Mögliche Probleme und Lösungen" behandelt werden, hier häufige Fälle, warum die kryptischen Zeilen nicht auftauchen:

* Zuerst bitte einfach einmal die Seite neu laden.
* Wenn Du FHEM-Web mit einem User/Passwort-Schutz versehen hast, wirst du folgende Fehlermeldung sehen:

<syntaxhighlight lang="bash" style="width:90%;">
alexaFHEM stopped; failed to connect to fhem: 401: Authorization Required
</syntaxhighlight>

* In der Regel musst du die Angaben User/Passwort noch einmal explizit setzen. Im Attribute-Abschnitt "alexaFHEM-auth" auswählen, User/Passwort mit ":" getrennt angeben und "attr" anklicken. alexa-fhem wird automatisch neu gestartet. Hier das Ganze in der Text-Variante:

<syntaxhighlight lang="bash" style="width:90%;">
attr alexa alexaFHEM-auth user:pass
</syntaxhighlight>

* Hast Du noch die Shell-Konsole offen? Dann prüfe bitte noch einmal auf der Konsole, ob nun zwei Prozesse laufen:

<syntaxhighlight lang="bash" style="width:50%;">
ps -ef | egrep '(alexa|ssh)'
</syntaxhighlight>

sollte Dir idealerweise so etwas anzeigen:
<syntaxhighlight lang="bash" style="width:90%;">
fhem 31322 1 99 13:56 ? 00:00:03 alexa
fhem 31332 31322 8 13:56 ? 00:00:00 /usr/bin/ssh -R 1234:127.0.0.1:<zufälliger port> -oServerAliveInterval=90 -p 58824 fhem-va.fhem.de
</syntaxhighlight>

"alexa" ist dabei der Node-JS-Prozess, der ssh-Prozess ist die aufgebaute Verbindung zum Vereinsserver.

Wenn Du diese Prozesse '''nicht''' siehst oder das Alexa-Device keinen Registrierungskey anzeigt, dann ist leider der Start nicht glatt verlaufen.

Im Logfile (über den link <code>Logfile</code> in der Detail-Ansicht über <code>set</Code>, oder über den Namen bei <it>currentlogfile</it> in den Internals) findest Du idealerweise selber Hinweise, wo es hakt, oder kannst im Forum nachfragen.

Jetzt solltest Du Dein Alexa-Device nicht mehr löschen, denn das im Reading angezeigte "bearerToken" zu löschen bedeutet, dass die Software die Zugriffe von nicht mehr überprüfen kann und keine Kommandos mehr funktionieren. In diesem Fall hilft nur die Neuinstallation des Skills.

=== Geräte im FHEM-Webfrontend zuweisen ===
Um das Aha-Erlebnis zu vergrößern, ist jetzt ein guter Zeitpunkt, 1 oder besser mind. 2 Geräte für den Alexa-Dienst zuzuweisen. Von Haus aus wird keines Deiner FHEM-Geräte automatisch Alexa zugewiesen!

Wähle die Geräte aus, rufe sie auf und setze das Attribut "alexaName". Hierbei in Kürze nur der Hinweis:
* Keine Angst vor Leerzeichen und Umlauten, funktioniert.
* Große Angst vor Rechtschreibfehlern (Terrasse, Rollladen) oder komplizierten Wörtern "handgebastelte Martinslaterne im Kinderzimmer Iphigenie-Chantal".
* Das Attribut "alexaRoom" ist NUR FÜR DEN CUSTOM SKILL relevant. Ausnahme: structure und LightScene Devices, siehe: [[FHEM_Connector_f%C3%BCr_Amazon_Alexa#Was_geht_alles_.3F]].

Lade die Geräte neu in die Software, indem Du <code>set <alexa> restart</code> ausführst!

== Finale: Skill verknüpfen ==
Suche im WebFrontend oder der Alexa-App den Skill "FHEM Connector". Für nicht-Mac/iOS Anwerder empfiehlt das WebFrontend (https://alexa.amazon.de) statt die App, damit Du den Anmeldeschlüssel auch bequem kopieren kannst.

Wenn du noch nicht bei Amazon angemeldet bist, erwartet Amazon zunächst, dass Du Dich normal bei Amazon anmeldest.

Sobald Du "FHEM Connector" aktivierst, öffnet sich ein Browser-Tab mit folgender Maske: 
[[Datei:FHEMlazy_login.png|240px]]

Hier kopierst Du Deinen Anmeldeschlüssel (im Klartext!) hinein und klickst auf Check. Als glücklicher Mensch ist auf der folgenden Statusseite alles grün: 
[[Datei:FHEMlazy_check.png|240px]]

Im Einzelnen wird hier geprüft, ob Du per SSH verbunden bist (und auch Deine IP zur Sicherheit angezeigt), ob der Reverse-Tunnel steht, ob nodeJS erreichbar ist und wie viele Geräte Alexa gleich finden sollte (in meinem Fall 22).

Sollte etwas nicht grün sein und Du eine Idee zum Fixen haben, kannst Du mit "Retry" neue Versuche auslösen.

Ist alles okay, klicke rechts den Button "Activate Skill". Du springst damit wieder zurück zu Amazon, die Dir hoffentlich zur erfolgreichen Verknüpfung gratulieren.

Amazon möchte nun unmittelbar die Gerätesuche starten, und unter SmartHome-Geräte sollten diese nun auftauchen.

== Was geht alles ? ==

* Geräte, die sich ein- und ausschalten lassen:
** Automatisch: Müssen <code>set on</code> und <code>set off</code> Kommandos haben
** dummys müssen <code>setList</code> mit on und off haben
** Über <code>genericDeviceType</code> switch bzw. light kann bestimmt werden ob es in alexa als Schalter oder Licht behandelt wird.
** Wenn die Set-Kommandos im FHEM Device anders benannt sind: hombridgeMapping On:cmdOn=<ein>,CmdOff=<aus> setzen
** Kommandos:
***Alexa, schalte <name> ein/aus
***Alexa, Licht an/aus
***Alexa, schalte <gruppe> ein/aus

* Geräte, die eine Temperatur messen
** Automatisch: Es muss ein Reading temperature geben
** Über <code>genericDeviceType</code> thermometer
** Sonst: hombridgeMapping CurrentTemperature:reading=<reading>

* Geräte, deren Helligkeit sich ändern lässt
** Automatisch: wenn <code>dim</code> oder <code>pct</code> Kommandos erkannt werden
** Über <code>genericDeviceType</code> light
** Über homebridgeMapping: Wenn <code>helligkeit</code> das Reading für die aktuelle Helligkeit enthält und die Helligkeit mit <code>set <device> prozent xxx</code> gesetzt wird, sieht das homebridgeMapping wie folgt aus:
*** homebridgeMapping Brightness=helligkeit::prozent,minValue=0,maxValue=<maximalwert>

**Kommandos:
***Alexa, mache <name> heller/dunkler
***Alexa, Licht heller/dunkler

* Geräte, deren Farbe sich ändern lässt
** ...

* Geräte, deren Farbtemperatur sich ändern lässt
** ...

* Geräte, bei denen sich eine Lautstärke einstellen lässt
** ...

* Geräte, bei denen sich ein prozentualer Wert einstellen lässt
** Automatisch: wenn <code>dim</code> oder <code>pct</code> Kommandos erkannt werden
** ...

* elektrische Türschlösser
** <code>genericDeviceType</code>: lock
** hombridgeMapping mit LockCurrentState und LockTargetState

* Thermostate
** Über <code>genericDeviceType</code> thermostate
** ...

* structure Devices aus FHEM (ab alexa-fhem version 0.5.7)
** können mit <code>genericDeviceType</code> scene als Szene eingebunden werden
** über <code>alexaRoom</code> kann der name um einen Ort ergänzt werden
** Szenen aus einer structure lassen sich ein- und ausschalten
** Wichtig:
*** Ein Skill darf nur 12 Szenen automatisch erkennen und einbinden.

* LightScene Devices aus FHEM (ab alexa-fhem version 0.5.8)
** können mit <code>genericDeviceType</code> scene als Szenen eingebunden werden
** über <code>alexaRoom</code> kann der name um einen Ort ergänzt werden
** Szenen aus einer LightScene lassen sich nur einschalten
** Wichtig:
*** Ein Skill darf nur 12 Szenen automatisch erkennen und einbinden.

* Geräte, deren Kanal sich umschalten lässt (ab alexa-fhem version 0.5.13)
** Über <code>genericDeviceType</code> media
** hombridgeMapping ChannelController:reading=<reading>,cmd=<cmd>
** Erlaubte Werte siehe hier: https://developer.amazon.com/de/docs/device-apis/alexa-channelcontroller.html#changechannel
** ...

* Geräte, deren Playback status sich schalten lässt (ab alexa-fhem version 0.5.13)
** Über <code>genericDeviceType</code> media
** hombridgeMapping PlaybackController:playback,values=Play;Pause;Stop;Previous;Next
** Erlaubte Werte siehe hier: https://developer.amazon.com/de/docs/device-apis/alexa-playbackcontroller.html#discovery
** ...

* Geräte, deren Eingang sich umschalten lässt (ab alexa-fhem version 0.5.13)
** Über <code>genericDeviceType</code> media
** hombridgeMapping InputController:reading=<reading>,cmd=<cmd>,values=HDMI+1;HDMI+2;XBOX
** Erlaubte Werte siehe hier: https://developer.amazon.com/de/docs/device-apis/alexa-property-schemas.html#input
** ...

* Kontaktsensoren (ab alexa-fhem version 0.5.15)
** Über <code>genericDeviceType</code> contact
** hombridgeMapping ContactSensorState:reading=<reading> oder CurrentDoorState:reading=<reading>
** Die Anzeige in der Alexa-App funktioniert sofort, die Abfrage per Sprache erst ab Version 0.5.27.

* Geräte, deren Lautstärke sich ändern lässt (ab alexa-fhem version 0.5.24)
** Über <code>genericDeviceType</code> speaker
** Automatisch: es muss ein Reading <code>volume</code> und/oder <code>mute</code> geben
** hombridgeMapping Volume:reading=<reading>,cmd=<cmd> Mute:reading=<reading>,cmd=<cmd>
** ...

* Geräte, die sich ein- (und optional) ausschalten lassen als Szene (ab alexa-fhem version 0.5.26)
** Über <code>genericDeviceType</code> scene
** Automatisch: Müssen <code>set on</code> und <code>set off</code> Kommandos haben
** hombridgeMapping On:reading=<reading>,cmdOn=<cmd>[,cmdOff=<cmd>]
** Hinweis: Fehlende Kommandos lassen sich mit cmdalias erzeugen
** Wichtig:
*** Ein Skill darf nur 12 Szenen automatisch erkennen und einbinden.

Es werden noch einige andere häufig verwendete Geräte (Homematic, hue,...) automatisch erkannt.

to be continued ...

In der [https://developer.amazon.com/docs/device-apis/list-of-interfaces.html List of Capability Interfaces] bei Amazon kann man sehen, welche Möglichkeiten das Smart Home Skill API aktuell in einzelnen Ländern bietet. Leider ohne die jeweiligen landessprachlichen Kommandos.

== Mögliche Probleme und Lösungen ==

Es kann vorkommen, dass Geräte zwar korrekt erkannt werden, aber das durch Alexa erkannte Kommando nicht richtig umgesetzt wird (Beispiel - mittlerweile behoben: {{Link2Forum|Topic=96766}}). Neben dem FHEM-Log gibt es noch das Logfile, welches von alexa-fhem angelegt wird.

=== Fehlersuche über die FHEM-Oberfläche ===

* alexa-fhem Logfile anschauen (Detail-Ansicht des <alexa>-Device aufrufen, klick auf '''Logfile''' oben)
* alexa-fhem im Debug-Modus aufrufen:
** -D zum alexaFHEM-params attribut hinzufügen
** Alexa-Befehl auslösen
** -D aus dem alexaFHEM-params attribut entfernen
* Die notwendigen Informationen finden sich in dem alexa-Logfile (siehe oben)

=== Fehlersuche über Kommandozeile (lies: Shell) + FHEM-Oberfläche ===

:* set <alexa> stop (FHEM-Oberfläche)
:* Auf der Kommandozeile <code>alexa-fhem -D -c /opt/fhem/alexa-fhem.cfg > debug.log</code> starten (dadurch wird die Datei debug.log erzeugt im aktuellen Verzeichnis)
:* Alexa-Befehl auslösen
:* alexa-fhem auf der Kommandozeile wieder stoppen (CTRL-C)
:* set <alexa> start (FHEM-Oberfläche)

Die Datei debug.log sollte Hinweise enthalten, wie das Problem zu lösen ist oder Dich zumindest in die richtige Richtung schieben.

Im Beispiel aus dem Forum fand sich in dem Logfile der Hinweis darauf, dass das Device mit falschen min/max-Werten unterwegs war.

=== Registrierungskey vergessen, Registrierung zurücksetzen ===

Auf der Kommandoshell:

<syntaxhighlight lang="bash" style="width:90%;">
pi@raspberrypi:~# sudo -u fhem ssh -p 58824 fhem-va.fhem.de status
Registered.
Registered on 2019-01-13T15:38:13Z.
</syntaxhighlight>

heisst, das der Vereinsserver eigentlich alles hat, was er will. Es wird kein neuer Schlüssel generiert.
Wenn Du die Situation zurücksetzen möchtest, wäre die hässliche Methode, Deinen SSH-Key zu löschen. Eleganter ist, die Registrierung auf Vereinsseite zu löschen:

<syntaxhighlight lang="bash" style="width:90%;">
pi@raspberrypi:~# sudo -u fhem ssh -p 58824 fhem-va.fhem.de unregister
Your registration has been removed
</syntaxhighlight>

löscht Deinen Schlüssel mitsamt allen dort gespeicherten Daten auf Vereinsseite. Bei Restart von alexa-fhem in FHEM-WEB wird jetzt ein neuer Registrierungskey angefordert.

== Sicherheitskonzept und Secrets ==

Um diesen Abschnitt zu verstehen, solltest Du den Abschnitt "Arbeitsweise" im Kopf haben. Einerseits ist Dir vermutlich einleuchtend, dass ein Server, der per SSH rückwärts nur ausgewählte Kommandos in den Tunnel, den Du aufgebaut hast, leitet, "irgendwie sicherer" ist. Andererseits möchte man nicht blind vertrauen.

=== SSH ===
==== SSH - macht das nichts Gefährliches? ====
SSH ist ein Veteran des Internet und entstand, um sich sicher (verschlüsselt) und schnell auf Servern einzuloggen. Schon früh wurde dabei der sogenannte "Reverse-Tunnel" implementiert: Also der vom Client (Deinem Rechner) geäußerte Wunsch: "Bitte leite mir Requests, die bei Dir, Server, auf Port xy eingehen, an meinen lokalen Port yz weiter.". Dieses Verfahren implementiert der Reverseproxy, wobei tatsächlich auf dem Server für Dich kein echter Port geöffnet wird.

Wie Dir ggf. sicher der Unix-Guru Deines Vertrauens bestätigen wird: Die Kombination
<syntaxhighlight lang="bash" style="width:50%;">
ssh -R 1234:localhost:<zufälliger port> zielserver
</syntaxhighlight>
erlaubt keine Ausführung von Shell-Kommandos auf Deinem Server, sondern einzig, dass vom SSH-Programm Verbindungen zu einem lokalen Port auf Deinem Server auf dem alexa-fhem lauscht aufgebaut werden. Du kannst also z.B. mit einem
<syntaxhighlight lang="bash" style="width:50%;">
sudo /usr/sbin/tcpdump -X -s 0 -i lo port <zufälliger port>
</syntaxhighlight>
vollständig überwachen (oder ggf. permanent aufzeichen), was auf Deinem Server von außen gesteuert passiert.

==== Wie wird bei SSH verschlüsselt? ====
Im Prinzip wie im Web auf SSL-Seiten, teils mit den gleichen Verschlüsselungsverfahren. Allerdings arbeitet SSH eher wie das im Web recht seltene Verfahren: Bei jeder Verbindung übermitteln sowohl Server wie auch Client den öffentlichen Teil ihres Schlüssels. Anders als im Web wird der Schlüssel aber nicht von einer öffentlichen Zertifizierungsstelle wie "LetsEncrypt" unterschrieben. Stattdessen entscheiden Server wie Client beim ersten Verbindungsaufbau typischerweise per manueller Frage: "Willst Du jetzt und künftig diesem Schlüssel vertrauen?" Bei der Installation wird diese Frage für Deine Seite bejaht, und fortan wird der öffentliche Schlüssel des FHEM-Servers auf Deinem Rechner gespeichert. Ab da bist Du z.B. davor sicher, dass jemand den DNS-Eintrag verbiegt oder sich in den Datenfluss Deines Providers einhängt: Ein geänderter Serverschlüssel würde bemerkt werden.
 
Soweit klar? Aus Deinem öffentlichen Schlüssel wiederum leitet der Server her: "Das ist definitiv wieder derjenige, der sich damals "registriert" hat". Und an dieser Stelle kann ich auch den ersten Teil des 3-teiligen Registrierungskeys erläutern: Die typischerweise 6-stellige Hex-Zahl am Anfang ist der Java-Hashcode Deines öffentlichen Schlüssel. Sie ist damit sozusagen Deine aus Deinem öffentlichen Schlüssel abgeleitete Benutzer-ID.

=== Die Rolle der Secrets ===
Wenn jetzt klar ist, dass die Verbindung zum Vereinsserver sicher und vertauschungsfrei funktioniert, bleiben noch 2 Probleme zu lösen:
1) Im Web bei der Skill-Aktivierung musst Du beweisen, dass Du der Mensch am Browser bist, dem der SSH-Tunnel von IP xy mit dem öffentlichen Schlüssel X gehört. Bei der automatischen Registrierung werden lokal auf Deinem Rechner zwei 64-Bit-Secrets generiert:
* Das Anmelde-Secret
* Das Bearer-Token
Beim Anmelden des SSH-Keys auf dem öffentlichen Server wird nun der Hashwert des ersten Secrets übertragen und dort in Verbindung mit Deinem öffentlichen Schlüssel gespeichert. Ein Hashwert bedeutet, dass (sofern das Verfahren, hier SHA256, funktioniert), niemand aus dem Hash das Secret zurückrechnen kann. Ein Datenbankklau auf dem Server gefährdet also nicht die Sicherheit Deines Passwortes.

Wenn Du nun beim Skill-Aktivieren den Registrierungskey eingibst, dann "sieht" der Server zum ersten Mal Dein ausgewürfeltes Secret, vergleicht es mit dem Hashwert und wird es anschließend wieder umgehend vergessen. Anhand des Hashwertes kann der Server aber entscheiden, dass Du der legitime Nutzer zum öffentlichen Schlüssel XY bist.

2) Das zweite Problem ist: Wie soll Amazon "beweisen", dass sie der legitime Aufrufer sind? Amazon erhält binnen wenigen Sekunden nach dem Klick auf "Activate Skill" den dritten Teil des Registrierungskeys als sogenanntes Bearer-Token. Zwar läuft er durch den Registrierungsserver, er wird dort, auf dem Registrierungs/Vereinsserver aber nicht gespeichert. Das Bearer-Token wird von Amazon bei allen Requests zu Deinem Server mitgesendet. Da es am Anfang zusätzlich Deine "User-ID" enthält, weiß der Vereinsserver, zu welchem SSH-Tunnel der Request zu senden ist. Aber lokal auf Deinem Rechner wird ausgewertet, ob das Token "stimmt".

== alexa-fhem Updaten ==
* alexa-fhem über FHEM anhalten:
:<syntaxhighlight lang="perl" style="width:50%;">set alexa stop</syntaxhighlight>

*Auf der Konsole wie anfangs bei der Installation:
:<syntaxhighlight lang="bash" style="width:50%;">sudo npm update -g alexa-fhem</syntaxhighlight>

:Manchmal hat npm Probleme mit einem Update. Dann einfach die aktuelle Version noch mal drüber Installieren:

:<syntaxhighlight lang="bash" style="width:50%;">sudo npm install -g alexa-fhem</syntaxhighlight>

*alexa-fhem über FHEM wieder starten:
:<syntaxhighlight lang="perl" style="width:50%;">set alexa start</syntaxhighlight>

== Bug- und Wunschliste ==
* Ist beim Start keine Internetverbindung vorhanden, erfolgt kein Retry -- alexa-fhem muss restartet werden (ssh_autoconfig wertet keine temporären Fehler aus)

==Weitergehende Informationen==
*[[Alexa_und_Mappings]]
*[[Alexa_Tipps_und_Kniffe]]
[[Kategorie:HOWTOS]]
[[Kategorie:Sprachsteuerung]]

FHEM Connector für Amazon Alexa

2019-07-25T14:55:55Z

Hoppel118: Fehlermeldung "401: Authorization Required" bei Aktivierung und SONOS als mögliche Devices im ersten Abschnitt ergänzt

{{Baustelle}}
'''Alexa FHEMlazy''' war historisch ein Fork des Original [[Alexa-Fhem|alexa-fhem]], der im Januar 2019 mit dem Original zusammengeführt wurde und nun als '''FHEM Connector''' verfügbar ist.

Er ermöglicht innerhalb von Minuten die Verknüpfung von FHEM mit einem Amazon Echo Gerät. Auch Geräte anderer Hersteller mit verbauten Mikrofonen und Alexa-Sprachassistenten-Unterstützung sollten problemlos funktionieren. Für folgende Geräte ist dies bspw. der Fall (Falls Ihr andere/weitere Gerätemodelle bzw. Hersteller in Verwendung habt, bitte hier pflegen):

* SONOS Beam und SONOS One

Gegenüber dem klassischen Ansatz ergeben sich Einschränkungen, so läuft die Software normalerweise unter dem gleichen Benutzer wie FHEM auf dem gleichen Server, und es wird z.Zt. nur der Smarthome-Skill unterstützt (die Variante, bei der die Möglichkeiten der Interaktion von Amazon festgelegt wurden).
Dafür ist weder ein Developer-Account bei Amazon, eigene Lambda- und Skillfunktionen, noch das Öffnen eines eingehenden Ports aus dem Internet nötig.
* Die Software integriert einen Installer, der die Erstkonfiguration und Anmeldung übernimmt
* Die Kommunikation zur Software auf dem heimischen Rechner und dann zu FHEM verläuft über SSH und einen vom FHEM-Verein gehosteten Server
* Funktioniert mit IPv4, IPv6, echtem Dual Stack und DS-Lite
* Als Skill bei Amazon wird der Skill "FHEM Connector" verwendet.

Der Thread im Forum zur Software ist hier: {{Link2Forum|Topic=94817}}.

{{Infobox Modul
|ModPurpose=Einfache Anbindung von FHEM an Amazon Assistent Alexa
|ModType=h
|ModCmdRef=alexa
|ModTechName=39_alexa.pm / alexa-fhem
|ModForumArea=Frontends/Sprachsteuerung
|ModOwner=gvzdus, André/ justme1968 ({{Link2FU|430|Forum}} / [[Benutzer Diskussion:Justme|Wiki]])
}}

==Einführung==

===Arbeitsweise und Datenfluss===
Vorläufig ist alexa-fhem im "FHEM Connector-Modus" ein reiner [https://developer.amazon.com/de/docs/smarthome/understand-the-smart-home-skill-api.html SmartHome-Skill].
SmartHome-Skills erhalten weder die Sprachdaten selber noch das, was Amazon in Textform verstanden hat, sondern vielmehr extrahiert Amazon aus dem verstandenen Text Anweisungen und Abfragen für Geräte, die dann an den Skill übermittelt werden. Charmant ist dabei, dass unmittelbar gefragt werden kann "Alexa, wie ist die Temperatur im Wohnzimmer?", während andere Skills zunächst explizit angesprochen werden müssen ("Alexa, frage FHEM nach der Temperatur im Wohnzimmer"). Außerdem kann der Nutzer mehrere Smarthome-Skills installieren, und die Geräte werden zu einer Gesamtmenge zusammengefasst.

Gehen wir den Datenfluss bei der konkreten Frage "Wie ist die Temperatur im Wohnzimmer?" durch:
* Alexa hat bei der Skillinstallation gelernt, dass "FHEM Connector" bei Dir einen Thermostaten im Raum Wohnzimmer kennt. Dadurch wird bei der Sprachanalyse von "Alexa Voice Service" in der Cloud erkannt, dass eine Abfrage an "FHEM Connector" erfolgversprechend ist.
* Zunächst wird die zentrale "Lambda-Funktion" von "FHEM Connector" aufgerufen. Die Funktion leitet aber im Kern nur den Request unverändert an den vom Verein bereitgestellten Server weiter. Im Request enthalten ist ein Token, das sogenannte "Bearer-Token".
* Der "Vereinsserver" prüft anhand dieses Tokens, ob es überhaupt bekannt ist, und zu welchem Nutzer es gehört. Ist dieser Nutzer verbunden, wird der Request wiederum quasi unverändert an den Nutzer weitergeleitet.
* Diese Weiterleitung passiert über einen sogenannten SSH-Reverse-Tunnel, der von Deiner Seite und der Software auf dem FHEM-Tunnel automatisch aufgebaut wird.
* Auf Deiner Seite läuft die eigentliche Software, und zwar unter nodeJS. nodeJS ist ein Javascript ausführender Miniserver, der lokal auf Port 3000 auf Requests "lauscht". In der Original-Version [[Alexa-Fhem|Alexa FHEM]] kommen die Requests aus dem Internet (hoffentlich von der eigenen Lambda-Funktion), hier bei "FHEM Connector" kommen sie ausschließlich aus dem SSH-Tunnel von lokal.
* Die Software validiert nun diesen Request anhand des Bearer-Tokens. Konkret wird dabei das bei der Installation generierte Token, dass bei der Skill-Aktivierung an Amazon übertragen wurde, mit dem lokal gespeicherten Wert verglichen. Stimmt das Token, wird der Befehl verarbeitet, üblicherweise wird hierbei ein Aufruf an die Webschnittstelle von FHEM abgesetzt.
* FHEM führt den Befehl aus

Hört sich langsam und kompliziert an? Kompliziert: Okay. Langsam eher nicht, in etlichen Fällen liegt die Gesamtantwortszeit unter 200 ms.

Soweit ein erster Überblick über die Datenflüsse. Im Abschnitt Sicherheit ist das Konzept der Absicherung deutlich genauer und ausführlicher beschrieben.

==Installation==

Du wirst bei der Installation zuerst auf der Kommandozeile auf Deinem Raspberry (o.ä.) unterwegs sein, anschließend im Webfrontend von FHEM, und zum Schluss auf der Alexa-Konsole im Web.

===node.js installieren===

Bei Jessy liegt NodeJS bereits in einer ausreichend aktuellen Version vor. Mit

<syntaxhighlight lang="bash" style="width:50%;">
sudo apt-get install nodejs npm
</syntaxhighlight>

kannst Du es installieren. Mit
<syntaxhighlight lang="bash" style="width:50%;">
node --version
</syntaxhighlight>

erfährst Du die aktuelle Version - wenn hier etwas mit "8" vorneweg erscheint, ist alles gut.
Ansonsten suche Dir bitte eine Anleitung im Web, wie Du NodeJS auf Deinem System auf einen aktuellen Stand bringen kannst.

=== Alexa-FHEM installieren ===

Nun installieren wir Alexa-fhem aus dem offiziellen Repository:

<syntaxhighlight lang="bash" style="width:50%;">
sudo npm install -g alexa-fhem
</syntaxhighlight>

Der Vorgang benötigt etwas Zeit.

=== Alexa-FHEM aktivieren ===

Wechsele jetzt in FHEM-Web!

Wichtig ist, dass das Alexa-Modul in der Version ab 14. Januar 2019 vorliegt. Dafür bitte einmal FHEM aktualisieren:
Speichern der Config nicht vergessen, und

<syntaxhighlight lang="bash" style="width:50%;">
update
shutdown restart
</syntaxhighlight>

Alles, was jetzt noch nötig ist, ist das Anlegen eines Alexa-Devices. Gib dafür in der FHEM-Web-Kommandozeile

<syntaxhighlight lang="bash" style="width:50%;">
define alexa alexa
</syntaxhighlight>

an. Nun läuft, während Du bereits das neu angelegte Alexa-Devices siehst, ein komplexer Prozess im Hintergrund:

* Falls noch kein SSH-Key für den Benutzer, unter dem FHEM läuft, existiert, wird einer generiert
* Es wird ein Secret-Key im Prozess generiert, dass den Server nicht verlässt, und der Skillanmeldung dient.
* Du wirst auf dem Server "va-fhem.fhem.de" des FHEM-Vereins mit dem SSH-Key angemeldet, und der Hash-Wert Deines Secret-Key dort abgelegt.

Und wenn Du diese Sätze gelesen hast, sollte inzwischen sich das Alexa-Device in FHEM-Web aktualisiert haben, und
ungefähr so aussehen:

[[Datei:Alexa-Device-2.png|800px]]

Neben dem Status für alexa-fhem und der Proxyverbindung ist wichtig, dass diese beiden Zeilen beim Reload aufgetaucht sind:

<syntaxhighlight lang="bash" style="width:90%;">
alexaFHEM.bearerToken crypt:...
alexaFHEM.skillRegKey crypt:...
</syntaxhighlight>

Ja, und diesen Schlüssel benötigst Du wirklich! Also am besten schon einmal mit

<syntaxhighlight lang="bash" style="width:90%;">
get <alexa> proxyKey
</syntaxhighlight>

in Klartext anzeigen lassen und in ein Editor-Fenster dauerhaft wegsichern.

==== Fehler bei der Aktivierung ====

Während kompliziertere Fehlerfälle im Abschnitt "Mögliche Probleme und Lösungen" behandelt werden, hier häufige Fälle, warum die kryptischen Zeilen nicht auftauchen:

* Zuerst bitte einfach einmal die Seite neu laden.
* Wenn Du FHEM-Web mit einem User/Passwort-Schutz versehen hast, wirst du folgende Fehlermeldung sehen:

<syntaxhighlight lang="bash" style="width:90%;">
alexaFHEM stopped; failed to connect to fhem: 401: Authorization Required
</syntaxhighlight>

* In der Regel musst du die Angaben User/Passwort noch einmal explizit setzen. Im Attribute-Abschnitt "alexaFHEM-auth" auswählen, User/Passwort mit ":" getrennt angeben und "attr" anklicken. alexa-fhem wird automatisch neu gestartet. Hier das Ganze in der Text-Variante:

<syntaxhighlight lang="bash" style="width:90%;">
attr alexa alexaFHEM-auth user:pass
</syntaxhighlight>

* Hast Du noch die Shell-Konsole offen? Dann prüfe bitte noch einmal auf der Konsole, ob nun zwei Prozesse laufen:

<syntaxhighlight lang="bash" style="width:50%;">
ps -ef | egrep '(alexa|ssh)'
</syntaxhighlight>

sollte Dir idealerweise so etwas anzeigen:
<syntaxhighlight lang="bash" style="width:90%;">
fhem 31322 1 99 13:56 ? 00:00:03 alexa
fhem 31332 31322 8 13:56 ? 00:00:00 /usr/bin/ssh -R 1234:127.0.0.1:<zufälliger port> -oServerAliveInterval=90 -p 58824 fhem-va.fhem.de
</syntaxhighlight>

"alexa" ist dabei der Node-JS-Prozess, der ssh-Prozess ist die aufgebaute Verbindung zum Vereinsserver.

Wenn Du diese Prozesse '''nicht''' siehst oder das Alexa-Device keinen Registrierungskey anzeigt, dann ist leider der Start nicht glatt verlaufen.

Im Logfile (über den link <code>Logfile</code> in der Detail-Ansicht über <code>set</Code>, oder über den Namen bei <it>currentlogfile</it> in den Internals) findest Du idealerweise selber Hinweise, wo es hakt, oder kannst im Forum nachfragen.

Jetzt solltest Du Dein Alexa-Device nicht mehr löschen, denn das im Reading angezeigte "bearerToken" zu löschen bedeutet, dass die Software die Zugriffe von nicht mehr überprüfen kann und keine Kommandos mehr funktionieren. In diesem Fall hilft nur die Neuinstallation des Skills.

=== Geräte im FHEM-Webfrontend zuweisen ===
Um das Aha-Erlebnis zu vergrößern, ist jetzt ein guter Zeitpunkt, 1 oder besser mind. 2 Geräte für den Alexa-Dienst zuzuweisen. Von Haus aus wird keines Deiner FHEM-Geräte automatisch Alexa zugewiesen!

Wähle die Geräte aus, rufe sie auf und setze das Attribut "alexaName". Hierbei in Kürze nur der Hinweis:
* Keine Angst vor Leerzeichen und Umlauten, funktioniert.
* Große Angst vor Rechtschreibfehlern (Terrasse, Rollladen) oder komplizierten Wörtern "handgebastelte Martinslaterne im Kinderzimmer Iphigenie-Chantal".

Lade die Geräte neu in die Software, indem Du <code>set <alexa> restart</code> ausführst!

== Finale: Skill verknüpfen ==
Suche im WebFrontend oder der Alexa-App den Skill "FHEM Connector". Für nicht-Mac/iOS Anwerder empfiehlt das WebFrontend (https://alexa.amazon.de) statt die App, damit Du den Anmeldeschlüssel auch bequem kopieren kannst.

Wenn du noch nicht bei Amazon angemeldet bist, erwartet Amazon zunächst, dass Du Dich normal bei Amazon anmeldest.

Sobald Du "FHEM Connector" aktivierst, öffnet sich ein Browser-Tab mit folgender Maske: 
[[Datei:FHEMlazy_login.png|240px]]

Hier kopierst Du Deinen Anmeldeschlüssel (im Klartext!) hinein und klickst auf Check. Als glücklicher Mensch ist auf der folgenden Statusseite alles grün: 
[[Datei:FHEMlazy_check.png|240px]]

Im Einzelnen wird hier geprüft, ob Du per SSH verbunden bist (und auch Deine IP zur Sicherheit angezeigt), ob der Reverse-Tunnel steht, ob nodeJS erreichbar ist und wie viele Geräte Alexa gleich finden sollte (in meinem Fall 22).

Sollte etwas nicht grün sein und Du eine Idee zum Fixen haben, kannst Du mit "Retry" neue Versuche auslösen.

Ist alles okay, klicke rechts den Button "Activate Skill". Du springst damit wieder zurück zu Amazon, die Dir hoffentlich zur erfolgreichen Verknüpfung gratulieren.

Amazon möchte nun unmittelbar die Gerätesuche starten, und unter SmartHome-Geräte sollten diese nun auftauchen.

== Was geht alles ? ==

* Geräte, die sich ein- und ausschalten lassen:
** Automatisch: Müssen <code>set on</code> und <code>set off</code> Kommandos haben
** dummys müssen <code>setList</code> mit on und off haben
** Über <code>genericDeviceType</code> switch bzw. light kann bestimmt werden ob es in alexa als Schalter oder Licht behandelt wird.
** Wenn die Set-Kommandos im FHEM Device anders benannt sind: hombridgeMapping On:cmdOn=<ein>,CmdOff=<aus> setzen
** Kommandos:
***Alexa, schalte <name> ein/aus
***Alexa, Licht an/aus
***Alexa, schalte <gruppe> ein/aus

* Geräte, die eine Temperatur messen
** Automatisch: Es muss ein Reading temperature geben
** Über <code>genericDeviceType</code> thermometer
** Sonst: hombridgeMapping CurrentTemperature:reading=<reading>

* Geräte, deren Helligkeit sich ändern lässt
** Automatisch: wenn <code>dim</code> oder <code>pct</code> Kommandos erkannt werden
** Über <code>genericDeviceType</code> light
** Über homebridgeMapping: Wenn <code>helligkeit</code> das Reading für die aktuelle Helligkeit enthält und die Helligkeit mit <code>set <device> prozent xxx</code> gesetzt wird, sieht das homebridgeMapping wie folgt aus:
*** homebridgeMapping Brightness=helligkeit::prozent,minValue=0,maxValue=<maximalwert>

**Kommandos:
***Alexa, mache <name> heller/dunkler
***Alexa, Licht heller/dunkler

* Geräte, deren Farbe sich ändern lässt
** ...

* Geräte, deren Farbtemperatur sich ändern lässt
** ...

* Geräte, bei denen sich eine Lautstärke einstellen lässt
** ...

* Geräte, bei denen sich ein prozentualer Wert einstellen lässt
** Automatisch: wenn <code>dim</code> oder <code>pct</code> Kommandos erkannt werden
** ...

* elektrische Türschlösser
** <code>genericDeviceType</code>: lock
** hombridgeMapping mit LockCurrentState und LockTargetState

* Thermostate
** Über <code>genericDeviceType</code> thermostate
** ...

* structure Devices aus FHEM (ab alexa-fhem version 0.5.7)
** können mit <code>genericDeviceType</code> scene als Szene eingebunden werden
** über <code>alexaRoom</code> kann der name um einen Ort ergänzt werden
** Szenen aus einer structure lassen sich ein- und ausschalten
** Wichtig:
*** Ein Skill darf nur 12 Szenen automatisch erkennen und einbinden.

* LightScene Devices aus FHEM (ab alexa-fhem version 0.5.8)
** können mit <code>genericDeviceType</code> scene als Szenen eingebunden werden
** über <code>alexaRoom</code> kann der name um einen Ort ergänzt werden
** Szenen aus einer LightScene lassen sich nur einschalten
** Wichtig:
*** Ein Skill darf nur 12 Szenen automatisch erkennen und einbinden.

* Geräte, deren Kanal sich umschalten lässt (ab alexa-fhem version 0.5.13)
** Über <code>genericDeviceType</code> media
** hombridgeMapping ChannelController:reading=<reading>,cmd=<cmd>
** Erlaubte Werte siehe hier: https://developer.amazon.com/de/docs/device-apis/alexa-channelcontroller.html#changechannel
** ...

* Geräte, deren Playback status sich schalten lässt (ab alexa-fhem version 0.5.13)
** Über <code>genericDeviceType</code> media
** hombridgeMapping PlaybackController:playback,values=Play;Pause;Stop;Previous;Next
** Erlaubte Werte siehe hier: https://developer.amazon.com/de/docs/device-apis/alexa-playbackcontroller.html#discovery
** ...

* Geräte, deren Eingang sich umschalten lässt (ab alexa-fhem version 0.5.13)
** Über <code>genericDeviceType</code> media
** hombridgeMapping InputController:reading=<reading>,cmd=<cmd>,values=HDMI+1;HDMI+2;XBOX
** Erlaubte Werte siehe hier: https://developer.amazon.com/de/docs/device-apis/alexa-property-schemas.html#input
** ...

* Kontaktsensoren (ab alexa-fhem version 0.5.15)
** Über <code>genericDeviceType</code> contact
** hombridgeMapping ContactSensorState:reading=<reading> oder CurrentDoorState:reading=<reading>
** Die Anzeige in der Alexa-App funktioniert sofort, die Abfrage per Sprache erst ab Version 0.5.27.

* Geräte, deren Lautstärke sich ändern lässt (ab alexa-fhem version 0.5.24)
** Über <code>genericDeviceType</code> speaker
** Automatisch: es muss ein Reading <code>volume</code> und/oder <code>mute</code> geben
** hombridgeMapping Volume:reading=<reading>,cmd=<cmd> Mute:reading=<reading>,cmd=<cmd>
** ...

* Geräte, die sich ein- (und optional) ausschalten lassen als Szene (ab alexa-fhem version 0.5.26)
** Über <code>genericDeviceType</code> scene
** Automatisch: Müssen <code>set on</code> und <code>set off</code> Kommandos haben
** hombridgeMapping On:reading=<reading>,cmdOn=<cmd>[,cmdOff=<cmd>]
** Hinweis: Fehlende Kommandos lassen sich mit cmdalias erzeugen
** Wichtig:
*** Ein Skill darf nur 12 Szenen automatisch erkennen und einbinden.

Es werden noch einige andere häufig verwendete Geräte (Homematic, hue,...) automatisch erkannt.

to be continued ...

In der [https://developer.amazon.com/docs/device-apis/list-of-interfaces.html List of Capability Interfaces] bei Amazon kann man sehen, welche Möglichkeiten das Smart Home Skill API aktuell in einzelnen Ländern bietet. Leider ohne die jeweiligen landessprachlichen Kommandos.

== Mögliche Probleme und Lösungen ==

Es kann vorkommen, dass Geräte zwar korrekt erkannt werden, aber das durch Alexa erkannte Kommando nicht richtig umgesetzt wird (Beispiel - mittlerweile behoben: {{Link2Forum|Topic=96766}}). Neben dem FHEM-Log gibt es noch das Logfile, welches von alexa-fhem angelegt wird.

=== Fehlersuche über die FHEM-Oberfläche ===

* alexa-fhem Logfile anschauen (Detail-Ansicht des <alexa>-Device aufrufen, klick auf '''Logfile''' oben)
* alexa-fhem im Debug-Modus aufrufen:
** -D zum alexaFHEM-params attribut hinzufügen
** Alexa-Befehl auslösen
** -D aus dem alexaFHEM-params attribut entfernen
* Die notwendigen Informationen finden sich in dem alexa-Logfile (siehe oben)

=== Fehlersuche über Kommandozeile (lies: Shell) + FHEM-Oberfläche ===

:* set <alexa> stop (FHEM-Oberfläche)
:* Auf der Kommandozeile <code>alexa-fhem -D -c /opt/fhem/alexa-fhem.cfg > debug.log</code> starten (dadurch wird die Datei debug.log erzeugt im aktuellen Verzeichnis)
:* Alexa-Befehl auslösen
:* alexa-fhem auf der Kommandozeile wieder stoppen (CTRL-C)
:* set <alexa> start (FHEM-Oberfläche)

Die Datei debug.log sollte Hinweise enthalten, wie das Problem zu lösen ist oder Dich zumindest in die richtige Richtung schieben.

Im Beispiel aus dem Forum fand sich in dem Logfile der Hinweis darauf, dass das Device mit falschen min/max-Werten unterwegs war.

=== Registrierungskey vergessen, Registrierung zurücksetzen ===

Auf der Kommandoshell:

<syntaxhighlight lang="bash" style="width:90%;">
pi@raspberrypi:~# sudo -u fhem ssh -p 58824 fhem-va.fhem.de status
Registered.
Registered on 2019-01-13T15:38:13Z.
</syntaxhighlight>

heisst, das der Vereinsserver eigentlich alles hat, was er will. Es wird kein neuer Schlüssel generiert.
Wenn Du die Situation zurücksetzen möchtest, wäre die hässliche Methode, Deinen SSH-Key zu löschen. Eleganter ist, die Registrierung auf Vereinsseite zu löschen:

<syntaxhighlight lang="bash" style="width:90%;">
pi@raspberrypi:~# sudo -u fhem ssh -p 58824 fhem-va.fhem.de unregister
Your registration has been removed
</syntaxhighlight>

löscht Deinen Schlüssel mitsamt allen dort gespeicherten Daten auf Vereinsseite. Bei Restart von alexa-fhem in FHEM-WEB wird jetzt ein neuer Registrierungskey angefordert.

== Sicherheitskonzept und Secrets ==

Um diesen Abschnitt zu verstehen, solltest Du den Abschnitt "Arbeitsweise" im Kopf haben. Einerseits ist Dir vermutlich einleuchtend, dass ein Server, der per SSH rückwärts nur ausgewählte Kommandos in den Tunnel, den Du aufgebaut hast, leitet, "irgendwie sicherer" ist. Andererseits möchte man nicht blind vertrauen.

=== SSH ===
==== SSH - macht das nichts Gefährliches? ====
SSH ist ein Veteran des Internet und entstand, um sich sicher (verschlüsselt) und schnell auf Servern einzuloggen. Schon früh wurde dabei der sogenannte "Reverse-Tunnel" implementiert: Also der vom Client (Deinem Rechner) geäußerte Wunsch: "Bitte leite mir Requests, die bei Dir, Server, auf Port xy eingehen, an meinen lokalen Port yz weiter.". Dieses Verfahren implementiert der Reverseproxy, wobei tatsächlich auf dem Server für Dich kein echter Port geöffnet wird.

Wie Dir ggf. sicher der Unix-Guru Deines Vertrauens bestätigen wird: Die Kombination
<syntaxhighlight lang="bash" style="width:50%;">
ssh -R 1234:localhost:<zufälliger port> zielserver
</syntaxhighlight>
erlaubt keine Ausführung von Shell-Kommandos auf Deinem Server, sondern einzig, dass vom SSH-Programm Verbindungen zu einem lokalen Port auf Deinem Server auf dem alexa-fhem lauscht aufgebaut werden. Du kannst also z.B. mit einem
<syntaxhighlight lang="bash" style="width:50%;">
sudo /usr/sbin/tcpdump -X -s 0 -i lo port <zufälliger port>
</syntaxhighlight>
vollständig überwachen (oder ggf. permanent aufzeichen), was auf Deinem Server von außen gesteuert passiert.

==== Wie wird bei SSH verschlüsselt? ====
Im Prinzip wie im Web auf SSL-Seiten, teils mit den gleichen Verschlüsselungsverfahren. Allerdings arbeitet SSH eher wie das im Web recht seltene Verfahren: Bei jeder Verbindung übermitteln sowohl Server wie auch Client den öffentlichen Teil ihres Schlüssels. Anders als im Web wird der Schlüssel aber nicht von einer öffentlichen Zertifizierungsstelle wie "LetsEncrypt" unterschrieben. Stattdessen entscheiden Server wie Client beim ersten Verbindungsaufbau typischerweise per manueller Frage: "Willst Du jetzt und künftig diesem Schlüssel vertrauen?" Bei der Installation wird diese Frage für Deine Seite bejaht, und fortan wird der öffentliche Schlüssel des FHEM-Servers auf Deinem Rechner gespeichert. Ab da bist Du z.B. davor sicher, dass jemand den DNS-Eintrag verbiegt oder sich in den Datenfluss Deines Providers einhängt: Ein geänderter Serverschlüssel würde bemerkt werden.
 
Soweit klar? Aus Deinem öffentlichen Schlüssel wiederum leitet der Server her: "Das ist definitiv wieder derjenige, der sich damals "registriert" hat". Und an dieser Stelle kann ich auch den ersten Teil des 3-teiligen Registrierungskeys erläutern: Die typischerweise 6-stellige Hex-Zahl am Anfang ist der Java-Hashcode Deines öffentlichen Schlüssel. Sie ist damit sozusagen Deine aus Deinem öffentlichen Schlüssel abgeleitete Benutzer-ID.

=== Die Rolle der Secrets ===
Wenn jetzt klar ist, dass die Verbindung zum Vereinsserver sicher und vertauschungsfrei funktioniert, bleiben noch 2 Probleme zu lösen:
1) Im Web bei der Skill-Aktivierung musst Du beweisen, dass Du der Mensch am Browser bist, dem der SSH-Tunnel von IP xy mit dem öffentlichen Schlüssel X gehört. Bei der automatischen Registrierung werden lokal auf Deinem Rechner zwei 64-Bit-Secrets generiert:
* Das Anmelde-Secret
* Das Bearer-Token
Beim Anmelden des SSH-Keys auf dem öffentlichen Server wird nun der Hashwert des ersten Secrets übertragen und dort in Verbindung mit Deinem öffentlichen Schlüssel gespeichert. Ein Hashwert bedeutet, dass (sofern das Verfahren, hier SHA256, funktioniert), niemand aus dem Hash das Secret zurückrechnen kann. Ein Datenbankklau auf dem Server gefährdet also nicht die Sicherheit Deines Passwortes.

Wenn Du nun beim Skill-Aktivieren den Registrierungskey eingibst, dann "sieht" der Server zum ersten Mal Dein ausgewürfeltes Secret, vergleicht es mit dem Hashwert und wird es anschließend wieder umgehend vergessen. Anhand des Hashwertes kann der Server aber entscheiden, dass Du der legitime Nutzer zum öffentlichen Schlüssel XY bist.

2) Das zweite Problem ist: Wie soll Amazon "beweisen", dass sie der legitime Aufrufer sind? Amazon erhält binnen wenigen Sekunden nach dem Klick auf "Activate Skill" den dritten Teil des Registrierungskeys als sogenanntes Bearer-Token. Zwar läuft er durch den Registrierungsserver, er wird dort, auf dem Registrierungs/Vereinsserver aber nicht gespeichert. Das Bearer-Token wird von Amazon bei allen Requests zu Deinem Server mitgesendet. Da es am Anfang zusätzlich Deine "User-ID" enthält, weiß der Vereinsserver, zu welchem SSH-Tunnel der Request zu senden ist. Aber lokal auf Deinem Rechner wird ausgewertet, ob das Token "stimmt".

== alexa-fhem Updaten ==
* alexa-fhem über FHEM anhalten:
:<syntaxhighlight lang="perl" style="width:50%;">set alexa stop</syntaxhighlight>

*Auf der Konsole wie anfangs bei der Installation:
:<syntaxhighlight lang="bash" style="width:50%;">sudo npm update -g alexa-fhem</syntaxhighlight>

:Manchmal hat npm Probleme mit einem Update. Dann einfach die aktuelle Version noch mal drüber Installieren:

:<syntaxhighlight lang="bash" style="width:50%;">sudo npm install -g alexa-fhem</syntaxhighlight>

*alexa-fhem über FHEM wieder starten:
:<syntaxhighlight lang="perl" style="width:50%;">set alexa start</syntaxhighlight>

==Weitergehende Informationen==
*[[Alexa_und_Mappings]]
*[[Alexa_Tipps_und_Kniffe]]
[[Kategorie:HOWTOS]]
[[Kategorie:Sprachsteuerung]]

Yowsup

2019-06-28T06:35:41Z

Hoppel118: WARNUNG ergänzt -> Blocken von Rufnummern bei yowsup Registrierungen

{{SEITENTITEL:yowsup}}
{{Infobox Modul
|ModPurpose=Schnittstelle, um WhatsApp-Nachrichten empfangen und senden zu können.
|ModType=d
|ModCmdRef=yowsup
|ModFTopic=27543
|ModForumArea=Unterstuetzende Dienste
|ModTechName=32_yowsup.pm
|ModOwner=André / justme1968 ({{Link2FU|430|Forum}} / [[Benutzer Diskussion:justme|Wiki]])
}}

Das Modul [[yowsup]] dient dazu, WhatsApp-Nachrichten zu empfangen und zu senden. Nachrichten können sein:
* '''Text''': senden und empfangen, z.b.: Infonachrichten senden, FHEM-Kommandos empfangen
* '''Bilder''': senden und empfangen, z.b.: Webcambilder nach Bewegungserkennung versenden
* '''Audio''': empfangen, z.b.: Sprachdurchsagen empfangen und über SONOS abspielen

== WARNUNG ==

Momentan wird beim Registrierungsprozess anscheinend erkannt, dass es sich um yowsup handelt. Dies führt dann nach Versand des des Registrierungscodes per SMS/Voice zur direkten Sperrung der Rufnummer. Bis auf weiteres ist es also nicht empfehlenswert, Registrierungen vorzunehmen. Der Status dazu kann auf Github verfolgt werden: https://github.com/tgalal/yowsup/issues/2829

Diese Warnung wird wieder entfernt, wenn das Problem gelöst ist.

== Voraussetzungen ==
* Die Funktionalität ist vermutlich auf Linux/Unix Systeme beschränkt.
* Nach der Erstinstallation/-einrichtung '''muss''' zwingend das ''cmd'' Attribut korrekt gesetzt werden.

== Installation ==
Die ursprüngliche Einrichtung wurde {{Link2Forum|Topic=27543|Message=204426|LinkText=hier beschrieben}}, jedoch sind noch einige wichtige Dinge zu setzen. Mit der Version 3.0.0 vom 24. April 2019 hat sich einiges in der Kommunikation mit WhatsApp geändert. Diese Änderungen führen dazu, dass alles komplett neu installiert und registriert werden muss.

=== Yowsup Installation ===
Bevor man loslegt sollte man wie immer sicherstellen, dass Debian auf dem aktuellen Stand ist: 
<code>sudo apt-get update</code> 
<code>sudo apt-get upgrade</code> 
<code>sudo apt-get dist-upgrade</code> 

Will man Bilder verarbeiten, so braucht man noch ein paar Pakete mehr:
* Paketinstallationen:
** Unter Debian Wheezy: <code>sudo apt-get install libtiff4-dev libjpeg8-dev zlib1g-dev libfreetype6-dev liblcms2-dev libwebp-dev tcl8.5-dev tk8.5-dev python-tk</code>
** Unter Debian Jessie: <code>sudo apt-get install libtiff5-dev libjpeg-dev zlib1g-dev libfreetype6-dev liblcms2-dev libwebp-dev tcl8.5-dev tk8.5-dev python-tk</code>
** Unter Debian Stretch: <code>sudo apt-get install libtiff5-dev libjpeg-dev zlib1g-dev libfreetype6-dev liblcms2-dev libwebp-dev tcl8.5-dev tk8.5-dev python-tk</code>

==== Python 2.7 ====
Los gehts mit den Paketen: 
<code>sudo apt-get install python-soappy python-dateutil python-pip python-dev build-essential libssl-dev libffi-dev libncurses5-dev</code> 

Nun erstmal pip updaten: 
<code>sudo pip install --upgrade pip</code> 

yowsup benötigt zwingend von six die Version 1.10 (unter /usr/local/lib/python2.7/dist-packages prüfen, ob eine andere Version von six installiert ist. Diese erst löschen): 
<code>sudo pip uninstall six</code> 
<code>sudo pip install six==1.10</code>

Und dann Axolotl, argparse, readline installieren (das dauert ne Weile): 
(eventuell wird auch noch appdirs benötigt) 
<code>sudo pip install argparse</code> 
<code>sudo pip install setuptools</code> 
<code>sudo pip install readline</code> 
<code>sudo pip install appdirs</code> 
<code>sudo pip install python-axolotl</code> 
<code>sudo pip install pillow</code> 

Zudem wird neben den Python Modulen noch eine Lib's von tgalal benötigt:
<pre>cd /opt/fhem/yowsup
sudo wget https://github.com/tgalal/python-axolotl/archive/master.zip
sudo unzip master.zip
cd python-axolotl-master
sudo python setup.py install
cd ..
rm master.zip</pre>

<pre>cd /opt/fhem/yowsup
sudo wget https://github.com/tgalal/dissononce/archive/master.zip
sudo unzip master.zip
cd dissononce-master
sudo python setup.py install
cd ..
rm master.zip</pre>

<pre>cd /opt/fhem/yowsup
sudo wget https://github.com/tgalal/consonance/archive/master.zip
sudo unzip master.zip
cd consonance-master
sudo python setup.py install
cd ..
rm master.zip</pre>

Desweiteren muss man nun yowsup installieren:
<pre>
cd /opt
sudo mkdir yowsup-config
sudo wget -N https://github.com/tgalal/yowsup/archive/master.zip
sudo unzip -o master.zip
cd yowsup-master
sudo python setup.py install
cd ..
rm master.zip</pre>

==== Python 3.5 ====
Bevor man loslegt sollte man wie immer sicherstellen, dass Debian auf dem aktuellen Stand ist: 
<code>sudo apt-get update</code> 
<code>sudo apt-get upgrade</code> 
<code>sudo apt-get dist-upgrade</code> 

Los gehts mit den Paketen: 
<code>sudo apt-get install python3-pip python3-dev python3-setuptools python-soappy python-dateutil build-essential libssl-dev libffi-dev libncurses5-dev</code> 

Nun erstmal pip updaten: 
<code>sudo pip3 install --upgrade pip</code> 

yowsup benötigt zwingend von six die Version 1.10 (unter /usr/local/lib/python3.5/dist-packages prüfen, ob eine andere Version von six installiert ist. Diese erst löschen): 
<code>sudo pip3 uninstall six</code> 
<code>sudo pip3 install six==1.10</code>

Und dann Axolotl, argparse, readline installieren (das dauert ne Weile): 
(eventuell wird auch noch appdirs benötigt) 
<code>sudo pip3 install argparse</code> 
<code>sudo pip3 install setuptools</code> 
<code>sudo pip3 install readline</code> 
<code>sudo pip3 install appdirs</code> 
<code>sudo pip3 install python-axolotl</code> 
<code>sudo pip3 install pillow</code> 

Zudem wird neben den Python Modulen noch Lib's von tgalal benötigt:
<pre>cd /opt/fhem/yowsup
sudo wget https://github.com/tgalal/python-axolotl/archive/master.zip
sudo unzip master.zip
cd python-axolotl-master
sudo python3 setup.py install
cd ..
rm master.zip</pre>

<pre>cd /opt/fhem/yowsup
sudo wget https://github.com/tgalal/dissononce/archive/master.zip
sudo unzip master.zip
cd dissononce-master
sudo python3 setup.py install
cd ..
rm master.zip</pre>

<pre>cd /opt/fhem/yowsup
sudo wget https://github.com/tgalal/consonance/archive/master.zip
sudo unzip master.zip
cd consonance-master
sudo python3 setup.py install
cd ..
rm master.zip</pre>

Desweiteren muss man nun yowsup installieren:
<pre>
cd /opt
sudo mkdir yowsup-config
sudo wget -N https://github.com/tgalal/yowsup/archive/master.zip
sudo unzip -o master.zip
cd yowsup-master
sudo python3 setup.py install
cd ..
rm master.zip
</pre>

==== Fhem vorbereiten ====
Vor den weiteren Schritten sollte geprüft werden, ob dem User fhem eine Loginshell zugewiesen ist:
:<code>getent passwd fhem</code>
Wird hier am Ende /bin/false ausgegeben, so muss dies angepasst werden:
:<code>sudo chsh -s /bin/bash fhem</code>

Mittels ''getent passwd fhem'' kann auch bereits das Home-Verzeichnis ausgelesen werden, dies steht in der ausgegebenen Doppelpunkt-separierten Liste an vorletzter Stelle.

Nun loggt man sich unter dem User ein, unter dem fhem läuft (in den folgenden Beispielen werden die vom fhem-Setup-Script generierten Defaults verwendet: User=fhem , home=/opt/fhem Gruppe=dialout) und liest dort die $HOME-Variable aus und prüft das Home-Verzeichnis:
<pre>sudo su - fhem
echo $HOME
cd $HOME
logout</pre>
Diesen Wert braucht man später - gut merken. Sollte hier ein Fehler auftreten (z.B. das home nicht vorhanden), so muss dies zuerst korrigiert werden.

Vor den weiteren Schritten sollte man nun erstmal die yowsup Verzeichnisse dem fhem-user zugängig machen:
<pre>sudo chown -R fhem:dialout /opt/yowsup-master /opt/yowsup-config</pre>

Für die folgenden Schritte würde ich auf den FHEM-Nutzer wechseln:
<pre>sudo su - fhem
cd /opt/yowsup-master</pre>

==== WhatsApp einrichten ====
Bitte daran denken...
<pre>sudo su - fhem
cd /opt/yowsup-master</pre>

Nun erfolgt die Anmeldung am WhatsApp-Server. Dies kann man nun via <code>voice</code> oder <code>sms</code> machen. Bei einem Handy bietet sich SMS an, bei Festnetzanschlüssen sollte voice gewählt werden, wenn man sich nicht sicher ist, dass der Anschluss die Funktion 'SMS im Festnetz' unterstützt. Dann wird der Bestätigungscode zwar auf Englisch vorgelesen, dafür ist die Zuverlässigkeit des Registrierungsvorganges zuverlässiger. Bei Festnetznummern sollte man unbedingt etwas zum Schreiben bereit halten! (49XXXXXXXX durch Eure Telefonnummer ersetzen.) 

'''Python 2.5'''
<pre>yowsup-cli registration --requestcode sms --config-phone 49XXXXXXXX --config-cc 49</pre>

'''Python 3.5'''
<pre>python3 yowsup-cli registration --requestcode sms --config-phone 49XXXXXXXX --config-cc 49</pre>

Die Rückmeldung ist nun entscheidend. Wenn man diese zurückbekommt:
<pre>de sms
status: fail
retry_after: 3600
reason: no_routes</pre>
Dann ist die Nummer so nicht kompatibel. Was man dann noch probieren kann, ist die registration via voice - meistens ist das aber vergebene Liebesmüh'.

Wenn man folgende Rückmeldung bekommt:
<pre>I 2019-04-24 15:05:22,368 yowsup.common.http.warequest - {"login":"49xxxxxxxxxx","status":"sent","length":6,"method":"sms","retry_after":65,"sms_wait":65,"voice_wait":65}

status: sent
voice_wait: 65
retry_after: 65
sms_wait: 65
length: 6
login: 49xxxxxxxxxx
method: sms</pre>

So ist alles gut gelaufen und man sollte kurz später eine SMS bekommen. Darin ist ein Text, der am Ende z.B. 123-456 lautet. Diesen fügt man ohne Bindestrich am Ende des folgenden Befehls ein (49XXXXXXXX durch Eure Telefonnummer ersetzen.): 

'''Python 2.5'''
<pre>python3 yowsup-cli registration --config-phone 49XXXXXXXX -R 123456</pre>

'''Python 3.5'''
<pre>python3 yowsup-cli registration --config-phone 49XXXXXXXX -R 123456</pre>

Dann kommt ein Text der etwa so aussehen sollte:
<pre>I 2019-04-24 15:15:09,118 yowsup.common.http.warequest - {"status":"ok","login":"49xxxxxxxxxx","type":"existing","edge_routing_info":"CAUIAg==","chat_dns_domain":"fb","security_code_set":false}

{
"__version__": 1,
"cc": "49",
"client_static_keypair": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"expid": "xxxxxxxxxxxxxxxxxxxxxxxx",
"fdid": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"mcc": "000",
"mnc": "000",
"phone": "49xxxxxxxxxx",
"sim_mcc": "000",
"sim_mnc": "000"
}</pre> 

Yowsup legt eine neue Konfigurationsdatei im unter $HOME/.config/49xxxxxxxxxx/. Diese wird automatisch herangezogen, wenn die entsprechende Telefonnummer mit --config-phone 49XXXXXXXX angegeben wird.

Nun mal ein schneller Test an die eigene Nummer (im Beispiel 491751234567):
<pre>python[3] yowsup-cli demos --config-phone 49XXXXXXXX -s 491751234567 "Das ist ein Test"</pre>

Hier seht ihr nun einen Status (die Anzahl prekeys wird hoch gezählt):
<pre>I 2019-04-24 15:33:58,647 yowsup.layers.network.layer - Connecting to e7.whatsapp.net:443
I 2019-04-24 15:33:59,230 yowsup.axolotl.manager - Generating 812 prekeys
I 2019-04-24 15:34:15,590 yowsup.axolotl.manager - Storing 812 prekeys
I 2019-04-24 15:35:03,100 yowsup.axolotl.manager - Loaded 812 unsent prekeys</pre>

Das sollte dir eine Nachricht einbringen. Wenn du darauf antwortest, kommt diese allerdings noch nicht an - der Client hat sich nach dem Befehl sofort beendet. Damit dieser dauerhaft im Hintergrund läuft legen wir nun in FHEM ein Gerät an, welches dies steuert.

=== FHEM Define ===
* FHEM Device anlegen: <code> define <name> yowsup</code>, also z.B. <code>define WhatsApp yowsup</code>
* Nun muss man den Pfad zu yowsup anpassen:
* Python 2.7
* <code>attr WhatsApp cmd /opt/yowsup-master/yowsup-cli demos --config-phone 49XXXXXXXX --yowsup</code>
* Python 3.5
* <code>attr WhatsApp cmd python3 /opt/yowsup-master/yowsup-cli demos --config-phone 49XXXXXXXX --yowsup</code>
* Und das Home directory mit dem Pfad zum Home des fhem users: <code>attr WhatsApp home PWD</code>
* Wenn alles gut geht, gibt es danach im Device ein internal PID und das Reading ''state''
* Im Whatsapp Client auf dem Handy sollte man sehen, dass FHEM online ist
* Zum Senden aus FHEM kann man das Kommando <code>set WhatsApp send <nummer> <text></code> verwenden

== Attribute ==
Bitte sieh immer in der {{Link2CmdRef|Anker=yowsup}} nach - diese hier könnten veraltet sein.

* <code>cmd</code> komplettes Kommando, um den yowsup Client zu starten. z.B.: <code>attr WhatsApp cmd /opt/yowsup-master/yowsup-cli demos -c /opt/yowsup-config/yowsup.config --yowsup</code>. Wenn die ab yowsup-Version 2.4 standartmässig aktivierte Verschlüsselung abgeschaltet werden muss weil die entsprechenden Libs nicht installiert sind: <code>attr WhatsApp cmd /opt/local/bin/yowsup-cli demos -c /root/yowsup-config --yowsup -M</code>.
* <code>acceptFrom</code> kommagetrennte Liste von Kontakten (Nummern), von denen Nachrichten akzeptiert werden. Ist das Attribut nicht gesetzt, so werden die Nachrichten von jedem akzeptiert.
* <code>commandPrefix</code> nicht gesetzt -> es werden keine Befehle akzeptiert. 0 -> es werden keine Befehle akzeptiert. 1 -> erlaubt Befehle, jede Nachricht wird als FHEM-Befehl interpretiert. alles andere -> Wenn die Nachricht mit diesem Prefix startet, wird alles weitere als Befehle interpretiert.
{{Randnotiz|RNTyp=Warn|RNText='''allowedCommands''' should work as intended, but no guarantee can be given, that there is no way to circumvent it.}}
* <code>allowedCommands</code> Eine Komma-getrennte Liste von zulässigen Befehlen für diesen Kontakt. Wenn die Liste leer ist (z.B. nur ein Komma), dann werden keine Befehle akzeptiert.
* <code>home</code> Setzt das Home-directory welches für yowsup verwendet werden soll.

== Befehle ==
* image -> Über diesen Befehl können Bilder gesendet werden.

* raw -> Status ändern :
<code>set WhatsApp raw /profile setStatus 'mein Status' <--- die ' ' müssen bleiben</code>

Name der angezeigt werden soll, wenn eine Nachricht z.B. ans iPhone geschickt wird:

<code>set WhatsApp raw /presence name <DeinNick></code>

Anzeige online :

<code>set WhatsApp raw /presence available</code>

Profilbild ändern :

<code>set WhatsApp raw /profile setPicture '/opt/fhem/fhem_logo.png'</code>
<--- der gesamte Pfad zum Bild muss angegeben werden und Rechte müssen ggfs. bei fhem liegen

Falls es nicht funktioniert disconnect/connect probieren.

== Update ==
Da am WhatsApp ständig geschraubt wird, bedarf es eines Updates des Yowsup, wenn keine Funktion mehr gegeben ist:
<pre>cd /opt
sudo rm master.zip
sudo mv yowsup-master yowsup-master-alt
sudo wget -N https://github.com/tgalal/yowsup/archive/master.zip
#alternativ sudo wget https://github.com/jlguardi/yowsup/archive/master.zip (Stand März 2016 aktueller)
sudo unzip master.zip
sudo chown fhem yowsup-master -R
sudo chgrp dialout yowsup-master -R</pre>Danach muss FHEM mittels 'shutdown restart' neu gestartet werden.

== Anwendungsbeispiele ==
=== Beispielnachricht ===
Beim Empfang einer Nachricht wird automatisch ein FHEM Device für diesen Kontakt angelegt. In diesem Device gibt es das Reading '''message''' für die empfangene Nachricht und ab der ersten Nachricht auch das Reading '''chatstate''', in dem zu sehen ist, ob gerade getippt wird.
Nachdem ein Device für einen Kontakt angelegt ist, lässt sich auch direkt dieses Device zum Senden verwenden:
:<code>set <device> send <text></code>,
d.h., man spart sich die Angabe der Nummer.

=== Gruppen ===
Gruppen müssen über die App (Smartphone / Tablet) angelegt werden. Nach dem Empfang einer entsprechenden Nachricht werden Gruppen genauso behandelt, wie einfache Teilnehmer.

=== Broadcast ===
Beim Senden über das Masterdevice lassen sich mehrere Empfänger mit Komma (und ohne Leerzeichen) getrennt angeben. Die entsprechenden Nachrichten werden dann per Broadcast an alle Teilnehmer gesendet. Die Broadcastempfänger müssen zuvor mindestens eine normale Nachricht erhalten haben.

=== Komponenten steuern ===
Um ein [[notify]] anlegen zu können, müssen wir zuerst eine Nachricht vom Handy an FHEM senden. Dadurch wird ein Device mit der Nummer als Namen angelegt. Danach sollte das Device umbenannt werden, da einige Befehle einen Namen ausschließlich aus Ziffern nicht akzeptieren. Dies geschieht wie folgt:

:<code>rename 49123456789 HandySeppel</code>

Danach kann ein ''notify'' angelegt werden:

<syntaxhighlight lang="perl">
define notifySeppelLicht notify HandySeppel:message.* {
if( $EVENT eq 'message: Licht an' ) {
fhem "set HandySeppel send Licht ist nun an...";
fhem "set FS20_a5d800 dim100%";

} elsif( $EVENT eq 'message: Licht aus' ) {
fhem "set HandySeppel send Licht ist nun aus...";
fhem "set FS20_a5d800 dim0%";

} else {
fhem "set HandySeppel send Wie bitte?"

}
}</syntaxhighlight>

Natürlich ist dieses ''notify'' noch auf die eigenen Wünsche anzupassen.

=== Autoresponder ===
Nachdem man nun seine Festnetznummer bei WhatsApp registriert hat, wird auch diese natürlich als erreichbares Ziel auf jedem Gerät angezeigt, auf dem sie gespeichert ist. So kann es passieren, dass WhatsApp-Nachrichten nicht gelesen werden. Hier schafft ein Autoresponder Abhilfe:
:<code>define not_WhatsApp_Autoresponder notify 491.*:message.* set $NAME send Hallo, Du hast eine Nachricht an unsere Festnetznummer geschickt. Da ist aber nur ein kleiner Computer auf Empfang, der Dir nur diese Antwort schicken kann. Bitte benutze unsere Mobilnummern, wenn Du willst, dass Deine Nachricht auch gelesen wird!</code>
Das Problem hierbei ist, dass noch nicht bekannt ist, wer etwas sendet und so der Kontakt u.U. noch nicht angelegt ist. Daher wird im obigen Beispiel auf 491*:message.* reagiert. So bekommen nur deutsche Mobilrufnummern die Antwort. Um das noch globaler zu fassen, könnte z.B. auf \d*.*:message.* reagiert werden, was aber voraussetzt, dass keine weiteren Modulnamen (die das Reading message haben) mit einer Ziffer beginnen.
Alle Kontakte, welche nicht den Autoresponder erhalten sollen, müssen wie oben beschrieben entspr. umbenannt werden:
:<code>rename 49123456789 HandySeppel</code>

== Probleme und Lösungen ==
=== Immer wieder offline ===
Das WhatsApp Device geht immer wieder offline und im Log wird folgendes protokolliert:

... yowsup.layers.axolotl.layer_receive:invalidmessage or keyid for ...

Lösung:

Verzeichnis .yowsup in /root löschen.
Das Verzeichnis entsteht durch das Testen auf der Konsole und verträgt sich dann nicht mit dem im Attribut home hinterlegten Verzeichnis.

=== UTF-8 Fehler ===

Lösung: https://forum.fhem.de/index.php/topic,27543.msg773746.html#msg773746

== Links ==
* {{Link2Forum|Topic=27543|LinkText=Forenthread}}, in dem die Whatsapp Anwendung beschrieben wird
* {{Link2Forum|Topic=27543|Message=299292|LinkText=Foreneintrag}}, ab dem das yowsup Modul beschrieben wird
* Die Python Whatsapp Library auf [https://github.com/tgalal/yowsup github]
* Imagehandling Bugfix [https://github.com/tgalal/yowsup/issues/901 github]

[[Kategorie:WhatsApp]]

Homebridge User Configs

2019-06-25T20:07:04Z

Hoppel118: Kopierfehler Homematic Thermostat behoben

Dieser Eintrag dient zur Sammlung funktionsfähiger Homebridge Configs.

Bitte immer die FHEM Version und Homebridge Version angegeben.

Sehr gute Hinweise gibt es hier: http://www.meintechblog.de/2015/10/mit-siri-und-fhem-das-gesamte-smart-home-per-stimme-steuern/
== Mögliche Mappings ==
Die Möglichen Mappings können hier nachgelesen werden https://github.com/KhaosT/HAP-NodeJS/blob/master/lib/gen/HomeKitTypes.js

Hier ein Beispiel:
Characteristic.Brightness = function() {
Characteristic.call(this, 'Brightness', '00000008-0000-1000-8000-0026BB765291');
this.setProps({
format: Characteristic.Formats.INT,
unit: Characteristic.Units.PERCENTAGE,
maxValue: 100,
minValue: 0,
minStep: 1,
perms: [Characteristic.Perms.READ, Characteristic.Perms.WRITE, Characteristic.Perms.NOTIFY]
});
this.value = this.getDefaultValue();
};

Das Mapping in diesem Fall, hat den Titel Brightness.

Die Werte können in 1er Schritten zwischen 0 und 100 liegen (max und min Value)
== Erstellung eines HomebridgeMappings am Beispiel "Feuchtesensor" ==
Zum Einstieg etwas leicht nachvollziehbares.

Feuchtesensoren haben in der Regel ein "humidity" Reading, im Falle des Opus XT300 Bodenfeuchtesensors auch Temperatur und Batterie Level. Homekit unterstützt einen "HumiditySensor" Service. Dieser ist in homebridge-fhem nicht standardmäßig vorhanden (kann also nicht aus dem dropdown ausgewählt werden, sondern muss über das Befehlsfeld zugewiesen werden):

<code>attr meinSensor genericDeviceType HumiditySensor</code>

Im nächsten Schritt werden die Readings gemappt:

<code>attr meinSensor homebridgeMapping clear CurrentRelativeHumidity=humidity StatusLowBattery=battery,values=ok:BATTERY_LEVEL_NORMAL;;/^.*/:BATTERY_LEVEL_LOW CurrentTemperature=temperature</code>

<code>clear</code>löscht default mappings - das wird in der Regel nicht notwendig sein, schadet aber nicht

<code>CurrentRelativeHumidity</code> ist die relevante Homekit Characteristic - wird mit dem entsprechenden Reading des Sensors gemappt.

<code>StatusLowBattery</code> erwartet entweder BATTERY_LEVEL_NORMAL oder _LOW. Mein Sensor liefert ok zurück, wenn alles gut ist, also wird "ok" auf _NORMAL gemappt, alles andere auf _LOW.

Der Opus XT300 Bodenfeuchtesensors liefert auch noch die Temperatur - der HumiditySensor Service sieht das eigentlich nicht vor, daher wird die Temperatur auch nicht in der Apple "Home" App angezeigt. Bei Eve wird die Temperatur hingegen berücksichtigt.

== BRAVIA Fernseher ==
Ein Beispiel homebridgeMapping für Sony Bravia Fernseher (iOS 12.2 beta!) und genericDeviceType Television:
<pre>
clear
ConfiguredName:model
Active:state,values=off:INACTIVE;on:ACTIVE,cmds=ACTIVE:on;INACTIVE:off
RemoteKey:key,cmds=REWIND:remoteControl+Rewind;FAST_FORWARD:remoteControl+FastForward;NEXT_TRACK:remoteControl+NEXT_TRACK;PREVIOUS_TRACK:remoteControl+PREVIOUS_TRACK;ARROW_UP:remoteControl+Up;ARROW_DOWN:remoteControl+Down;ARROW_LEFT:remoteControl+Left;ARROW_RIGHT:remoteControl+Right;SELECT:remoteControl+Ok;BACK:remoteControl+RETURN;EXIT:remoteControl+Exit;PLAY_PAUSE:remoteControl+Play;INFORMATION:remoteControl+Info
SleepDiscoveryMode:default=ALWAYS_DISCOVERABLE
ClosedCaptions:default=0
DisplayOrder:default=Test1
CurrentMediaState:default=0:currentTitle
TargetMediaState:default=0,cmds=PLAY:remoteControl+play;PAUSE:remoteControl+pause;STOP:remoteControl+stop;
PictureMode:default=1
PowerModeSelection:default=1,cmds=0:remoteControl+options
ActiveIdentifier:input,default=0,values=/tv.dvbt|TV...DVB-T/:1;/HDMI.3/:2,cmds=1:input+TV+/+DVB-T;2:input+HDMI+3/ARC;3:application+Plex
TelevisionSpeaker#Mute=mute
Active:default=ACTIVE
VolumeSelector:volume,cmds=INCREMENT:VolumeUp;DECREMENT:VolumeDown
VolumeControlType:default=RELATIVE_WITH_CURRENT
linkedTo=Television
InputSource(1)#Identifier:default=1
ConfiguredName:default=TV
IsConfigured:default=CONFIGURED
InputSourceType:default=TUNER
CurrentVisibilityState:default=SHOWN
linkedTo=Television
InputSource(2)#Identifier:default=2
ConfiguredName:default=APPLE+TV
IsConfigured:default=CONFIGURED
InputSourceType:default=HDMI
CurrentVisibilityState:default=SHOWN
linkedTo=Television
InputSource(3)#Identifier:default=3
ConfiguredName:default=PLEX
IsConfigured:default=CONFIGURED
InputSourceType:default=APPLICATION
CurrentVisibilityState:default=SHOWN
linkedTo=Television
</pre>

damit lässt sich der Fernseher über Siri/Homekit ein- und ausschalten sowie über das appleTV Control-Center Widget steuern.

== EnOcean STM 250 Tür-/Fensterkontakt ==
Der STM 250 liefert als Status in FHEM <code>open</code>, wenn das Fenster offen und damit der Kontakt "offen" ist. Analog liefert er <code>closed</code> wenn das Fenster geschlossen und damit auch der Kontakt geschlossen ist. Diese Statusangaben sind sehr intuitiv zu verstehen und zu interpretieren.

Die characteristic <code>ContactSensorState</code> von HomeKit liefert entweder den Wert <code>CONTACT_DETECTED=0</code> oder <code>CONTACT_NOT_DETECTED=1</code> zurück. Wobei <code>CONTACT_DETECTED</code> bedeutet, dass der Kontakt geschlossen ist. Je nach Darstellung in der HomeKit-fähigen App muss dieses Verhalten bei der Interpretation berücksichtigt werden. Die App Eve von Elgato zum Beispiel liefert für Kontaktsensoren "JA" oder "NEIN" mit der Bedeutung <code>CONTACT_DETECTED=0=JA</code> bzw. <code>CONTACT_NOT_DETECTED=1=NEIN</code> zurück.

Noch ein wichtiger Punkt: Um einen Sensorkontakt sinnvoll einzurichten sollte als zusätzlicher Wert für das Attribut <code>genericdeviceType</code> der Wert <code>ContactSensor</code> hinzugefügt werden. Wie das geht ist im Eintrag [[Homebridge_einrichten#FHEM_konfigurieren | Homebridge einrichten]] ausführlicher beschrieben.

Folgende Attribute dann hinzufügen:
attr STM250 genericDeviceType ContactSensor
attr STM250 homebridgeMapping ContactSensorState=state,values=closed:CONTACT_DETECTED;open:CONTACT_NOT_DETECTED

Getestet mit
FHEM 5.7 Rev. 9893
Homebridge 0.2.16
homebridge-fhem Vorschauversion aus {{Link2Forum|Topic=48558|Message=402024|LinkText=homebridge/homekit}}

== Modul RESIDENTS für Anwesenheitserkennung und Steuerung der Anwesenheit benutzen ==
[[Datei:Homebridge_bewohner_zu_szene.jpeg|mini|Schaltzustand eines Bewohners zu einer Szene hinzufügen]]
Aus den einzelnen Komponenten des Moduls RESIDENTS, homebridge sowie der characteristic <code>On</code> und der Szenensteuerung lässt sich eine gleichzeitige Steuerung der Anwesenheit und Anwesenheitserkennung basteln.

Dazu müssen folgende Schritte unternommen werden:
* einem Bewohner aus dem Modul ROOMMATE die Steuerung über homebridgeMapping hinzufügen
* Szene für "Ich bin zu Hause" und "Ich gehe jetzt" in einer HomeKit-fähigen App wie z.B. Eve einrichten

Man kann einen beliebigen Bewohner aus dem Modul ROOMMATE nehmen und ihn über die characteristic <code>On</code> in Form eines Schalters sozusagen schaltbar machen. Nur wird das Ein- und Ausschalten des Bewohners über HomeKit in FHEM auf den Status home bzw. absent gemappt. Seit dem 06.02.2016 werden RESIDENTS automatisch als Occupancy Sensor für HomeKit annonciert. Nun noch die Attribute des ROOMMATE wie folgt setzen:
attr <ROOMMATE> genericDeviceType switch
attr <ROOMMATE> homebridgeMapping On=state,valueOn=/home|awoken|asleep|gotosleep/,valueOff=/gone|absent/,cmdOn=home,cmdOff=absent

Natürlich muss der Bewohner noch dem Filter von homebridge hinzugefügt und homebridge neu gestartet werden.

Anschließend geht es in der HomeKit-fähigen App Deiner Wahl weiter. In Eve von Elgato ist von vornherein zum Beispiel vorgesehen, dass man zwei Szenen "Ich bin zuhause" und "Ich verlasse das Haus" hat. Zu diesen Szenen wird eine Aktion hinzugefügt indem der Bewohner, den das ROOMMATE-Modul meldet zur Szene hinzugefügt wird und beim Nachhausekommen "eingeschaltet" wird. Genauso wird mit der Szene "Ich verlasse das Haus" verfahren: Bewohner zur Szene hinzufügen und den Schaltvorgang auf "ausschalten" setzen.

Mit den Sprachbefehlen "Ich bin zuhause" oder "Ich verlasse das Haus" wird die entsprechende Szene eingeschaltet, homebridge schaltet über das <code>homebridgeMapping</code> Attribut dann den Bewohner auf "home" oder "absent".

Getestet mit
FHEM 5.7 Rev. 9893
Homebridge 0.2.16
homebridge-fhem Vorschauversion aus {{Link2Forum|Topic=48558|Message=402024|LinkText=homebridge/homekit}}

Eine noch etwas bessere Schaltmöglichkeit bietet '''genericDeviceType security'''.
Das Mapping für ROOMMATE sieht wie folgt aus:
attr TYPE=ROOMMATE genericDeviceType security
attr TYPE=ROOMMATE homebridgeMapping SecuritySystemCurrentState=state,values=/home|awoken/:0;;absent:1;;/asleep|gotosleep/:2;;gone:3 SecuritySystemTargetState=SecuritySystemCurrentState,cmds=0:state+home;;1:state+absent;;2:state+gotosleep;;3:state+gone,delay=1
für GUEST:
attr TYPE=GUEST genericDeviceType security
attr TYPE=GUEST homebridgeMapping SecuritySystemCurrentState=state,values=/home|awoken/:0;;absent:1;;/asleep|gotosleep/:2;;none:3 SecuritySystemTargetState=SecuritySystemCurrentState,cmds=0:state+home;;1:state+absent;;2:state+gotosleep;;3:state+none,delay=1

== Homematic Luftfeuchtigkeits- und Tmeperatursensoren ==

Mit folgenden Geräten wurde folgendes Mapping erstellt und somit erfolgreich getestet:

- HM-WDS10-TH-O
- HM-WDS40-TH-I
- HM-WDS40-TH-I-2

Achtung: Hier wird genericDeviceType "TemperatureSensor" verwendet, um eine history in EVE zu erhalten. Mit einem "HumiditySensor" funktionierte dies bei den Tests (Februar 2019) nicht.

attr <THSensor> genericDeviceType TemperatureSensor

attr <THSensor> CurrentRelativeHumidity=humidity
CurrentTemperature=temperature
StatusLowBattery=battery,values=ok:BATTERY_LEVEL_NORMAL;/^.*/:BATTERY_LEVEL_LOW
history:size=1024

== Homematic SmokeDetector HM-SEC-SD und HM-SEC-SD2 ==
[[Datei:Homebridge-Homematic-Smokedetector-Gen1.jpg|mini|Homebridge-Homematic-Smokedetector-Gen1 in EVE]]
Es sind keine Homebridge Mappings für die Rauch Meldung erforderlich.

Allerdings ist ein Mapping für den Batterie Zustand nötig, siehe Unten.

attr <SmokeDetector> genericDeviceType SmokeSensor
attr <SmokeDetector> subType smokeDetector

attr <SmokeDetector> homebridgeMapping StatusLowBattery=battery,values=ok:BATTERY_LEVEL_NORMAL;;/^.*/:BATTERY_LEVEL_LOW

== Homematic Heizkörperthermostat HM-CC-RT-DN ==
[[Datei:HM-CC-RT-DN-Eve.PNG|mini|Darstellung des HM-CC-RT-DN in der iOS App Eve]]
attr <HMCCRTDN_Channel2_Clima> homebridgeMapping TargetTemperature=desired-temp::desired-temp,minValue=5,maxValue=35,minStep=0.5,nocache=1
CurrentTemperature=BU_Heizung_01_Clima:measured-temp,nocache=1
StatusLowBattery=BU_Heizung_01:battery,values=ok:BATTERY_LEVEL_NORMAL;;/^.*/:BATTERY_LEVEL_LOW
TargetHeatingCoolingState=heatingState,values=OFF:0;;HEAT:1;;COOL:2;;AUTO:3,cmds=OFF:controlManu+off;;HEAT:controlMode+boost;;AUTO:controlMode+auto;;COOL:controlManu+17.0
CurrentHeatingCoolingState=heatingState,values=OFF:0;;HEAT:1;;COOL:2;;AUTO:0,valud=OFF
attr <HMCCRTDN_Channel2_Clima> siriName Robby
Dieses Mapping bezieht sich auf ein vorhandenes ''userReading'' mit dem Namen <code>heatingState</code>, womit Homekit die einzelnen Status nachher unterscheidet.
attr <HM-CC-RT-DN_Clima> userReadings heatingState {(ReadingsVal($NAME,"ValvePosition",0) > 0 || ReadingsVal($NAME,"desired-temp","-") eq "on") ? "HEAT" : ReadingsVal($NAME,"desired-temp","-") eq "off" ? "OFF" : ReadingsVal($NAME,"controlMode","auto") eq "auto" ? "AUTO" : (ReadingsVal($NAME,"measured-temp",20) > ReadingsVal($NAME,"desired-temp",20)) ? "COOL" : "AUTO"}
Global auf alle in FHEM angelegten HM-CC-RT-DN, lässt sich mit folgendem Befehl das ''userReading'' anlegen.
Siehe [https://forum.fhem.de/index.php/topic,59211.msg505986.html#msg505986 Forumsthread].

attr TYPE=CUL_HM:FILTER=model=HM-CC-RT-DN:FILTER=chanNo=04 userReadings heatingState {(ReadingsVal($NAME,"ValvePosition",0) > 0 || ReadingsVal($NAME,"desired-temp","-") eq "on") ? "HEAT" : ReadingsVal($NAME,"desired-temp","-") eq "off" ? "OFF" : ReadingsVal($NAME,"controlMode","auto") eq "auto" ? "AUTO" : (ReadingsVal($NAME,"measured-temp",20) > ReadingsVal($NAME,"desired-temp",20)) ? "COOL" : "AUTO"}

== Homematic Wetterstation OC3 HM-WDS100-C6-O-2 ==
[[Datei: homebridge-wetter.jpg|mini|Wetterstation in EVE]]
Mit der EVE und den hier: [https://github.com/naofireblade/homebridge-weather-plus/blob/master/util/characteristics.js] beschriebenen Characteristics lässt sich eine lokale Homematic OC3 Wetterstation aus FHEM einbinden:
<pre>
clear
CurrentTemperature:temperature
CurrentRelativeHumidity:humidity
49C8AE5A-A3A5-41AB-BF1F-12D5654F9F41:windSpeed,name=WINDGESCHWINDIGKEIT,format=FLOAT,unit=kmh,maxValue=250,minValue=0,minStep=1
46f1284c-1912-421b-82f5-eb75008b167e:windDirection,name=WINDRICHTUNG,format=UINT8,unit=ARC_DEGREE,maxValue=360,minValue=0,minStep=1
StatusLowBattery:battery,values=ok:BATTERY_LEVEL_NORMAL;/^.*/:BATTERY_LEVEL_LOW
ccc04890-565b-4376-b39a-3113341d9e0f:RegenmengeLast24Hours:state,name=REGEN_24h,format=FLOAT,unit=mm,maxValue=100,minValue=0,minStep=1
10c88f40-7ec4-478c-8d5a-bd0c3cce14b7:RegenmengeLast1Hours:state,name=REGEN_1h,format=FLOAT,unit=mm,maxValue=100,minValue=0,minStep=1
0000006B-0000-1000-8000-0026BB765291:brightness,name=BRIGHTNESS,format=FLOAT,unit=LUX,maxValue=10000,minValue=0,minStep=.0001
cd65a9ab-85ad-494a-b2bd-2f380084134c:isRaining,name=BEDINGUNGKATEGORIE,values=0:0;1:2,format=UINT8,maxValue=3,minValue=0,minStep=1
cd65a9ab-85ad-494a-b2bd-2f380084134d:isRaining,name=BEDINGUNG,format=STRING,values=0:-;/.*/:Regen
</pre>

== Roomba über THINKINGCLEANER Modul ==
attr <THINKINGCLEANER> genericDeviceType switch
attr <THINKINGCLEANER> homebridgeMapping clear On=state,valueOn=/^(on|dock)/,cmdOn=on,cmdOff=off,nocache=1 ChargingState=deviceStatus,values=/(_recon|_full|_trickle)$/:CHARGING;/^.*/:NOT_CHARGING
attr <THINKINGCLEANER> siriName Robby

Getestet mit
FHEM 5.7 Rev. 12680
homebridge 0.4.11
homebridge-fhem 0.2.66

== Vallox Belüftungsanlage ==
Die Steuerung der Lüftungsgeschwindigkeit ist nur in Prozent möglich. Die Umrechnung erfolgt im [[Vallox]] Modul.
Hierzu wurde das Reading ''FanSpeedPct'' hinzugefügt.

attr <Vallox> genericDeviceType Fan
attr <Vallox> homebridgeMapping clear
model=Vallox
On=PowerState,valueOn=1,readOnly=1
RotationSpeed=FanSpeedPct,minValue=1,maxValue=100,cmd=FanSpeedPct,delay=1

== Xiaomi Vacuum Cleaner 1. Generation ==
[[Datei:XIAOMI_VACUUM_CLEANER-Gen1.jpg|mini|XIAOMI VACUUM 1. GEN in EVE]]
Voraussetzung zur Verwendung der Mappings, ist ein eingebundener Staubsauger mit dem Modul 72_XiaomiDevice.

Siehe [https://forum.fhem.de/index.php/topic,73052.0.html Forumsthread]
Das Modul muss manuell installiert werden.

attr <XIAOMI> genericDeviceType switch
attr <XIAOMI> homebridgeMapping On=state,valueOn=Cleaning,cmdOn=start,cmdOff=charge
RotationSpeed=fan_power,minValue=0,maxValue=90,cmd=fan_power,delay=1
BatteryLevel=batteryLevel,maxValue=100,minValue=0,minStep=1
StatusLowBattery=battery,values=ok:BATTERY_LEVEL_NORMAL;;low:BATTERY_LEVEL_LOW
ChargingState=state,values=Docked:NOT_CHARGING;;Charging:CHARGING;;/.*/:NOT_CHARGEABLE
OccupancyDetected=state,values=/Docked|Charging/:OCCUPANCY_DETECTED;;/.*/:OCCUPANCY_NOT_DETECTED
FilterLifeLevel=consumables_filter,minValue=0,maxValue=100
FilterChangeIndication=consumables_filter,values=0:CHANGE_FILTER

== Roborock S50 (2. Generation des Xiaomi Vacuum Cleaners) ==
[[Datei:Roborock S50.png|mini]]
Voraussetzung zur Verwendung der Mappings, ist ein eingebundener Staubsauger mit dem Modul 72_XiaomiDevice.

Siehe [https://forum.fhem.de/index.php/topic,73052.0.html Forumsthread]
Das Modul muss manuell installiert werden.

Das folgende Mapping für den Roborook S50 beinhaltet neben den Characteristics der 1. Genration des Xiaomi Vacuum Cleaners weitere Custom Mappings. Diese werden auch auf dem Bild dargestellt. Falls das einem zu viele Informationen sind, können diese beim Einfügen einfach weggelassen oder in EVE ausgeblendet werden.

attr <XIAOMI> genericDeviceType switch
attr <XIAOMI> homebridgeMapping On=state,valueOn=Cleaning,cmdOn=start,cmdOff=charge
RotationSpeed=fan_power,minValue=0,maxValue=90,cmd=fan_power,delay=1
BatteryLevel=batteryPercent,maxValue=100,minValue=0,minStep=1
StatusLowBattery=batteryState,values=ok:BATTERY_LEVEL_NORMAL;;low:BATTERY_LEVEL_LOW
ChargingState=state,values=Docked:NOT_CHARGING;;Charging:CHARGING;;/.*/:NOT_CHARGEABLE
OccupancyDetected=state,values=/Docked|Charging/:OCCUPANCY_DETECTED;;/.*/:OCCUPANCY_NOT_DETECTED
2af6d0d0-3691-4f0d-9c9c-c1098295b1cb=consumables_sensors,name=Reinigung+Sensoren,minValue=0,maxValue=100,format=FLOAT,minStep=1,unit=%
fd11b965-052e-430f-b08f-206287d8bc00=consumables_filter,name=Austausch+Filter,minValue=0,maxValue=100,format=FLOAT,minStep=1,unit=%
fe7a8dac-dff3-4a07-8a5e-0d6abbf0df0c=consumables_main_brush,name=Austausch+Hauptbürste,minValue=0,maxValue=100,format=FLOAT,minStep=1,unit=%
4f9b2a22-b764-4fc1-8cd2-99383924394c=consumables_side_brush,name=Austausch+Seitenbürste,minValue=0,maxValue=100,format=FLOAT,minStep=1,unit=%
FilterLifeLevel=consumables_filter,minValue=0,maxValue=100
FilterChangeIndication=consumables_filter,values=0:CHANGE_FILTER
4896763a-26f7-400b-9734-2ce6564ceba2=total_clean_time,name=Lebenszeitersparnis,format=FLOAT,minStep=1,unit=h
82af5fd7-50a3-4ab3-81d3-1f7903de612a=total_clean_area,name=Gereinigte+Fläche,format=FLOAT,minStep=1,unit=m²
00d2ef14-b429-4569-8af3-c342d41cf383=total_cleans,name=Reinigungsvorgänge,format=FLOAT,minStep=1
e8d1027e-b068-40d5-9efd-f161b1b52774=device_firmware,name=Firmware,format=STRING

== Xiaomi Fan (ältere Generationen mit Luftfeuchtigkeits- und Temperatursensor und Battery-Readings) ==
[[Datei:Xiaomi DC Pedestal Fan.png|mini]]
Voraussetzung zur Verwendung der Mappings, ist ein eingebundener Ventilator mit dem Modul 72_XiaomiDevice.
Siehe [https://forum.fhem.de/index.php/topic,73052.0.html Forumsthread]
Das Modul muss manuell installiert werden.

Die ältere Generation enthält Sensoren und somit Readings für Luftfeuchtigkeit, Temperatur und auch Batteriestatus. Diese fehlen bei den neueren Generation dieses Ventilators, siehe Bilder. Da anscheinend jedes Jahr neue Generationen dieses Ventilators herausgekommen sind, ist nicht klar bis zu welcher Generation diese Sensoren enthalten waren.

Mit folgenden Geräten wurde folgendes Mapping erstellt und somit erfolgreich getestet:

- Xiaomi DC Pedestal Fan (FHEM model fehlt, Default Hostname am Router: zhimi-fan-v3)
- Liste bitte ergänzen!

Um möglichst viele Funktionen bereitzustellen, wurden auch Characteristics von anderen DeviceTypes verwendet. Erklärung zu den Characteristics:

- Die Kindersicherung (LockPhysicalControls) ist in Eve über das kleine Einstellungssymbol zu finden.
- Mit AudioFeedback/Audio-Bestätigung werden die Töne des Lüfters ein bzw. ausgeschaltet.
- Mit NightVision/Nachtsicht werden die LEDs ein (bright) bzw. ausgeschaltet (off).
- Mit Mute/Audio wird der Windmodus von Straight zu Natural geschaltet.
- Mit TargetTiltAngle/Neigung kann der Schwenkwinkel justiert werden.
- Mit SwingMode/Schwenken kann der Schwenkmodus ein bzw. ausgeschaltet werden.
- Der Rest ist selbsterklärend.

homebridgeMapping:

attr <XIAOMI> genericDeviceType Fan
attr <XIAOMI> homebridgeMapping
clear
On:power,cmdOn=on,cmdOff=off,valueOn=on,valueOff=off
LockPhysicalControls=child_lock,values=on:CONTROL_LOCK_ENABLED;;off:CONTROL_LOCK_DISABLED,cmds=CONTROL_LOCK_ENABLED:child_lock+on;CONTROL_LOCK_DISABLED:child_lock+off
RotationSpeed=level,minValue=0,maxValue=100,cmd=level,delay=1
TargetTiltAngle=angle,minValue=30,maxValue=120,minStep=30,cmd=angle
SwingMode=angle_enable,values=on:SWING_ENABLED;;off:SWING_DISABLED,cmdOn=angle_enable+on,cmdOff=angle_enable+off
CurrentRelativeHumidity=humidity
CurrentTemperature=temperature
BatteryLevel=batteryPercent,maxValue=100,minValue=0,minStep=1
StatusLowBattery=batteryState,values=ok:BATTERY_LEVEL_NORMAL;;low:BATTERY_LEVEL_LOW
ChargingState=charging,values=complete:NOT_CHARGING;;progress:CHARGING;;/.*/:NOT_CHARGEABLE
AudioFeedback:buzzer,cmdOn=buzzer+on,cmdOff=buzzer+off,valueOn=on,valueOff=off
NightVision:led,cmdOn=led+off,cmdOff=led+bright,valueOn=off,valueOff=bright
Mute:mode,cmdOn=mode+straight,cmdOff=mode+natural,valueOn=straight,valueOff=natural
CurrentFanState:power,values=on:BLOWING_AIR;;off:INACTIVE;;/.*/:IDLE

== Xiaomi Fan (neuere Generationen ohne Luftfeuchtigkeits- und Temperatursensor und Battery-Readings) ==
[[Datei:Xiaomi Standing Fan 2 bzw. 2S.png|mini]]
Voraussetzung zur Verwendung der Mappings, ist ein eingebundener Ventilator mit dem Modul 72_XiaomiDevice.
Siehe [https://forum.fhem.de/index.php/topic,73052.0.html Forumsthread]
Das Modul muss manuell installiert werden.

Den neueren Generationen dieses Ventilators fehlen Sensoren und somit Readings für Luftfeuchtigkeit, Temperatur und auch Batteriestatus. Diese sind bei der älteren Generation dieses Ventilators enthalten, siehe vorangegangenes Beispiel.

Dieses Mapping wurde mit dem "2S" erstellt. Es sollte aber mindestens auch mit einem "Xiaomi Standing Fan 2" (ohne Akku) funktionieren, da auch der "Xiaomi Standing Fan 2S" (mit Akku) kein Reading für die Batterie bereitstellt. Ansonsten gibt es wohl auch noch Generationen zwischen dem "Xiaomi DC Pedestal Fan" und den "Xiaomi Standing Fan 2/2S". Es ist davon auszugehen, dass dieses Beispiel genauso auch bei diesen Modellen funktioniert.

Mit folgenden Geräten wurde folgendes Mapping erstellt und somit erfolgreich getestet:

- 2019 Xiaomi Standing Fan 2S (FHEM model bzw. Default Hostname am Router: zhimi-fan-za4)
- 2018 Xiaomi ZhiMiDCVariableFrequencyFan ZRFFS01ZM (FHEM model bzw. Default Hostname am Router: zhimi-fan-za1)
- Liste bitte ergänzen!

Um möglichst viele Funktionen bereitzustellen, wurden auch Characteristics von anderen DeviceTypes verwendet. Erklärung zu den Characteristics:

- Die Kindersicherung (LockPhysicalControls) ist in Eve über das kleine Einstellungssymbol zu finden.
- Mit AudioFeedback/Audio-Bestätigung werden die Töne des Lüfters ein bzw. ausgeschaltet.
- Mit NightVision/Nachtsicht werden die LEDs ein (bright) bzw. ausgeschaltet (off).
- Mit Mute/Audio wird der Windmodus von Straight zu Natural geschaltet.
- Mit TargetTiltAngle/Neigung kann der Schwenkwinkel justiert werden.
- Mit SwingMode/Schwenken kann der Schwenkmodus ein bzw. ausgeschaltet werden.
- Der Rest ist selbsterklärend.

homebridgeMapping:

attr <XIAOMI> genericDeviceType Fan
attr <XIAOMI> homebridgeMapping
clear
On:power,cmdOn=on,cmdOff=off,valueOn=on,valueOff=off
LockPhysicalControls=child_lock,values=on:CONTROL_LOCK_ENABLED;;off:CONTROL_LOCK_DISABLED,cmds=CONTROL_LOCK_ENABLED:child_lock+on;CONTROL_LOCK_DISABLED:child_lock+off
RotationSpeed=level,minValue=0,maxValue=100,cmd=level,delay=1
TargetTiltAngle=angle,minValue=30,maxValue=120,minStep=30,cmd=angle
SwingMode=angle_enable,values=on:SWING_ENABLED;;off:SWING_DISABLED,cmdOn=angle_enable+on,cmdOff=angle_enable+off
AudioFeedback:buzzer,cmdOn=buzzer+on,cmdOff=buzzer+off,valueOn=on,valueOff=off
NightVision:led,cmdOn=led+off,cmdOff=led+bright,valueOn=off,valueOff=bright
Mute:mode,cmdOn=mode+straight,cmdOff=mode+natural,valueOn=straight,valueOff=natural
CurrentFanState:power,values=on:BLOWING_AIR;;off:INACTIVE;;/.*/:IDLE

== ZWave Türschloss Vision ZM1701 einbinden ==
Das ZWave Türschloss ZM1701 von der Firma Vision sendet seinen aktuellen Schließstatus in ein einzelnes Reading wie "lock", sondern schickt eine ganze Reihe von Informationen über den Zustand in das Reading <code>doorLockOperation</code>. Das Schließen und Öffnen der Türschlosses wird auch nicht mit einem Setzen des <code>state</code> erreicht, sondern mit dem Setzen von <code>doorLockOperation</code>. Das macht das Einbinden in homebridge nicht trivial, funktioniert aber über folgendes Homebridge-Mapping:
attr <ZM1701> genericDeviceType lock
attr <ZM1701> homebridgeMapping LockCurrentState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED LockTargetState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED,cmds=SECURED:doorLockOperation+close;UNSECURED:doorLockOperation+open

Kurz zur Erklärung: Um ein Schloss über HomeKit steuern zu können braucht es zwei characteristics. LockCurrentState zeigt an, ob das Schloss geöffnet oder geschlossen ist. Und mit LockTargetState wird das Schloss geöffnet oder geschlossen. Damit der aktuelle Status des Schlosses ausgelesen werden kann, muss aus dem FHEM-Reading <code>doorLockOperation</code> die Zeichenfolge <code> secured</code> oder <code>unsecured</code> extrahiert werden, daher die beiden regulären Ausdrücke <code>/\ssecured/</code> und <code>/unsecured/</code>. In der characteristic <code>LockTargetState</code> muss sowohl der aktuelle Status des Schlosses als auch das Kommando angegeben werden, schließlich möchte man ein geschlossenes Schloss nicht nochmal schließen. Daher wird erst aus dem Reading <code>doorLockOperation</code> der aktuelle Status des Schlosses ausgelesen und die damit korrespondierenden Befehle über <code>cmds=SECURED:doorLockOperation+close;UNSECURED:doorLockOperation+open</code> generiert.

Wer es in FHEM über ein webCmd einfacher zu bedienen haben möchte, fügt bitte noch die dafür notwendigen Attribute und die leicht geänderten homebridgeMappings wie folgt ein:
attr <ZM1701> genericDeviceType lock
attr <ZM1701> homebridgeMapping LockCurrentState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED LockTargetState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED,cmds=SECURED:close;UNSECURED:open
attr <ZM1701> /doorLockOperation open:open/doorLockOperation close:close
attr <ZM1701> webCmd open:close

Getestet mit
FHEM 5.7 Rev. 12191
homebridge 0.4.6
homebridge-fhem 0.2.48

[[Kategorie:HOWTOS]]
[[Kategorie:Code Snippets]]

Homebridge einrichten

2019-06-25T15:19:43Z

Hoppel118: Bravia Fernseher und Wetterstation hier entfernt und nach Homebridge_User_Configs verschoben

Dieses HOWTO zeigt die Installation und Erstinbetriebnahme von Homebridge.

Damit kann Siri benutzt werden, um FHEM-Devices zu steuern. So können Devices angesprochen werden, die offiziell HomeKit nicht unterstützen (die Vorgehensweise wurde auf einem Intel NUC mit Ubuntu Server 14.04 LTS und auf einem Raspberry Pi mit Raspbian getestet). Der Wiki-Eintrag bezieht sich hauptsächlich auf eine {{Link2Forum|Topic=32652|LinkText=Diskussion im FHEM-Forum}}. Ein Riesendank gilt vor allem {{Link2FU|430|Andre (justme1968)}}.

Die Konfiguration der inzwischen aktuellen zweiten Version des Homekit-Plugins ist in einem neuen {{Link2Forum|Topic= 48558 |LinkText=Thread im FHEM-Forum}} beschrieben. Hinzugekommen ist vor allem die freie Konfigurierbarkeit der Zuordnung zwischen FHEM Device und Homekit Accessory/Service, zwischen FHEM Reading und Homekit Characteristic, das mapping vom FHEM Readingwerten zu Homekit Werten sowie das Mapping von Homekit Werten zu FHEM Set-Kommandos und Werten.

Eine Sammlung funktionsfähiger Homebridge FHEM Konfigurationen kann hier gefunden werden: [[Homebridge User Configs]]. Die Sammlung befindet sich noch im Aufbau.

= Vorbereitung der Umgebung =

== NodeJS installieren ==
''Die nachfolgenden Befehle sind alle mit "sudo" prefixed. Wenn du unter "root" arbeitest oder deine Distribution einen anderen Mechanismus verwendet, so kannst du dies natürlich weglassen.''

Zunächst wird das Betriebssystem (in diesem Falle Debian oder Ubuntu) auf den aktuellen Stand gebracht:
<syntaxhighlight lang="bash" style="width:50%;">
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install build-essential libssl-dev</syntaxhighlight>

Nun muss NodeJS installiert werden. Leider ist die Version im Debian Repository deutlich zu alt, daher wird mit den folgenden Befehlen das Node Repository hinzugefügt und NodeJS (in der LTS Version) entsprechend installiert:

'''NodeJS V4'''
<syntaxhighlight lang="bash" style="width:50%;">
curl -sL https://deb.nodesource.com/setup_4.x | sudo -E bash -
sudo apt-get install -y nodejs
</syntaxhighlight>

{{Randnotiz|RNTyp=y|RNText=Bei Installation von NodeJS auf einem "alten" RasPi (B) bitte die besonderen Hinweise in {{Link2Forum|Topic=32652|Message=419325|LinkText=diesem Forenbeitrag}} beachten.}}
'''NodeJS V5'''
<syntaxhighlight lang="bash" style="width:50%">
curl -sL https://deb.nodesource.com/setup_5.x | sudo -E bash -
sudo apt-get install -y nodejs
</syntaxhighlight>

'''NodeJS V6'''
<syntaxhighlight lang="bash" style="width:50%">
curl -sL https://deb.nodesource.com/setup_6.x | sudo -E bash -
sudo apt-get install -y nodejs
</syntaxhighlight>

'''NodeJS V11'''
<syntaxhighlight lang="bash" style="width:50%">
curl -sL https://deb.nodesource.com/setup_11.x | sudo -E bash -
sudo apt-get install -y nodejs
</syntaxhighlight>

Bei Ubunutu ist es noch nötig apt-get wie folgt auszuführen.
<syntaxhighlight lang="bash" style="width:50%">
sudo apt-get install -y nodejs
</syntaxhighlight>

Damit ist NodeJS installiert.

== Python, g++, MDNS installieren ==
<syntaxhighlight lang="bash" style="width:50%;">
sudo apt-get install python g++ libavahi-compat-libdnssd-dev
</syntaxhighlight>

Nun sind alle Voraussetzungen geschaffen.

= Installation von Homebridge & notwendiger Shims =
Im nachfolgenden Absatz wird die Installation von Homebridge sowie des notwendigen Plugins (Shim) für FHEM erläutert.
Eventuell muss vor die Befehle ein
<syntaxhighlight lang="bash" style="width:50%;">
sudo
</syntaxhighlight>
vorangestellt werden.
== Homebridge installieren ==
Die aktuelle Homebridge version wird mit
<syntaxhighlight lang="bash" style="width:50%;">
npm install -g --unsafe-perm homebridge
</syntaxhighlight>
installiert, was eine Weile dauert. Anschließend wird der FHEM platform shim mit:
<syntaxhighlight lang="bash" style="width:60%;">
npm install -g homebridge-fhem
</syntaxhighlight>
installiert.

=== Fehler während der Installation ===
Bei folgendem Fehler ist das Abrufen von Github nicht möglich.
<pre>npm ERR! git clone --template=/home/hs-server-admin/.npm/_git-remotes/_templates --mirror
git://github.com/KhaosT/ed25519.git /home/hs-server-admin/.npm/_git-remotes/git-github-com-KhaosT-ed25519-git-d8bdee1d:
github.com[0: 192.30.252.128]: errno=Die Wartezeit für die Verbindung ist abgelaufen</pre>
Fehler könnte hier durch eine aktive Firewall verursacht werden.

Kommt eine DNS Fehlermeldung fehlt meistens der AVAHI-DAEMON, zu installieren via
<syntaxhighlight lang="bash" style="width=50%">
sudo apt-get install avahi-daemon
</syntaxhighlight>

Wenn npm beim Kompilieren von mdns mit der Meldung abbricht, dass "dns_sd.h" nicht gefunden wird, fehlt das Paket libavahi-compat-libdnssd-dev, zu installieren via
<syntaxhighlight lang="bash" style="width=50%">
sudo apt-get install libavahi-compat-libdnssd-dev
</syntaxhighlight>

== Homebridge aktualisieren ==
Prüfen, ob es Updates gibt:
<syntaxhighlight lang="bash" style="width:50%;">
npm -g outdated
</syntaxhighlight>
Die aktuelle Homebridge version wird mit
<syntaxhighlight lang="bash" style="width:50%;">
npm -g update homebridge
</syntaxhighlight>
installiert, was eine Weile dauert. Anschließend wird der FHEM platform shim mit:
<syntaxhighlight lang="bash" style="width:60%;">
npm -g update homebridge-fhem
</syntaxhighlight>
installiert.

Sollte dies nicht funktionieren, kann mit
<syntaxhighlight lang="bash" style="width:60%;">
npm -g install homebridge
</syntaxhighlight>
bzw.
<syntaxhighlight lang="bash" style="width:60%;">
npm -g install homebridge-fhem
</syntaxhighlight>
das Update installiert werden.

Um eine spezielle Version zu installieren, können die Installationsbefehle, von oben, wie folgt angepasst werden.
<syntaxhighlight lang="bash" style="width:60%;">
npm -g install homebridge-fhem@0.4.5
</syntaxhighlight>

= Homebridge konfigurieren =
''Wichtig: Für die weiteren Schritte sollte man nicht root verwenden, sondern beispielsweise einen dedizierten Nutzer für homebridge oder der Einfachheit halber den Nutzer, unter dem auch FHEM läuft (meist "fhem").''

== Einstellungen für homebridge ==
Zunächst wird das Verzeichnis für die Konfigurationsdatei erstellt und in dieses gewechselt:
<syntaxhighlight lang="bash" style="width:50%;">
mkdir -p ~/.homebridge
cd ~/.homebridge/
</syntaxhighlight>

Nun muss darin noch die config.json erstellt bzw. angepasst werden:
<syntaxhighlight lang="bash" style="width:50%;">
nano ~/.homebridge/config.json
</syntaxhighlight>

Hinweise zur Konfiguration:
* "''bridge''":
** "''username''": Sollte so belassen werden. Sollte später auf dem iOS Device keine Homebridge gefunden werden, so kann man hier beispielsweise den String auf 31 statt 30 enden lassen um so eine neue Homebridge vorzutäuschen.
** "''port''": Sollte so belassen werden
** "''pin''": Der PIN kann beliebig in dem Format xxx-xx-xxx angepasst werden. Dieser muss nur einmal bei der Einrichtung in iOS eingegeben werden.
* "''platforms''":
** "''platform''": Hier muss "FHEM" beibehalten werden.
** "''server''": Hier muss die IP des FHEM-Servers eingetragen werden. Dabei muss Homebridge nicht auf dem selben Server laufen wie FHEM, kann aber. Wenn es auf dem gleichen Rechner läuft, dann bietet es sich an, die IP 127.0.0.1 zu verwenden.
** "''port''": Hier muss der Port des gewählten FHEMWEBs eingetragen werden (muss nicht das "normale" sein, kann eine extra Instanz sein)
** "''auth''": Ist FHEM nicht mit Nutzername/Password abgesichert, so kann man diese Zeile einfach entfernen.
** "''filter''": Damit nicht alle Devices von Homebridge berücksichtigt werden, bietet es sich an, die Devices zu filtern. In diesem Beispiel wurden alle Devices, die über Siri steuerbar sein sollen, zusätzlich in den Raum Homekit konfiguriert.
<syntaxhighlight lang="json" style="width:50%;">
{
"bridge": {
"name": "Homebridge",
"username": "CC:22:3D:E3:CE:30",
"port": 51826,
"pin": "031-45-154"
},

"platforms": [
{
"platform": "FHEM",
"name": "FHEM",
"server": "127.0.0.1",
"port": "8083",
"auth": {"user": "FhemUser", "pass": "XXX"},
"filter": "room=Homekit"
}
],

"accessories": []
}
</syntaxhighlight>

Wenn für FHEMWEB kein user/password vergeben ist muss die "auth" Zeile weggelassen werden.
Wird FHEM mit SSL abgesichert, so muss zusätzlich in der Sektion "platforms" noch diese Zeile (nach "port") eingefügt werden:
<syntaxhighlight lang="javascript" style="width:50%;">
"ssl": true,
</syntaxhighlight>
Wenn man SSL ohne user/password benutzt, muss man "auth" Zeile einfugen, wobei die Werte weggelassen werden:
<syntaxhighlight lang="javascript" style="width:50%;">
"auth": {"user": "", "pass": ""},
</syntaxhighlight>

Natürlich kann man auch nach beliebigen anderen Kriterien filtern. z.b. nach Device TYPE, nach subtype Attribut, ... Es können mehrere FHEM platforms Abschnitte mit eigenem Filter im config file stehen (dabei das Komma zwischen den einzelnen Abschnitten nicht vergessen!) . Auch Geräte auf die mehr als ein Filterausdruck matched werden dabei nur einmal hinzugefügt.

= FHEM konfigurieren =
Es empfiehlt sich ein siri Gerät in FHEM anzulegen.
define siri siri

Die benötigten Attribute werden inzwischen beim ersten Start von homebridge-fhem automatisch auf FHEM Seite eingetragen.

Mehr zu den inzwischen verfügbaren Konfigurationsmöglichkeiten findet sich auf den github und npmjs Seiten des Plugins und im ersten Beitrag des zugehörigen Thread im {{Link2Forum|Topic= 48558 |LinkText=Diskussion im FHEM-Forum}}

= Start von Homebridge =

== Hinweis ==
Nach allen Änderungen die in FHEM gemacht werden, welche Homebridge betreffen, muss Homebridge neu gestartet werden. Wie der Neustart erfolgen muss, ist abhängig davon, wie man Homebridge gestartet hat. Bitte den entsprechenden Methoden entnehmen.

== Einmaliger Manueller Start ==
<syntaxhighlight lang="bash" style="width:50%;">
homebridge
</syntaxhighlight>

Homebridge sollte nun laufen. Hier kann man die Kommunikation nachverfolgen. Abbrechen kann das ganze mit CTRL+c (es sind dann auch keine Befehle mehr mit Siri möglich). Damit Siri auch Befehle ohne ständig offenes Terminal bearbeiten kann, bitte nächsten Punkt beachten.

=== Fehler während des Manuellen Starts ===
Kommt ein Fehler der ähnlich aussieht wie folgender, sollte zuerst die Nodesversion geprüft werden.
Die Nodes version kann durch ein System Update auf eine niedrigere Version wie benötigt gedowngraded werden
<syntaxhighlight lang="bash" style="width=50%">
Error: Module version mismatch. Expected 47, got 46.
at Error (native)
at Object.Module._extensions..node (module.js:450:18)
at Module.load (module.js:356:32)
at Function.Module._load (module.js:313:12)
at Module.require (module.js:366:17)
at require (module.js:385:17)
at Object.<anonymous> (/usr/lib/node_modules/homebridge/node_modules/mdns/lib/dns_sd.js:24:20)
at Module._compile (module.js:425:26)
at Object.Module._extensions..js (module.js:432:10)
at Module.load (module.js:356:32)
</syntaxhighlight>
Geprüft werden kann die Nodes Version mit:
<syntaxhighlight lang="bash" style="width=50%">node -v zeigt mir: v0.10.28, nodejs -v: v5.11.1</syntaxhighlight>
Hier ist die Version v0.10.28 wobei v0.12 Mindestvorraussetzung ist.
Die Installation der richtigen Nodes Version kann oben am Anhang des Wiki Artikels entnommen werden.

== Homebridge automatisch starten ==
Es gibt verschiedene Methoden, Homebridge automatisch zu starten.

=== Steuerung via FHEM ===
Auf Basis der unten stehenden ''Alternativen Methode'' wurde eine Version entwickelt, mit der man auch den Status einsehen und den Restart des Dienstes aus FHEM heraus erledigen kann. Diese Version ist auf der Seite [[Homebridge Start und Status in FHEM]] im Detail beschrieben.

=== Alternative Methode: Init-Skript ===
Dies startet homebridge als einen Service.

==== Service anlegen ====
<code>
sudo nano /etc/init.d/homebridge
</code>

Code einfügen (startet den Homebridge Server als Benutzer "pi" und nimmt an, dass sich .homebridge/config.json in seinem Homeverzeichnis unter /home/pi/ befindet):

<syntaxhighlight lang=bash>
#!/bin/sh
### BEGIN INIT INFO
# Provides: homebridge
# Required-Start: $network $remote_fs $syslog
# Required-Stop: $remote_fs $syslog
# Default-Start: 2 3 4 5
# Default-Stop: 0 1 6
# Short-Description: Start daemon at boot time for homebridge
# Description: Enable service provided by daemon.
### END INIT INFO
export PATH=$PATH:/usr/local/bin
export NODE_PATH=$NODE_PATH:/usr/local/lib/node_modules
PID=`pidof homebridge`
case "$1" in
start)
if ps -p $PID > /dev/null 2>&1; then
echo "Homebridge is already running"
else
su - pi -c "homebridge > /dev/null 2>&1 &"
echo "Homebridge starting"
$0 status
fi
;;
stop)
if ! ps -p $PID > /dev/null 2>&1; then
echo "Homebridge is not running"
else
kill $PID
echo "Homebridge closed"
fi
;;
restart)
if ! ps -p $PID > /dev/null 2>&1; then
$0 start
else
$0 stop
$0 start
fi
;;
status)
if ps -p $PID > /dev/null 2>&1; then
echo "Homebridge is running PID $PID"
else
echo "Homebridge is not running"
fi
;;
*)
echo "Usage: $0 {start|stop|status|restart}"
exit 1
;;
esac
exit 0
</syntaxhighlight>

==== Autostart aktivieren ====

<code>
sudo chmod 755 /etc/init.d/homebridge

sudo update-rc.d homebridge defaults
</code>

Nun kann man mit

<code>
sudo service homebridge start
</code>

bzw.

<code>
sudo /etc/init.d/homebridge start
</code>

den Dienst starten

=== Alternative Methode: systemd ===

Während das Init-Skript grundsätzlich auch mit systemd funktioniert, kann man natürlich für Homebridge auch ein systemd-Skript anlegen. Wie das geht, ist im [https://github.com/nfarina/homebridge/wiki/Running-HomeBridge-on-a-Raspberry-Pi#running-homebridge-on-bootup-systemd Wiki zu Homebridge] beschrieben.

== FHEM Device Einstellungen ==
Damit die zu schaltenden Geräte überhaupt in der Homebridge aufgenommen werden, muss man sie im Raum Homekit hinzufügen.

Um HM-CC-RT-DN Thermostate steuern zu können, muss wie oben beschrieben folgendes attribute gesetzt werden (hier als Beispiel das Device "Heizung"):
# attr Heizung subtype thermostat
Für einen Dummy muss man den genericDeviceType setzen, also beispielsweise:
# attr Dummy genericDeviceType switch
# attr Dummy setList on off

Wie bereits vorher angemerkt: fügt man ein Device hinzu oder führt eine Änderung an einem Device durch, so sollte homebridge neu gestartet werden.

= HomeKit in iOS =

== Einrichtung ==
Um FHEM über Homebridge in iOS nutzen zu können, muss HomeKit eingerichtet werden.

Es gibt verschiedene Apps. Im Folgenden wird die App EVE von Elgato empfohlen, die aus dem App-Store geladen werden muss.
In der App auf:
<pre style="width:50%;">
Gerät hinzufügen
</pre>
Es sollte ein Gerät mit der Bezeichnung "Homebridge" zur Auswahl erscheinen. Zur Ersteinrichtung auf PIN manuell eingeben gehen und (falls in der config.json nicht geändert):
<pre style="width:50%;">
031-45-154
</pre>
eingeben.

Im Anschluss können die Devices nach Belieben verschiedenen Räumen zugeteilt werden, sowie Szenen und Bereiche erstellt werden.

== Schalten mit Siri ==
'''HolyMoly''' aus dem FHEM-Forum hat ein paar Beispiele gegeben, wie man Siri dazu bringt Devices zu schalten:
<pre style="width:50%;">
"Schalte alle Lampen im Obergeschoss ein."
"Schalte Chloes Licht aus."
"Dimme das Licht in der Küche."
"Dimme das Licht im Esszimmer auf 50 %."
"Stelle das Licht in der Küche am hellsten ein."
"Stelle die Temperatur im Tahoe-Haus auf 22 °C ein."
"Stelle das Thermostat im Erdgeschoss auf 21 °C ein.
"Schalte den Drucker im Büro ein."
"Siri, bereite alles für eine Party vor."
"Bereite das Ambiente fürs Abendessen vor."
"Aktiviere den Nachtruhemodus."
</pre>

Mittlerweile kann Siri auch noch die Lichtfarbe von LEDs ändern.

= Hinweise =

== Unterstützte Geräte ==
Das FHEM Plugin von {{Link2FU|430|Andre (justme1968)}} unterstützt automatisch mindestens die folgenden Geräte:

switches (devices with set on and set off commands)
lights (devices with set on and set off commands)
HomeMatic, FS20 and ZWave dimmers (devices with set on, set off and set dim or set pct commands)
HUE, WifiLight, MilightDevice, SWAP_0000002200000003 (hue, sat, bri, rgb)
homematic, max and pid20 thermostats
homematic, DUOFERN and FS20/IT(?) blinds
homematic, MAX and FHTTK contact sensors (door, window)
HM-SEC-WIN, HM-SEC-KEY
presence, ROOMMATE
SONOS (power, volume)
harmony scenes
temperaturecw and humidity sensors
CO20 air quality sensor
probably some more ...

Über eine entsprechende Konfiguration lässt sich darüber hinaus jedes mit FHEM steuerbare Gerät auf die unterstützten Homekit-Typen abbilden.

Die aktuelle Liste und eine Beschreibung der Konfigurationsmöglichkeiten findet sich [https://www.npmjs.com/package/homebridge-fhem auf den npmjs seiten] bzw. [https://github.com/justme-1968/homebridge-fhem auf github].

Mehr zum homebridgeMapping findet sich hier: [[Alexa_und_Mappings#homebridgeMapping]]

Mehr zu den unterstützen Services und Characteristics findet sich hier: [https://github.com/KhaosT/HAP-NodeJS/blob/master/lib/gen/HomeKitTypes.js]

Über eine '''history''' Characteristic lässt sich für bestimmte Service-Typen eine Eve-Kompatible history aktivieren:
... history:size=1024 ...

=== Beispiele ===

Gesammelte Beispiele funktionierender HomebridgeMappings sind hier zu finden: [[Homebridge_User_Configs]]

== Zusätzliche Plugins ==
Für manche der über FHEM steuerbaren Geräte wie z.b. MiLight, Harmony Hub, Philips Hue, Sonos,... gibt es eigene homekit plugins. Wenn immer möglich, empfiehlt es sich aber diese '''nicht''' zu verwenden, sondern die Steuerung über die FHEM-Integration zu realisieren, da
* diese in der Regel sehr viel mächtiger und frei konfigurierbar ist
* es FHEM erlaubt, als zentrale Instanz den Überblick über den aktuellen Gesamtzustand zu haben (wichtig bei Geräten, die gepollt werden)
* die Ressourcen auf den angesteuerten Geräten schont, da Werte optimal gecached werden und nur eine einzige Verbindung aufgebaut wird

== Hinweis für alte homebridge Versionen ==
UPDATE: Homebridge funktioniert mit einer kleinen Einschränkung nun auch mit node 4.0.0. Laut
[https://github.com/cflurin/homebridge-shims/wiki/Minimalist-Homebridge-on-a-Raspberry-Pi Homebridge on a Raspberry Pi] müssen die folgenden Abhängigkeiten (Dependencies) aus der '''package.json''' entfernt werden:
<pre>
"harmonyhubjs-client": "^1.1.4",
"harmonyhubjs-discover": "git+https://github.com/swissmanu/harmonyhubjs-discover.git"
</pre>

== Hinweis zur Geschwindigkeitsoptimierung auf einem Raspberry PI ==
Damit es auf einem Raspberry schneller läuft, wird darüber hinaus empfohlen, auch diverse Abhängigkeiten aus der '''package.json''' zu entfernen:
<pre>
"ad2usb": "git+https://github.com/alistairg/node-ad2usb.git#local",
"carwingsjs": "0.0.x",
"chokidar": "^1.0.5",
"eibd": "^0.3.1",
"elkington": "kevinohara80/elkington",
"harmonyhubjs-client": "^1.1.4",
"harmonyhubjs-discover": "git+https://github.com/swissmanu/harmonyhubjs-discover.git",
"lifx-api": "^1.0.1",
"lifx": "git+https://github.com/magicmonkey/lifxjs.git",
"node-hue-api": "^1.0.5",
"node-icontrol": "^0.1.4",
"node-milight-promise": "0.0.x",
"tough-cookie": "^2.0.0",
"sonos": "0.8.x",
"telldus-live": "0.2.x",
"teslams": "1.0.1",
"unofficial-nest-api": "git+https://github.com/hachidorii/unofficial_nodejs_nest.git#d8d48edc952b049ff6320ef99afa7b2f04cdee98",
"wemo": "0.2.x",
"wink-js": "0.0.5",
"komponist" : "0.1.0",
"yamaha-nodejs": "0.4.x",
</pre>

Daher zunächst ein Backup der Datei anlegen
<pre>sudo cp package.json package.json.bkp </pre>
Am einfachsten geht das Entfernen der Zeilen mit einem Editor, beispielsweise nano oder vi.
<pre>sudo nano package.json</pre>

Das config file sollte dann wie folgt aussehen: Achtung vor den letzten zwei "}" am Ende darf kein Komma sein.
<syntaxhighlight lang="json">
{
"name": "homebridge",
"description": "HomeKit support for the impatient",
"version": "0.1.1",
"scripts": {
"start": "DEBUG=* node app.js || true"
},
"repository": {
"type": "git",
"url": "git://github.com/nfarina/homebridge.git"
},
"license": "ISC",
"dependencies": {
"async": "^1.4.2",
"color": "0.10.x",
"debug": "^2.2.0",
"hap-nodejs": "^0.0.2",
"isy-js": "",
"mdns": "^2.2.4",
"netatmo": "1.3.0",
"node-cache": "3.0.0",
"node-persist": "0.0.x",
"node-xmpp-client": "1.0.0-alpha23",
"q": "1.4.x",
"queue": "^3.1.0",
"request": "2.49.x",
"xml2js": "0.4.x",
"xmldoc": "0.1.x"
}
}
</syntaxhighlight>

== Links ==
* [https://github.com/nfarina/homebridge Github homebridge]
* [https://github.com/justme-1968/homebridge-fhem Github homebridge-fhem]
* [https://www.npmjs.com/package/homebridge NPM homebridge]
* [https://www.npmjs.com/package/homebridge-fhem NPM homebridge-fhem]

[[Kategorie:HOWTOS]]
[[Kategorie:Sprachsteuerung]]

Homebridge User Configs

2019-06-25T15:11:06Z

Hoppel118: zwave Türschloss verschoben, Überschrift FeuchteSensor angepasst und Homematic Feuchtigkeitssensor ergänzt

Dieser Eintrag dient zur Sammlung funktionsfähiger Homebridge Configs.

Bitte immer die FHEM Version und Homebridge Version angegeben.

Sehr gute Hinweise gibt es hier: http://www.meintechblog.de/2015/10/mit-siri-und-fhem-das-gesamte-smart-home-per-stimme-steuern/
== Mögliche Mappings ==
Die Möglichen Mappings können hier nachgelesen werden https://github.com/KhaosT/HAP-NodeJS/blob/master/lib/gen/HomeKitTypes.js

Hier ein Beispiel:
Characteristic.Brightness = function() {
Characteristic.call(this, 'Brightness', '00000008-0000-1000-8000-0026BB765291');
this.setProps({
format: Characteristic.Formats.INT,
unit: Characteristic.Units.PERCENTAGE,
maxValue: 100,
minValue: 0,
minStep: 1,
perms: [Characteristic.Perms.READ, Characteristic.Perms.WRITE, Characteristic.Perms.NOTIFY]
});
this.value = this.getDefaultValue();
};

Das Mapping in diesem Fall, hat den Titel Brightness.

Die Werte können in 1er Schritten zwischen 0 und 100 liegen (max und min Value)
== Erstellung eines HomebridgeMappings am Beispiel "Feuchtesensor" ==
Zum Einstieg etwas leicht nachvollziehbares.

Feuchtesensoren haben in der Regel ein "humidity" Reading, im Falle des Opus XT300 Bodenfeuchtesensors auch Temperatur und Batterie Level. Homekit unterstützt einen "HumiditySensor" Service. Dieser ist in homebridge-fhem nicht standardmäßig vorhanden (kann also nicht aus dem dropdown ausgewählt werden, sondern muss über das Befehlsfeld zugewiesen werden):

<code>attr meinSensor genericDeviceType HumiditySensor</code>

Im nächsten Schritt werden die Readings gemappt:

<code>attr meinSensor homebridgeMapping clear CurrentRelativeHumidity=humidity StatusLowBattery=battery,values=ok:BATTERY_LEVEL_NORMAL;;/^.*/:BATTERY_LEVEL_LOW CurrentTemperature=temperature</code>

<code>clear</code>löscht default mappings - das wird in der Regel nicht notwendig sein, schadet aber nicht

<code>CurrentRelativeHumidity</code> ist die relevante Homekit Characteristic - wird mit dem entsprechenden Reading des Sensors gemappt.

<code>StatusLowBattery</code> erwartet entweder BATTERY_LEVEL_NORMAL oder _LOW. Mein Sensor liefert ok zurück, wenn alles gut ist, also wird "ok" auf _NORMAL gemappt, alles andere auf _LOW.

Der Opus XT300 Bodenfeuchtesensors liefert auch noch die Temperatur - der HumiditySensor Service sieht das eigentlich nicht vor, daher wird die Temperatur auch nicht in der Apple "Home" App angezeigt. Bei Eve wird die Temperatur hingegen berücksichtigt.

== BRAVIA Fernseher ==
Ein Beispiel homebridgeMapping für Sony Bravia Fernseher (iOS 12.2 beta!) und genericDeviceType Television:
<pre>
clear
ConfiguredName:model
Active:state,values=off:INACTIVE;on:ACTIVE,cmds=ACTIVE:on;INACTIVE:off
RemoteKey:key,cmds=REWIND:remoteControl+Rewind;FAST_FORWARD:remoteControl+FastForward;NEXT_TRACK:remoteControl+NEXT_TRACK;PREVIOUS_TRACK:remoteControl+PREVIOUS_TRACK;ARROW_UP:remoteControl+Up;ARROW_DOWN:remoteControl+Down;ARROW_LEFT:remoteControl+Left;ARROW_RIGHT:remoteControl+Right;SELECT:remoteControl+Ok;BACK:remoteControl+RETURN;EXIT:remoteControl+Exit;PLAY_PAUSE:remoteControl+Play;INFORMATION:remoteControl+Info
SleepDiscoveryMode:default=ALWAYS_DISCOVERABLE
ClosedCaptions:default=0
DisplayOrder:default=Test1
CurrentMediaState:default=0:currentTitle
TargetMediaState:default=0,cmds=PLAY:remoteControl+play;PAUSE:remoteControl+pause;STOP:remoteControl+stop;
PictureMode:default=1
PowerModeSelection:default=1,cmds=0:remoteControl+options
ActiveIdentifier:input,default=0,values=/tv.dvbt|TV...DVB-T/:1;/HDMI.3/:2,cmds=1:input+TV+/+DVB-T;2:input+HDMI+3/ARC;3:application+Plex
TelevisionSpeaker#Mute=mute
Active:default=ACTIVE
VolumeSelector:volume,cmds=INCREMENT:VolumeUp;DECREMENT:VolumeDown
VolumeControlType:default=RELATIVE_WITH_CURRENT
linkedTo=Television
InputSource(1)#Identifier:default=1
ConfiguredName:default=TV
IsConfigured:default=CONFIGURED
InputSourceType:default=TUNER
CurrentVisibilityState:default=SHOWN
linkedTo=Television
InputSource(2)#Identifier:default=2
ConfiguredName:default=APPLE+TV
IsConfigured:default=CONFIGURED
InputSourceType:default=HDMI
CurrentVisibilityState:default=SHOWN
linkedTo=Television
InputSource(3)#Identifier:default=3
ConfiguredName:default=PLEX
IsConfigured:default=CONFIGURED
InputSourceType:default=APPLICATION
CurrentVisibilityState:default=SHOWN
linkedTo=Television
</pre>

damit lässt sich der Fernseher über Siri/Homekit ein- und ausschalten sowie über das appleTV Control-Center Widget steuern.

== EnOcean STM 250 Tür-/Fensterkontakt ==
Der STM 250 liefert als Status in FHEM <code>open</code>, wenn das Fenster offen und damit der Kontakt "offen" ist. Analog liefert er <code>closed</code> wenn das Fenster geschlossen und damit auch der Kontakt geschlossen ist. Diese Statusangaben sind sehr intuitiv zu verstehen und zu interpretieren.

Die characteristic <code>ContactSensorState</code> von HomeKit liefert entweder den Wert <code>CONTACT_DETECTED=0</code> oder <code>CONTACT_NOT_DETECTED=1</code> zurück. Wobei <code>CONTACT_DETECTED</code> bedeutet, dass der Kontakt geschlossen ist. Je nach Darstellung in der HomeKit-fähigen App muss dieses Verhalten bei der Interpretation berücksichtigt werden. Die App Eve von Elgato zum Beispiel liefert für Kontaktsensoren "JA" oder "NEIN" mit der Bedeutung <code>CONTACT_DETECTED=0=JA</code> bzw. <code>CONTACT_NOT_DETECTED=1=NEIN</code> zurück.

Noch ein wichtiger Punkt: Um einen Sensorkontakt sinnvoll einzurichten sollte als zusätzlicher Wert für das Attribut <code>genericdeviceType</code> der Wert <code>ContactSensor</code> hinzugefügt werden. Wie das geht ist im Eintrag [[Homebridge_einrichten#FHEM_konfigurieren | Homebridge einrichten]] ausführlicher beschrieben.

Folgende Attribute dann hinzufügen:
attr STM250 genericDeviceType ContactSensor
attr STM250 homebridgeMapping ContactSensorState=state,values=closed:CONTACT_DETECTED;open:CONTACT_NOT_DETECTED

Getestet mit
FHEM 5.7 Rev. 9893
Homebridge 0.2.16
homebridge-fhem Vorschauversion aus {{Link2Forum|Topic=48558|Message=402024|LinkText=homebridge/homekit}}

== Modul RESIDENTS für Anwesenheitserkennung und Steuerung der Anwesenheit benutzen ==
[[Datei:Homebridge_bewohner_zu_szene.jpeg|mini|Schaltzustand eines Bewohners zu einer Szene hinzufügen]]
Aus den einzelnen Komponenten des Moduls RESIDENTS, homebridge sowie der characteristic <code>On</code> und der Szenensteuerung lässt sich eine gleichzeitige Steuerung der Anwesenheit und Anwesenheitserkennung basteln.

Dazu müssen folgende Schritte unternommen werden:
* einem Bewohner aus dem Modul ROOMMATE die Steuerung über homebridgeMapping hinzufügen
* Szene für "Ich bin zu Hause" und "Ich gehe jetzt" in einer HomeKit-fähigen App wie z.B. Eve einrichten

Man kann einen beliebigen Bewohner aus dem Modul ROOMMATE nehmen und ihn über die characteristic <code>On</code> in Form eines Schalters sozusagen schaltbar machen. Nur wird das Ein- und Ausschalten des Bewohners über HomeKit in FHEM auf den Status home bzw. absent gemappt. Seit dem 06.02.2016 werden RESIDENTS automatisch als Occupancy Sensor für HomeKit annonciert. Nun noch die Attribute des ROOMMATE wie folgt setzen:
attr <ROOMMATE> genericDeviceType switch
attr <ROOMMATE> homebridgeMapping On=state,valueOn=/home|awoken|asleep|gotosleep/,valueOff=/gone|absent/,cmdOn=home,cmdOff=absent

Natürlich muss der Bewohner noch dem Filter von homebridge hinzugefügt und homebridge neu gestartet werden.

Anschließend geht es in der HomeKit-fähigen App Deiner Wahl weiter. In Eve von Elgato ist von vornherein zum Beispiel vorgesehen, dass man zwei Szenen "Ich bin zuhause" und "Ich verlasse das Haus" hat. Zu diesen Szenen wird eine Aktion hinzugefügt indem der Bewohner, den das ROOMMATE-Modul meldet zur Szene hinzugefügt wird und beim Nachhausekommen "eingeschaltet" wird. Genauso wird mit der Szene "Ich verlasse das Haus" verfahren: Bewohner zur Szene hinzufügen und den Schaltvorgang auf "ausschalten" setzen.

Mit den Sprachbefehlen "Ich bin zuhause" oder "Ich verlasse das Haus" wird die entsprechende Szene eingeschaltet, homebridge schaltet über das <code>homebridgeMapping</code> Attribut dann den Bewohner auf "home" oder "absent".

Getestet mit
FHEM 5.7 Rev. 9893
Homebridge 0.2.16
homebridge-fhem Vorschauversion aus {{Link2Forum|Topic=48558|Message=402024|LinkText=homebridge/homekit}}

Eine noch etwas bessere Schaltmöglichkeit bietet '''genericDeviceType security'''.
Das Mapping für ROOMMATE sieht wie folgt aus:
attr TYPE=ROOMMATE genericDeviceType security
attr TYPE=ROOMMATE homebridgeMapping SecuritySystemCurrentState=state,values=/home|awoken/:0;;absent:1;;/asleep|gotosleep/:2;;gone:3 SecuritySystemTargetState=SecuritySystemCurrentState,cmds=0:state+home;;1:state+absent;;2:state+gotosleep;;3:state+gone,delay=1
für GUEST:
attr TYPE=GUEST genericDeviceType security
attr TYPE=GUEST homebridgeMapping SecuritySystemCurrentState=state,values=/home|awoken/:0;;absent:1;;/asleep|gotosleep/:2;;none:3 SecuritySystemTargetState=SecuritySystemCurrentState,cmds=0:state+home;;1:state+absent;;2:state+gotosleep;;3:state+none,delay=1

== Homematic Luftfeuchtigkeits- und Tmeperatursensoren ==

Mit folgenden Geräten wurde folgendes Mapping erstellt und somit erfolgreich getestet:

- HM-WDS10-TH-O
- HM-WDS40-TH-I
- HM-WDS40-TH-I-2

Achtung: Hier wird genericDeviceType "TemperatureSensor" verwendet, um eine history in EVE zu erhalten. Mit einem "HumiditySensor" funktionierte dies bei den Tests (Februar 2019) nicht.

attr <THSensor> genericDeviceType TemperatureSensor

attr <THSensor> CurrentRelativeHumidity=humidity
CurrentTemperature=temperature
StatusLowBattery=battery,values=ok:BATTERY_LEVEL_NORMAL;/^.*/:BATTERY_LEVEL_LOW
history:size=1024

== Homematic Heizkörperthermostat HM-CC-RT-DN ==
[[Datei:HM-CC-RT-DN-Eve.PNG|mini|Darstellung des HM-CC-RT-DN in der iOS App Eve]]
attr <HMCCRTDN_Channel2_Clima> homebridgeMapping TargetTemperature=desired-temp::desired-temp,minValue=5,maxValue=35,minStep=0.5,nocache=1
CurrentTemperature=BU_Heizung_01_Clima:measured-temp,nocache=1
StatusLowBattery=BU_Heizung_01:battery,values=ok:BATTERY_LEVEL_NORMAL;;/^.*/:BATTERY_LEVEL_LOW
TargetHeatingCoolingState=heatingState,values=OFF:0;;HEAT:1;;COOL:2;;AUTO:3,cmds=OFF:controlManu+off;;HEAT:controlMode+boost;;AUTO:controlMode+auto;;COOL:controlManu+17.0
CurrentHeatingCoolingState=heatingState,values=OFF:0;;HEAT:1;;COOL:2;;AUTO:0,valud=OFF
attr <HMCCRTDN_Channel2_Clima> siriName Robby
Dieses Mapping bezieht sich auf ein vorhandenes

== Homematic SmokeDetector HM-SEC-SD und HM-SEC-SD2 ==
[[Datei:Homebridge-Homematic-Smokedetector-Gen1.jpg|mini|Homebridge-Homematic-Smokedetector-Gen1 in EVE]]
Es sind keine Homebridge Mappings für die Rauch Meldung erforderlich.

Allerdings ist ein Mapping für den Batterie Zustand nötig, siehe Unten.

attr <SmokeDetector> genericDeviceType SmokeSensor
attr <SmokeDetector> subType smokeDetector

attr <SmokeDetector> homebridgeMapping StatusLowBattery=battery,values=ok:BATTERY_LEVEL_NORMAL;;/^.*/:BATTERY_LEVEL_LOW

== Homematic Heizkörperthermostat HM-CC-RT-DN ==
[[Datei:HM-CC-RT-DN-Eve.PNG|mini|Darstellung des HM-CC-RT-DN in der iOS App Eve]]
attr <HMCCRTDN_Channel2_Clima> homebridgeMapping TargetTemperature=desired-temp::desired-temp,minValue=5,maxValue=35,minStep=0.5,nocache=1
CurrentTemperature=BU_Heizung_01_Clima:measured-temp,nocache=1
StatusLowBattery=BU_Heizung_01:battery,values=ok:BATTERY_LEVEL_NORMAL;;/^.*/:BATTERY_LEVEL_LOW
TargetHeatingCoolingState=heatingState,values=OFF:0;;HEAT:1;;COOL:2;;AUTO:3,cmds=OFF:controlManu+off;;HEAT:controlMode+boost;;AUTO:controlMode+auto;;COOL:controlManu+17.0
CurrentHeatingCoolingState=heatingState,values=OFF:0;;HEAT:1;;COOL:2;;AUTO:0,valud=OFF
attr <HMCCRTDN_Channel2_Clima> siriName Robby
Dieses Mapping bezieht sich auf ein vorhandenes ''userReading'' mit dem Namen <code>heatingState</code>, womit Homekit die einzelnen Status nachher unterscheidet.
attr <HM-CC-RT-DN_Clima> userReadings heatingState {(ReadingsVal($NAME,"ValvePosition",0) > 0 || ReadingsVal($NAME,"desired-temp","-") eq "on") ? "HEAT" : ReadingsVal($NAME,"desired-temp","-") eq "off" ? "OFF" : ReadingsVal($NAME,"controlMode","auto") eq "auto" ? "AUTO" : (ReadingsVal($NAME,"measured-temp",20) > ReadingsVal($NAME,"desired-temp",20)) ? "COOL" : "AUTO"}
Global auf alle in FHEM angelegten HM-CC-RT-DN, lässt sich mit folgendem Befehl das ''userReading'' anlegen.
Siehe [https://forum.fhem.de/index.php/topic,59211.msg505986.html#msg505986 Forumsthread].

attr TYPE=CUL_HM:FILTER=model=HM-CC-RT-DN:FILTER=chanNo=04 userReadings heatingState {(ReadingsVal($NAME,"ValvePosition",0) > 0 || ReadingsVal($NAME,"desired-temp","-") eq "on") ? "HEAT" : ReadingsVal($NAME,"desired-temp","-") eq "off" ? "OFF" : ReadingsVal($NAME,"controlMode","auto") eq "auto" ? "AUTO" : (ReadingsVal($NAME,"measured-temp",20) > ReadingsVal($NAME,"desired-temp",20)) ? "COOL" : "AUTO"}

== Homematic Wetterstation OC3 HM-WDS100-C6-O-2 ==
[[Datei: homebridge-wetter.jpg|mini|Wetterstation in EVE]]
Mit der EVE und den hier: [https://github.com/naofireblade/homebridge-weather-plus/blob/master/util/characteristics.js] beschriebenen Characteristics lässt sich eine lokale Homematic OC3 Wetterstation aus FHEM einbinden:
<pre>
clear
CurrentTemperature:temperature
CurrentRelativeHumidity:humidity
49C8AE5A-A3A5-41AB-BF1F-12D5654F9F41:windSpeed,name=WINDGESCHWINDIGKEIT,format=FLOAT,unit=kmh,maxValue=250,minValue=0,minStep=1
46f1284c-1912-421b-82f5-eb75008b167e:windDirection,name=WINDRICHTUNG,format=UINT8,unit=ARC_DEGREE,maxValue=360,minValue=0,minStep=1
StatusLowBattery:battery,values=ok:BATTERY_LEVEL_NORMAL;/^.*/:BATTERY_LEVEL_LOW
ccc04890-565b-4376-b39a-3113341d9e0f:RegenmengeLast24Hours:state,name=REGEN_24h,format=FLOAT,unit=mm,maxValue=100,minValue=0,minStep=1
10c88f40-7ec4-478c-8d5a-bd0c3cce14b7:RegenmengeLast1Hours:state,name=REGEN_1h,format=FLOAT,unit=mm,maxValue=100,minValue=0,minStep=1
0000006B-0000-1000-8000-0026BB765291:brightness,name=BRIGHTNESS,format=FLOAT,unit=LUX,maxValue=10000,minValue=0,minStep=.0001
cd65a9ab-85ad-494a-b2bd-2f380084134c:isRaining,name=BEDINGUNGKATEGORIE,values=0:0;1:2,format=UINT8,maxValue=3,minValue=0,minStep=1
cd65a9ab-85ad-494a-b2bd-2f380084134d:isRaining,name=BEDINGUNG,format=STRING,values=0:-;/.*/:Regen
</pre>

== Roomba über THINKINGCLEANER Modul ==
attr <THINKINGCLEANER> genericDeviceType switch
attr <THINKINGCLEANER> homebridgeMapping clear On=state,valueOn=/^(on|dock)/,cmdOn=on,cmdOff=off,nocache=1 ChargingState=deviceStatus,values=/(_recon|_full|_trickle)$/:CHARGING;/^.*/:NOT_CHARGING
attr <THINKINGCLEANER> siriName Robby

Getestet mit
FHEM 5.7 Rev. 12680
homebridge 0.4.11
homebridge-fhem 0.2.66

== Vallox Belüftungsanlage ==
Die Steuerung der Lüftungsgeschwindigkeit ist nur in Prozent möglich. Die Umrechnung erfolgt im [[Vallox]] Modul.
Hierzu wurde das Reading ''FanSpeedPct'' hinzugefügt.

attr <Vallox> genericDeviceType Fan
attr <Vallox> homebridgeMapping clear
model=Vallox
On=PowerState,valueOn=1,readOnly=1
RotationSpeed=FanSpeedPct,minValue=1,maxValue=100,cmd=FanSpeedPct,delay=1

== Xiaomi Vacuum Cleaner 1. Generation ==
[[Datei:XIAOMI_VACUUM_CLEANER-Gen1.jpg|mini|XIAOMI VACUUM 1. GEN in EVE]]
Voraussetzung zur Verwendung der Mappings, ist ein eingebundener Staubsauger mit dem Modul 72_XiaomiDevice.

Siehe [https://forum.fhem.de/index.php/topic,73052.0.html Forumsthread]
Das Modul muss manuell installiert werden.

attr <XIAOMI> genericDeviceType switch
attr <XIAOMI> homebridgeMapping On=state,valueOn=Cleaning,cmdOn=start,cmdOff=charge
RotationSpeed=fan_power,minValue=0,maxValue=90,cmd=fan_power,delay=1
BatteryLevel=batteryLevel,maxValue=100,minValue=0,minStep=1
StatusLowBattery=battery,values=ok:BATTERY_LEVEL_NORMAL;;low:BATTERY_LEVEL_LOW
ChargingState=state,values=Docked:NOT_CHARGING;;Charging:CHARGING;;/.*/:NOT_CHARGEABLE
OccupancyDetected=state,values=/Docked|Charging/:OCCUPANCY_DETECTED;;/.*/:OCCUPANCY_NOT_DETECTED
FilterLifeLevel=consumables_filter,minValue=0,maxValue=100
FilterChangeIndication=consumables_filter,values=0:CHANGE_FILTER

== Roborock S50 (2. Generation des Xiaomi Vacuum Cleaners) ==
[[Datei:Roborock S50.png|mini]]
Voraussetzung zur Verwendung der Mappings, ist ein eingebundener Staubsauger mit dem Modul 72_XiaomiDevice.

Siehe [https://forum.fhem.de/index.php/topic,73052.0.html Forumsthread]
Das Modul muss manuell installiert werden.

Das folgende Mapping für den Roborook S50 beinhaltet neben den Characteristics der 1. Genration des Xiaomi Vacuum Cleaners weitere Custom Mappings. Diese werden auch auf dem Bild dargestellt. Falls das einem zu viele Informationen sind, können diese beim Einfügen einfach weggelassen oder in EVE ausgeblendet werden.

attr <XIAOMI> genericDeviceType switch
attr <XIAOMI> homebridgeMapping On=state,valueOn=Cleaning,cmdOn=start,cmdOff=charge
RotationSpeed=fan_power,minValue=0,maxValue=90,cmd=fan_power,delay=1
BatteryLevel=batteryPercent,maxValue=100,minValue=0,minStep=1
StatusLowBattery=batteryState,values=ok:BATTERY_LEVEL_NORMAL;;low:BATTERY_LEVEL_LOW
ChargingState=state,values=Docked:NOT_CHARGING;;Charging:CHARGING;;/.*/:NOT_CHARGEABLE
OccupancyDetected=state,values=/Docked|Charging/:OCCUPANCY_DETECTED;;/.*/:OCCUPANCY_NOT_DETECTED
2af6d0d0-3691-4f0d-9c9c-c1098295b1cb=consumables_sensors,name=Reinigung+Sensoren,minValue=0,maxValue=100,format=FLOAT,minStep=1,unit=%
fd11b965-052e-430f-b08f-206287d8bc00=consumables_filter,name=Austausch+Filter,minValue=0,maxValue=100,format=FLOAT,minStep=1,unit=%
fe7a8dac-dff3-4a07-8a5e-0d6abbf0df0c=consumables_main_brush,name=Austausch+Hauptbürste,minValue=0,maxValue=100,format=FLOAT,minStep=1,unit=%
4f9b2a22-b764-4fc1-8cd2-99383924394c=consumables_side_brush,name=Austausch+Seitenbürste,minValue=0,maxValue=100,format=FLOAT,minStep=1,unit=%
FilterLifeLevel=consumables_filter,minValue=0,maxValue=100
FilterChangeIndication=consumables_filter,values=0:CHANGE_FILTER
4896763a-26f7-400b-9734-2ce6564ceba2=total_clean_time,name=Lebenszeitersparnis,format=FLOAT,minStep=1,unit=h
82af5fd7-50a3-4ab3-81d3-1f7903de612a=total_clean_area,name=Gereinigte+Fläche,format=FLOAT,minStep=1,unit=m²
00d2ef14-b429-4569-8af3-c342d41cf383=total_cleans,name=Reinigungsvorgänge,format=FLOAT,minStep=1
e8d1027e-b068-40d5-9efd-f161b1b52774=device_firmware,name=Firmware,format=STRING

== Xiaomi Fan (ältere Generationen mit Luftfeuchtigkeits- und Temperatursensor und Battery-Readings) ==
[[Datei:Xiaomi DC Pedestal Fan.png|mini]]
Voraussetzung zur Verwendung der Mappings, ist ein eingebundener Ventilator mit dem Modul 72_XiaomiDevice.
Siehe [https://forum.fhem.de/index.php/topic,73052.0.html Forumsthread]
Das Modul muss manuell installiert werden.

Die ältere Generation enthält Sensoren und somit Readings für Luftfeuchtigkeit, Temperatur und auch Batteriestatus. Diese fehlen bei den neueren Generation dieses Ventilators, siehe Bilder. Da anscheinend jedes Jahr neue Generationen dieses Ventilators herausgekommen sind, ist nicht klar bis zu welcher Generation diese Sensoren enthalten waren.

Mit folgenden Geräten wurde folgendes Mapping erstellt und somit erfolgreich getestet:

- Xiaomi DC Pedestal Fan (FHEM model fehlt, Default Hostname am Router: zhimi-fan-v3)
- Liste bitte ergänzen!

Um möglichst viele Funktionen bereitzustellen, wurden auch Characteristics von anderen DeviceTypes verwendet. Erklärung zu den Characteristics:

- Die Kindersicherung (LockPhysicalControls) ist in Eve über das kleine Einstellungssymbol zu finden.
- Mit AudioFeedback/Audio-Bestätigung werden die Töne des Lüfters ein bzw. ausgeschaltet.
- Mit NightVision/Nachtsicht werden die LEDs ein (bright) bzw. ausgeschaltet (off).
- Mit Mute/Audio wird der Windmodus von Straight zu Natural geschaltet.
- Mit TargetTiltAngle/Neigung kann der Schwenkwinkel justiert werden.
- Mit SwingMode/Schwenken kann der Schwenkmodus ein bzw. ausgeschaltet werden.
- Der Rest ist selbsterklärend.

homebridgeMapping:

attr <XIAOMI> genericDeviceType Fan
attr <XIAOMI> homebridgeMapping
clear
On:power,cmdOn=on,cmdOff=off,valueOn=on,valueOff=off
LockPhysicalControls=child_lock,values=on:CONTROL_LOCK_ENABLED;;off:CONTROL_LOCK_DISABLED,cmds=CONTROL_LOCK_ENABLED:child_lock+on;CONTROL_LOCK_DISABLED:child_lock+off
RotationSpeed=level,minValue=0,maxValue=100,cmd=level,delay=1
TargetTiltAngle=angle,minValue=30,maxValue=120,minStep=30,cmd=angle
SwingMode=angle_enable,values=on:SWING_ENABLED;;off:SWING_DISABLED,cmdOn=angle_enable+on,cmdOff=angle_enable+off
CurrentRelativeHumidity=humidity
CurrentTemperature=temperature
BatteryLevel=batteryPercent,maxValue=100,minValue=0,minStep=1
StatusLowBattery=batteryState,values=ok:BATTERY_LEVEL_NORMAL;;low:BATTERY_LEVEL_LOW
ChargingState=charging,values=complete:NOT_CHARGING;;progress:CHARGING;;/.*/:NOT_CHARGEABLE
AudioFeedback:buzzer,cmdOn=buzzer+on,cmdOff=buzzer+off,valueOn=on,valueOff=off
NightVision:led,cmdOn=led+off,cmdOff=led+bright,valueOn=off,valueOff=bright
Mute:mode,cmdOn=mode+straight,cmdOff=mode+natural,valueOn=straight,valueOff=natural
CurrentFanState:power,values=on:BLOWING_AIR;;off:INACTIVE;;/.*/:IDLE

== Xiaomi Fan (neuere Generationen ohne Luftfeuchtigkeits- und Temperatursensor und Battery-Readings) ==
[[Datei:Xiaomi Standing Fan 2 bzw. 2S.png|mini]]
Voraussetzung zur Verwendung der Mappings, ist ein eingebundener Ventilator mit dem Modul 72_XiaomiDevice.
Siehe [https://forum.fhem.de/index.php/topic,73052.0.html Forumsthread]
Das Modul muss manuell installiert werden.

Den neueren Generationen dieses Ventilators fehlen Sensoren und somit Readings für Luftfeuchtigkeit, Temperatur und auch Batteriestatus. Diese sind bei der älteren Generation dieses Ventilators enthalten, siehe vorangegangenes Beispiel.

Dieses Mapping wurde mit dem "2S" erstellt. Es sollte aber mindestens auch mit einem "Xiaomi Standing Fan 2" (ohne Akku) funktionieren, da auch der "Xiaomi Standing Fan 2S" (mit Akku) kein Reading für die Batterie bereitstellt. Ansonsten gibt es wohl auch noch Generationen zwischen dem "Xiaomi DC Pedestal Fan" und den "Xiaomi Standing Fan 2/2S". Es ist davon auszugehen, dass dieses Beispiel genauso auch bei diesen Modellen funktioniert.

Mit folgenden Geräten wurde folgendes Mapping erstellt und somit erfolgreich getestet:

- 2019 Xiaomi Standing Fan 2S (FHEM model bzw. Default Hostname am Router: zhimi-fan-za4)
- 2018 Xiaomi ZhiMiDCVariableFrequencyFan ZRFFS01ZM (FHEM model bzw. Default Hostname am Router: zhimi-fan-za1)
- Liste bitte ergänzen!

Um möglichst viele Funktionen bereitzustellen, wurden auch Characteristics von anderen DeviceTypes verwendet. Erklärung zu den Characteristics:

- Die Kindersicherung (LockPhysicalControls) ist in Eve über das kleine Einstellungssymbol zu finden.
- Mit AudioFeedback/Audio-Bestätigung werden die Töne des Lüfters ein bzw. ausgeschaltet.
- Mit NightVision/Nachtsicht werden die LEDs ein (bright) bzw. ausgeschaltet (off).
- Mit Mute/Audio wird der Windmodus von Straight zu Natural geschaltet.
- Mit TargetTiltAngle/Neigung kann der Schwenkwinkel justiert werden.
- Mit SwingMode/Schwenken kann der Schwenkmodus ein bzw. ausgeschaltet werden.
- Der Rest ist selbsterklärend.

homebridgeMapping:

attr <XIAOMI> genericDeviceType Fan
attr <XIAOMI> homebridgeMapping
clear
On:power,cmdOn=on,cmdOff=off,valueOn=on,valueOff=off
LockPhysicalControls=child_lock,values=on:CONTROL_LOCK_ENABLED;;off:CONTROL_LOCK_DISABLED,cmds=CONTROL_LOCK_ENABLED:child_lock+on;CONTROL_LOCK_DISABLED:child_lock+off
RotationSpeed=level,minValue=0,maxValue=100,cmd=level,delay=1
TargetTiltAngle=angle,minValue=30,maxValue=120,minStep=30,cmd=angle
SwingMode=angle_enable,values=on:SWING_ENABLED;;off:SWING_DISABLED,cmdOn=angle_enable+on,cmdOff=angle_enable+off
AudioFeedback:buzzer,cmdOn=buzzer+on,cmdOff=buzzer+off,valueOn=on,valueOff=off
NightVision:led,cmdOn=led+off,cmdOff=led+bright,valueOn=off,valueOff=bright
Mute:mode,cmdOn=mode+straight,cmdOff=mode+natural,valueOn=straight,valueOff=natural
CurrentFanState:power,values=on:BLOWING_AIR;;off:INACTIVE;;/.*/:IDLE

== ZWave Türschloss Vision ZM1701 einbinden ==
Das ZWave Türschloss ZM1701 von der Firma Vision sendet seinen aktuellen Schließstatus in ein einzelnes Reading wie "lock", sondern schickt eine ganze Reihe von Informationen über den Zustand in das Reading <code>doorLockOperation</code>. Das Schließen und Öffnen der Türschlosses wird auch nicht mit einem Setzen des <code>state</code> erreicht, sondern mit dem Setzen von <code>doorLockOperation</code>. Das macht das Einbinden in homebridge nicht trivial, funktioniert aber über folgendes Homebridge-Mapping:
attr <ZM1701> genericDeviceType lock
attr <ZM1701> homebridgeMapping LockCurrentState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED LockTargetState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED,cmds=SECURED:doorLockOperation+close;UNSECURED:doorLockOperation+open

Kurz zur Erklärung: Um ein Schloss über HomeKit steuern zu können braucht es zwei characteristics. LockCurrentState zeigt an, ob das Schloss geöffnet oder geschlossen ist. Und mit LockTargetState wird das Schloss geöffnet oder geschlossen. Damit der aktuelle Status des Schlosses ausgelesen werden kann, muss aus dem FHEM-Reading <code>doorLockOperation</code> die Zeichenfolge <code> secured</code> oder <code>unsecured</code> extrahiert werden, daher die beiden regulären Ausdrücke <code>/\ssecured/</code> und <code>/unsecured/</code>. In der characteristic <code>LockTargetState</code> muss sowohl der aktuelle Status des Schlosses als auch das Kommando angegeben werden, schließlich möchte man ein geschlossenes Schloss nicht nochmal schließen. Daher wird erst aus dem Reading <code>doorLockOperation</code> der aktuelle Status des Schlosses ausgelesen und die damit korrespondierenden Befehle über <code>cmds=SECURED:doorLockOperation+close;UNSECURED:doorLockOperation+open</code> generiert.

Wer es in FHEM über ein webCmd einfacher zu bedienen haben möchte, fügt bitte noch die dafür notwendigen Attribute und die leicht geänderten homebridgeMappings wie folgt ein:
attr <ZM1701> genericDeviceType lock
attr <ZM1701> homebridgeMapping LockCurrentState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED LockTargetState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED,cmds=SECURED:close;UNSECURED:open
attr <ZM1701> /doorLockOperation open:open/doorLockOperation close:close
attr <ZM1701> webCmd open:close

Getestet mit
FHEM 5.7 Rev. 12191
homebridge 0.4.6
homebridge-fhem 0.2.48

[[Kategorie:HOWTOS]]
[[Kategorie:Code Snippets]]

Homebridge User Configs

2019-06-25T14:54:53Z

Hoppel118: Bravia Fernseher und Wetterstation aus der Homebridge-Konfiguration entfernt und hier ergänzt, kleinere Umsortierung vorgenommen, Dieser Artikel benötigt eine völlig andere Struktur.

Dieser Eintrag dient zur Sammlung funktionsfähiger Homebridge Configs.

Bitte immer die FHEM Version und Homebridge Version angegeben.

Sehr gute Hinweise gibt es hier: http://www.meintechblog.de/2015/10/mit-siri-und-fhem-das-gesamte-smart-home-per-stimme-steuern/
== Mögliche Mappings ==
Die Möglichen Mappings können hier nachgelesen werden https://github.com/KhaosT/HAP-NodeJS/blob/master/lib/gen/HomeKitTypes.js

Hier ein Beispiel:
Characteristic.Brightness = function() {
Characteristic.call(this, 'Brightness', '00000008-0000-1000-8000-0026BB765291');
this.setProps({
format: Characteristic.Formats.INT,
unit: Characteristic.Units.PERCENTAGE,
maxValue: 100,
minValue: 0,
minStep: 1,
perms: [Characteristic.Perms.READ, Characteristic.Perms.WRITE, Characteristic.Perms.NOTIFY]
});
this.value = this.getDefaultValue();
};

Das Mapping in diesem Fall, hat den Titel Brightness.

Die Werte können in 1er Schritten zwischen 0 und 100 liegen (max und min Value)
== Feuchtesensor ==
Zum Einstieg etwas leicht nachvollziehbares.

Feuchtesensoren haben in der Regel ein "humidity" Reading, im Falle des Opus XT300 Bodenfeuchtesensors auch Temperatur und Batterie Level. Homekit unterstützt einen "HumiditySensor" Service. Dieser ist in homebridge-fhem nicht standardmäßig vorhanden (kann also nicht aus dem dropdown ausgewählt werden, sondern muss über das Befehlsfeld zugewiesen werden):

<code>attr meinSensor genericDeviceType HumiditySensor</code>

Im nächsten Schritt werden die Readings gemappt:

<code>attr meinSensor homebridgeMapping clear CurrentRelativeHumidity=humidity StatusLowBattery=battery,values=ok:BATTERY_LEVEL_NORMAL;;/^.*/:BATTERY_LEVEL_LOW CurrentTemperature=temperature</code>

<code>clear</code>löscht default mappings - das wird in der Regel nicht notwendig sein, schadet aber nicht

<code>CurrentRelativeHumidity</code> ist die relevante Homekit Characteristic - wird mit dem entsprechenden Reading des Sensors gemappt.

<code>StatusLowBattery</code> erwartet entweder BATTERY_LEVEL_NORMAL oder _LOW. Mein Sensor liefert ok zurück, wenn alles gut ist, also wird "ok" auf _NORMAL gemappt, alles andere auf _LOW.

Der Opus XT300 Bodenfeuchtesensors liefert auch noch die Temperatur - der HumiditySensor Service sieht das eigentlich nicht vor, daher wird die Temperatur auch nicht in der Apple "Home" App angezeigt. Bei Eve wird die Temperatur hingegen berücksichtigt.

== BRAVIA Fernseher ==
Ein Beispiel homebridgeMapping für Sony Bravia Fernseher (iOS 12.2 beta!) und genericDeviceType Television:
<pre>
clear
ConfiguredName:model
Active:state,values=off:INACTIVE;on:ACTIVE,cmds=ACTIVE:on;INACTIVE:off
RemoteKey:key,cmds=REWIND:remoteControl+Rewind;FAST_FORWARD:remoteControl+FastForward;NEXT_TRACK:remoteControl+NEXT_TRACK;PREVIOUS_TRACK:remoteControl+PREVIOUS_TRACK;ARROW_UP:remoteControl+Up;ARROW_DOWN:remoteControl+Down;ARROW_LEFT:remoteControl+Left;ARROW_RIGHT:remoteControl+Right;SELECT:remoteControl+Ok;BACK:remoteControl+RETURN;EXIT:remoteControl+Exit;PLAY_PAUSE:remoteControl+Play;INFORMATION:remoteControl+Info
SleepDiscoveryMode:default=ALWAYS_DISCOVERABLE
ClosedCaptions:default=0
DisplayOrder:default=Test1
CurrentMediaState:default=0:currentTitle
TargetMediaState:default=0,cmds=PLAY:remoteControl+play;PAUSE:remoteControl+pause;STOP:remoteControl+stop;
PictureMode:default=1
PowerModeSelection:default=1,cmds=0:remoteControl+options
ActiveIdentifier:input,default=0,values=/tv.dvbt|TV...DVB-T/:1;/HDMI.3/:2,cmds=1:input+TV+/+DVB-T;2:input+HDMI+3/ARC;3:application+Plex
TelevisionSpeaker#Mute=mute
Active:default=ACTIVE
VolumeSelector:volume,cmds=INCREMENT:VolumeUp;DECREMENT:VolumeDown
VolumeControlType:default=RELATIVE_WITH_CURRENT
linkedTo=Television
InputSource(1)#Identifier:default=1
ConfiguredName:default=TV
IsConfigured:default=CONFIGURED
InputSourceType:default=TUNER
CurrentVisibilityState:default=SHOWN
linkedTo=Television
InputSource(2)#Identifier:default=2
ConfiguredName:default=APPLE+TV
IsConfigured:default=CONFIGURED
InputSourceType:default=HDMI
CurrentVisibilityState:default=SHOWN
linkedTo=Television
InputSource(3)#Identifier:default=3
ConfiguredName:default=PLEX
IsConfigured:default=CONFIGURED
InputSourceType:default=APPLICATION
CurrentVisibilityState:default=SHOWN
linkedTo=Television
</pre>

damit lässt sich der Fernseher über Siri/Homekit ein- und ausschalten sowie über das appleTV Control-Center Widget steuern.

== EnOcean STM 250 Tür-/Fensterkontakt ==
Der STM 250 liefert als Status in FHEM <code>open</code>, wenn das Fenster offen und damit der Kontakt "offen" ist. Analog liefert er <code>closed</code> wenn das Fenster geschlossen und damit auch der Kontakt geschlossen ist. Diese Statusangaben sind sehr intuitiv zu verstehen und zu interpretieren.

Die characteristic <code>ContactSensorState</code> von HomeKit liefert entweder den Wert <code>CONTACT_DETECTED=0</code> oder <code>CONTACT_NOT_DETECTED=1</code> zurück. Wobei <code>CONTACT_DETECTED</code> bedeutet, dass der Kontakt geschlossen ist. Je nach Darstellung in der HomeKit-fähigen App muss dieses Verhalten bei der Interpretation berücksichtigt werden. Die App Eve von Elgato zum Beispiel liefert für Kontaktsensoren "JA" oder "NEIN" mit der Bedeutung <code>CONTACT_DETECTED=0=JA</code> bzw. <code>CONTACT_NOT_DETECTED=1=NEIN</code> zurück.

Noch ein wichtiger Punkt: Um einen Sensorkontakt sinnvoll einzurichten sollte als zusätzlicher Wert für das Attribut <code>genericdeviceType</code> der Wert <code>ContactSensor</code> hinzugefügt werden. Wie das geht ist im Eintrag [[Homebridge_einrichten#FHEM_konfigurieren | Homebridge einrichten]] ausführlicher beschrieben.

Folgende Attribute dann hinzufügen:
attr STM250 genericDeviceType ContactSensor
attr STM250 homebridgeMapping ContactSensorState=state,values=closed:CONTACT_DETECTED;open:CONTACT_NOT_DETECTED

Getestet mit
FHEM 5.7 Rev. 9893
Homebridge 0.2.16
homebridge-fhem Vorschauversion aus {{Link2Forum|Topic=48558|Message=402024|LinkText=homebridge/homekit}}

== Modul RESIDENTS für Anwesenheitserkennung und Steuerung der Anwesenheit benutzen ==
[[Datei:Homebridge_bewohner_zu_szene.jpeg|mini|Schaltzustand eines Bewohners zu einer Szene hinzufügen]]
Aus den einzelnen Komponenten des Moduls RESIDENTS, homebridge sowie der characteristic <code>On</code> und der Szenensteuerung lässt sich eine gleichzeitige Steuerung der Anwesenheit und Anwesenheitserkennung basteln.

Dazu müssen folgende Schritte unternommen werden:
* einem Bewohner aus dem Modul ROOMMATE die Steuerung über homebridgeMapping hinzufügen
* Szene für "Ich bin zu Hause" und "Ich gehe jetzt" in einer HomeKit-fähigen App wie z.B. Eve einrichten

Man kann einen beliebigen Bewohner aus dem Modul ROOMMATE nehmen und ihn über die characteristic <code>On</code> in Form eines Schalters sozusagen schaltbar machen. Nur wird das Ein- und Ausschalten des Bewohners über HomeKit in FHEM auf den Status home bzw. absent gemappt. Seit dem 06.02.2016 werden RESIDENTS automatisch als Occupancy Sensor für HomeKit annonciert. Nun noch die Attribute des ROOMMATE wie folgt setzen:
attr <ROOMMATE> genericDeviceType switch
attr <ROOMMATE> homebridgeMapping On=state,valueOn=/home|awoken|asleep|gotosleep/,valueOff=/gone|absent/,cmdOn=home,cmdOff=absent

Natürlich muss der Bewohner noch dem Filter von homebridge hinzugefügt und homebridge neu gestartet werden.

Anschließend geht es in der HomeKit-fähigen App Deiner Wahl weiter. In Eve von Elgato ist von vornherein zum Beispiel vorgesehen, dass man zwei Szenen "Ich bin zuhause" und "Ich verlasse das Haus" hat. Zu diesen Szenen wird eine Aktion hinzugefügt indem der Bewohner, den das ROOMMATE-Modul meldet zur Szene hinzugefügt wird und beim Nachhausekommen "eingeschaltet" wird. Genauso wird mit der Szene "Ich verlasse das Haus" verfahren: Bewohner zur Szene hinzufügen und den Schaltvorgang auf "ausschalten" setzen.

Mit den Sprachbefehlen "Ich bin zuhause" oder "Ich verlasse das Haus" wird die entsprechende Szene eingeschaltet, homebridge schaltet über das <code>homebridgeMapping</code> Attribut dann den Bewohner auf "home" oder "absent".

Getestet mit
FHEM 5.7 Rev. 9893
Homebridge 0.2.16
homebridge-fhem Vorschauversion aus {{Link2Forum|Topic=48558|Message=402024|LinkText=homebridge/homekit}}

Eine noch etwas bessere Schaltmöglichkeit bietet '''genericDeviceType security'''.
Das Mapping für ROOMMATE sieht wie folgt aus:
attr TYPE=ROOMMATE genericDeviceType security
attr TYPE=ROOMMATE homebridgeMapping SecuritySystemCurrentState=state,values=/home|awoken/:0;;absent:1;;/asleep|gotosleep/:2;;gone:3 SecuritySystemTargetState=SecuritySystemCurrentState,cmds=0:state+home;;1:state+absent;;2:state+gotosleep;;3:state+gone,delay=1
für GUEST:
attr TYPE=GUEST genericDeviceType security
attr TYPE=GUEST homebridgeMapping SecuritySystemCurrentState=state,values=/home|awoken/:0;;absent:1;;/asleep|gotosleep/:2;;none:3 SecuritySystemTargetState=SecuritySystemCurrentState,cmds=0:state+home;;1:state+absent;;2:state+gotosleep;;3:state+none,delay=1

== ZWave Türschloss Vision ZM1701 einbinden ==
Das ZWave Türschloss ZM1701 von der Firma Vision sendet seinen aktuellen Schließstatus in ein einzelnes Reading wie "lock", sondern schickt eine ganze Reihe von Informationen über den Zustand in das Reading <code>doorLockOperation</code>. Das Schließen und Öffnen der Türschlosses wird auch nicht mit einem Setzen des <code>state</code> erreicht, sondern mit dem Setzen von <code>doorLockOperation</code>. Das macht das Einbinden in homebridge nicht trivial, funktioniert aber über folgendes Homebridge-Mapping:
attr <ZM1701> genericDeviceType lock
attr <ZM1701> homebridgeMapping LockCurrentState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED LockTargetState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED,cmds=SECURED:doorLockOperation+close;UNSECURED:doorLockOperation+open

Kurz zur Erklärung: Um ein Schloss über HomeKit steuern zu können braucht es zwei characteristics. LockCurrentState zeigt an, ob das Schloss geöffnet oder geschlossen ist. Und mit LockTargetState wird das Schloss geöffnet oder geschlossen. Damit der aktuelle Status des Schlosses ausgelesen werden kann, muss aus dem FHEM-Reading <code>doorLockOperation</code> die Zeichenfolge <code> secured</code> oder <code>unsecured</code> extrahiert werden, daher die beiden regulären Ausdrücke <code>/\ssecured/</code> und <code>/unsecured/</code>. In der characteristic <code>LockTargetState</code> muss sowohl der aktuelle Status des Schlosses als auch das Kommando angegeben werden, schließlich möchte man ein geschlossenes Schloss nicht nochmal schließen. Daher wird erst aus dem Reading <code>doorLockOperation</code> der aktuelle Status des Schlosses ausgelesen und die damit korrespondierenden Befehle über <code>cmds=SECURED:doorLockOperation+close;UNSECURED:doorLockOperation+open</code> generiert.

Wer es in FHEM über ein webCmd einfacher zu bedienen haben möchte, fügt bitte noch die dafür notwendigen Attribute und die leicht geänderten homebridgeMappings wie folgt ein:
attr <ZM1701> genericDeviceType lock
attr <ZM1701> homebridgeMapping LockCurrentState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED LockTargetState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED,cmds=SECURED:close;UNSECURED:open
attr <ZM1701> /doorLockOperation open:open/doorLockOperation close:close
attr <ZM1701> webCmd open:close

Getestet mit
FHEM 5.7 Rev. 12191
homebridge 0.4.6
homebridge-fhem 0.2.48

== Homematic SmokeDetector HM-SEC-SD und HM-SEC-SD2 ==
[[Datei:Homebridge-Homematic-Smokedetector-Gen1.jpg|mini|Homebridge-Homematic-Smokedetector-Gen1 in EVE]]
Es sind keine Homebridge Mappings für die Rauch Meldung erforderlich.

Allerdings ist ein Mapping für den Batterie Zustand nötig, siehe Unten.

attr <SmokeDetector> genericDeviceType SmokeSensor
attr <SmokeDetector> subType smokeDetector

attr <SmokeDetector> homebridgeMapping StatusLowBattery=battery,values=ok:BATTERY_LEVEL_NORMAL;;/^.*/:BATTERY_LEVEL_LOW

== Homematic Heizkörperthermostat HM-CC-RT-DN ==
[[Datei:HM-CC-RT-DN-Eve.PNG|mini|Darstellung des HM-CC-RT-DN in der iOS App Eve]]
attr <HMCCRTDN_Channel2_Clima> homebridgeMapping TargetTemperature=desired-temp::desired-temp,minValue=5,maxValue=35,minStep=0.5,nocache=1
CurrentTemperature=BU_Heizung_01_Clima:measured-temp,nocache=1
StatusLowBattery=BU_Heizung_01:battery,values=ok:BATTERY_LEVEL_NORMAL;;/^.*/:BATTERY_LEVEL_LOW
TargetHeatingCoolingState=heatingState,values=OFF:0;;HEAT:1;;COOL:2;;AUTO:3,cmds=OFF:controlManu+off;;HEAT:controlMode+boost;;AUTO:controlMode+auto;;COOL:controlManu+17.0
CurrentHeatingCoolingState=heatingState,values=OFF:0;;HEAT:1;;COOL:2;;AUTO:0,valud=OFF
attr <HMCCRTDN_Channel2_Clima> siriName Robby
Dieses Mapping bezieht sich auf ein vorhandenes ''userReading'' mit dem Namen <code>heatingState</code>, womit Homekit die einzelnen Status nachher unterscheidet.
attr <HM-CC-RT-DN_Clima> userReadings heatingState {(ReadingsVal($NAME,"ValvePosition",0) > 0 || ReadingsVal($NAME,"desired-temp","-") eq "on") ? "HEAT" : ReadingsVal($NAME,"desired-temp","-") eq "off" ? "OFF" : ReadingsVal($NAME,"controlMode","auto") eq "auto" ? "AUTO" : (ReadingsVal($NAME,"measured-temp",20) > ReadingsVal($NAME,"desired-temp",20)) ? "COOL" : "AUTO"}
Global auf alle in FHEM angelegten HM-CC-RT-DN, lässt sich mit folgendem Befehl das ''userReading'' anlegen.
Siehe [https://forum.fhem.de/index.php/topic,59211.msg505986.html#msg505986 Forumsthread].

attr TYPE=CUL_HM:FILTER=model=HM-CC-RT-DN:FILTER=chanNo=04 userReadings heatingState {(ReadingsVal($NAME,"ValvePosition",0) > 0 || ReadingsVal($NAME,"desired-temp","-") eq "on") ? "HEAT" : ReadingsVal($NAME,"desired-temp","-") eq "off" ? "OFF" : ReadingsVal($NAME,"controlMode","auto") eq "auto" ? "AUTO" : (ReadingsVal($NAME,"measured-temp",20) > ReadingsVal($NAME,"desired-temp",20)) ? "COOL" : "AUTO"}

== Homematic Wetterstation OC3 HM-WDS100-C6-O-2 ==
[[Datei: homebridge-wetter.jpg|mini|Wetterstation in EVE]]
Mit der EVE und den hier: [https://github.com/naofireblade/homebridge-weather-plus/blob/master/util/characteristics.js] beschriebenen Characteristics lässt sich eine lokale Homematic OC3 Wetterstation aus FHEM einbinden:
<pre>
clear
CurrentTemperature:temperature
CurrentRelativeHumidity:humidity
49C8AE5A-A3A5-41AB-BF1F-12D5654F9F41:windSpeed,name=WINDGESCHWINDIGKEIT,format=FLOAT,unit=kmh,maxValue=250,minValue=0,minStep=1
46f1284c-1912-421b-82f5-eb75008b167e:windDirection,name=WINDRICHTUNG,format=UINT8,unit=ARC_DEGREE,maxValue=360,minValue=0,minStep=1
StatusLowBattery:battery,values=ok:BATTERY_LEVEL_NORMAL;/^.*/:BATTERY_LEVEL_LOW
ccc04890-565b-4376-b39a-3113341d9e0f:RegenmengeLast24Hours:state,name=REGEN_24h,format=FLOAT,unit=mm,maxValue=100,minValue=0,minStep=1
10c88f40-7ec4-478c-8d5a-bd0c3cce14b7:RegenmengeLast1Hours:state,name=REGEN_1h,format=FLOAT,unit=mm,maxValue=100,minValue=0,minStep=1
0000006B-0000-1000-8000-0026BB765291:brightness,name=BRIGHTNESS,format=FLOAT,unit=LUX,maxValue=10000,minValue=0,minStep=.0001
cd65a9ab-85ad-494a-b2bd-2f380084134c:isRaining,name=BEDINGUNGKATEGORIE,values=0:0;1:2,format=UINT8,maxValue=3,minValue=0,minStep=1
cd65a9ab-85ad-494a-b2bd-2f380084134d:isRaining,name=BEDINGUNG,format=STRING,values=0:-;/.*/:Regen
</pre>

== Roomba über THINKINGCLEANER Modul ==
attr <THINKINGCLEANER> genericDeviceType switch
attr <THINKINGCLEANER> homebridgeMapping clear On=state,valueOn=/^(on|dock)/,cmdOn=on,cmdOff=off,nocache=1 ChargingState=deviceStatus,values=/(_recon|_full|_trickle)$/:CHARGING;/^.*/:NOT_CHARGING
attr <THINKINGCLEANER> siriName Robby

Getestet mit
FHEM 5.7 Rev. 12680
homebridge 0.4.11
homebridge-fhem 0.2.66

== Vallox Belüftungsanlage ==
Die Steuerung der Lüftungsgeschwindigkeit ist nur in Prozent möglich. Die Umrechnung erfolgt im [[Vallox]] Modul.
Hierzu wurde das Reading ''FanSpeedPct'' hinzugefügt.

attr <Vallox> genericDeviceType Fan
attr <Vallox> homebridgeMapping clear
model=Vallox
On=PowerState,valueOn=1,readOnly=1
RotationSpeed=FanSpeedPct,minValue=1,maxValue=100,cmd=FanSpeedPct,delay=1

== Xiaomi Vacuum Cleaner 1. Generation ==
[[Datei:XIAOMI_VACUUM_CLEANER-Gen1.jpg|mini|XIAOMI VACUUM 1. GEN in EVE]]
Voraussetzung zur Verwendung der Mappings, ist ein eingebundener Staubsauger mit dem Modul 72_XiaomiDevice.

Siehe [https://forum.fhem.de/index.php/topic,73052.0.html Forumsthread]
Das Modul muss manuell installiert werden.

attr <XIAOMI> genericDeviceType switch
attr <XIAOMI> homebridgeMapping On=state,valueOn=Cleaning,cmdOn=start,cmdOff=charge
RotationSpeed=fan_power,minValue=0,maxValue=90,cmd=fan_power,delay=1
BatteryLevel=batteryLevel,maxValue=100,minValue=0,minStep=1
StatusLowBattery=battery,values=ok:BATTERY_LEVEL_NORMAL;;low:BATTERY_LEVEL_LOW
ChargingState=state,values=Docked:NOT_CHARGING;;Charging:CHARGING;;/.*/:NOT_CHARGEABLE
OccupancyDetected=state,values=/Docked|Charging/:OCCUPANCY_DETECTED;;/.*/:OCCUPANCY_NOT_DETECTED
FilterLifeLevel=consumables_filter,minValue=0,maxValue=100
FilterChangeIndication=consumables_filter,values=0:CHANGE_FILTER

== Roborock S50 (2. Generation des Xiaomi Vacuum Cleaners) ==
[[Datei:Roborock S50.png|mini]]
Voraussetzung zur Verwendung der Mappings, ist ein eingebundener Staubsauger mit dem Modul 72_XiaomiDevice.

Siehe [https://forum.fhem.de/index.php/topic,73052.0.html Forumsthread]
Das Modul muss manuell installiert werden.

Das folgende Mapping für den Roborook S50 beinhaltet neben den Characteristics der 1. Genration des Xiaomi Vacuum Cleaners weitere Custom Mappings. Diese werden auch auf dem Bild dargestellt. Falls das einem zu viele Informationen sind, können diese beim Einfügen einfach weggelassen oder in EVE ausgeblendet werden.

attr <XIAOMI> genericDeviceType switch
attr <XIAOMI> homebridgeMapping On=state,valueOn=Cleaning,cmdOn=start,cmdOff=charge
RotationSpeed=fan_power,minValue=0,maxValue=90,cmd=fan_power,delay=1
BatteryLevel=batteryPercent,maxValue=100,minValue=0,minStep=1
StatusLowBattery=batteryState,values=ok:BATTERY_LEVEL_NORMAL;;low:BATTERY_LEVEL_LOW
ChargingState=state,values=Docked:NOT_CHARGING;;Charging:CHARGING;;/.*/:NOT_CHARGEABLE
OccupancyDetected=state,values=/Docked|Charging/:OCCUPANCY_DETECTED;;/.*/:OCCUPANCY_NOT_DETECTED
2af6d0d0-3691-4f0d-9c9c-c1098295b1cb=consumables_sensors,name=Reinigung+Sensoren,minValue=0,maxValue=100,format=FLOAT,minStep=1,unit=%
fd11b965-052e-430f-b08f-206287d8bc00=consumables_filter,name=Austausch+Filter,minValue=0,maxValue=100,format=FLOAT,minStep=1,unit=%
fe7a8dac-dff3-4a07-8a5e-0d6abbf0df0c=consumables_main_brush,name=Austausch+Hauptbürste,minValue=0,maxValue=100,format=FLOAT,minStep=1,unit=%
4f9b2a22-b764-4fc1-8cd2-99383924394c=consumables_side_brush,name=Austausch+Seitenbürste,minValue=0,maxValue=100,format=FLOAT,minStep=1,unit=%
FilterLifeLevel=consumables_filter,minValue=0,maxValue=100
FilterChangeIndication=consumables_filter,values=0:CHANGE_FILTER
4896763a-26f7-400b-9734-2ce6564ceba2=total_clean_time,name=Lebenszeitersparnis,format=FLOAT,minStep=1,unit=h
82af5fd7-50a3-4ab3-81d3-1f7903de612a=total_clean_area,name=Gereinigte+Fläche,format=FLOAT,minStep=1,unit=m²
00d2ef14-b429-4569-8af3-c342d41cf383=total_cleans,name=Reinigungsvorgänge,format=FLOAT,minStep=1
e8d1027e-b068-40d5-9efd-f161b1b52774=device_firmware,name=Firmware,format=STRING

== Xiaomi Fan (ältere Generationen mit Luftfeuchtigkeits- und Temperatursensor und Battery-Readings) ==
[[Datei:Xiaomi DC Pedestal Fan.png|mini]]
Voraussetzung zur Verwendung der Mappings, ist ein eingebundener Ventilator mit dem Modul 72_XiaomiDevice.
Siehe [https://forum.fhem.de/index.php/topic,73052.0.html Forumsthread]
Das Modul muss manuell installiert werden.

Die ältere Generation enthält Sensoren und somit Readings für Luftfeuchtigkeit, Temperatur und auch Batteriestatus. Diese fehlen bei den neueren Generation dieses Ventilators, siehe Bilder. Da anscheinend jedes Jahr neue Generationen dieses Ventilators herausgekommen sind, ist nicht klar bis zu welcher Generation diese Sensoren enthalten waren.

Mit folgenden Geräten wurde folgendes Mapping erstellt und somit erfolgreich getestet:

- Xiaomi DC Pedestal Fan (FHEM model fehlt, Default Hostname am Router: zhimi-fan-v3)
- Liste bitte ergänzen!

Um möglichst viele Funktionen bereitzustellen, wurden auch Characteristics von anderen DeviceTypes verwendet. Erklärung zu den Characteristics:

- Die Kindersicherung (LockPhysicalControls) ist in Eve über das kleine Einstellungssymbol zu finden.
- Mit AudioFeedback/Audio-Bestätigung werden die Töne des Lüfters ein bzw. ausgeschaltet.
- Mit NightVision/Nachtsicht werden die LEDs ein (bright) bzw. ausgeschaltet (off).
- Mit Mute/Audio wird der Windmodus von Straight zu Natural geschaltet.
- Mit TargetTiltAngle/Neigung kann der Schwenkwinkel justiert werden.
- Mit SwingMode/Schwenken kann der Schwenkmodus ein bzw. ausgeschaltet werden.
- Der Rest ist selbsterklärend.

homebridgeMapping:

attr <XIAOMI> genericDeviceType Fan
attr <XIAOMI> homebridgeMapping
clear
On:power,cmdOn=on,cmdOff=off,valueOn=on,valueOff=off
LockPhysicalControls=child_lock,values=on:CONTROL_LOCK_ENABLED;;off:CONTROL_LOCK_DISABLED,cmds=CONTROL_LOCK_ENABLED:child_lock+on;CONTROL_LOCK_DISABLED:child_lock+off
RotationSpeed=level,minValue=0,maxValue=100,cmd=level,delay=1
TargetTiltAngle=angle,minValue=30,maxValue=120,minStep=30,cmd=angle
SwingMode=angle_enable,values=on:SWING_ENABLED;;off:SWING_DISABLED,cmdOn=angle_enable+on,cmdOff=angle_enable+off
CurrentRelativeHumidity=humidity
CurrentTemperature=temperature
BatteryLevel=batteryPercent,maxValue=100,minValue=0,minStep=1
StatusLowBattery=batteryState,values=ok:BATTERY_LEVEL_NORMAL;;low:BATTERY_LEVEL_LOW
ChargingState=charging,values=complete:NOT_CHARGING;;progress:CHARGING;;/.*/:NOT_CHARGEABLE
AudioFeedback:buzzer,cmdOn=buzzer+on,cmdOff=buzzer+off,valueOn=on,valueOff=off
NightVision:led,cmdOn=led+off,cmdOff=led+bright,valueOn=off,valueOff=bright
Mute:mode,cmdOn=mode+straight,cmdOff=mode+natural,valueOn=straight,valueOff=natural
CurrentFanState:power,values=on:BLOWING_AIR;;off:INACTIVE;;/.*/:IDLE

== Xiaomi Fan (neuere Generationen ohne Luftfeuchtigkeits- und Temperatursensor und Battery-Readings) ==
[[Datei:Xiaomi Standing Fan 2 bzw. 2S.png|mini]]
Voraussetzung zur Verwendung der Mappings, ist ein eingebundener Ventilator mit dem Modul 72_XiaomiDevice.
Siehe [https://forum.fhem.de/index.php/topic,73052.0.html Forumsthread]
Das Modul muss manuell installiert werden.

Den neueren Generationen dieses Ventilators fehlen Sensoren und somit Readings für Luftfeuchtigkeit, Temperatur und auch Batteriestatus. Diese sind bei der älteren Generation dieses Ventilators enthalten, siehe vorangegangenes Beispiel.

Dieses Mapping wurde mit dem "2S" erstellt. Es sollte aber mindestens auch mit einem "Xiaomi Standing Fan 2" (ohne Akku) funktionieren, da auch der "Xiaomi Standing Fan 2S" (mit Akku) kein Reading für die Batterie bereitstellt. Ansonsten gibt es wohl auch noch Generationen zwischen dem "Xiaomi DC Pedestal Fan" und den "Xiaomi Standing Fan 2/2S". Es ist davon auszugehen, dass dieses Beispiel genauso auch bei diesen Modellen funktioniert.

Mit folgenden Geräten wurde folgendes Mapping erstellt und somit erfolgreich getestet:

- 2019 Xiaomi Standing Fan 2S (FHEM model bzw. Default Hostname am Router: zhimi-fan-za4)
- 2018 Xiaomi ZhiMiDCVariableFrequencyFan ZRFFS01ZM (FHEM model bzw. Default Hostname am Router: zhimi-fan-za1)
- Liste bitte ergänzen!

Um möglichst viele Funktionen bereitzustellen, wurden auch Characteristics von anderen DeviceTypes verwendet. Erklärung zu den Characteristics:

- Die Kindersicherung (LockPhysicalControls) ist in Eve über das kleine Einstellungssymbol zu finden.
- Mit AudioFeedback/Audio-Bestätigung werden die Töne des Lüfters ein bzw. ausgeschaltet.
- Mit NightVision/Nachtsicht werden die LEDs ein (bright) bzw. ausgeschaltet (off).
- Mit Mute/Audio wird der Windmodus von Straight zu Natural geschaltet.
- Mit TargetTiltAngle/Neigung kann der Schwenkwinkel justiert werden.
- Mit SwingMode/Schwenken kann der Schwenkmodus ein bzw. ausgeschaltet werden.
- Der Rest ist selbsterklärend.

homebridgeMapping:

attr <XIAOMI> genericDeviceType Fan
attr <XIAOMI> homebridgeMapping
clear
On:power,cmdOn=on,cmdOff=off,valueOn=on,valueOff=off
LockPhysicalControls=child_lock,values=on:CONTROL_LOCK_ENABLED;;off:CONTROL_LOCK_DISABLED,cmds=CONTROL_LOCK_ENABLED:child_lock+on;CONTROL_LOCK_DISABLED:child_lock+off
RotationSpeed=level,minValue=0,maxValue=100,cmd=level,delay=1
TargetTiltAngle=angle,minValue=30,maxValue=120,minStep=30,cmd=angle
SwingMode=angle_enable,values=on:SWING_ENABLED;;off:SWING_DISABLED,cmdOn=angle_enable+on,cmdOff=angle_enable+off
AudioFeedback:buzzer,cmdOn=buzzer+on,cmdOff=buzzer+off,valueOn=on,valueOff=off
NightVision:led,cmdOn=led+off,cmdOff=led+bright,valueOn=off,valueOff=bright
Mute:mode,cmdOn=mode+straight,cmdOff=mode+natural,valueOn=straight,valueOff=natural
CurrentFanState:power,values=on:BLOWING_AIR;;off:INACTIVE;;/.*/:IDLE

[[Kategorie:HOWTOS]]
[[Kategorie:Code Snippets]]

Homebridge User Configs

2019-06-20T22:48:21Z

Hoppel118: Anpassungen an den Xiaomi Ventilatoren

Dieser Eintrag dient zur Sammlung funktionsfähiger Homebridge Configs.

Bitte immer die FHEM Version und Homebridge Version angegeben.

Sehr gute Hinweise gibt es hier: http://www.meintechblog.de/2015/10/mit-siri-und-fhem-das-gesamte-smart-home-per-stimme-steuern/
== Mögliche Mappings ==
Die Möglichen Mappings können hier nachgelesen werden https://github.com/KhaosT/HAP-NodeJS/blob/master/lib/gen/HomeKitTypes.js

Hier ein Beispiel:
Characteristic.Brightness = function() {
Characteristic.call(this, 'Brightness', '00000008-0000-1000-8000-0026BB765291');
this.setProps({
format: Characteristic.Formats.INT,
unit: Characteristic.Units.PERCENTAGE,
maxValue: 100,
minValue: 0,
minStep: 1,
perms: [Characteristic.Perms.READ, Characteristic.Perms.WRITE, Characteristic.Perms.NOTIFY]
});
this.value = this.getDefaultValue();
};

Das Mapping in diesem Fall, hat den Titel Brightness.

Die Werte können in 1er Schritten zwischen 0 und 100 liegen (max und min Value)
== Feuchtesensor ==
Zum Einstieg etwas leicht nachvollziehbares.

Feuchtesensoren haben in der Regel ein "humidity" Reading, im Falle des Opus XT300 Bodenfeuchtesensors auch Temperatur und Batterie Level. Homekit unterstützt einen "HumiditySensor" Service. Dieser ist in homebridge-fhem nicht standardmäßig vorhanden (kann also nicht aus dem dropdown ausgewählt werden, sondern muss über das Befehlsfeld zugewiesen werden):

<code>attr meinSensor genericDeviceType HumiditySensor</code>

Im nächsten Schritt werden die Readings gemappt:

<code>attr meinSensor homebridgeMapping clear CurrentRelativeHumidity=humidity StatusLowBattery=battery,values=ok:BATTERY_LEVEL_NORMAL;;/^.*/:BATTERY_LEVEL_LOW CurrentTemperature=temperature</code>

<code>clear</code>löscht default mappings - das wird in der Regel nicht notwendig sein, schadet aber nicht

<code>CurrentRelativeHumidity</code> ist die relevante Homekit Characteristic - wird mit dem entsprechenden Reading des Sensors gemappt.

<code>StatusLowBattery</code> erwartet entweder BATTERY_LEVEL_NORMAL oder _LOW. Mein Sensor liefert ok zurück, wenn alles gut ist, also wird "ok" auf _NORMAL gemappt, alles andere auf _LOW.

Der Opus XT300 Bodenfeuchtesensors liefert auch noch die Temperatur - der HumiditySensor Service sieht das eigentlich nicht vor, daher wird die Temperatur auch nicht in der Apple "Home" App angezeigt. Bei Eve wird die Temperatur hingegen berücksichtigt.

== EnOcean STM 250 Tür-/Fensterkontakt ==
Der STM 250 liefert als Status in FHEM <code>open</code>, wenn das Fenster offen und damit der Kontakt "offen" ist. Analog liefert er <code>closed</code> wenn das Fenster geschlossen und damit auch der Kontakt geschlossen ist. Diese Statusangaben sind sehr intuitiv zu verstehen und zu interpretieren.

Die characteristic <code>ContactSensorState</code> von HomeKit liefert entweder den Wert <code>CONTACT_DETECTED=0</code> oder <code>CONTACT_NOT_DETECTED=1</code> zurück. Wobei <code>CONTACT_DETECTED</code> bedeutet, dass der Kontakt geschlossen ist. Je nach Darstellung in der HomeKit-fähigen App muss dieses Verhalten bei der Interpretation berücksichtigt werden. Die App Eve von Elgato zum Beispiel liefert für Kontaktsensoren "JA" oder "NEIN" mit der Bedeutung <code>CONTACT_DETECTED=0=JA</code> bzw. <code>CONTACT_NOT_DETECTED=1=NEIN</code> zurück.

Noch ein wichtiger Punkt: Um einen Sensorkontakt sinnvoll einzurichten sollte als zusätzlicher Wert für das Attribut <code>genericdeviceType</code> der Wert <code>ContactSensor</code> hinzugefügt werden. Wie das geht ist im Eintrag [[Homebridge_einrichten#FHEM_konfigurieren | Homebridge einrichten]] ausführlicher beschrieben.

Folgende Attribute dann hinzufügen:
attr STM250 genericDeviceType ContactSensor
attr STM250 homebridgeMapping ContactSensorState=state,values=closed:CONTACT_DETECTED;open:CONTACT_NOT_DETECTED

Getestet mit
FHEM 5.7 Rev. 9893
Homebridge 0.2.16
homebridge-fhem Vorschauversion aus {{Link2Forum|Topic=48558|Message=402024|LinkText=homebridge/homekit}}

== Modul RESIDENTS für Anwesenheitserkennung und Steuerung der Anwesenheit benutzen ==
[[Datei:Homebridge_bewohner_zu_szene.jpeg|mini|Schaltzustand eines Bewohners zu einer Szene hinzufügen]]
Aus den einzelnen Komponenten des Moduls RESIDENTS, homebridge sowie der characteristic <code>On</code> und der Szenensteuerung lässt sich eine gleichzeitige Steuerung der Anwesenheit und Anwesenheitserkennung basteln.

Dazu müssen folgende Schritte unternommen werden:
* einem Bewohner aus dem Modul ROOMMATE die Steuerung über homebridgeMapping hinzufügen
* Szene für "Ich bin zu Hause" und "Ich gehe jetzt" in einer HomeKit-fähigen App wie z.B. Eve einrichten

Man kann einen beliebigen Bewohner aus dem Modul ROOMMATE nehmen und ihn über die characteristic <code>On</code> in Form eines Schalters sozusagen schaltbar machen. Nur wird das Ein- und Ausschalten des Bewohners über HomeKit in FHEM auf den Status home bzw. absent gemappt. Seit dem 06.02.2016 werden RESIDENTS automatisch als Occupancy Sensor für HomeKit annonciert. Nun noch die Attribute des ROOMMATE wie folgt setzen:
attr <ROOMMATE> genericDeviceType switch
attr <ROOMMATE> homebridgeMapping On=state,valueOn=/home|awoken|asleep|gotosleep/,valueOff=/gone|absent/,cmdOn=home,cmdOff=absent

Natürlich muss der Bewohner noch dem Filter von homebridge hinzugefügt und homebridge neu gestartet werden.

Anschließend geht es in der HomeKit-fähigen App Deiner Wahl weiter. In Eve von Elgato ist von vornherein zum Beispiel vorgesehen, dass man zwei Szenen "Ich bin zuhause" und "Ich verlasse das Haus" hat. Zu diesen Szenen wird eine Aktion hinzugefügt indem der Bewohner, den das ROOMMATE-Modul meldet zur Szene hinzugefügt wird und beim Nachhausekommen "eingeschaltet" wird. Genauso wird mit der Szene "Ich verlasse das Haus" verfahren: Bewohner zur Szene hinzufügen und den Schaltvorgang auf "ausschalten" setzen.

Mit den Sprachbefehlen "Ich bin zuhause" oder "Ich verlasse das Haus" wird die entsprechende Szene eingeschaltet, homebridge schaltet über das <code>homebridgeMapping</code> Attribut dann den Bewohner auf "home" oder "absent".

Getestet mit
FHEM 5.7 Rev. 9893
Homebridge 0.2.16
homebridge-fhem Vorschauversion aus {{Link2Forum|Topic=48558|Message=402024|LinkText=homebridge/homekit}}

Eine noch etwas bessere Schaltmöglichkeit bietet '''genericDeviceType security'''.
Das Mapping für ROOMMATE sieht wie folgt aus:
attr TYPE=ROOMMATE genericDeviceType security
attr TYPE=ROOMMATE homebridgeMapping SecuritySystemCurrentState=state,values=/home|awoken/:0;;absent:1;;/asleep|gotosleep/:2;;gone:3 SecuritySystemTargetState=SecuritySystemCurrentState,cmds=0:state+home;;1:state+absent;;2:state+gotosleep;;3:state+gone,delay=1
für GUEST:
attr TYPE=GUEST genericDeviceType security
attr TYPE=GUEST homebridgeMapping SecuritySystemCurrentState=state,values=/home|awoken/:0;;absent:1;;/asleep|gotosleep/:2;;none:3 SecuritySystemTargetState=SecuritySystemCurrentState,cmds=0:state+home;;1:state+absent;;2:state+gotosleep;;3:state+none,delay=1

== ZWave Türschloss Vision ZM1701 einbinden ==
Das ZWave Türschloss ZM1701 von der Firma Vision sendet seinen aktuellen Schließstatus in ein einzelnes Reading wie "lock", sondern schickt eine ganze Reihe von Informationen über den Zustand in das Reading <code>doorLockOperation</code>. Das Schließen und Öffnen der Türschlosses wird auch nicht mit einem Setzen des <code>state</code> erreicht, sondern mit dem Setzen von <code>doorLockOperation</code>. Das macht das Einbinden in homebridge nicht trivial, funktioniert aber über folgendes Homebridge-Mapping:
attr <ZM1701> genericDeviceType lock
attr <ZM1701> homebridgeMapping LockCurrentState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED LockTargetState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED,cmds=SECURED:doorLockOperation+close;UNSECURED:doorLockOperation+open

Kurz zur Erklärung: Um ein Schloss über HomeKit steuern zu können braucht es zwei characteristics. LockCurrentState zeigt an, ob das Schloss geöffnet oder geschlossen ist. Und mit LockTargetState wird das Schloss geöffnet oder geschlossen. Damit der aktuelle Status des Schlosses ausgelesen werden kann, muss aus dem FHEM-Reading <code>doorLockOperation</code> die Zeichenfolge <code> secured</code> oder <code>unsecured</code> extrahiert werden, daher die beiden regulären Ausdrücke <code>/\ssecured/</code> und <code>/unsecured/</code>. In der characteristic <code>LockTargetState</code> muss sowohl der aktuelle Status des Schlosses als auch das Kommando angegeben werden, schließlich möchte man ein geschlossenes Schloss nicht nochmal schließen. Daher wird erst aus dem Reading <code>doorLockOperation</code> der aktuelle Status des Schlosses ausgelesen und die damit korrespondierenden Befehle über <code>cmds=SECURED:doorLockOperation+close;UNSECURED:doorLockOperation+open</code> generiert.

Wer es in FHEM über ein webCmd einfacher zu bedienen haben möchte, fügt bitte noch die dafür notwendigen Attribute und die leicht geänderten homebridgeMappings wie folgt ein:
attr <ZM1701> genericDeviceType lock
attr <ZM1701> homebridgeMapping LockCurrentState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED LockTargetState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED,cmds=SECURED:close;UNSECURED:open
attr <ZM1701> /doorLockOperation open:open/doorLockOperation close:close
attr <ZM1701> webCmd open:close

Getestet mit
FHEM 5.7 Rev. 12191
homebridge 0.4.6
homebridge-fhem 0.2.48

== Roomba über THINKINGCLEANER Modul ==
attr <THINKINGCLEANER> genericDeviceType switch
attr <THINKINGCLEANER> homebridgeMapping clear On=state,valueOn=/^(on|dock)/,cmdOn=on,cmdOff=off,nocache=1 ChargingState=deviceStatus,values=/(_recon|_full|_trickle)$/:CHARGING;/^.*/:NOT_CHARGING
attr <THINKINGCLEANER> siriName Robby

Getestet mit
FHEM 5.7 Rev. 12680
homebridge 0.4.11
homebridge-fhem 0.2.66

== Homematic HM-CC-RT-DN Funk-Heizkörperthermostat ==
[[Datei:HM-CC-RT-DN-Eve.PNG|mini|Darstellung des HM-CC-RT-DN in der iOS App Eve]]
attr <HMCCRTDN_Channel2_Clima> homebridgeMapping TargetTemperature=desired-temp::desired-temp,minValue=5,maxValue=35,minStep=0.5,nocache=1
CurrentTemperature=BU_Heizung_01_Clima:measured-temp,nocache=1
StatusLowBattery=BU_Heizung_01:battery,values=ok:BATTERY_LEVEL_NORMAL;;/^.*/:BATTERY_LEVEL_LOW
TargetHeatingCoolingState=heatingState,values=OFF:0;;HEAT:1;;COOL:2;;AUTO:3,cmds=OFF:controlManu+off;;HEAT:controlMode+boost;;AUTO:controlMode+auto;;COOL:controlManu+17.0
CurrentHeatingCoolingState=heatingState,values=OFF:0;;HEAT:1;;COOL:2;;AUTO:0,valud=OFF
attr <HMCCRTDN_Channel2_Clima> siriName Robby
Dieses Mapping bezieht sich auf ein vorhandenes ''userReading'' mit dem Namen <code>heatingState</code>, womit Homekit die einzelnen Status nachher unterscheidet.
attr <HM-CC-RT-DN_Clima> userReadings heatingState {(ReadingsVal($NAME,"ValvePosition",0) > 0 || ReadingsVal($NAME,"desired-temp","-") eq "on") ? "HEAT" : ReadingsVal($NAME,"desired-temp","-") eq "off" ? "OFF" : ReadingsVal($NAME,"controlMode","auto") eq "auto" ? "AUTO" : (ReadingsVal($NAME,"measured-temp",20) > ReadingsVal($NAME,"desired-temp",20)) ? "COOL" : "AUTO"}
Global auf alle in FHEM angelegten HM-CC-RT-DN, lässt sich mit folgendem Befehl das ''userReading'' anlegen.
Siehe [https://forum.fhem.de/index.php/topic,59211.msg505986.html#msg505986 Forumsthread].

attr TYPE=CUL_HM:FILTER=model=HM-CC-RT-DN:FILTER=chanNo=04 userReadings heatingState {(ReadingsVal($NAME,"ValvePosition",0) > 0 || ReadingsVal($NAME,"desired-temp","-") eq "on") ? "HEAT" : ReadingsVal($NAME,"desired-temp","-") eq "off" ? "OFF" : ReadingsVal($NAME,"controlMode","auto") eq "auto" ? "AUTO" : (ReadingsVal($NAME,"measured-temp",20) > ReadingsVal($NAME,"desired-temp",20)) ? "COOL" : "AUTO"}

== Xiaomi Vacuum Cleaner 1. Generation ==
[[Datei:XIAOMI_VACUUM_CLEANER-Gen1.jpg|mini|XIAOMI VACUUM 1. GEN in EVE]]
Voraussetzung zur Verwendung der Mappings, ist ein eingebundener Staubsauger mit dem Modul 72_XiaomiDevice.

Siehe [https://forum.fhem.de/index.php/topic,73052.0.html Forumsthread]
Das Modul muss manuell installiert werden.

attr <XIAOMI> genericDeviceType switch
attr <XIAOMI> homebridgeMapping On=state,valueOn=Cleaning,cmdOn=start,cmdOff=charge
RotationSpeed=fan_power,minValue=0,maxValue=90,cmd=fan_power,delay=1
BatteryLevel=batteryLevel,maxValue=100,minValue=0,minStep=1
StatusLowBattery=battery,values=ok:BATTERY_LEVEL_NORMAL;;low:BATTERY_LEVEL_LOW
ChargingState=state,values=Docked:NOT_CHARGING;;Charging:CHARGING;;/.*/:NOT_CHARGEABLE
OccupancyDetected=state,values=/Docked|Charging/:OCCUPANCY_DETECTED;;/.*/:OCCUPANCY_NOT_DETECTED
FilterLifeLevel=consumables_filter,minValue=0,maxValue=100
FilterChangeIndication=consumables_filter,values=0:CHANGE_FILTER

== Roborock S50 (2. Generation des Xiaomi Vacuum Cleaners) ==
[[Datei:Roborock S50.png|mini]]
Voraussetzung zur Verwendung der Mappings, ist ein eingebundener Staubsauger mit dem Modul 72_XiaomiDevice.

Siehe [https://forum.fhem.de/index.php/topic,73052.0.html Forumsthread]
Das Modul muss manuell installiert werden.

Das folgende Mapping für den Roborook S50 beinhaltet neben den Characteristics der 1. Genration des Xiaomi Vacuum Cleaners weitere Custom Mappings. Diese werden auch auf dem Bild dargestellt. Falls das einem zu viele Informationen sind, können diese beim Einfügen einfach weggelassen oder in EVE ausgeblendet werden.

attr <XIAOMI> genericDeviceType switch
attr <XIAOMI> homebridgeMapping On=state,valueOn=Cleaning,cmdOn=start,cmdOff=charge
RotationSpeed=fan_power,minValue=0,maxValue=90,cmd=fan_power,delay=1
BatteryLevel=batteryPercent,maxValue=100,minValue=0,minStep=1
StatusLowBattery=batteryState,values=ok:BATTERY_LEVEL_NORMAL;;low:BATTERY_LEVEL_LOW
ChargingState=state,values=Docked:NOT_CHARGING;;Charging:CHARGING;;/.*/:NOT_CHARGEABLE
OccupancyDetected=state,values=/Docked|Charging/:OCCUPANCY_DETECTED;;/.*/:OCCUPANCY_NOT_DETECTED
2af6d0d0-3691-4f0d-9c9c-c1098295b1cb=consumables_sensors,name=Reinigung+Sensoren,minValue=0,maxValue=100,format=FLOAT,minStep=1,unit=%
fd11b965-052e-430f-b08f-206287d8bc00=consumables_filter,name=Austausch+Filter,minValue=0,maxValue=100,format=FLOAT,minStep=1,unit=%
fe7a8dac-dff3-4a07-8a5e-0d6abbf0df0c=consumables_main_brush,name=Austausch+Hauptbürste,minValue=0,maxValue=100,format=FLOAT,minStep=1,unit=%
4f9b2a22-b764-4fc1-8cd2-99383924394c=consumables_side_brush,name=Austausch+Seitenbürste,minValue=0,maxValue=100,format=FLOAT,minStep=1,unit=%
FilterLifeLevel=consumables_filter,minValue=0,maxValue=100
FilterChangeIndication=consumables_filter,values=0:CHANGE_FILTER
4896763a-26f7-400b-9734-2ce6564ceba2=total_clean_time,name=Lebenszeitersparnis,format=FLOAT,minStep=1,unit=h
82af5fd7-50a3-4ab3-81d3-1f7903de612a=total_clean_area,name=Gereinigte+Fläche,format=FLOAT,minStep=1,unit=m²
00d2ef14-b429-4569-8af3-c342d41cf383=total_cleans,name=Reinigungsvorgänge,format=FLOAT,minStep=1
e8d1027e-b068-40d5-9efd-f161b1b52774=device_firmware,name=Firmware,format=STRING

== Xiaomi Fan (ältere Generationen mit Luftfeuchtigkeits- und Temperatursensor und Battery-Readings) ==
[[Datei:Xiaomi DC Pedestal Fan.png|mini]]
Voraussetzung zur Verwendung der Mappings, ist ein eingebundener Ventilator mit dem Modul 72_XiaomiDevice.
Siehe [https://forum.fhem.de/index.php/topic,73052.0.html Forumsthread]
Das Modul muss manuell installiert werden.

Die ältere Generation enthält Sensoren und somit Readings für Luftfeuchtigkeit, Temperatur und auch Batteriestatus. Diese fehlen bei den neueren Generation dieses Ventilators, siehe Bilder. Da anscheinend jedes Jahr neue Generationen dieses Ventilators herausgekommen sind, ist nicht klar bis zu welcher Generation diese Sensoren enthalten waren.

Mit folgenden Geräten wurde folgendes Mapping erstellt und somit erfolgreich getestet:

- Xiaomi DC Pedestal Fan (FHEM model fehlt, Default Hostname am Router: zhimi-fan-v3)
- Liste bitte ergänzen!

Um möglichst viele Funktionen bereitzustellen, wurden auch Characteristics von anderen DeviceTypes verwendet. Erklärung zu den Characteristics:

- Die Kindersicherung (LockPhysicalControls) ist in Eve über das kleine Einstellungssymbol zu finden.
- Mit AudioFeedback/Audio-Bestätigung werden die Töne des Lüfters ein bzw. ausgeschaltet.
- Mit NightVision/Nachtsicht werden die LEDs ein (bright) bzw. ausgeschaltet (off).
- Mit Mute/Audio wird der Windmodus von Straight zu Natural geschaltet.
- Mit TargetTiltAngle/Neigung kann der Schwenkwinkel justiert werden.
- Mit SwingMode/Schwenken kann der Schwenkmodus ein bzw. ausgeschaltet werden.
- Der Rest ist selbsterklärend.

homebridgeMapping:

attr <XIAOMI> genericDeviceType Fan
attr <XIAOMI> homebridgeMapping
clear
On:power,cmdOn=on,cmdOff=off,valueOn=on,valueOff=off
LockPhysicalControls=child_lock,values=on:CONTROL_LOCK_ENABLED;;off:CONTROL_LOCK_DISABLED,cmds=CONTROL_LOCK_ENABLED:child_lock+on;CONTROL_LOCK_DISABLED:child_lock+off
RotationSpeed=level,minValue=0,maxValue=100,cmd=level,delay=1
TargetTiltAngle=angle,minValue=30,maxValue=120,minStep=30,cmd=angle
SwingMode=angle_enable,values=on:SWING_ENABLED;;off:SWING_DISABLED,cmdOn=angle_enable+on,cmdOff=angle_enable+off
CurrentRelativeHumidity=humidity
CurrentTemperature=temperature
BatteryLevel=batteryPercent,maxValue=100,minValue=0,minStep=1
StatusLowBattery=batteryState,values=ok:BATTERY_LEVEL_NORMAL;;low:BATTERY_LEVEL_LOW
ChargingState=charging,values=complete:NOT_CHARGING;;progress:CHARGING;;/.*/:NOT_CHARGEABLE
AudioFeedback:buzzer,cmdOn=buzzer+on,cmdOff=buzzer+off,valueOn=on,valueOff=off
NightVision:led,cmdOn=led+off,cmdOff=led+bright,valueOn=off,valueOff=bright
Mute:mode,cmdOn=mode+straight,cmdOff=mode+natural,valueOn=straight,valueOff=natural
CurrentFanState:power,values=on:BLOWING_AIR;;off:INACTIVE;;/.*/:IDLE

== Xiaomi Fan (neuere Generationen ohne Luftfeuchtigkeits- und Temperatursensor und Battery-Readings) ==
[[Datei:Xiaomi Standing Fan 2 bzw. 2S.png|mini]]
Voraussetzung zur Verwendung der Mappings, ist ein eingebundener Ventilator mit dem Modul 72_XiaomiDevice.
Siehe [https://forum.fhem.de/index.php/topic,73052.0.html Forumsthread]
Das Modul muss manuell installiert werden.

Den neueren Generationen dieses Ventilators fehlen Sensoren und somit Readings für Luftfeuchtigkeit, Temperatur und auch Batteriestatus. Diese sind bei der älteren Generation dieses Ventilators enthalten, siehe vorangegangenes Beispiel.

Dieses Mapping wurde mit dem "2S" erstellt. Es sollte aber mindestens auch mit einem "Xiaomi Standing Fan 2" (ohne Akku) funktionieren, da auch der "Xiaomi Standing Fan 2S" (mit Akku) kein Reading für die Batterie bereitstellt. Ansonsten gibt es wohl auch noch Generationen zwischen dem "Xiaomi DC Pedestal Fan" und den "Xiaomi Standing Fan 2/2S". Es ist davon auszugehen, dass dieses Beispiel genauso auch bei diesen Modellen funktioniert.

Mit folgenden Geräten wurde folgendes Mapping erstellt und somit erfolgreich getestet:

- 2019 Xiaomi Standing Fan 2S (FHEM model bzw. Default Hostname am Router: zhimi-fan-za4)
- 2018 Xiaomi ZhiMiDCVariableFrequencyFan ZRFFS01ZM (FHEM model bzw. Default Hostname am Router: zhimi-fan-za1)
- Liste bitte ergänzen!

Um möglichst viele Funktionen bereitzustellen, wurden auch Characteristics von anderen DeviceTypes verwendet. Erklärung zu den Characteristics:

- Die Kindersicherung (LockPhysicalControls) ist in Eve über das kleine Einstellungssymbol zu finden.
- Mit AudioFeedback/Audio-Bestätigung werden die Töne des Lüfters ein bzw. ausgeschaltet.
- Mit NightVision/Nachtsicht werden die LEDs ein (bright) bzw. ausgeschaltet (off).
- Mit Mute/Audio wird der Windmodus von Straight zu Natural geschaltet.
- Mit TargetTiltAngle/Neigung kann der Schwenkwinkel justiert werden.
- Mit SwingMode/Schwenken kann der Schwenkmodus ein bzw. ausgeschaltet werden.
- Der Rest ist selbsterklärend.

homebridgeMapping:

attr <XIAOMI> genericDeviceType Fan
attr <XIAOMI> homebridgeMapping
clear
On:power,cmdOn=on,cmdOff=off,valueOn=on,valueOff=off
LockPhysicalControls=child_lock,values=on:CONTROL_LOCK_ENABLED;;off:CONTROL_LOCK_DISABLED,cmds=CONTROL_LOCK_ENABLED:child_lock+on;CONTROL_LOCK_DISABLED:child_lock+off
RotationSpeed=level,minValue=0,maxValue=100,cmd=level,delay=1
TargetTiltAngle=angle,minValue=30,maxValue=120,minStep=30,cmd=angle
SwingMode=angle_enable,values=on:SWING_ENABLED;;off:SWING_DISABLED,cmdOn=angle_enable+on,cmdOff=angle_enable+off
AudioFeedback:buzzer,cmdOn=buzzer+on,cmdOff=buzzer+off,valueOn=on,valueOff=off
NightVision:led,cmdOn=led+off,cmdOff=led+bright,valueOn=off,valueOff=bright
Mute:mode,cmdOn=mode+straight,cmdOff=mode+natural,valueOn=straight,valueOff=natural
CurrentFanState:power,values=on:BLOWING_AIR;;off:INACTIVE;;/.*/:IDLE

== Homematic SmokeDetector ==
[[Datei:Homebridge-Homematic-Smokedetector-Gen1.jpg|mini|Homebridge-Homematic-Smokedetector-Gen1 in EVE]]
Es sind keine Homebridge Mappings für die Rauch Meldung erforderlich.

Allerdings ist ein Mapping für den Batterie Zustand nötig, siehe Unten.

attr <SmokeDetector> genericDeviceType SmokeSensor
attr <SmokeDetector> subType smokeDetector

attr <SmokeDetector> homebridgeMapping StatusLowBattery=battery,values=ok:BATTERY_LEVEL_NORMAL;;/^.*/:BATTERY_LEVEL_LOW

== Vallox Belüftungsanlage ==
Die Steuerung der Lüftungsgeschwindigkeit ist nur in Prozent möglich. Die Umrechnung erfolgt im [[Vallox]] Modul.
Hierzu wurde das Reading ''FanSpeedPct'' hinzugefügt.

attr <Vallox> genericDeviceType Fan
attr <Vallox> homebridgeMapping clear
model=Vallox
On=PowerState,valueOn=1,readOnly=1
RotationSpeed=FanSpeedPct,minValue=1,maxValue=100,cmd=FanSpeedPct,delay=1

[[Kategorie:HOWTOS]]
[[Kategorie:Code Snippets]]

Homebridge User Configs

2019-06-19T22:59:42Z

Hoppel118: Bilder ergänzt bei den beiden Xiaomi Fans und dem Roborock S50

Dieser Eintrag dient zur Sammlung funktionsfähiger Homebridge Configs.

Bitte immer die FHEM Version und Homebridge Version angegeben.

Sehr gute Hinweise gibt es hier: http://www.meintechblog.de/2015/10/mit-siri-und-fhem-das-gesamte-smart-home-per-stimme-steuern/
== Mögliche Mappings ==
Die Möglichen Mappings können hier nachgelesen werden https://github.com/KhaosT/HAP-NodeJS/blob/master/lib/gen/HomeKitTypes.js

Hier ein Beispiel:
Characteristic.Brightness = function() {
Characteristic.call(this, 'Brightness', '00000008-0000-1000-8000-0026BB765291');
this.setProps({
format: Characteristic.Formats.INT,
unit: Characteristic.Units.PERCENTAGE,
maxValue: 100,
minValue: 0,
minStep: 1,
perms: [Characteristic.Perms.READ, Characteristic.Perms.WRITE, Characteristic.Perms.NOTIFY]
});
this.value = this.getDefaultValue();
};

Das Mapping in diesem Fall, hat den Titel Brightness.

Die Werte können in 1er Schritten zwischen 0 und 100 liegen (max und min Value)
== Feuchtesensor ==
Zum Einstieg etwas leicht nachvollziehbares.

Feuchtesensoren haben in der Regel ein "humidity" Reading, im Falle des Opus XT300 Bodenfeuchtesensors auch Temperatur und Batterie Level. Homekit unterstützt einen "HumiditySensor" Service. Dieser ist in homebridge-fhem nicht standardmäßig vorhanden (kann also nicht aus dem dropdown ausgewählt werden, sondern muss über das Befehlsfeld zugewiesen werden):

<code>attr meinSensor genericDeviceType HumiditySensor</code>

Im nächsten Schritt werden die Readings gemappt:

<code>attr meinSensor homebridgeMapping clear CurrentRelativeHumidity=humidity StatusLowBattery=battery,values=ok:BATTERY_LEVEL_NORMAL;;/^.*/:BATTERY_LEVEL_LOW CurrentTemperature=temperature</code>

<code>clear</code>löscht default mappings - das wird in der Regel nicht notwendig sein, schadet aber nicht

<code>CurrentRelativeHumidity</code> ist die relevante Homekit Characteristic - wird mit dem entsprechenden Reading des Sensors gemappt.

<code>StatusLowBattery</code> erwartet entweder BATTERY_LEVEL_NORMAL oder _LOW. Mein Sensor liefert ok zurück, wenn alles gut ist, also wird "ok" auf _NORMAL gemappt, alles andere auf _LOW.

Der Opus XT300 Bodenfeuchtesensors liefert auch noch die Temperatur - der HumiditySensor Service sieht das eigentlich nicht vor, daher wird die Temperatur auch nicht in der Apple "Home" App angezeigt. Bei Eve wird die Temperatur hingegen berücksichtigt.

== EnOcean STM 250 Tür-/Fensterkontakt ==
Der STM 250 liefert als Status in FHEM <code>open</code>, wenn das Fenster offen und damit der Kontakt "offen" ist. Analog liefert er <code>closed</code> wenn das Fenster geschlossen und damit auch der Kontakt geschlossen ist. Diese Statusangaben sind sehr intuitiv zu verstehen und zu interpretieren.

Die characteristic <code>ContactSensorState</code> von HomeKit liefert entweder den Wert <code>CONTACT_DETECTED=0</code> oder <code>CONTACT_NOT_DETECTED=1</code> zurück. Wobei <code>CONTACT_DETECTED</code> bedeutet, dass der Kontakt geschlossen ist. Je nach Darstellung in der HomeKit-fähigen App muss dieses Verhalten bei der Interpretation berücksichtigt werden. Die App Eve von Elgato zum Beispiel liefert für Kontaktsensoren "JA" oder "NEIN" mit der Bedeutung <code>CONTACT_DETECTED=0=JA</code> bzw. <code>CONTACT_NOT_DETECTED=1=NEIN</code> zurück.

Noch ein wichtiger Punkt: Um einen Sensorkontakt sinnvoll einzurichten sollte als zusätzlicher Wert für das Attribut <code>genericdeviceType</code> der Wert <code>ContactSensor</code> hinzugefügt werden. Wie das geht ist im Eintrag [[Homebridge_einrichten#FHEM_konfigurieren | Homebridge einrichten]] ausführlicher beschrieben.

Folgende Attribute dann hinzufügen:
attr STM250 genericDeviceType ContactSensor
attr STM250 homebridgeMapping ContactSensorState=state,values=closed:CONTACT_DETECTED;open:CONTACT_NOT_DETECTED

Getestet mit
FHEM 5.7 Rev. 9893
Homebridge 0.2.16
homebridge-fhem Vorschauversion aus {{Link2Forum|Topic=48558|Message=402024|LinkText=homebridge/homekit}}

== Modul RESIDENTS für Anwesenheitserkennung und Steuerung der Anwesenheit benutzen ==
[[Datei:Homebridge_bewohner_zu_szene.jpeg|mini|Schaltzustand eines Bewohners zu einer Szene hinzufügen]]
Aus den einzelnen Komponenten des Moduls RESIDENTS, homebridge sowie der characteristic <code>On</code> und der Szenensteuerung lässt sich eine gleichzeitige Steuerung der Anwesenheit und Anwesenheitserkennung basteln.

Dazu müssen folgende Schritte unternommen werden:
* einem Bewohner aus dem Modul ROOMMATE die Steuerung über homebridgeMapping hinzufügen
* Szene für "Ich bin zu Hause" und "Ich gehe jetzt" in einer HomeKit-fähigen App wie z.B. Eve einrichten

Man kann einen beliebigen Bewohner aus dem Modul ROOMMATE nehmen und ihn über die characteristic <code>On</code> in Form eines Schalters sozusagen schaltbar machen. Nur wird das Ein- und Ausschalten des Bewohners über HomeKit in FHEM auf den Status home bzw. absent gemappt. Seit dem 06.02.2016 werden RESIDENTS automatisch als Occupancy Sensor für HomeKit annonciert. Nun noch die Attribute des ROOMMATE wie folgt setzen:
attr <ROOMMATE> genericDeviceType switch
attr <ROOMMATE> homebridgeMapping On=state,valueOn=/home|awoken|asleep|gotosleep/,valueOff=/gone|absent/,cmdOn=home,cmdOff=absent

Natürlich muss der Bewohner noch dem Filter von homebridge hinzugefügt und homebridge neu gestartet werden.

Anschließend geht es in der HomeKit-fähigen App Deiner Wahl weiter. In Eve von Elgato ist von vornherein zum Beispiel vorgesehen, dass man zwei Szenen "Ich bin zuhause" und "Ich verlasse das Haus" hat. Zu diesen Szenen wird eine Aktion hinzugefügt indem der Bewohner, den das ROOMMATE-Modul meldet zur Szene hinzugefügt wird und beim Nachhausekommen "eingeschaltet" wird. Genauso wird mit der Szene "Ich verlasse das Haus" verfahren: Bewohner zur Szene hinzufügen und den Schaltvorgang auf "ausschalten" setzen.

Mit den Sprachbefehlen "Ich bin zuhause" oder "Ich verlasse das Haus" wird die entsprechende Szene eingeschaltet, homebridge schaltet über das <code>homebridgeMapping</code> Attribut dann den Bewohner auf "home" oder "absent".

Getestet mit
FHEM 5.7 Rev. 9893
Homebridge 0.2.16
homebridge-fhem Vorschauversion aus {{Link2Forum|Topic=48558|Message=402024|LinkText=homebridge/homekit}}

Eine noch etwas bessere Schaltmöglichkeit bietet '''genericDeviceType security'''.
Das Mapping für ROOMMATE sieht wie folgt aus:
attr TYPE=ROOMMATE genericDeviceType security
attr TYPE=ROOMMATE homebridgeMapping SecuritySystemCurrentState=state,values=/home|awoken/:0;;absent:1;;/asleep|gotosleep/:2;;gone:3 SecuritySystemTargetState=SecuritySystemCurrentState,cmds=0:state+home;;1:state+absent;;2:state+gotosleep;;3:state+gone,delay=1
für GUEST:
attr TYPE=GUEST genericDeviceType security
attr TYPE=GUEST homebridgeMapping SecuritySystemCurrentState=state,values=/home|awoken/:0;;absent:1;;/asleep|gotosleep/:2;;none:3 SecuritySystemTargetState=SecuritySystemCurrentState,cmds=0:state+home;;1:state+absent;;2:state+gotosleep;;3:state+none,delay=1

== ZWave Türschloss Vision ZM1701 einbinden ==
Das ZWave Türschloss ZM1701 von der Firma Vision sendet seinen aktuellen Schließstatus in ein einzelnes Reading wie "lock", sondern schickt eine ganze Reihe von Informationen über den Zustand in das Reading <code>doorLockOperation</code>. Das Schließen und Öffnen der Türschlosses wird auch nicht mit einem Setzen des <code>state</code> erreicht, sondern mit dem Setzen von <code>doorLockOperation</code>. Das macht das Einbinden in homebridge nicht trivial, funktioniert aber über folgendes Homebridge-Mapping:
attr <ZM1701> genericDeviceType lock
attr <ZM1701> homebridgeMapping LockCurrentState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED LockTargetState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED,cmds=SECURED:doorLockOperation+close;UNSECURED:doorLockOperation+open

Kurz zur Erklärung: Um ein Schloss über HomeKit steuern zu können braucht es zwei characteristics. LockCurrentState zeigt an, ob das Schloss geöffnet oder geschlossen ist. Und mit LockTargetState wird das Schloss geöffnet oder geschlossen. Damit der aktuelle Status des Schlosses ausgelesen werden kann, muss aus dem FHEM-Reading <code>doorLockOperation</code> die Zeichenfolge <code> secured</code> oder <code>unsecured</code> extrahiert werden, daher die beiden regulären Ausdrücke <code>/\ssecured/</code> und <code>/unsecured/</code>. In der characteristic <code>LockTargetState</code> muss sowohl der aktuelle Status des Schlosses als auch das Kommando angegeben werden, schließlich möchte man ein geschlossenes Schloss nicht nochmal schließen. Daher wird erst aus dem Reading <code>doorLockOperation</code> der aktuelle Status des Schlosses ausgelesen und die damit korrespondierenden Befehle über <code>cmds=SECURED:doorLockOperation+close;UNSECURED:doorLockOperation+open</code> generiert.

Wer es in FHEM über ein webCmd einfacher zu bedienen haben möchte, fügt bitte noch die dafür notwendigen Attribute und die leicht geänderten homebridgeMappings wie folgt ein:
attr <ZM1701> genericDeviceType lock
attr <ZM1701> homebridgeMapping LockCurrentState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED LockTargetState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED,cmds=SECURED:close;UNSECURED:open
attr <ZM1701> /doorLockOperation open:open/doorLockOperation close:close
attr <ZM1701> webCmd open:close

Getestet mit
FHEM 5.7 Rev. 12191
homebridge 0.4.6
homebridge-fhem 0.2.48

== Roomba über THINKINGCLEANER Modul ==
attr <THINKINGCLEANER> genericDeviceType switch
attr <THINKINGCLEANER> homebridgeMapping clear On=state,valueOn=/^(on|dock)/,cmdOn=on,cmdOff=off,nocache=1 ChargingState=deviceStatus,values=/(_recon|_full|_trickle)$/:CHARGING;/^.*/:NOT_CHARGING
attr <THINKINGCLEANER> siriName Robby

Getestet mit
FHEM 5.7 Rev. 12680
homebridge 0.4.11
homebridge-fhem 0.2.66

== Homematic HM-CC-RT-DN Funk-Heizkörperthermostat ==
[[Datei:HM-CC-RT-DN-Eve.PNG|mini|Darstellung des HM-CC-RT-DN in der iOS App Eve]]
attr <HMCCRTDN_Channel2_Clima> homebridgeMapping TargetTemperature=desired-temp::desired-temp,minValue=5,maxValue=35,minStep=0.5,nocache=1
CurrentTemperature=BU_Heizung_01_Clima:measured-temp,nocache=1
StatusLowBattery=BU_Heizung_01:battery,values=ok:BATTERY_LEVEL_NORMAL;;/^.*/:BATTERY_LEVEL_LOW
TargetHeatingCoolingState=heatingState,values=OFF:0;;HEAT:1;;COOL:2;;AUTO:3,cmds=OFF:controlManu+off;;HEAT:controlMode+boost;;AUTO:controlMode+auto;;COOL:controlManu+17.0
CurrentHeatingCoolingState=heatingState,values=OFF:0;;HEAT:1;;COOL:2;;AUTO:0,valud=OFF
attr <HMCCRTDN_Channel2_Clima> siriName Robby
Dieses Mapping bezieht sich auf ein vorhandenes ''userReading'' mit dem Namen <code>heatingState</code>, womit Homekit die einzelnen Status nachher unterscheidet.
attr <HM-CC-RT-DN_Clima> userReadings heatingState {(ReadingsVal($NAME,"ValvePosition",0) > 0 || ReadingsVal($NAME,"desired-temp","-") eq "on") ? "HEAT" : ReadingsVal($NAME,"desired-temp","-") eq "off" ? "OFF" : ReadingsVal($NAME,"controlMode","auto") eq "auto" ? "AUTO" : (ReadingsVal($NAME,"measured-temp",20) > ReadingsVal($NAME,"desired-temp",20)) ? "COOL" : "AUTO"}
Global auf alle in FHEM angelegten HM-CC-RT-DN, lässt sich mit folgendem Befehl das ''userReading'' anlegen.
Siehe [https://forum.fhem.de/index.php/topic,59211.msg505986.html#msg505986 Forumsthread].

attr TYPE=CUL_HM:FILTER=model=HM-CC-RT-DN:FILTER=chanNo=04 userReadings heatingState {(ReadingsVal($NAME,"ValvePosition",0) > 0 || ReadingsVal($NAME,"desired-temp","-") eq "on") ? "HEAT" : ReadingsVal($NAME,"desired-temp","-") eq "off" ? "OFF" : ReadingsVal($NAME,"controlMode","auto") eq "auto" ? "AUTO" : (ReadingsVal($NAME,"measured-temp",20) > ReadingsVal($NAME,"desired-temp",20)) ? "COOL" : "AUTO"}

== Xiaomi Vacuum Cleaner 1. Generation ==
[[Datei:XIAOMI_VACUUM_CLEANER-Gen1.jpg|mini|XIAOMI VACUUM 1. GEN in EVE]]
Voraussetzung zur Verwendung der Mappings, ist ein eingebundener Staubsauger mit dem Modul 72_XiaomiDevice.

Siehe [https://forum.fhem.de/index.php/topic,73052.0.html Forumsthread]
Das Modul muss manuell installiert werden.

attr <XIAOMI> genericDeviceType switch
attr <XIAOMI> homebridgeMapping On=state,valueOn=Cleaning,cmdOn=start,cmdOff=charge
RotationSpeed=fan_power,minValue=0,maxValue=90,cmd=fan_power,delay=1
BatteryLevel=batteryLevel,maxValue=100,minValue=0,minStep=1
StatusLowBattery=battery,values=ok:BATTERY_LEVEL_NORMAL;;low:BATTERY_LEVEL_LOW
ChargingState=state,values=Docked:NOT_CHARGING;;Charging:CHARGING;;/.*/:NOT_CHARGEABLE
OccupancyDetected=state,values=/Docked|Charging/:OCCUPANCY_DETECTED;;/.*/:OCCUPANCY_NOT_DETECTED
FilterLifeLevel=consumables_filter,minValue=0,maxValue=100
FilterChangeIndication=consumables_filter,values=0:CHANGE_FILTER

== Roborock S50 (2. Generation des Xiaomi Vacuum Cleaners) ==
[[Datei:Roborock S50.png|mini]]
Voraussetzung zur Verwendung der Mappings, ist ein eingebundener Staubsauger mit dem Modul 72_XiaomiDevice.

Siehe [https://forum.fhem.de/index.php/topic,73052.0.html Forumsthread]
Das Modul muss manuell installiert werden.

Das folgende Mapping für den Roborook S50 beinhaltet neben den Characteristics der 1. Genration des Xiaomi Vacuum Cleaners weitere Custom Mappings. Diese werden auch auf dem Bild dargestellt. Falls das einem zu viele Informationen sind, können diese beim Einfügen einfach weggelassen oder in EVE ausgeblendet werden.

attr <XIAOMI> genericDeviceType switch
attr <XIAOMI> homebridgeMapping On=state,valueOn=Cleaning,cmdOn=start,cmdOff=charge
RotationSpeed=fan_power,minValue=0,maxValue=90,cmd=fan_power,delay=1
BatteryLevel=batteryPercent,maxValue=100,minValue=0,minStep=1
StatusLowBattery=batteryState,values=ok:BATTERY_LEVEL_NORMAL;;low:BATTERY_LEVEL_LOW
ChargingState=state,values=Docked:NOT_CHARGING;;Charging:CHARGING;;/.*/:NOT_CHARGEABLE
OccupancyDetected=state,values=/Docked|Charging/:OCCUPANCY_DETECTED;;/.*/:OCCUPANCY_NOT_DETECTED
2af6d0d0-3691-4f0d-9c9c-c1098295b1cb=consumables_sensors,name=Reinigung+Sensoren,minValue=0,maxValue=100,format=FLOAT,minStep=1,unit=%
fd11b965-052e-430f-b08f-206287d8bc00=consumables_filter,name=Austausch+Filter,minValue=0,maxValue=100,format=FLOAT,minStep=1,unit=%
fe7a8dac-dff3-4a07-8a5e-0d6abbf0df0c=consumables_main_brush,name=Austausch+Hauptbürste,minValue=0,maxValue=100,format=FLOAT,minStep=1,unit=%
4f9b2a22-b764-4fc1-8cd2-99383924394c=consumables_side_brush,name=Austausch+Seitenbürste,minValue=0,maxValue=100,format=FLOAT,minStep=1,unit=%
FilterLifeLevel=consumables_filter,minValue=0,maxValue=100
FilterChangeIndication=consumables_filter,values=0:CHANGE_FILTER
4896763a-26f7-400b-9734-2ce6564ceba2=total_clean_time,name=Lebenszeitersparnis,format=FLOAT,minStep=1,unit=h
82af5fd7-50a3-4ab3-81d3-1f7903de612a=total_clean_area,name=Gereinigte+Fläche,format=FLOAT,minStep=1,unit=m²
00d2ef14-b429-4569-8af3-c342d41cf383=total_cleans,name=Reinigungsvorgänge,format=FLOAT,minStep=1
e8d1027e-b068-40d5-9efd-f161b1b52774=device_firmware,name=Firmware,format=STRING

== Xiaomi DC Pedestal Fan (ältere Generation) ==
[[Datei:Xiaomi DC Pedestal Fan.png|mini]]
Voraussetzung zur Verwendung der Mappings, ist ein eingebundener Ventilator mit dem Modul 72_XiaomiDevice.
Siehe [https://forum.fhem.de/index.php/topic,73052.0.html Forumsthread]
Das Modul muss manuell installiert werden.

Die ältere Generation enthält Sensoren und somit Readings für Luftfeuchtigkeit, Temperatur und auch Batteriestatus. Diese fehlen bei der neueren Generation dieses Ventilators, siehe Bilder.

Erklärung zu den Readings:

- Die Kindersicherung (LockPhysicalControls) ist in Eve über das kleine Einstellungssymbol zu finden.
- Mit AudioFeedback/Audio-Bestätigung werden die Töne des Lüfters ein bzw. ausgeschaltet.
- Mit NightVision/Nachtsicht werden die LEDs ein bzw. ausgeschaltet.
- Mit Mute/Audio wird der Windmodus von Straight zu Natural geschaltet.
- Der Rest ist selbsterklärend.

attr <XIAOMI> genericDeviceType Fan
attr <XIAOMI> homebridgeMapping clear
On:power,cmdOn=on,cmdOff=off,valueOn=on,valueOff=off
LockPhysicalControls=child_lock,values=on:CONTROL_LOCK_ENABLED;;off:CONTROL_LOCK_DISABLED,cmds=CONTROL_LOCK_ENABLED:child_lock+on;CONTROL_LOCK_DISABLED:child_lock+off
RotationSpeed=level,minValue=0,maxValue=100,cmd=level,delay=1
TargetTiltAngle=angle,minValue=30,maxValue=120,minStep=30,cmd=angle
SwingMode=angle_enable,values=on:SWING_ENABLED;;off:SWING_DISABLED,cmdOn=angle_enable+on,cmdOff=angle_enable+off
CurrentRelativeHumidity=humidity
CurrentTemperature=temperature
BatteryLevel=batteryPercent,maxValue=100,minValue=0,minStep=1
AudioFeedback:buzzer,cmdOn=buzzer+on,cmdOff=buzzer+off,valueOn=on,valueOff=off
NightVision:led,cmdOn=led+off,cmdOff=led+bright,valueOn=off,valueOff=bright
Mute:mode,cmdOn=mode+straight,cmdOff=mode+natural,valueOn=straight,valueOff=natural

== Xiaomi Standing Fan 2 bzw. 2S (neuere Generation) ==
[[Datei:Xiaomi Standing Fan 2 bzw. 2S.png|mini]]
Voraussetzung zur Verwendung der Mappings, ist ein eingebundener Ventilator mit dem Modul 72_XiaomiDevice.
Siehe [https://forum.fhem.de/index.php/topic,73052.0.html Forumsthread]
Das Modul muss manuell installiert werden.

Den neueren Generationen dieses Ventilators fehlen Sensoren und somit Readings für Luftfeuchtigkeit, Temperatur und auch Batteriestatus. Diese sind bei der älteren Generation dieses Ventilators enthalten, siehe vorangegangenes Beispiel.

Dieses Mapping wurde mit dem "2S" erstellt. Es sollte aber mindestens auch mit einem "Xiaomi Standing Fan 2" (ohne Akku) funktionieren, da auch der "Xiaomi Standing Fan 2S" (mit Akku) kein Reading für die Batterie bereitstellt. Ansonsten gibt es wohl auch noch Generationen zwischen dem "Xiaomi DC Pedestal Fan" und den "Xiaomi Standing Fan 2/2S". Es ist davon auszugehen, dass dieses Beispiel genauso auch bei diesen Modellen funktioniert.

Erklärung zu den Readings:

- Die Kindersicherung (LockPhysicalControls) ist in Eve über das kleine Einstellungssymbol zu finden.
- Mit AudioFeedback/Audio-Bestätigung werden die Töne des Lüfters ein bzw. ausgeschaltet. (Da "buzzer" bei diesem Modell "noch" nicht funktioniert, ist dies derzeitig noch ohne Funktion.)
- Mit NightVision/Nachtsicht werden die LEDs ein bzw. ausgeschaltet.
- Mit Mute/Audio wird der Windmodus von Straight zu Natural geschaltet. (Die Bezeichnung ist nicht ganz selbst erklärend.)
- Der Rest ist selbsterklärend.

attr <XIAOMI> genericDeviceType Fan
attr <XIAOMI> homebridgeMapping clear
On:power,cmdOn=on,cmdOff=off,valueOn=on,valueOff=off
LockPhysicalControls=child_lock,values=on:CONTROL_LOCK_ENABLED;;off:CONTROL_LOCK_DISABLED,cmds=CONTROL_LOCK_ENABLED:child_lock+on;CONTROL_LOCK_DISABLED:child_lock+off
RotationSpeed=level,minValue=0,maxValue=100,cmd=level,delay=1
TargetTiltAngle=angle,minValue=30,maxValue=120,minStep=30,cmd=angle
SwingMode=angle_enable,values=on:SWING_ENABLED;;off:SWING_DISABLED,cmdOn=angle_enable+on,cmdOff=angle_enable+off
CurrentRelativeHumidity=humidity
CurrentTemperature=temperature
BatteryLevel=batteryPercent,maxValue=100,minValue=0,minStep=1
AudioFeedback:buzzer,cmdOn=buzzer+on,cmdOff=buzzer+off,valueOn=on,valueOff=off
NightVision:led,cmdOn=led+off,cmdOff=led+bright,valueOn=off,valueOff=bright
Mute:mode,cmdOn=mode+straight,cmdOff=mode+natural,valueOn=straight,valueOff=natural

== Homematic SmokeDetector ==
[[Datei:Homebridge-Homematic-Smokedetector-Gen1.jpg|mini|Homebridge-Homematic-Smokedetector-Gen1 in EVE]]
Es sind keine Homebridge Mappings für die Rauch Meldung erforderlich.

Allerdings ist ein Mapping für den Batterie Zustand nötig, siehe Unten.

attr <SmokeDetector> genericDeviceType SmokeSensor
attr <SmokeDetector> subType smokeDetector

attr <SmokeDetector> homebridgeMapping StatusLowBattery=battery,values=ok:BATTERY_LEVEL_NORMAL;;/^.*/:BATTERY_LEVEL_LOW

== Vallox Belüftungsanlage ==
Die Steuerung der Lüftungsgeschwindigkeit ist nur in Prozent möglich. Die Umrechnung erfolgt im [[Vallox]] Modul.
Hierzu wurde das Reading ''FanSpeedPct'' hinzugefügt.

attr <Vallox> genericDeviceType Fan
attr <Vallox> homebridgeMapping clear
model=Vallox
On=PowerState,valueOn=1,readOnly=1
RotationSpeed=FanSpeedPct,minValue=1,maxValue=100,cmd=FanSpeedPct,delay=1

[[Kategorie:HOWTOS]]
[[Kategorie:Code Snippets]]

Datei:Xiaomi DC Pedestal Fan.png

2019-06-19T22:58:10Z

Hoppel118:

Xiaomi DC Pedestal Fan

Datei:Roborock S50.png

2019-06-19T22:57:44Z

Hoppel118:

Roborock S50

Homebridge User Configs

2019-06-19T22:47:12Z

Hoppel118:

Dieser Eintrag dient zur Sammlung funktionsfähiger Homebridge Configs.

Bitte immer die FHEM Version und Homebridge Version angegeben.

Sehr gute Hinweise gibt es hier: http://www.meintechblog.de/2015/10/mit-siri-und-fhem-das-gesamte-smart-home-per-stimme-steuern/
== Mögliche Mappings ==
Die Möglichen Mappings können hier nachgelesen werden https://github.com/KhaosT/HAP-NodeJS/blob/master/lib/gen/HomeKitTypes.js

Hier ein Beispiel:
Characteristic.Brightness = function() {
Characteristic.call(this, 'Brightness', '00000008-0000-1000-8000-0026BB765291');
this.setProps({
format: Characteristic.Formats.INT,
unit: Characteristic.Units.PERCENTAGE,
maxValue: 100,
minValue: 0,
minStep: 1,
perms: [Characteristic.Perms.READ, Characteristic.Perms.WRITE, Characteristic.Perms.NOTIFY]
});
this.value = this.getDefaultValue();
};

Das Mapping in diesem Fall, hat den Titel Brightness.

Die Werte können in 1er Schritten zwischen 0 und 100 liegen (max und min Value)
== Feuchtesensor ==
Zum Einstieg etwas leicht nachvollziehbares.

Feuchtesensoren haben in der Regel ein "humidity" Reading, im Falle des Opus XT300 Bodenfeuchtesensors auch Temperatur und Batterie Level. Homekit unterstützt einen "HumiditySensor" Service. Dieser ist in homebridge-fhem nicht standardmäßig vorhanden (kann also nicht aus dem dropdown ausgewählt werden, sondern muss über das Befehlsfeld zugewiesen werden):

<code>attr meinSensor genericDeviceType HumiditySensor</code>

Im nächsten Schritt werden die Readings gemappt:

<code>attr meinSensor homebridgeMapping clear CurrentRelativeHumidity=humidity StatusLowBattery=battery,values=ok:BATTERY_LEVEL_NORMAL;;/^.*/:BATTERY_LEVEL_LOW CurrentTemperature=temperature</code>

<code>clear</code>löscht default mappings - das wird in der Regel nicht notwendig sein, schadet aber nicht

<code>CurrentRelativeHumidity</code> ist die relevante Homekit Characteristic - wird mit dem entsprechenden Reading des Sensors gemappt.

<code>StatusLowBattery</code> erwartet entweder BATTERY_LEVEL_NORMAL oder _LOW. Mein Sensor liefert ok zurück, wenn alles gut ist, also wird "ok" auf _NORMAL gemappt, alles andere auf _LOW.

Der Opus XT300 Bodenfeuchtesensors liefert auch noch die Temperatur - der HumiditySensor Service sieht das eigentlich nicht vor, daher wird die Temperatur auch nicht in der Apple "Home" App angezeigt. Bei Eve wird die Temperatur hingegen berücksichtigt.

== EnOcean STM 250 Tür-/Fensterkontakt ==
Der STM 250 liefert als Status in FHEM <code>open</code>, wenn das Fenster offen und damit der Kontakt "offen" ist. Analog liefert er <code>closed</code> wenn das Fenster geschlossen und damit auch der Kontakt geschlossen ist. Diese Statusangaben sind sehr intuitiv zu verstehen und zu interpretieren.

Die characteristic <code>ContactSensorState</code> von HomeKit liefert entweder den Wert <code>CONTACT_DETECTED=0</code> oder <code>CONTACT_NOT_DETECTED=1</code> zurück. Wobei <code>CONTACT_DETECTED</code> bedeutet, dass der Kontakt geschlossen ist. Je nach Darstellung in der HomeKit-fähigen App muss dieses Verhalten bei der Interpretation berücksichtigt werden. Die App Eve von Elgato zum Beispiel liefert für Kontaktsensoren "JA" oder "NEIN" mit der Bedeutung <code>CONTACT_DETECTED=0=JA</code> bzw. <code>CONTACT_NOT_DETECTED=1=NEIN</code> zurück.

Noch ein wichtiger Punkt: Um einen Sensorkontakt sinnvoll einzurichten sollte als zusätzlicher Wert für das Attribut <code>genericdeviceType</code> der Wert <code>ContactSensor</code> hinzugefügt werden. Wie das geht ist im Eintrag [[Homebridge_einrichten#FHEM_konfigurieren | Homebridge einrichten]] ausführlicher beschrieben.

Folgende Attribute dann hinzufügen:
attr STM250 genericDeviceType ContactSensor
attr STM250 homebridgeMapping ContactSensorState=state,values=closed:CONTACT_DETECTED;open:CONTACT_NOT_DETECTED

Getestet mit
FHEM 5.7 Rev. 9893
Homebridge 0.2.16
homebridge-fhem Vorschauversion aus {{Link2Forum|Topic=48558|Message=402024|LinkText=homebridge/homekit}}

== Modul RESIDENTS für Anwesenheitserkennung und Steuerung der Anwesenheit benutzen ==
[[Datei:Homebridge_bewohner_zu_szene.jpeg|mini|Schaltzustand eines Bewohners zu einer Szene hinzufügen]]
Aus den einzelnen Komponenten des Moduls RESIDENTS, homebridge sowie der characteristic <code>On</code> und der Szenensteuerung lässt sich eine gleichzeitige Steuerung der Anwesenheit und Anwesenheitserkennung basteln.

Dazu müssen folgende Schritte unternommen werden:
* einem Bewohner aus dem Modul ROOMMATE die Steuerung über homebridgeMapping hinzufügen
* Szene für "Ich bin zu Hause" und "Ich gehe jetzt" in einer HomeKit-fähigen App wie z.B. Eve einrichten

Man kann einen beliebigen Bewohner aus dem Modul ROOMMATE nehmen und ihn über die characteristic <code>On</code> in Form eines Schalters sozusagen schaltbar machen. Nur wird das Ein- und Ausschalten des Bewohners über HomeKit in FHEM auf den Status home bzw. absent gemappt. Seit dem 06.02.2016 werden RESIDENTS automatisch als Occupancy Sensor für HomeKit annonciert. Nun noch die Attribute des ROOMMATE wie folgt setzen:
attr <ROOMMATE> genericDeviceType switch
attr <ROOMMATE> homebridgeMapping On=state,valueOn=/home|awoken|asleep|gotosleep/,valueOff=/gone|absent/,cmdOn=home,cmdOff=absent

Natürlich muss der Bewohner noch dem Filter von homebridge hinzugefügt und homebridge neu gestartet werden.

Anschließend geht es in der HomeKit-fähigen App Deiner Wahl weiter. In Eve von Elgato ist von vornherein zum Beispiel vorgesehen, dass man zwei Szenen "Ich bin zuhause" und "Ich verlasse das Haus" hat. Zu diesen Szenen wird eine Aktion hinzugefügt indem der Bewohner, den das ROOMMATE-Modul meldet zur Szene hinzugefügt wird und beim Nachhausekommen "eingeschaltet" wird. Genauso wird mit der Szene "Ich verlasse das Haus" verfahren: Bewohner zur Szene hinzufügen und den Schaltvorgang auf "ausschalten" setzen.

Mit den Sprachbefehlen "Ich bin zuhause" oder "Ich verlasse das Haus" wird die entsprechende Szene eingeschaltet, homebridge schaltet über das <code>homebridgeMapping</code> Attribut dann den Bewohner auf "home" oder "absent".

Getestet mit
FHEM 5.7 Rev. 9893
Homebridge 0.2.16
homebridge-fhem Vorschauversion aus {{Link2Forum|Topic=48558|Message=402024|LinkText=homebridge/homekit}}

Eine noch etwas bessere Schaltmöglichkeit bietet '''genericDeviceType security'''.
Das Mapping für ROOMMATE sieht wie folgt aus:
attr TYPE=ROOMMATE genericDeviceType security
attr TYPE=ROOMMATE homebridgeMapping SecuritySystemCurrentState=state,values=/home|awoken/:0;;absent:1;;/asleep|gotosleep/:2;;gone:3 SecuritySystemTargetState=SecuritySystemCurrentState,cmds=0:state+home;;1:state+absent;;2:state+gotosleep;;3:state+gone,delay=1
für GUEST:
attr TYPE=GUEST genericDeviceType security
attr TYPE=GUEST homebridgeMapping SecuritySystemCurrentState=state,values=/home|awoken/:0;;absent:1;;/asleep|gotosleep/:2;;none:3 SecuritySystemTargetState=SecuritySystemCurrentState,cmds=0:state+home;;1:state+absent;;2:state+gotosleep;;3:state+none,delay=1

== ZWave Türschloss Vision ZM1701 einbinden ==
Das ZWave Türschloss ZM1701 von der Firma Vision sendet seinen aktuellen Schließstatus in ein einzelnes Reading wie "lock", sondern schickt eine ganze Reihe von Informationen über den Zustand in das Reading <code>doorLockOperation</code>. Das Schließen und Öffnen der Türschlosses wird auch nicht mit einem Setzen des <code>state</code> erreicht, sondern mit dem Setzen von <code>doorLockOperation</code>. Das macht das Einbinden in homebridge nicht trivial, funktioniert aber über folgendes Homebridge-Mapping:
attr <ZM1701> genericDeviceType lock
attr <ZM1701> homebridgeMapping LockCurrentState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED LockTargetState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED,cmds=SECURED:doorLockOperation+close;UNSECURED:doorLockOperation+open

Kurz zur Erklärung: Um ein Schloss über HomeKit steuern zu können braucht es zwei characteristics. LockCurrentState zeigt an, ob das Schloss geöffnet oder geschlossen ist. Und mit LockTargetState wird das Schloss geöffnet oder geschlossen. Damit der aktuelle Status des Schlosses ausgelesen werden kann, muss aus dem FHEM-Reading <code>doorLockOperation</code> die Zeichenfolge <code> secured</code> oder <code>unsecured</code> extrahiert werden, daher die beiden regulären Ausdrücke <code>/\ssecured/</code> und <code>/unsecured/</code>. In der characteristic <code>LockTargetState</code> muss sowohl der aktuelle Status des Schlosses als auch das Kommando angegeben werden, schließlich möchte man ein geschlossenes Schloss nicht nochmal schließen. Daher wird erst aus dem Reading <code>doorLockOperation</code> der aktuelle Status des Schlosses ausgelesen und die damit korrespondierenden Befehle über <code>cmds=SECURED:doorLockOperation+close;UNSECURED:doorLockOperation+open</code> generiert.

Wer es in FHEM über ein webCmd einfacher zu bedienen haben möchte, fügt bitte noch die dafür notwendigen Attribute und die leicht geänderten homebridgeMappings wie folgt ein:
attr <ZM1701> genericDeviceType lock
attr <ZM1701> homebridgeMapping LockCurrentState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED LockTargetState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED,cmds=SECURED:close;UNSECURED:open
attr <ZM1701> /doorLockOperation open:open/doorLockOperation close:close
attr <ZM1701> webCmd open:close

Getestet mit
FHEM 5.7 Rev. 12191
homebridge 0.4.6
homebridge-fhem 0.2.48

== Roomba über THINKINGCLEANER Modul ==
attr <THINKINGCLEANER> genericDeviceType switch
attr <THINKINGCLEANER> homebridgeMapping clear On=state,valueOn=/^(on|dock)/,cmdOn=on,cmdOff=off,nocache=1 ChargingState=deviceStatus,values=/(_recon|_full|_trickle)$/:CHARGING;/^.*/:NOT_CHARGING
attr <THINKINGCLEANER> siriName Robby

Getestet mit
FHEM 5.7 Rev. 12680
homebridge 0.4.11
homebridge-fhem 0.2.66

== Homematic HM-CC-RT-DN Funk-Heizkörperthermostat ==
[[Datei:HM-CC-RT-DN-Eve.PNG|mini|Darstellung des HM-CC-RT-DN in der iOS App Eve]]
attr <HMCCRTDN_Channel2_Clima> homebridgeMapping TargetTemperature=desired-temp::desired-temp,minValue=5,maxValue=35,minStep=0.5,nocache=1
CurrentTemperature=BU_Heizung_01_Clima:measured-temp,nocache=1
StatusLowBattery=BU_Heizung_01:battery,values=ok:BATTERY_LEVEL_NORMAL;;/^.*/:BATTERY_LEVEL_LOW
TargetHeatingCoolingState=heatingState,values=OFF:0;;HEAT:1;;COOL:2;;AUTO:3,cmds=OFF:controlManu+off;;HEAT:controlMode+boost;;AUTO:controlMode+auto;;COOL:controlManu+17.0
CurrentHeatingCoolingState=heatingState,values=OFF:0;;HEAT:1;;COOL:2;;AUTO:0,valud=OFF
attr <HMCCRTDN_Channel2_Clima> siriName Robby
Dieses Mapping bezieht sich auf ein vorhandenes ''userReading'' mit dem Namen <code>heatingState</code>, womit Homekit die einzelnen Status nachher unterscheidet.
attr <HM-CC-RT-DN_Clima> userReadings heatingState {(ReadingsVal($NAME,"ValvePosition",0) > 0 || ReadingsVal($NAME,"desired-temp","-") eq "on") ? "HEAT" : ReadingsVal($NAME,"desired-temp","-") eq "off" ? "OFF" : ReadingsVal($NAME,"controlMode","auto") eq "auto" ? "AUTO" : (ReadingsVal($NAME,"measured-temp",20) > ReadingsVal($NAME,"desired-temp",20)) ? "COOL" : "AUTO"}
Global auf alle in FHEM angelegten HM-CC-RT-DN, lässt sich mit folgendem Befehl das ''userReading'' anlegen.
Siehe [https://forum.fhem.de/index.php/topic,59211.msg505986.html#msg505986 Forumsthread].

attr TYPE=CUL_HM:FILTER=model=HM-CC-RT-DN:FILTER=chanNo=04 userReadings heatingState {(ReadingsVal($NAME,"ValvePosition",0) > 0 || ReadingsVal($NAME,"desired-temp","-") eq "on") ? "HEAT" : ReadingsVal($NAME,"desired-temp","-") eq "off" ? "OFF" : ReadingsVal($NAME,"controlMode","auto") eq "auto" ? "AUTO" : (ReadingsVal($NAME,"measured-temp",20) > ReadingsVal($NAME,"desired-temp",20)) ? "COOL" : "AUTO"}

== Xiaomi Vacuum Cleaner 1. Generation ==
[[Datei:XIAOMI_VACUUM_CLEANER-Gen1.jpg|mini|XIAOMI VACUUM 1. GEN in EVE]]
Voraussetzung zur Verwendung der Mappings, ist ein eingebundener Staubsauger mit dem Modul 72_XiaomiDevice.

Siehe [https://forum.fhem.de/index.php/topic,73052.0.html Forumsthread]
Das Modul muss manuell installiert werden.

attr <XIAOMI> genericDeviceType switch
attr <XIAOMI> homebridgeMapping On=state,valueOn=Cleaning,cmdOn=start,cmdOff=charge
RotationSpeed=fan_power,minValue=0,maxValue=90,cmd=fan_power,delay=1
BatteryLevel=batteryLevel,maxValue=100,minValue=0,minStep=1
StatusLowBattery=battery,values=ok:BATTERY_LEVEL_NORMAL;;low:BATTERY_LEVEL_LOW
ChargingState=state,values=Docked:NOT_CHARGING;;Charging:CHARGING;;/.*/:NOT_CHARGEABLE
OccupancyDetected=state,values=/Docked|Charging/:OCCUPANCY_DETECTED;;/.*/:OCCUPANCY_NOT_DETECTED
FilterLifeLevel=consumables_filter,minValue=0,maxValue=100
FilterChangeIndication=consumables_filter,values=0:CHANGE_FILTER

== Roborock S50 (2. Generation des Xiaomi Vacuum Cleaners) ==

Voraussetzung zur Verwendung der Mappings, ist ein eingebundener Staubsauger mit dem Modul 72_XiaomiDevice.

Siehe [https://forum.fhem.de/index.php/topic,73052.0.html Forumsthread]
Das Modul muss manuell installiert werden.

attr <XIAOMI> genericDeviceType switch
attr <XIAOMI> homebridgeMapping On=state,valueOn=Cleaning,cmdOn=start,cmdOff=charge
RotationSpeed=fan_power,minValue=0,maxValue=90,cmd=fan_power,delay=1
BatteryLevel=batteryPercent,maxValue=100,minValue=0,minStep=1
StatusLowBattery=batteryState,values=ok:BATTERY_LEVEL_NORMAL;;low:BATTERY_LEVEL_LOW
ChargingState=state,values=Docked:NOT_CHARGING;;Charging:CHARGING;;/.*/:NOT_CHARGEABLE
OccupancyDetected=state,values=/Docked|Charging/:OCCUPANCY_DETECTED;;/.*/:OCCUPANCY_NOT_DETECTED
2af6d0d0-3691-4f0d-9c9c-c1098295b1cb=consumables_sensors,name=Reinigung+Sensoren,minValue=0,maxValue=100,format=FLOAT,minStep=1,unit=%
fd11b965-052e-430f-b08f-206287d8bc00=consumables_filter,name=Austausch+Filter,minValue=0,maxValue=100,format=FLOAT,minStep=1,unit=%
fe7a8dac-dff3-4a07-8a5e-0d6abbf0df0c=consumables_main_brush,name=Austausch+Hauptbürste,minValue=0,maxValue=100,format=FLOAT,minStep=1,unit=%
4f9b2a22-b764-4fc1-8cd2-99383924394c=consumables_side_brush,name=Austausch+Seitenbürste,minValue=0,maxValue=100,format=FLOAT,minStep=1,unit=%
FilterLifeLevel=consumables_filter,minValue=0,maxValue=100
FilterChangeIndication=consumables_filter,values=0:CHANGE_FILTER
4896763a-26f7-400b-9734-2ce6564ceba2=total_clean_time,name=Lebenszeitersparnis,format=FLOAT,minStep=1,unit=h
82af5fd7-50a3-4ab3-81d3-1f7903de612a=total_clean_area,name=Gereinigte+Fläche,format=FLOAT,minStep=1,unit=m²
00d2ef14-b429-4569-8af3-c342d41cf383=total_cleans,name=Reinigungsvorgänge,format=FLOAT,minStep=1
e8d1027e-b068-40d5-9efd-f161b1b52774=device_firmware,name=Firmware,format=STRING

== Xiaomi DC Pedestal Fan (ältere Generation) ==

Voraussetzung zur Verwendung der Mappings, ist ein eingebundener Ventilator mit dem Modul 72_XiaomiDevice.
Siehe [https://forum.fhem.de/index.php/topic,73052.0.html Forumsthread]
Das Modul muss manuell installiert werden.

Die ältere Generation enthält Sensoren und somit Readings für Luftfeuchtigkeit, Temperatur und auch Batteriestatus. Diese fehlen bei der neueren Generation dieses Ventilators.

Erklärung zu den Readings:

- Die Kindersicherung (LockPhysicalControls) ist in Eve über das kleine Einstellungssymbol zu finden.
- Mit AudioFeedback/Audio-Bestätigung werden die Töne des Lüfters ein bzw. ausgeschaltet.
- Mit NightVision/Nachtsicht werden die LEDs ein bzw. ausgeschaltet.
- Mit Mute/Audio wird der Windmodus von Straight zu Natural geschaltet.
- Der Rest ist selbsterklärend.

attr <XIAOMI> genericDeviceType Fan
attr <XIAOMI> homebridgeMapping clear
On:power,cmdOn=on,cmdOff=off,valueOn=on,valueOff=off
LockPhysicalControls=child_lock,values=on:CONTROL_LOCK_ENABLED;;off:CONTROL_LOCK_DISABLED,cmds=CONTROL_LOCK_ENABLED:child_lock+on;CONTROL_LOCK_DISABLED:child_lock+off
RotationSpeed=level,minValue=0,maxValue=100,cmd=level,delay=1
TargetTiltAngle=angle,minValue=30,maxValue=120,minStep=30,cmd=angle
SwingMode=angle_enable,values=on:SWING_ENABLED;;off:SWING_DISABLED,cmdOn=angle_enable+on,cmdOff=angle_enable+off
CurrentRelativeHumidity=humidity
CurrentTemperature=temperature
BatteryLevel=batteryPercent,maxValue=100,minValue=0,minStep=1
AudioFeedback:buzzer,cmdOn=buzzer+on,cmdOff=buzzer+off,valueOn=on,valueOff=off
NightVision:led,cmdOn=led+off,cmdOff=led+bright,valueOn=off,valueOff=bright
Mute:mode,cmdOn=mode+straight,cmdOff=mode+natural,valueOn=straight,valueOff=natural

== Xiaomi Standing Fan 2 bzw. 2S (neuere Generation) ==
[[Datei:Xiaomi Standing Fan 2 bzw. 2S.png|mini]]
Voraussetzung zur Verwendung der Mappings, ist ein eingebundener Ventilator mit dem Modul 72_XiaomiDevice.
Siehe [https://forum.fhem.de/index.php/topic,73052.0.html Forumsthread]
Das Modul muss manuell installiert werden.

Den neueren Generationen dieses Ventilators fehlen Sensoren und somit Readings für Luftfeuchtigkeit, Temperatur und auch Batteriestatus. Diese sind bei der älteren Generation dieses Ventilators enthalten, siehe vorangegangenes Beispiel.

Dieses Mapping wurde mit dem "2S" erstellt. Es sollte aber mindestens auch mit einem "Xiaomi Standing Fan 2" (ohne Akku) funktionieren, da auch der "Xiaomi Standing Fan 2S" (mit Akku) kein Reading für die Batterie bereitstellt. Ansonsten gibt es wohl auch noch Generationen zwischen dem "Xiaomi DC Pedestal Fan" und den "Xiaomi Standing Fan 2/2S". Es ist davon auszugehen, dass dieses Beispiel genauso auch bei diesen Modellen funktioniert.

Erklärung zu den Readings:

- Die Kindersicherung (LockPhysicalControls) ist in Eve über das kleine Einstellungssymbol zu finden.
- Mit AudioFeedback/Audio-Bestätigung werden die Töne des Lüfters ein bzw. ausgeschaltet. (Da "buzzer" bei diesem Modell "noch" nicht funktioniert, ist dies derzeitig noch ohne Funktion.)
- Mit NightVision/Nachtsicht werden die LEDs ein bzw. ausgeschaltet.
- Mit Mute/Audio wird der Windmodus von Straight zu Natural geschaltet. (Die Bezeichnung ist nicht ganz selbst erklärend.)
- Der Rest ist selbsterklärend.

attr <XIAOMI> genericDeviceType Fan
attr <XIAOMI> homebridgeMapping clear
On:power,cmdOn=on,cmdOff=off,valueOn=on,valueOff=off
LockPhysicalControls=child_lock,values=on:CONTROL_LOCK_ENABLED;;off:CONTROL_LOCK_DISABLED,cmds=CONTROL_LOCK_ENABLED:child_lock+on;CONTROL_LOCK_DISABLED:child_lock+off
RotationSpeed=level,minValue=0,maxValue=100,cmd=level,delay=1
TargetTiltAngle=angle,minValue=30,maxValue=120,minStep=30,cmd=angle
SwingMode=angle_enable,values=on:SWING_ENABLED;;off:SWING_DISABLED,cmdOn=angle_enable+on,cmdOff=angle_enable+off
CurrentRelativeHumidity=humidity
CurrentTemperature=temperature
BatteryLevel=batteryPercent,maxValue=100,minValue=0,minStep=1
AudioFeedback:buzzer,cmdOn=buzzer+on,cmdOff=buzzer+off,valueOn=on,valueOff=off
NightVision:led,cmdOn=led+off,cmdOff=led+bright,valueOn=off,valueOff=bright
Mute:mode,cmdOn=mode+straight,cmdOff=mode+natural,valueOn=straight,valueOff=natural

== Homematic SmokeDetector ==
[[Datei:Homebridge-Homematic-Smokedetector-Gen1.jpg|mini|Homebridge-Homematic-Smokedetector-Gen1 in EVE]]
Es sind keine Homebridge Mappings für die Rauch Meldung erforderlich.

Allerdings ist ein Mapping für den Batterie Zustand nötig, siehe Unten.

attr <SmokeDetector> genericDeviceType SmokeSensor
attr <SmokeDetector> subType smokeDetector

attr <SmokeDetector> homebridgeMapping StatusLowBattery=battery,values=ok:BATTERY_LEVEL_NORMAL;;/^.*/:BATTERY_LEVEL_LOW

== Vallox Belüftungsanlage ==
Die Steuerung der Lüftungsgeschwindigkeit ist nur in Prozent möglich. Die Umrechnung erfolgt im [[Vallox]] Modul.
Hierzu wurde das Reading ''FanSpeedPct'' hinzugefügt.

attr <Vallox> genericDeviceType Fan
attr <Vallox> homebridgeMapping clear
model=Vallox
On=PowerState,valueOn=1,readOnly=1
RotationSpeed=FanSpeedPct,minValue=1,maxValue=100,cmd=FanSpeedPct,delay=1

[[Kategorie:HOWTOS]]
[[Kategorie:Code Snippets]]

Datei:Xiaomi Standing Fan 2 bzw. 2S.png

2019-06-19T22:46:25Z

Hoppel118:

Xiaomi Standing Fan 2 bzw. 2S

Homebridge User Configs

2019-06-19T22:28:04Z

Hoppel118: Roborock S50, Xiaomi DC Pedestal Fan und Xiaomi Standing Fan 2S ergänzt

Dieser Eintrag dient zur Sammlung funktionsfähiger Homebridge Configs.

Bitte immer die FHEM Version und Homebridge Version angegeben.

Sehr gute Hinweise gibt es hier: http://www.meintechblog.de/2015/10/mit-siri-und-fhem-das-gesamte-smart-home-per-stimme-steuern/
== Mögliche Mappings ==
Die Möglichen Mappings können hier nachgelesen werden https://github.com/KhaosT/HAP-NodeJS/blob/master/lib/gen/HomeKitTypes.js

Hier ein Beispiel:
Characteristic.Brightness = function() {
Characteristic.call(this, 'Brightness', '00000008-0000-1000-8000-0026BB765291');
this.setProps({
format: Characteristic.Formats.INT,
unit: Characteristic.Units.PERCENTAGE,
maxValue: 100,
minValue: 0,
minStep: 1,
perms: [Characteristic.Perms.READ, Characteristic.Perms.WRITE, Characteristic.Perms.NOTIFY]
});
this.value = this.getDefaultValue();
};

Das Mapping in diesem Fall, hat den Titel Brightness.

Die Werte können in 1er Schritten zwischen 0 und 100 liegen (max und min Value)
== Feuchtesensor ==
Zum Einstieg etwas leicht nachvollziehbares.

Feuchtesensoren haben in der Regel ein "humidity" Reading, im Falle des Opus XT300 Bodenfeuchtesensors auch Temperatur und Batterie Level. Homekit unterstützt einen "HumiditySensor" Service. Dieser ist in homebridge-fhem nicht standardmäßig vorhanden (kann also nicht aus dem dropdown ausgewählt werden, sondern muss über das Befehlsfeld zugewiesen werden):

<code>attr meinSensor genericDeviceType HumiditySensor</code>

Im nächsten Schritt werden die Readings gemappt:

<code>attr meinSensor homebridgeMapping clear CurrentRelativeHumidity=humidity StatusLowBattery=battery,values=ok:BATTERY_LEVEL_NORMAL;;/^.*/:BATTERY_LEVEL_LOW CurrentTemperature=temperature</code>

<code>clear</code>löscht default mappings - das wird in der Regel nicht notwendig sein, schadet aber nicht

<code>CurrentRelativeHumidity</code> ist die relevante Homekit Characteristic - wird mit dem entsprechenden Reading des Sensors gemappt.

<code>StatusLowBattery</code> erwartet entweder BATTERY_LEVEL_NORMAL oder _LOW. Mein Sensor liefert ok zurück, wenn alles gut ist, also wird "ok" auf _NORMAL gemappt, alles andere auf _LOW.

Der Opus XT300 Bodenfeuchtesensors liefert auch noch die Temperatur - der HumiditySensor Service sieht das eigentlich nicht vor, daher wird die Temperatur auch nicht in der Apple "Home" App angezeigt. Bei Eve wird die Temperatur hingegen berücksichtigt.

== EnOcean STM 250 Tür-/Fensterkontakt ==
Der STM 250 liefert als Status in FHEM <code>open</code>, wenn das Fenster offen und damit der Kontakt "offen" ist. Analog liefert er <code>closed</code> wenn das Fenster geschlossen und damit auch der Kontakt geschlossen ist. Diese Statusangaben sind sehr intuitiv zu verstehen und zu interpretieren.

Die characteristic <code>ContactSensorState</code> von HomeKit liefert entweder den Wert <code>CONTACT_DETECTED=0</code> oder <code>CONTACT_NOT_DETECTED=1</code> zurück. Wobei <code>CONTACT_DETECTED</code> bedeutet, dass der Kontakt geschlossen ist. Je nach Darstellung in der HomeKit-fähigen App muss dieses Verhalten bei der Interpretation berücksichtigt werden. Die App Eve von Elgato zum Beispiel liefert für Kontaktsensoren "JA" oder "NEIN" mit der Bedeutung <code>CONTACT_DETECTED=0=JA</code> bzw. <code>CONTACT_NOT_DETECTED=1=NEIN</code> zurück.

Noch ein wichtiger Punkt: Um einen Sensorkontakt sinnvoll einzurichten sollte als zusätzlicher Wert für das Attribut <code>genericdeviceType</code> der Wert <code>ContactSensor</code> hinzugefügt werden. Wie das geht ist im Eintrag [[Homebridge_einrichten#FHEM_konfigurieren | Homebridge einrichten]] ausführlicher beschrieben.

Folgende Attribute dann hinzufügen:
attr STM250 genericDeviceType ContactSensor
attr STM250 homebridgeMapping ContactSensorState=state,values=closed:CONTACT_DETECTED;open:CONTACT_NOT_DETECTED

Getestet mit
FHEM 5.7 Rev. 9893
Homebridge 0.2.16
homebridge-fhem Vorschauversion aus {{Link2Forum|Topic=48558|Message=402024|LinkText=homebridge/homekit}}

== Modul RESIDENTS für Anwesenheitserkennung und Steuerung der Anwesenheit benutzen ==
[[Datei:Homebridge_bewohner_zu_szene.jpeg|mini|Schaltzustand eines Bewohners zu einer Szene hinzufügen]]
Aus den einzelnen Komponenten des Moduls RESIDENTS, homebridge sowie der characteristic <code>On</code> und der Szenensteuerung lässt sich eine gleichzeitige Steuerung der Anwesenheit und Anwesenheitserkennung basteln.

Dazu müssen folgende Schritte unternommen werden:
* einem Bewohner aus dem Modul ROOMMATE die Steuerung über homebridgeMapping hinzufügen
* Szene für "Ich bin zu Hause" und "Ich gehe jetzt" in einer HomeKit-fähigen App wie z.B. Eve einrichten

Man kann einen beliebigen Bewohner aus dem Modul ROOMMATE nehmen und ihn über die characteristic <code>On</code> in Form eines Schalters sozusagen schaltbar machen. Nur wird das Ein- und Ausschalten des Bewohners über HomeKit in FHEM auf den Status home bzw. absent gemappt. Seit dem 06.02.2016 werden RESIDENTS automatisch als Occupancy Sensor für HomeKit annonciert. Nun noch die Attribute des ROOMMATE wie folgt setzen:
attr <ROOMMATE> genericDeviceType switch
attr <ROOMMATE> homebridgeMapping On=state,valueOn=/home|awoken|asleep|gotosleep/,valueOff=/gone|absent/,cmdOn=home,cmdOff=absent

Natürlich muss der Bewohner noch dem Filter von homebridge hinzugefügt und homebridge neu gestartet werden.

Anschließend geht es in der HomeKit-fähigen App Deiner Wahl weiter. In Eve von Elgato ist von vornherein zum Beispiel vorgesehen, dass man zwei Szenen "Ich bin zuhause" und "Ich verlasse das Haus" hat. Zu diesen Szenen wird eine Aktion hinzugefügt indem der Bewohner, den das ROOMMATE-Modul meldet zur Szene hinzugefügt wird und beim Nachhausekommen "eingeschaltet" wird. Genauso wird mit der Szene "Ich verlasse das Haus" verfahren: Bewohner zur Szene hinzufügen und den Schaltvorgang auf "ausschalten" setzen.

Mit den Sprachbefehlen "Ich bin zuhause" oder "Ich verlasse das Haus" wird die entsprechende Szene eingeschaltet, homebridge schaltet über das <code>homebridgeMapping</code> Attribut dann den Bewohner auf "home" oder "absent".

Getestet mit
FHEM 5.7 Rev. 9893
Homebridge 0.2.16
homebridge-fhem Vorschauversion aus {{Link2Forum|Topic=48558|Message=402024|LinkText=homebridge/homekit}}

Eine noch etwas bessere Schaltmöglichkeit bietet '''genericDeviceType security'''.
Das Mapping für ROOMMATE sieht wie folgt aus:
attr TYPE=ROOMMATE genericDeviceType security
attr TYPE=ROOMMATE homebridgeMapping SecuritySystemCurrentState=state,values=/home|awoken/:0;;absent:1;;/asleep|gotosleep/:2;;gone:3 SecuritySystemTargetState=SecuritySystemCurrentState,cmds=0:state+home;;1:state+absent;;2:state+gotosleep;;3:state+gone,delay=1
für GUEST:
attr TYPE=GUEST genericDeviceType security
attr TYPE=GUEST homebridgeMapping SecuritySystemCurrentState=state,values=/home|awoken/:0;;absent:1;;/asleep|gotosleep/:2;;none:3 SecuritySystemTargetState=SecuritySystemCurrentState,cmds=0:state+home;;1:state+absent;;2:state+gotosleep;;3:state+none,delay=1

== ZWave Türschloss Vision ZM1701 einbinden ==
Das ZWave Türschloss ZM1701 von der Firma Vision sendet seinen aktuellen Schließstatus in ein einzelnes Reading wie "lock", sondern schickt eine ganze Reihe von Informationen über den Zustand in das Reading <code>doorLockOperation</code>. Das Schließen und Öffnen der Türschlosses wird auch nicht mit einem Setzen des <code>state</code> erreicht, sondern mit dem Setzen von <code>doorLockOperation</code>. Das macht das Einbinden in homebridge nicht trivial, funktioniert aber über folgendes Homebridge-Mapping:
attr <ZM1701> genericDeviceType lock
attr <ZM1701> homebridgeMapping LockCurrentState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED LockTargetState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED,cmds=SECURED:doorLockOperation+close;UNSECURED:doorLockOperation+open

Kurz zur Erklärung: Um ein Schloss über HomeKit steuern zu können braucht es zwei characteristics. LockCurrentState zeigt an, ob das Schloss geöffnet oder geschlossen ist. Und mit LockTargetState wird das Schloss geöffnet oder geschlossen. Damit der aktuelle Status des Schlosses ausgelesen werden kann, muss aus dem FHEM-Reading <code>doorLockOperation</code> die Zeichenfolge <code> secured</code> oder <code>unsecured</code> extrahiert werden, daher die beiden regulären Ausdrücke <code>/\ssecured/</code> und <code>/unsecured/</code>. In der characteristic <code>LockTargetState</code> muss sowohl der aktuelle Status des Schlosses als auch das Kommando angegeben werden, schließlich möchte man ein geschlossenes Schloss nicht nochmal schließen. Daher wird erst aus dem Reading <code>doorLockOperation</code> der aktuelle Status des Schlosses ausgelesen und die damit korrespondierenden Befehle über <code>cmds=SECURED:doorLockOperation+close;UNSECURED:doorLockOperation+open</code> generiert.

Wer es in FHEM über ein webCmd einfacher zu bedienen haben möchte, fügt bitte noch die dafür notwendigen Attribute und die leicht geänderten homebridgeMappings wie folgt ein:
attr <ZM1701> genericDeviceType lock
attr <ZM1701> homebridgeMapping LockCurrentState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED LockTargetState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED,cmds=SECURED:close;UNSECURED:open
attr <ZM1701> /doorLockOperation open:open/doorLockOperation close:close
attr <ZM1701> webCmd open:close

Getestet mit
FHEM 5.7 Rev. 12191
homebridge 0.4.6
homebridge-fhem 0.2.48

== Roomba über THINKINGCLEANER Modul ==
attr <THINKINGCLEANER> genericDeviceType switch
attr <THINKINGCLEANER> homebridgeMapping clear On=state,valueOn=/^(on|dock)/,cmdOn=on,cmdOff=off,nocache=1 ChargingState=deviceStatus,values=/(_recon|_full|_trickle)$/:CHARGING;/^.*/:NOT_CHARGING
attr <THINKINGCLEANER> siriName Robby

Getestet mit
FHEM 5.7 Rev. 12680
homebridge 0.4.11
homebridge-fhem 0.2.66

== Homematic HM-CC-RT-DN Funk-Heizkörperthermostat ==
[[Datei:HM-CC-RT-DN-Eve.PNG|mini|Darstellung des HM-CC-RT-DN in der iOS App Eve]]
attr <HMCCRTDN_Channel2_Clima> homebridgeMapping TargetTemperature=desired-temp::desired-temp,minValue=5,maxValue=35,minStep=0.5,nocache=1
CurrentTemperature=BU_Heizung_01_Clima:measured-temp,nocache=1
StatusLowBattery=BU_Heizung_01:battery,values=ok:BATTERY_LEVEL_NORMAL;;/^.*/:BATTERY_LEVEL_LOW
TargetHeatingCoolingState=heatingState,values=OFF:0;;HEAT:1;;COOL:2;;AUTO:3,cmds=OFF:controlManu+off;;HEAT:controlMode+boost;;AUTO:controlMode+auto;;COOL:controlManu+17.0
CurrentHeatingCoolingState=heatingState,values=OFF:0;;HEAT:1;;COOL:2;;AUTO:0,valud=OFF
attr <HMCCRTDN_Channel2_Clima> siriName Robby
Dieses Mapping bezieht sich auf ein vorhandenes ''userReading'' mit dem Namen <code>heatingState</code>, womit Homekit die einzelnen Status nachher unterscheidet.
attr <HM-CC-RT-DN_Clima> userReadings heatingState {(ReadingsVal($NAME,"ValvePosition",0) > 0 || ReadingsVal($NAME,"desired-temp","-") eq "on") ? "HEAT" : ReadingsVal($NAME,"desired-temp","-") eq "off" ? "OFF" : ReadingsVal($NAME,"controlMode","auto") eq "auto" ? "AUTO" : (ReadingsVal($NAME,"measured-temp",20) > ReadingsVal($NAME,"desired-temp",20)) ? "COOL" : "AUTO"}
Global auf alle in FHEM angelegten HM-CC-RT-DN, lässt sich mit folgendem Befehl das ''userReading'' anlegen.
Siehe [https://forum.fhem.de/index.php/topic,59211.msg505986.html#msg505986 Forumsthread].

attr TYPE=CUL_HM:FILTER=model=HM-CC-RT-DN:FILTER=chanNo=04 userReadings heatingState {(ReadingsVal($NAME,"ValvePosition",0) > 0 || ReadingsVal($NAME,"desired-temp","-") eq "on") ? "HEAT" : ReadingsVal($NAME,"desired-temp","-") eq "off" ? "OFF" : ReadingsVal($NAME,"controlMode","auto") eq "auto" ? "AUTO" : (ReadingsVal($NAME,"measured-temp",20) > ReadingsVal($NAME,"desired-temp",20)) ? "COOL" : "AUTO"}

== Xiaomi Vacuum Cleaner 1. Generation ==
[[Datei:XIAOMI_VACUUM_CLEANER-Gen1.jpg|mini|XIAOMI VACUUM 1. GEN in EVE]]
Voraussetzung zur Verwendung der Mappings, ist ein eingebundener Staubsauger mit dem Modul 72_XiaomiDevice.

Siehe [https://forum.fhem.de/index.php/topic,73052.0.html Forumsthread]
Das Modul muss manuell installiert werden.

attr <XIAOMI> genericDeviceType switch
attr <XIAOMI> homebridgeMapping On=state,valueOn=Cleaning,cmdOn=start,cmdOff=charge
RotationSpeed=fan_power,minValue=0,maxValue=90,cmd=fan_power,delay=1
BatteryLevel=batteryLevel,maxValue=100,minValue=0,minStep=1
StatusLowBattery=battery,values=ok:BATTERY_LEVEL_NORMAL;;low:BATTERY_LEVEL_LOW
ChargingState=state,values=Docked:NOT_CHARGING;;Charging:CHARGING;;/.*/:NOT_CHARGEABLE
OccupancyDetected=state,values=/Docked|Charging/:OCCUPANCY_DETECTED;;/.*/:OCCUPANCY_NOT_DETECTED
FilterLifeLevel=consumables_filter,minValue=0,maxValue=100
FilterChangeIndication=consumables_filter,values=0:CHANGE_FILTER

== Roborock S50 (2. Generation des Xiaomi Vacuum Cleaners) ==

Voraussetzung zur Verwendung der Mappings, ist ein eingebundener Staubsauger mit dem Modul 72_XiaomiDevice.

Siehe [https://forum.fhem.de/index.php/topic,73052.0.html Forumsthread]
Das Modul muss manuell installiert werden.

attr <XIAOMI> genericDeviceType switch
attr <XIAOMI> homebridgeMapping On=state,valueOn=Cleaning,cmdOn=start,cmdOff=charge
RotationSpeed=fan_power,minValue=0,maxValue=90,cmd=fan_power,delay=1
BatteryLevel=batteryPercent,maxValue=100,minValue=0,minStep=1
StatusLowBattery=batteryState,values=ok:BATTERY_LEVEL_NORMAL;;low:BATTERY_LEVEL_LOW
ChargingState=state,values=Docked:NOT_CHARGING;;Charging:CHARGING;;/.*/:NOT_CHARGEABLE
OccupancyDetected=state,values=/Docked|Charging/:OCCUPANCY_DETECTED;;/.*/:OCCUPANCY_NOT_DETECTED
2af6d0d0-3691-4f0d-9c9c-c1098295b1cb=consumables_sensors,name=Reinigung+Sensoren,minValue=0,maxValue=100,format=FLOAT,minStep=1,unit=%
fd11b965-052e-430f-b08f-206287d8bc00=consumables_filter,name=Austausch+Filter,minValue=0,maxValue=100,format=FLOAT,minStep=1,unit=%
fe7a8dac-dff3-4a07-8a5e-0d6abbf0df0c=consumables_main_brush,name=Austausch+Hauptbürste,minValue=0,maxValue=100,format=FLOAT,minStep=1,unit=%
4f9b2a22-b764-4fc1-8cd2-99383924394c=consumables_side_brush,name=Austausch+Seitenbürste,minValue=0,maxValue=100,format=FLOAT,minStep=1,unit=%
FilterLifeLevel=consumables_filter,minValue=0,maxValue=100
FilterChangeIndication=consumables_filter,values=0:CHANGE_FILTER
4896763a-26f7-400b-9734-2ce6564ceba2=total_clean_time,name=Lebenszeitersparnis,format=FLOAT,minStep=1,unit=h
82af5fd7-50a3-4ab3-81d3-1f7903de612a=total_clean_area,name=Gereinigte+Fläche,format=FLOAT,minStep=1,unit=m²
00d2ef14-b429-4569-8af3-c342d41cf383=total_cleans,name=Reinigungsvorgänge,format=FLOAT,minStep=1
e8d1027e-b068-40d5-9efd-f161b1b52774=device_firmware,name=Firmware,format=STRING

== Xiaomi DC Pedestal Fan (ältere Generation) ==

Voraussetzung zur Verwendung der Mappings, ist ein eingebundener Ventilator mit dem Modul 72_XiaomiDevice.
Siehe [https://forum.fhem.de/index.php/topic,73052.0.html Forumsthread]
Das Modul muss manuell installiert werden.

Die ältere Generation enthält Sensoren und somit Readings für Luftfeuchtigkeit, Temperatur und auch Batteriestatus. Diese fehlen bei der neueren Generation dieses Ventilators.

Erklärung zu den Readings:

- Die Kindersicherung (LockPhysicalControls) ist in Eve über das kleine Einstellungssymbol zu finden.
- Mit AudioFeedback/Audio-Bestätigung werden die Töne des Lüfters ein bzw. ausgeschaltet.
- Mit NightVision/Nachtsicht werden die LEDs ein bzw. ausgeschaltet.
- Mit Mute/Audio wird der Windmodus von Straight zu Natural geschaltet.
- Der Rest ist selbsterklärend.

attr <XIAOMI> genericDeviceType Fan
attr <XIAOMI> homebridgeMapping clear
On:power,cmdOn=on,cmdOff=off,valueOn=on,valueOff=off
LockPhysicalControls=child_lock,values=on:CONTROL_LOCK_ENABLED;;off:CONTROL_LOCK_DISABLED,cmds=CONTROL_LOCK_ENABLED:child_lock+on;CONTROL_LOCK_DISABLED:child_lock+off
RotationSpeed=level,minValue=0,maxValue=100,cmd=level,delay=1
TargetTiltAngle=angle,minValue=30,maxValue=120,minStep=30,cmd=angle
SwingMode=angle_enable,values=on:SWING_ENABLED;;off:SWING_DISABLED,cmdOn=angle_enable+on,cmdOff=angle_enable+off
CurrentRelativeHumidity=humidity
CurrentTemperature=temperature
BatteryLevel=batteryPercent,maxValue=100,minValue=0,minStep=1
AudioFeedback:buzzer,cmdOn=buzzer+on,cmdOff=buzzer+off,valueOn=on,valueOff=off
NightVision:led,cmdOn=led+off,cmdOff=led+bright,valueOn=off,valueOff=bright
Mute:mode,cmdOn=mode+straight,cmdOff=mode+natural,valueOn=straight,valueOff=natural

== Xiaomi Standing Fan 2 bzw. 2S (neuere Generation) ==

Voraussetzung zur Verwendung der Mappings, ist ein eingebundener Ventilator mit dem Modul 72_XiaomiDevice.
Siehe [https://forum.fhem.de/index.php/topic,73052.0.html Forumsthread]
Das Modul muss manuell installiert werden.

Den neueren Generationen dieses Ventilators fehlen Sensoren und somit Readings für Luftfeuchtigkeit, Temperatur und auch Batteriestatus. Diese sind bei der älteren Generation dieses Ventilators enthalten, siehe vorangegangenes Beispiel.

Dieses Mapping wurde mit dem "2S" erstellt. Es sollte aber mindestens auch mit einem "Xiaomi Standing Fan 2" (ohne Akku) funktionieren, da auch der "Xiaomi Standing Fan 2S" (mit Akku) kein Reading für die Batterie bereitstellt. Ansonsten gibt es wohl auch noch Generationen zwischen dem "Xiaomi DC Pedestal Fan" und den "Xiaomi Standing Fan 2/2S". Es ist davon auszugehen, dass dieses Beispiel genauso auch bei diesen Modellen funktioniert.

Erklärung zu den Readings:

- Die Kindersicherung (LockPhysicalControls) ist in Eve über das kleine Einstellungssymbol zu finden.
- Mit AudioFeedback/Audio-Bestätigung werden die Töne des Lüfters ein bzw. ausgeschaltet. (Da "buzzer" bei diesem Modell "noch" nicht funktioniert, ist dies derzeitig noch ohne Funktion.)
- Mit NightVision/Nachtsicht werden die LEDs ein bzw. ausgeschaltet.
- Mit Mute/Audio wird der Windmodus von Straight zu Natural geschaltet. (Die Bezeichnung ist nicht ganz selbst erklärend.)
- Der Rest ist selbsterklärend.

attr <XIAOMI> genericDeviceType Fan
attr <XIAOMI> homebridgeMapping clear
On:power,cmdOn=on,cmdOff=off,valueOn=on,valueOff=off
LockPhysicalControls=child_lock,values=on:CONTROL_LOCK_ENABLED;;off:CONTROL_LOCK_DISABLED,cmds=CONTROL_LOCK_ENABLED:child_lock+on;CONTROL_LOCK_DISABLED:child_lock+off
RotationSpeed=level,minValue=0,maxValue=100,cmd=level,delay=1
TargetTiltAngle=angle,minValue=30,maxValue=120,minStep=30,cmd=angle
SwingMode=angle_enable,values=on:SWING_ENABLED;;off:SWING_DISABLED,cmdOn=angle_enable+on,cmdOff=angle_enable+off
CurrentRelativeHumidity=humidity
CurrentTemperature=temperature
BatteryLevel=batteryPercent,maxValue=100,minValue=0,minStep=1
AudioFeedback:buzzer,cmdOn=buzzer+on,cmdOff=buzzer+off,valueOn=on,valueOff=off
NightVision:led,cmdOn=led+off,cmdOff=led+bright,valueOn=off,valueOff=bright
Mute:mode,cmdOn=mode+straight,cmdOff=mode+natural,valueOn=straight,valueOff=natural

== Homematic SmokeDetector ==
[[Datei:Homebridge-Homematic-Smokedetector-Gen1.jpg|mini|Homebridge-Homematic-Smokedetector-Gen1 in EVE]]
Es sind keine Homebridge Mappings für die Rauch Meldung erforderlich.

Allerdings ist ein Mapping für den Batterie Zustand nötig, siehe Unten.

attr <SmokeDetector> genericDeviceType SmokeSensor
attr <SmokeDetector> subType smokeDetector

attr <SmokeDetector> homebridgeMapping StatusLowBattery=battery,values=ok:BATTERY_LEVEL_NORMAL;;/^.*/:BATTERY_LEVEL_LOW

== Vallox Belüftungsanlage ==
Die Steuerung der Lüftungsgeschwindigkeit ist nur in Prozent möglich. Die Umrechnung erfolgt im [[Vallox]] Modul.
Hierzu wurde das Reading ''FanSpeedPct'' hinzugefügt.

attr <Vallox> genericDeviceType Fan
attr <Vallox> homebridgeMapping clear
model=Vallox
On=PowerState,valueOn=1,readOnly=1
RotationSpeed=FanSpeedPct,minValue=1,maxValue=100,cmd=FanSpeedPct,delay=1

[[Kategorie:HOWTOS]]
[[Kategorie:Code Snippets]]

Yowsup

2019-06-01T19:45:40Z

Hoppel118: 1. Paketinstallationen -> "Debian Stretch" ergänzt, 2. Python 2.7 und 3.5 --> Paket "sudo apt-get install ... libncurses5-dev" ergänzt, 3. Python 2.7 und 3.5 --> Befehl: "sudo pip/pip3 install setuptools" ergänzt

{{SEITENTITEL:yowsup}}
{{Infobox Modul
|ModPurpose=Schnittstelle, um WhatsApp-Nachrichten empfangen und senden zu können.
|ModType=d
|ModCmdRef=yowsup
|ModFTopic=27543
|ModForumArea=Unterstuetzende Dienste
|ModTechName=32_yowsup.pm
|ModOwner=André / justme1968 ({{Link2FU|430|Forum}} / [[Benutzer Diskussion:justme|Wiki]])
}}

Das Modul [[yowsup]] dient dazu, WhatsApp-Nachrichten zu empfangen und zu senden. Nachrichten können sein:
* '''Text''': senden und empfangen, z.b.: Infonachrichten senden, FHEM-Kommandos empfangen
* '''Bilder''': senden und empfangen, z.b.: Webcambilder nach Bewegungserkennung versenden
* '''Audio''': empfangen, z.b.: Sprachdurchsagen empfangen und über SONOS abspielen

== Voraussetzungen ==
* Die Funktionalität ist vermutlich auf Linux/Unix Systeme beschränkt.
* Nach der Erstinstallation/-einrichtung '''muss''' zwingend das ''cmd'' Attribut korrekt gesetzt werden.

== Installation ==
Die ursprüngliche Einrichtung wurde {{Link2Forum|Topic=27543|Message=204426|LinkText=hier beschrieben}}, jedoch sind noch einige wichtige Dinge zu setzen. Mit der Version 3.0.0 vom 24. April 2019 hat sich einiges in der Kommunikation mit WhatsApp geändert. Diese Änderungen führen dazu, dass alles komplett neu installiert und registriert werden muss.

=== Yowsup Installation ===
Bevor man loslegt sollte man wie immer sicherstellen, dass Debian auf dem aktuellen Stand ist: 
<code>sudo apt-get update</code> 
<code>sudo apt-get upgrade</code> 
<code>sudo apt-get dist-upgrade</code> 

Will man Bilder verarbeiten, so braucht man noch ein paar Pakete mehr:
* Paketinstallationen:
** Unter Debian Wheezy: <code>sudo apt-get install libtiff4-dev libjpeg8-dev zlib1g-dev libfreetype6-dev liblcms2-dev libwebp-dev tcl8.5-dev tk8.5-dev python-tk</code>
** Unter Debian Jessie: <code>sudo apt-get install libtiff5-dev libjpeg-dev zlib1g-dev libfreetype6-dev liblcms2-dev libwebp-dev tcl8.5-dev tk8.5-dev python-tk</code>
** Unter Debian Stretch: <code>sudo apt-get install libtiff5-dev libjpeg-dev zlib1g-dev libfreetype6-dev liblcms2-dev libwebp-dev tcl8.5-dev tk8.5-dev python-tk</code>

==== Python 2.7 ====
Los gehts mit den Paketen: 
<code>sudo apt-get install python-soappy python-dateutil python-pip python-dev build-essential libssl-dev libffi-dev libncurses5-dev</code> 

Nun erstmal pip updaten: 
<code>sudo pip install --upgrade pip</code> 

yowsup benötigt zwingend von six die Version 1.10 (unter /usr/local/lib/python2.7/dist-packages prüfen, ob eine andere Version von six installiert ist. Diese erst löschen): 
<code>sudo pip uninstall six</code> 
<code>sudo pip install six==1.10</code>

Und dann Axolotl, argparse, readline installieren (das dauert ne Weile): 
(eventuell wird auch noch appdirs benötigt) 
<code>sudo pip install argparse</code> 
<code>sudo pip install setuptools</code> 
<code>sudo pip install readline</code> 
<code>sudo pip install appdirs</code> 
<code>sudo pip install python-axolotl</code> 
<code>sudo pip install pillow</code> 

Zudem wird neben den Python Modulen noch eine Lib's von tgalal benötigt:
<pre>cd /opt/fhem/yowsup
sudo wget https://github.com/tgalal/python-axolotl/archive/master.zip
sudo unzip master.zip
cd python-axolotl-master
sudo python setup.py install
cd ..
rm master.zip</pre>

<pre>cd /opt/fhem/yowsup
sudo wget https://github.com/tgalal/dissononce/archive/master.zip
sudo unzip master.zip
cd dissononce-master
sudo python setup.py install
cd ..
rm master.zip</pre>

<pre>cd /opt/fhem/yowsup
sudo wget https://github.com/tgalal/consonance/archive/master.zip
sudo unzip master.zip
cd consonance-master
sudo python setup.py install
cd ..
rm master.zip</pre>

Desweiteren muss man nun yowsup installieren:
<pre>
cd /opt
sudo mkdir yowsup-config
sudo wget -N https://github.com/tgalal/yowsup/archive/master.zip
sudo unzip -o master.zip
cd yowsup-master
sudo python setup.py install
cd ..
rm master.zip</pre>

==== Python 3.5 ====
Bevor man loslegt sollte man wie immer sicherstellen, dass Debian auf dem aktuellen Stand ist: 
<code>sudo apt-get update</code> 
<code>sudo apt-get upgrade</code> 
<code>sudo apt-get dist-upgrade</code> 
sudo apt-get install python3-setuptools
sudo apt-get install python3-dev
sudo apt-get install python3-pip

Los gehts mit den Paketen: 
<code>sudo apt-get install python3-pip python3-dev python3-setuptools python-soappy python-dateutil build-essential libssl-dev libffi-dev libncurses5-dev</code> 

Nun erstmal pip updaten: 
<code>sudo pip3 install --upgrade pip</code> 

yowsup benötigt zwingend von six die Version 1.10 (unter /usr/local/lib/python3.5/dist-packages prüfen, ob eine andere Version von six installiert ist. Diese erst löschen): 
<code>sudo pip3 uninstall six</code> 
<code>sudo pip3 install six==1.10</code>

Und dann Axolotl, argparse, readline installieren (das dauert ne Weile): 
(eventuell wird auch noch appdirs benötigt) 
<code>sudo pip3 install argparse</code> 
<code>sudo pip3 install setuptools</code> 
<code>sudo pip3 install readline</code> 
<code>sudo pip3 install appdirs</code> 
<code>sudo pip3 install python-axolotl</code> 
<code>sudo pip3 install pillow</code> 

Zudem wird neben den Python Modulen noch Lib's von tgalal benötigt:
<pre>cd /opt/fhem/yowsup
sudo wget https://github.com/tgalal/python-axolotl/archive/master.zip
sudo unzip master.zip
cd python-axolotl-master
sudo python3 setup.py install
cd ..
rm master.zip</pre>

<pre>cd /opt/fhem/yowsup
sudo wget https://github.com/tgalal/dissononce/archive/master.zip
sudo unzip master.zip
cd dissononce-master
sudo python3 setup.py install
cd ..
rm master.zip</pre>

<pre>cd /opt/fhem/yowsup
sudo wget https://github.com/tgalal/consonance/archive/master.zip
sudo unzip master.zip
cd consonance-master
sudo python3 setup.py install
cd ..
rm master.zip</pre>

Desweiteren muss man nun yowsup installieren:
<pre>
cd /opt
sudo mkdir yowsup-config
sudo wget -N https://github.com/tgalal/yowsup/archive/master.zip
sudo unzip -o master.zip
cd yowsup-master
sudo python3 setup.py install
cd ..
rm master.zip
</pre>

==== Fhem vorbereiten ====
Vor den weiteren Schritten sollte geprüft werden, ob dem User fhem eine Loginshell zugewiesen ist:
:<code>getent passwd fhem</code>
Wird hier am Ende /bin/false ausgegeben, so muss dies angepasst werden:
:<code>sudo chsh -s /bin/bash fhem</code>

Mittels ''getent passwd fhem'' kann auch bereits das Home-Verzeichnis ausgelesen werden, dies steht in der ausgegebenen Doppelpunkt-separierten Liste an vorletzter Stelle.

Nun loggt man sich unter dem User ein, unter dem fhem läuft (in den folgenden Beispielen werden die vom fhem-Setup-Script generierten Defaults verwendet: User=fhem , home=/opt/fhem Gruppe=dialout) und liest dort die $HOME-Variable aus und prüft das Home-Verzeichnis:
<pre>sudo su - fhem
echo $HOME
cd $HOME
logout</pre>
Diesen Wert braucht man später - gut merken. Sollte hier ein Fehler auftreten (z.B. das home nicht vorhanden), so muss dies zuerst korrigiert werden.

Vor den weiteren Schritten sollte man nun erstmal die yowsup Verzeichnisse dem fhem-user zugängig machen:
<pre>sudo chown -R fhem:dialout /opt/yowsup-master /opt/yowsup-config</pre>

Für die folgenden Schritte würde ich auf den FHEM-Nutzer wechseln:
<pre>sudo su - fhem
cd /opt/yowsup-master</pre>

==== WhatsApp einrichten ====
Bitte daran denken...
<pre>sudo su - fhem
cd /opt/yowsup-master</pre>

Nun erfolgt die Anmeldung am WhatsApp-Server. Dies kann man nun via <code>voice</code> oder <code>sms</code> machen. Bei einem Handy bietet sich SMS an, bei Festnetzanschlüssen sollte voice gewählt werden, wenn man sich nicht sicher ist, dass der Anschluss die Funktion 'SMS im Festnetz' unterstützt. Dann wird der Bestätigungscode zwar auf Englisch vorgelesen, dafür ist die Zuverlässigkeit des Registrierungsvorganges zuverlässiger. Bei Festnetznummern sollte man unbedingt etwas zum Schreiben bereit halten! (49XXXXXXXX durch Eure Telefonnummer ersetzen.) 

'''Python 2.5'''
<pre>yowsup-cli registration --requestcode sms --config-phone 49XXXXXXXX --config-cc 49</pre>

'''Python 3.5'''
<pre>python3 yowsup-cli registration --requestcode sms --config-phone 49XXXXXXXX --config-cc 49</pre>

Die Rückmeldung ist nun entscheidend. Wenn man diese zurückbekommt:
<pre>de sms
status: fail
retry_after: 3600
reason: no_routes</pre>
Dann ist die Nummer so nicht kompatibel. Was man dann noch probieren kann, ist die registration via voice - meistens ist das aber vergebene Liebesmüh'.

Wenn man folgende Rückmeldung bekommt:
<pre>I 2019-04-24 15:05:22,368 yowsup.common.http.warequest - {"login":"49xxxxxxxxxx","status":"sent","length":6,"method":"sms","retry_after":65,"sms_wait":65,"voice_wait":65}

status: sent
voice_wait: 65
retry_after: 65
sms_wait: 65
length: 6
login: 49xxxxxxxxxx
method: sms</pre>

So ist alles gut gelaufen und man sollte kurz später eine SMS bekommen. Darin ist ein Text, der am Ende z.B. 123-456 lautet. Diesen fügt man ohne Bindestrich am Ende des folgenden Befehls ein (49XXXXXXXX durch Eure Telefonnummer ersetzen.): 

'''Python 2.5'''
<pre>python3 yowsup-cli registration --config-phone 49XXXXXXXX -R 123456</pre>

'''Python 3.5'''
<pre>python3 yowsup-cli registration --config-phone 49XXXXXXXX -R 123456</pre>

Dann kommt ein Text der etwa so aussehen sollte:
<pre>I 2019-04-24 15:15:09,118 yowsup.common.http.warequest - {"status":"ok","login":"49xxxxxxxxxx","type":"existing","edge_routing_info":"CAUIAg==","chat_dns_domain":"fb","security_code_set":false}

{
"__version__": 1,
"cc": "49",
"client_static_keypair": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"expid": "xxxxxxxxxxxxxxxxxxxxxxxx",
"fdid": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"mcc": "000",
"mnc": "000",
"phone": "49xxxxxxxxxx",
"sim_mcc": "000",
"sim_mnc": "000"
}</pre> 

Yowsup legt eine neue Konfigurationsdatei im unter $HOME/.config/49xxxxxxxxxx/. Diese wird automatisch herangezogen, wenn die entsprechende Telefonnummer mit --config-phone 49XXXXXXXX angegeben wird.

Nun mal ein schneller Test an die eigene Nummer (im Beispiel 491751234567):
<pre>python[3] yowsup-cli demos --config-phone 49XXXXXXXX -s 491751234567 "Das ist ein Test"</pre>

Hier seht ihr nun einen Status (die Anzahl prekeys wird hoch gezählt):
<pre>I 2019-04-24 15:33:58,647 yowsup.layers.network.layer - Connecting to e7.whatsapp.net:443
I 2019-04-24 15:33:59,230 yowsup.axolotl.manager - Generating 812 prekeys
I 2019-04-24 15:34:15,590 yowsup.axolotl.manager - Storing 812 prekeys
I 2019-04-24 15:35:03,100 yowsup.axolotl.manager - Loaded 812 unsent prekeys</pre>

Das sollte dir eine Nachricht einbringen. Wenn du darauf antwortest, kommt diese allerdings noch nicht an - der Client hat sich nach dem Befehl sofort beendet. Damit dieser dauerhaft im Hintergrund läuft legen wir nun in FHEM ein Gerät an, welches dies steuert.

=== FHEM Define ===
* FHEM Device anlegen: <code> define <name> yowsup</code>, also z.B. <code>define WhatsApp yowsup</code>
* Nun muss man den Pfad zu yowsup anpassen:
* Python 2.7
* <code>attr WhatsApp cmd /opt/yowsup-master/yowsup-cli demos --config-phone 49XXXXXXXX --yowsup</code>
* Python 3.5
* <code>attr WhatsApp cmd python3 /opt/yowsup-master/yowsup-cli demos --config-phone 49XXXXXXXX --yowsup</code>
* Und das Home directory mit dem Pfad zum Home des fhem users: <code>attr WhatsApp home PWD</code>
* Wenn alles gut geht, gibt es danach im Device ein internal PID und das Reading ''state''
* Im Whatsapp Client auf dem Handy sollte man sehen, dass FHEM online ist
* Zum Senden aus FHEM kann man das Kommando <code>set WhatsApp send <nummer> <text></code> verwenden

== Attribute ==
Bitte sieh immer in der {{Link2CmdRef|Anker=yowsup}} nach - diese hier könnten veraltet sein.

* <code>cmd</code> komplettes Kommando, um den yowsup Client zu starten. z.B.: <code>attr WhatsApp cmd /opt/yowsup-master/yowsup-cli demos -c /opt/yowsup-config/yowsup.config --yowsup</code>. Wenn die ab yowsup-Version 2.4 standartmässig aktivierte Verschlüsselung abgeschaltet werden muss weil die entsprechenden Libs nicht installiert sind: <code>attr WhatsApp cmd /opt/local/bin/yowsup-cli demos -c /root/yowsup-config --yowsup -M</code>.
* <code>acceptFrom</code> kommagetrennte Liste von Kontakten (Nummern), von denen Nachrichten akzeptiert werden. Ist das Attribut nicht gesetzt, so werden die Nachrichten von jedem akzeptiert.
* <code>commandPrefix</code> nicht gesetzt -> es werden keine Befehle akzeptiert. 0 -> es werden keine Befehle akzeptiert. 1 -> erlaubt Befehle, jede Nachricht wird als FHEM-Befehl interpretiert. alles andere -> Wenn die Nachricht mit diesem Prefix startet, wird alles weitere als Befehle interpretiert.
{{Randnotiz|RNTyp=Warn|RNText='''allowedCommands''' should work as intended, but no guarantee can be given, that there is no way to circumvent it.}}
* <code>allowedCommands</code> Eine Komma-getrennte Liste von zulässigen Befehlen für diesen Kontakt. Wenn die Liste leer ist (z.B. nur ein Komma), dann werden keine Befehle akzeptiert.
* <code>home</code> Setzt das Home-directory welches für yowsup verwendet werden soll.

== Befehle ==
* image -> Über diesen Befehl können Bilder gesendet werden.

* raw -> Status ändern :
<code>set WhatsApp raw /profile setStatus 'mein Status' <--- die ' ' müssen bleiben</code>

Name der angezeigt werden soll, wenn eine Nachricht z.B. ans iPhone geschickt wird:

<code>set WhatsApp raw /presence name <DeinNick></code>

Anzeige online :

<code>set WhatsApp raw /presence available</code>

Profilbild ändern :

<code>set WhatsApp raw /profile setPicture '/opt/fhem/fhem_logo.png'</code>
<--- der gesamte Pfad zum Bild muss angegeben werden und Rechte müssen ggfs. bei fhem liegen

Falls es nicht funktioniert disconnect/connect probieren.

== Update ==
Da am WhatsApp ständig geschraubt wird, bedarf es eines Updates des Yowsup, wenn keine Funktion mehr gegeben ist:
<pre>cd /opt
sudo rm master.zip
sudo mv yowsup-master yowsup-master-alt
sudo wget -N https://github.com/tgalal/yowsup/archive/master.zip
#alternativ sudo wget https://github.com/jlguardi/yowsup/archive/master.zip (Stand März 2016 aktueller)
sudo unzip master.zip
sudo chown fhem yowsup-master -R
sudo chgrp dialout yowsup-master -R</pre>Danach muss FHEM mittels 'shutdown restart' neu gestartet werden.

== Anwendungsbeispiele ==
=== Beispielnachricht ===
Beim Empfang einer Nachricht wird automatisch ein FHEM Device für diesen Kontakt angelegt. In diesem Device gibt es das Reading '''message''' für die empfangene Nachricht und ab der ersten Nachricht auch das Reading '''chatstate''', in dem zu sehen ist, ob gerade getippt wird.
Nachdem ein Device für einen Kontakt angelegt ist, lässt sich auch direkt dieses Device zum Senden verwenden:
:<code>set <device> send <text></code>,
d.h., man spart sich die Angabe der Nummer.

=== Gruppen ===
Gruppen müssen über die App (Smartphone / Tablet) angelegt werden. Nach dem Empfang einer entsprechenden Nachricht werden Gruppen genauso behandelt, wie einfache Teilnehmer.

=== Broadcast ===
Beim Senden über das Masterdevice lassen sich mehrere Empfänger mit Komma (und ohne Leerzeichen) getrennt angeben. Die entsprechenden Nachrichten werden dann per Broadcast an alle Teilnehmer gesendet. Die Broadcastempfänger müssen zuvor mindestens eine normale Nachricht erhalten haben.

=== Komponenten steuern ===
Um ein [[notify]] anlegen zu können, müssen wir zuerst eine Nachricht vom Handy an FHEM senden. Dadurch wird ein Device mit der Nummer als Namen angelegt. Danach sollte das Device umbenannt werden, da einige Befehle einen Namen ausschließlich aus Ziffern nicht akzeptieren. Dies geschieht wie folgt:

:<code>rename 49123456789 HandySeppel</code>

Danach kann ein ''notify'' angelegt werden:

<syntaxhighlight lang="perl">
define notifySeppelLicht notify HandySeppel:message.* {
if( $EVENT eq 'message: Licht an' ) {
fhem "set HandySeppel send Licht ist nun an...";
fhem "set FS20_a5d800 dim100%";

} elsif( $EVENT eq 'message: Licht aus' ) {
fhem "set HandySeppel send Licht ist nun aus...";
fhem "set FS20_a5d800 dim0%";

} else {
fhem "set HandySeppel send Wie bitte?"

}
}</syntaxhighlight>

Natürlich ist dieses ''notify'' noch auf die eigenen Wünsche anzupassen.

=== Autoresponder ===
Nachdem man nun seine Festnetznummer bei WhatsApp registriert hat, wird auch diese natürlich als erreichbares Ziel auf jedem Gerät angezeigt, auf dem sie gespeichert ist. So kann es passieren, dass WhatsApp-Nachrichten nicht gelesen werden. Hier schafft ein Autoresponder Abhilfe:
:<code>define not_WhatsApp_Autoresponder notify 491.*:message.* set $NAME send Hallo, Du hast eine Nachricht an unsere Festnetznummer geschickt. Da ist aber nur ein kleiner Computer auf Empfang, der Dir nur diese Antwort schicken kann. Bitte benutze unsere Mobilnummern, wenn Du willst, dass Deine Nachricht auch gelesen wird!</code>
Das Problem hierbei ist, dass noch nicht bekannt ist, wer etwas sendet und so der Kontakt u.U. noch nicht angelegt ist. Daher wird im obigen Beispiel auf 491*:message.* reagiert. So bekommen nur deutsche Mobilrufnummern die Antwort. Um das noch globaler zu fassen, könnte z.B. auf \d*.*:message.* reagiert werden, was aber voraussetzt, dass keine weiteren Modulnamen (die das Reading message haben) mit einer Ziffer beginnen.
Alle Kontakte, welche nicht den Autoresponder erhalten sollen, müssen wie oben beschrieben entspr. umbenannt werden:
:<code>rename 49123456789 HandySeppel</code>

== Probleme und Lösungen ==
=== Immer wieder offline ===
Das WhatsApp Device geht immer wieder offline und im Log wird folgendes protokolliert:

... yowsup.layers.axolotl.layer_receive:invalidmessage or keyid for ...

Lösung:

Verzeichnis .yowsup in /root löschen.
Das Verzeichnis entsteht durch das Testen auf der Konsole und verträgt sich dann nicht mit dem im Attribut home hinterlegten Verzeichnis.

=== UTF-8 Fehler ===

Lösung: https://forum.fhem.de/index.php/topic,27543.msg773746.html#msg773746

== Links ==
* {{Link2Forum|Topic=27543|LinkText=Forenthread}}, in dem die Whatsapp Anwendung beschrieben wird
* {{Link2Forum|Topic=27543|Message=299292|LinkText=Foreneintrag}}, ab dem das yowsup Modul beschrieben wird
* Die Python Whatsapp Library auf [https://github.com/tgalal/yowsup github]
* Imagehandling Bugfix [https://github.com/tgalal/yowsup/issues/901 github]

[[Kategorie:WhatsApp]]