FHEM Connector für Amazon Alexa

FHEM Connector für Amazon Alexa
Zweck / Funktion
	Anbindung von FHEM an Amazon Assistent Alexa
Allgemein
Typ	Inoffiziell
Details
Dokumentation	siehe Forum
Support (Forum)	Frontends/Sprachsteuerung
Modulname
Ersteller	gvzdus
	Wichtig: sofern vorhanden, gilt im Zweifel immer die (englische) Beschreibung in der commandref!

Alexa FHEMlazy ist historisch ein Fork des Original Alexa FHEM, der im Januar 2019 mit dem Original zusammengeführt wurde. Er ermöglicht innerhalb von Minuten die Verknüpfung von FHEM mit einem Amazon Echo-Gerät. Gegenüber dem klassischen Ansatz ergeben sich Einschränkungen, so läuft die Software zwangsweise 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
Als Skill bei Amazon wird der (z.Zt. noch im Beta-Test befindliche) Skill "FHEMlazy" verwendet.

Der Thread im Forum zur Software ist Thema.

Einführung

Arbeitsweise und Datenfluss

Vorläufig ist alexa-fhem im "LazyModus" ein reiner 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 FHEMlazy 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 FHEMlazy erfolgversprechend ist.
Zunächst wird die zentrale "Lambda-Funktion" von FHEMlazy 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 kommen die Requests aus dem Internet (hoffentlich von der eigenen Lambda-Funktion), hier bei FHEMlazy 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 einmal auf der Kommandozeile auf Deinem Raspberry (o.ä.) unterwegs sein, anschließend im Webfrontend von FHEM, und zum Schluss auf der Alexa-Konsole im Web.

root werden

Logge Dich auf dem System ein. Da offizielle Software (nodejs etc.) installiert wird, muss Du root werden

sudo /bin/bash

node.js installieren

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

sudo apt-get install nodejs

kannst Du es installieren. Mit

node --version

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:

sudo npm install -g alexa-fhem

Der Vorgang benötigt etwas Zeit.

Alexa-FHEM aktivieren

Wechsele jetzt in FHEM-Web!

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

define alexa alexa

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 perfekterweise so aussehen:

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

alexaFHEM.bearerToken crypt:...
alexaFHEM.skillRegKey crypt:...

Ja, und diesen Schlüssel benötigst Du wirklich! Also am besten schon einmal mit get <alexa> proxyKey in Klartext anzeigen lassen und in ein Editor-Fenster dauerhaft wegsichern.

Hast Du noch die Shell-Konsole offen?

Dann prüfe bitte noch einmal auf der Konsole, ob nun zwei Prozesse laufen:

ps -ef | egrep '(alexa|ssh)'

sollte Dir idealerweise so etwas anzeigen:

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

"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 Logfile in der Detail-Ansicht über set, 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 keins der 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 set <alexa> restart ausführst! Wenn

Finale: Skill verknüpfen

Zum Zeitpunkt des Beta-Tests muss noch jeder Benutzer einzeln zur Nutzung des Skills eingeladen werden. Schreibe mir - ohne lange Umstände und Huldigungen - eine Email an

gvz-fhembeta@garnix.de

In dieser Email sollte aber Dein Anmeldename bei Amazon enthalten sein, wie Du ihn für Alexa nutzt: Denn genau dieser Account wird freigegeben!

Mit dem Aufruf der erhaltenen URL solltest Du jetzt den Skill hinzufügen können, und nutze bitte hierfür das WebFrontend (https://alexa.amazon.de) statt die App, damit Du den Anmeldeschlüssel auch bequem kopieren kannst.

Amazon erwartet zunächst, dass Du Dich normal bei Amazon anmeldest. Sobald Du FHEMlazy verknüpfst, öffnet sich ein Browser-Tab mit folgender Maske:

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:

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 wird unmittelbar die Gerätesuche starten, und unter SmartHome-Geräte sollten diese nun auftauchen.

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

ssh -R 1234:localhost:<zufälliger port> zielserver

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

sudo /usr/sbin/tcpdump -X -s 0 -i lo port <zufälliger port>

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 "Mit FHEM-Lazy verbinden" 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".

Updaten

1) Im Web-Frontend "FHEM.Alexa" suchen und auf "Stop" klicken.

2) Auf die Konsole und wie anfangs bei der Installation

Mit dem richtigen Nutzer eine Shell starten:

sudo -u fhem bash

Für git-Nutzer:

Wechsele ins Software-Verzeichnis:

cd ~/alexa-fhem
git pull

Für curl/wget-Nutzer:

cd ~/
wget https://va.fhem.de/alexa-fhem.tar.gz
tar xzf alexa-fhem.tar.gz

bzw:

cd ~/
curl -O https://va.fhem.de/alexa-fhem.tar.gz
tar xzf alexa-fhem.tar.gz

Ggf. die für die Software benötigten NodeJS-Bibliotheken nachladen:

npm install

3) Im Web-Frontend auf "Start" klicken.

Weitergehende Informationen