Alexa-Fhem

Alexa-Fhem
Zweck / Funktion
	Anbindung von FHEM an Amazon Assistent Alexa
Allgemein
Typ	Inoffiziell
Details
Dokumentation	siehe Forum
Support (Forum)	Sonstige Systeme
Modulname
Ersteller	justme1968
	Wichtig: sofern vorhanden, gilt im Zweifel immer die (englische) Beschreibung in der commandref!

Alexa-Fhem ist eine in JavaScript geschriebene und auf NodeJS basierende Software, welche es ermöglicht, der digitalen Amazon Assistentin Alexa zusätzliche Skills für die Heimautomatisierung via FHEM beizubringen. Eine erste funktionierende Version wurde von justme1968 im Forum veröffentlicht. Das ist eine erste Version der Dokumentation zur Installation und Einrichtung, eine Erweiterung wird sicherlich in nächster Zeit noch folgen.

Einführung

Glossar

Echo bzw. Echo Dot (im Folgenden maskulin bezeichnet) sind die derzeit verfügbaren Geräte des Alexa-Systems BILDER EINSTELLEN - Achtung Urheberrecht
AVS ist der Amazon Voice Service, d.h. die Spracherkennungskomponente des Systems.
Für die Nutzung der Amazon AWS-Dienste müssen zwingend die Daten einer Kreditkarte angegeben werden. Nach gegenwärtigem Kenntnisstand sollen jedoch keine Kosten für die Nutzung der im Rahmen dieses How To beschriebenen Dienste anfallen, sofern diese in einem Rahmen genutzt werden, der selbst eine intensive private Nutzung nicht überschreitet. Der Benutzer sei an dieser Stelle auf die von Amazon veröffentlichten Preislisten verwiesen. Die Autoren dieser Anleitung und der darin beschriebenen Module übernehmen keine Haftung für eventuelle Kosten, die aus der Nutzung der AWS entstehen.

AWS sind die Amazon Web Services, also per URL erreichbare Dienste zur Ausführung von Berechnungen etc. Im Rahmen von Alexa-Fhem wird bei AWS eine eigene JavaScript-Funktion hinterlegt, die zur Kommunikation mit dem FHEM-Server dient. Im Jargon von Amazon ist dies eine so genannte Lambda-Funktion WARUM ? Nachlesen bei Amazon.
Skill (engl. für Fähigkeit) ist die Bezeichnung für eine per Spracherkennung bediente Funktionalität des Alexa-Systems, z.B. zur Nachrichtenansage, zur Wettervorhersage oder zur Steuerung von FHEM

Arbeitsweise und Datenfluss

Grafische Darstellung der beteiligten Komponenten

Echo -> AVS -> AWS Lambda -> alexa-fhem -> AWS Lambda -> AVS -> Echo

Der Echo (oder ein anderes Alexa/AVS fähiges Gerät) nimmt Audiodaten auf und schickt diese an AVS (Amazon Voice Service) zur Erkennung
AVS führt die Spracherkennung durch und erzeugt ein Event mit Informationen zu den erkannten Daten

Beim Alexa SmartHome Skill sind die möglichen Sätze für die Spracherkennung relativ fest vorgegeben
Beim Alexa Custom Skill kommen die dazu nötigen Informationen aus dem Interaction Model der Alexa Skills Configuration

Das Event wird an den unter Configuration in der Alexa Skills Configuration hinterlegten Endpoint geschickt

Beim Alexa SmartHome Skill ist das zwingend eine AWS Lambda Routine
Beim Alexa Custom Skill kann das im Prinzip auch ein eigener Web Service sein

Das Event wird vom lambda.js code an alexa-fhem weitergeleitet
alexa-fhem steuert FHEM und sendet ein Antwort-Event zurück
lambda.js nimmt diese Antwort entgegen und gibt sie an AVS zurück
AVS sogt dafür das der Echo 'antwortet' und dass die Card in der Alexa App erscheint

Anmerkungen

Ein Skill hat keinen Zugriff auf die Audiodaten
Mit dem Skill API kann ein Skill zu zu keiner Zeit von sich aus aktiv werden und 'einfach' Daten an den Echo schicken oder ihn dazu bringen irgendetwas zu tun.
Wenn man berücksichtigt welchen Weg die Daten insgesamt gehen, ist es erstaunlich, wie schnell die Reaktion auf einen gesprochenen Satz erfolgt.

Abgrenzung des Alexa Smart Home Skills und des Alexa Custom Skills

Der Alexa Smart Home Skill ist ein Amazon-Alexa-Standard-Skill, der wesentliche Basisfunktionalitäten bereitstellt. Zu diesen gehört im Wesentlichen die Funktionalität, durch Alexa-FHEM bereitgestellte Devices im Alexa-Account des Benutzers anzulegen. Der Alexa Smart Home Skill reagiert auf gesprochene Interaktion in einem beschränkten Umfang. Beispielsweise genügt ein "Alexa, schalte die Wohnzimmerlampe an" um eine Interaktion zwischen Alexa Smart Home Skill und FHEM-Alexa auszulösen. Nach erfolgreicher Einrichtung wird dieser Skill in der Alexa-App bzw. im Web in der Rubrik "Smart Home" als Skill angezeigt.

Der Alexa Custom Skill ist kein Standard-Smart-Home-Skill, sondern ein individuell entwickelter Skill, so wie alle anderen Skills auch. Er wird daher auch nicht in der Alexa-App unter der Rubrik "Smart Home" angezeigt. Gesprochene Interaktion mit diesem Skill erfolgt dadurch, dass entweder der Skill explizit gestartet wird (z.B. "Alexa, starte [Name des Skills]") oder direkt angesprochen wird (z.B. "Alexa, frage [Name des Skills] wie ist der Status von [Device] "). Der Alexa Custom Skill befindet sich in Entwicklung und wird hinsichtlich seiner Funktionalitäten laufend weiterentwickelt. Die Einrichtung dieses Skills ist grundsätzlich optional, jedoch werden anspruchsvollere Steuerungsmöglichkeiten nur mit diesem realisiert werden können.

Installation

Da die einzelnen Schritte der Anleitung an verschiedenen Stellen unterbrochen und später fortgesetzt werden müssen, empfiehlt es sich, die Anleitung einmal vollständig gelesen zu haben. Während der Konfiguration sollten alle nachfolgenden Abschnitte parallel in gleichzeitig geöffneten Browserfenstern durchgeführt werden, die jeweils bis zum Abschluss geöffnet bleiben müssen.

Grundvoraussetzung für alle folgenden Schritte ist das Vorhandensein eines Amazon-Accounts. Es wird davon ausgegangen, dass die Konten für alle im Folgenden genutzten Amazon-Dienste eingerichtet wurden.

node.js installieren

Zunächst wird das Betriebssystem (in diesem Falle Debian oder Ubuntu) auf den aktuellen Stand gebracht:

sudo apt-get update
sudo apt-get upgrade
sudo apt-get install build-essential libssl-dev

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:

curl -sL https://deb.nodesource.com/setup_4.x | sudo -E bash -
sudo apt-get install -y nodejs

Alexa-Fhem installieren

Aktuelle Version: [alexa-fhem.0.1.9.tgz]

Ältere Version, nur der Vollständigkeit halber: [alexa-fhem.0.1.3.tgz]

Die tgz-Datei unter Linux im Hauptverzeichnis von FHEM (typischerweise /opt/fhem) entpacken (nicht unter Windows, das zerstört die Rechteeinstellungen).
Das dabei entstandene Verzeichnis package in alexa-fhem umbenennen
```
mv package alexa-fhem
```
Durch
```
cd alexa-fhem
```
in das Verzeichnis wechseln
Mit
```
npm install
```
alle Abhängigkeiten installieren (kein sudo!).
SSL Zertifikat erzeugen durch Aufruf von
```
./createKey.sh
```
(kein sudo!). Hierbei beachten, dass ein Kennwort vergeben werden muss, das mindestens aus 4 Zeichen besteht, dieses Kennwort bitte merken.
Das Verzeichnis ~/.alexa anlegen (im Home-Verzeichnis des gegenwärtigen Users)
Die Datei config-sample.json nach ~/.alexa/config.json kopieren. Achtung: Das gilt natürlich

nur dann, wenn man als derjenige Nutzer eingeloggt ist, der FHEM laufen lässt - das Symbol ~/ verweist auf dessen Home-Verzeichnis. Auf einem Raspberry Pi, bei dem kein eigenes Home-Verzeichnis für FHEM angelegt wurd, ist dies /home/pi. Installiert man alexa-fhem als root-user, zeigt das Symbol ~/ auf /root - und wird ggf. bei einem manuellen Start von Alexa-Fhem nicht gefunden. Achtung: Ggf. müssen auch die Dateien key.pem und cert.pem ins entsprechende Verzeichnis kopiert werden.

Alexa-Fhem konfigurieren

Der Inhalt der Datei ~/.alexa/config.json muss an die eigene Umgebung angepasst werden.

nat-pmp -> wenn nat-pmp verwendet werden soll: die ip des eigenen routers,
nat-upnp -> wenn nat-upnp verwendet werden soll: true,
applicationId
- Wenn man nur den SmartHome-Skill verwenden möchte, kann dieser Eintrag leer bleiben.
- Ansonsten ist er mit der SkillID des Alexa Custom Skills zu belegen, siehe Abschnitt Skill Id bestimmen
- oauthClientID -> Client ID dem Abschnitt Login with Amazon, Punkt 1
- server -> IP-Adresse des eigenen FHEM-Servers
- port -> Portnummer des eigenen FHEM-Servers

Beispiel:

{
   "alexa": {
       "name": "Alexa TEST",
       "keyFile": "./key.pem",
       "certFile": "./cert.pem",
       "applicationId": "amzn1.ask.skill.xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
       "oauthClientID": "amzn1.application-oa2-client.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
   },
   "connections": [
       {
           "name": "FHEM",
           "server": "192.168.0.xxx.xxx",
           "port": "8083",
           "filter": "room=AlexaRoom"
       }
   ]
}

Danach durch Aufruf von

./bin/alexa

den Dienst starten (kein sudo!)

Der Start des Alexa-Dienstes auf der Console ist immer dann zu empfehlen, wenn man auf die Ausgaben des Dienstes angewiesen ist und beispielsweise sehen möchte, welche Devices durch den Dienst bereitgestellt werden oder ob Fehler auftreten. Beendet man die Console-Session wird auch der Dienst wieder beendet. Insofern ist die vorgenannte Vorgehensweise nur für ein Debugging zu empfehlen und nicht im Regelbetrieb. Nachfolgend ist beschrieben, wie man den Alexa-Dienst aus FHEM heraus starten / stoppen und neu starten kann.

Alexa-Fhem aus FHEM heraus starten

Zunächst das Start-up-Skript aus diesem Post herunterladen https://forum.fhem.de/index.php/topic,60244.msg517271.html#msg517271 und unter /etc/init.d/alexa speichern.

Das Script geht davon aus, das der alexa-fhem script unter /opt/fhem/alexa-fhem liegt, und die logfiles später unter /opt/fhem/log. Sollte das nicht der Fall sein, muss das Skript angepasst werden.

Nun folgende Kommandos ausführen:

sudo chmod 755 /etc/init.d/alexa
sudo update-rc.d alexa defaults

In der Datei /etc/sudoers den User fhem für die Nutzung von sudo zulassen (sudo nano /etc/sudoers), z.B. durch Anfügen der nachfolgenden Zeile: fhem ALL=(ALL) NOPASSWD: ALL

Nun folgende Devices anlegen (ggf. einem Raum zuordnen, z.B. AlexaControl):

define FHEM.Alexa.Status dummy

define FHEM.Alexa dummy
attr FHEM.Alexa event-on-change-reading state
attr FHEM.Alexa webCmd status:start:stop:restart

define FHEM.Alexa.DOIF DOIF ([FHEM.Alexa] eq "start") 
(set FHEM.Alexa on, {system ("sudo /etc/init.d/alexa start > /dev/null 2>&1 &")}) 
DOELSEIF ([FHEM.Alexa] eq "stop")
(set FHEM.Alexa on, {system ("sudo /etc/init.d/alexa stop > /dev/null 2>&1 &")}) 
DOELSEIF ([FHEM.Alexa] eq "restart") 
(set FHEM.Alexa on, {system ("sudo /etc/init.d/alexa restart > /dev/null 2>&1 &")}) 
DOELSEIF ([FHEM.Alexa] eq "status") 
(set FHEM.Alexa on, {system ("sudo /etc/init.d/alexa status > /dev/null 2>&1 &")})

Alexa-Fhem testen

Node.Js stellt einen Web-Server am Port 3000 bereit, das oben erzeugte Zertifikat sichert diesen Zugang per SSL ab. Durch Aufruf der Adresse https://<IP-Adresse des Servers>:3000 kann man testen, ob der Alexa-Fhem Service läuft - der Seitenaufruf liefert eine Zeile JSON-Code, beginnend mit {"header":{"name":"UnsupportedOperationError"...

Alexa Device anlegen

Das Modul 39_alexa.pm stellt innerhalb von FHEM verschiedene Attribute z.B. alexaName oder alexaRoom zur Verfügung. Manche dieser Attribute (wie z.b. alexaName) werden in beiden Skills verwendet, andere werden ausschließlich bei einer Nutzung des Alexa Custom Skill verwendet.

Die Einrichtung des Alexa Device geschieht durch die nachfolgende Definition:

define MyAlexa alexa

Alexa Skills

Für folgende Schritte muss man unter der Adresse http://developer.amazon.com angemeldet sein

Anmeldung auswählen
Anmeldedaten eingeben

Security Profile anlegen

Die Erzeugung eines Sicherheitsprofils muss nur einmal erfolgen, es wird dann für alle weiteren Skills verwendet.

Nach der Anmeldung Auswahl von APPS & SERVICES
Anschließend auswählen Security Profiles
Auswählen Create a New Security Profile aus
Dann einen Namen und eine Beschreibung für das Profil eingeben und mit Save bestätigen

Login with Amazon

Hier wird beschrieben, wo Client Id und Client Secret zu finden sind

Oben rechts auf Login with Amazon klicken.
Auf der neu geladenen Seite auswählen Sign up
Anschließend im Dropdown Menü das vorher angelegte Profil auswählen und mit Confirm bestätigen
Im folgenden Fenster die Adresse https://www.amazon.com/gp/help/customer/display.html?nodeId=468496 eingeben und mit Save bestätigen. Todo Erklärungsbedarf: WARUM diese Adresse
Anschließend bei dem neu angelegten Eintrag auf der rechten Seite auf das Zahnrad klicken und Web Settings auswählen
Im neu geladenen Fenster anklicken von Edit
Anschließend bei Allowed Return URLs die folgenden drei Adressen eingeben. xxx muss hierbei durch den Wert ersetzt werden, der im Abschnitt Skill Kit einrichten, Punkt 6 unter Redirect Urls am Ende der URLs angezeigt wird

.

Skills bearbeiten

Im Menü den Punkt ALEXA auswählen
Anschließend im Feld Alexa Skills Kit auf Get started klicken

SmartHome Skill anlegen

Oben rechts Add a New Skill auswählen
Auf der folgenden Seite eingeben und dann mit Next bestätigen:
- Skill Type -> SmartHome Skill API
- Language -> German
- Name -> beliebiger Name, z.B. "MySmartHome Basic")
Die folgende Seite einfach mit Next überspringen
Auf der Seite Configuration Folgendes eingeben:
- Service Endpoint Type -> AWS Lambda ist vorausgewählt und kann nicht geändert werden.
- Geographical Region -> Europe auswählen und im Textfeld die ARN aus Abschnitt AWS Lambda Funktion eintragen.
- Authorization URL -> https://www.amazon.com/ap/oa
- Client ID -> Client ID aus Abschnitt Login with Amazon, Punkt 1
- Scope -> profile:user_id
- Redirect URLs - sollten vorbelegt sein
- Authorization Grant Type -> Auth Code Grant auswählen
- Access Token URI -> https://api.amazon.com/auth/o2/token
- Client Secret -> Client Secret aus Abschnitt Login with Amazon, Punkt 1
- Client Authentication Scheme -> HTTP Basic
- Privacy Policy URL -> https://www.amazon.com/gp/help/customer/display.html?nodeId=468496

Custom Skill anlegen

Oben rechts Add a New Skill auswählen
Auf der folgenden Seite eingeben und dann mit Next bestätigen:
- Skill Type -> Custom Interaction Model
- Language -> German
- Name -> beliebiger Name, z.B. "MySmartHome Advanced". Dieser wird in der Alexa App unter "Meine Skills" angezeigt.
- Invocation Name -> Aufruf des Skills, unter dem dieser später gestartet wird. Z.B. "Alexa, starte James"
Auf der Seite Interaction Model folgende Eingaben tätigen und mit Next abschließen

In einem separaten Browserfenster FHEM aufrufen, und für das bereits definierte Alexa-Gerät das Kommando get MyAlexa interactionModel aufrufen. Es erscheint ein Popup-Fenster mit ziemlich vielen Zeilen.
In die Box Intent Schema kopiert man den ersten Teil dieser FHEM-Ausgabe hinein, also:

{ 
  "intents" : [ 
   <hier ziemlich viele Zeilen>  
  ]
}

Nun die Custom Slot Types einrichten. Dazu muss aus dem zweiten Teil der FHEM-Ausgabe jeweils der Slot-Type (z.B. FHEM_article) in das Feld TYPE eingetragen werden, das nach dem Anklicken von Add Slot Type erscheint. In das darunter liegende größere Textfeld kommen die möglichen Werte für diesen Slot, so wie sie aus der FHEM-Ausgabe abzulesen sind. Dann mit Save sichern. Als Custom Slot Type erscheint dann für diesen Beispiel-Slot

FHEM_article 	der | die | das | den

d.h., die Zeilenumbrüche bei den möglichen Werten werden als "|" dargestellt.

Hier muss nun ein Bruch im Arbeitsfluss durchgeführt werden, denn bei der Erstellung des Custom Skills kommt es auf die Reihenfolge der Einträge an. Deshalb zunächst diese FHEM-Ausgabe schließen, und für dasselbe FHEM-Device get MyAlexa customSlotTypes ausführen. Auch diese Ausgabe wird, wie oben beschriebeen, in Custom Slot Types eingetragen (erst der TYPE, dann die möglichen Werte)
Anschließend erneut die FHEM-Ausgabe schließen und erneut für das bereits definierte Alexa-Gerät das Kommando get MyAlexa interactionModel aufrufen.
Unter Sample Utterances nun den Text aus dem dritten Teil dieser FHEM-Ausgabe hineinkopieren

Auf der Seite Configuration Folgendes eingeben und mit Next bestätigen:
- Service Endpoint Type -> AWS Lambda auswählen
- Geographical Region -> Europe auswählen und im Textfeld den Wert aus Abschnitt AWS Lambda Funktion anlegen (Punkt 12) eintragen.
- Do you allow users to create an account or link to an existing account with you? -> Yes
- Authorization URL -> https://www.amazon.com/ap/oa
- Client ID -> Client ID aus Abschnitt Login with Amazon, Punkt 1
- Scope -> profile:user_id
- Redirect URLs - sollten vorbelegt sein
- Authorization Grant Type -> Auth Code Grant auswählen
- Access Token URI -> https://api.amazon.com/auth/o2/token
- Client Secret -> Client Secret aus Abschnitt Login with Amazon, Punkt 1
- Client Authentication Scheme -> HTTP Basic
- Privacy Policy URL -> https://www.amazon.com/gp/help/customer/display.html?nodeId=468496

Beim Sichern dieser Seite mit Next kann es zu einer Fehlermeldung kommen, wenn man seine Skill-Definitionen mit dem einfachen SmartHome-Skill begonnen hat. Deshalb muss noch der entsprechende Trigger für die AWS Lambda Funktion nachgetragen werden, dies wird in Abschnitt Trigger für Custom Skill hinzufügen beschrieben.

Testen

Hat man den Custom Skill angelegt, bietet dieser auch eine komfortable Testmöglichkeit. Dazu wählt man in der Übersichtsseite All Skills den Button Edit des Alexa Custom Skill aus. Auf der nachfolgenden Seite dann links Test. Die Testseite enthält

ein Feld Voice Simulator, mit dem man die Sprachsausgabe testen kann,
ein Feld Service Simulator, mit dem die Verarbeitung von Alexa-Kommandois getestet werden kann. Hier kann man z.B. eintragen

"Alexa, sage <Custom Skill Invocation Name>: Stelle Weckzeit auf Neunzehn Siebenundzwanzig Uhr"
"Alexa, frage <Custom Skill Invocation Name> nach dem Status von Weckzeit"

Dabei ist natürlich der Custom Skill Invocation Name durch den Wert zu ersetzen, den man im Abschnitt Custom Skill Anlegen unter Punkt 2 eingetragen hat.

Skill Id bestimmen

Hier wird beschrieben, wo die Alexa Skill Id zu finden ist

Für das Anlegen einer AWS Lambda Funktion bzw für die Konfiguration von Alexa-Fhem wird die Alexa Skill Id benötigt. An diese kommt man wie folgt:

Anmelden wie unter Alexa Skills beschrieben.
Menüpunkt ALEXA auswählen, wie Skills bearbeiten erklärt.
Beim gewünschten Eintrag auf Edit klicken
Die Id, die nun oben angezeigt wird, ist die gesuchte. Sie hat typischerweise das Format amzn1.ask.skill.[Zahlen und Bindestriche]

AWS Lambda Funktion

Für folgende Schritte muss man unter der Adresse http://aws.amazon.com angemeldet sein

Anmeldung auswählen
Anmeldedaten eingeben
Den Punkt Lambda links auf der Startseite auswählen, bzw. im Menü Services unter Compute den Menüpunkt Lambda auswählen

AWS Lambda Funktion anlegen

Für eine erste Lambda-Funktion den Punkt Get Started Now auswählen
Den Blueprint Blank function auswählen
Im neuen Fenster dann auf den gestrichelten Kasten klicken und Alexa Smart Home auswählen und mit Next bestätigen
1. Achtung, es ist möglich, dass dabei Alexa Smart Home überhaupt nicht angeboten wird. Dann bitte ganz rechts oben in der Ecke nachsehen, welche Region bzw. welches Land ausgewählt ist. Empfohlen wird, Ireland auszuwählen. Dann erscheint bei den Funktionen auch Alexa Smart Home.
Bei Application Id den Wert eintragen, dessen Ermittlung im Abschnitt Skill Id bestimmen beschrieben wird, den Haken bei Enable trigger setzen und mit Next bestätigen
Auf der Konfigurationsseite eingeben:
1. Name -> FHEM
2. Runtime -> Node.js 4.3.
3. Role -> Choose an existing role
  1. Achtung: wenn es noch keine existing role gibt, zuerst Create a custom role -> in dem Popup dann lambda_basic_execution auswählen und auf Allow klicken sowie bei Existing role dann x wählen.
Auf der Code-Seite wird bzw. im großen Textfeld ist dann der Code aus der Datei lambda.js im Paket Alexa-Fhem vollständig einzufügen. Dabei muss noch der Hostname im Quellcode an den eigenen Hostnamen angepasst werden.
Anschließend alles mit Next bestätigen.
Auf der Übersichtsseite dann Create function anklicken

Trigger für Custom Skill hinzufügen

Editiert man eine Lambda-Funktion, werden auf der Seite Triggers diejenigen Dienste angezeigt, die diese Funktion aufrufen.

Hier taucht der Trigger Alexa Smart Home zusammen mit der Application Id auf, der bei der Einrichtung des SmartHome-Skills eingetragen wurde.
Zur Verbindung mit dem Custom Skill ist es nötig, einen zweiten Trigger hinzuzufügen. Durch Anklicken von Add Trigger wird eine Auswahlseite eingeblendet. Im neuen Fenster dann auf den gestrichelten Kasten klicken und Alexa Skills Kit' auswählen und mit Next bestätigen

ARN der AWS Lambda Funktion bestimmen

Auf der Übersichtsseite oben links den Menüpunkt Functions aúswählen
Anschließend den Radiobutton der angelegten Funktion FHEM markieren und im Menü Action den Punkt Show ARN auswählen
Es wird nun eine ARN Adresse angezeigt, die für den Abschnitt SmartHome Skill anlegen benötigt wird

Einrichtung in der Alexa App

Nachdem die Alexa Skills angelegt wurden, müssen diese noch in der Alexa App eingerichtet werden. Dafür jeweils per Desktop-Browser auf alexa.amazon.de anmelden, nicht die App unter iOS oder Android verwenden. Diese hat Probleme mit der OAuth Verknüpfung.

Alexa Skill

Auf Skills klicken
Oben rechts Meine Skills bzw. Ihre Skills auswählen
In der Liste der Skills sollte das angelegte FHEM Skill angezeigt werden. Dieses anklicken
Oben Rechts in den Details des Skills auf Skill aktivieren klicken
In dem neu geöffneten Fenster die Autorisierung bestätigen
Anschließend sollte die Verbindung erfolgreich aufgebaut worden sein

Geräte

Auf http://alexa.amazon.de anmelden
Auf Smart Home klicken
Anschließend den Punkt Geräte suchen anklicken
Wurde soweit alles korrekt eingerichtet, werden nun die gefundenen Geräte angezeigt.

Tip: Es macht Sinn, unter Meine Gruppen Gruppen benannt nach den Räumen einzurichten. Hierdurch kann Alexa die Geräte besser auseinander halten, vor allem wenn die den gleichen Alias (z.B. "Licht") haben.

Einrichtung unter FHEM

Im Folgenden werden exemplarisch ein paar Geräte beschrieben, die man nutzbringend mit FHEM einsetzen kann.

Bei Verwendung des Custom Skills übersetzt die Kombination der Attribute alexaMapping und homebridgeMapping Sprachbefehle ("Intents") in gerätespezifische Kommandos.

Das Attribut alexaMapping wird am Alexa-Device gesetzt und dient dazu, erkannte Sprachkommandos in abstrakte Characteristiken zu überführen. Für den einfacheren SmartHome Skill hat darum das Attribut alexaMapping keine Bedeutung, sondern nur der genericDeviceType des zu steuernden Gerätes.
Das Attribut homebridgeMapping wird für beide Skills am zu steuernden Gerät gesetzt und übersetzt diese Charakteristiken in die konkreten Befehle, die das Gerät versteht. Der inhalt des Attributs wird von links nach rechts ausgewertet und ist wie folgt aufgebaut:
- Das Attribut enthält eine durch Leerzeichen getrennte Liste aus Konfigurationen für jeweils eine Characteristik
- Jede einzelne der Characteristik-Konfigurationen besteht aus dem Namen der Characteristik, gefolgt von "=" und einer kommaseparierten Liste von Parametern.

 attr <device> homebridgeMapping <Characteristic1>=<param1.1>,<param1.2>,... <Characteristic2>=<param2.1>,<param2.2>,...

- Jeder Parameter besteht entweder aus
  - <cmd>:<device>:<reading>, hier können nicht verwendete Elemente von links nach rechts weg gelassen werden.
  - <name>=<value>, hier kann <value> entweder ein Wert oder semikolonseparierte Liste sein.
  - Oder dem schlüsselwort clear, welches alle vorhandenen (default) Parameter dieser Characteristik löscht. clear kann auch an Stelle einer ganzen Characteristik-Konfiguration stehen

Weiter führende Dokumentation zum homebridgeMapping findet sich unter https://forum.fhem.de/index.php/topic,48558.0.html

Einfacher Schalter

Ein einfacher Schalter, der die set-Kommandos on und off kennt, kann direkt mit Alexa-Fhem gekoppelt werden
Für kompliziertere Aktionen, etwa das Übermitteln eines spezifischen Schaltbefehls an FHEM, ist die Einrichtung eines Dummies zu empfehlen.

Ob Dummy oder nicht, wichtig sind die drei fett gedruckten Zeilen

define Alexa.Party dummy
attr Alexa.Party alexaName party
attr Alexa.Party alexaRoom alexaroom
attr Alexa.Party genericDeviceType switch
attr Alexa.Party group AlexaGeräte
attr Alexa.Party room AlexaRoom
attr Alexa.Party setList on off

Selbstverständlich kann man diesen Dummy mit einem notify oder DOIF abfangen, um die gewünschte Schaltaktion auszuführen.

Ein Alternative zum Dummy ist das Anlegen eines readingsProxy, dem die entsprechenden Attribute gegeben werden.

Weil es sich hierbei um eines der einfachen Geräte handelt, die Alexa selbst im SmartHome Skill bearbeiten kann, ist auch der zweite Schritt bei der Einrichtung in der Alexa App sinnvoll: Der Schalter wird dann im Bereich Smart Home der Alexa App erkannt. Wer ihn auch mit dem Custon Skill bedienen möchte, muss natürlich Sorge tragen, dass der Alexa-Name party bei den FHEM_Devices auftaucht und die entsprechenden weiteren Slot Types und Example Utterances in der Konfiguration des Custom Skills vorhanden sind (siehe Abschnitt Custom Skill Anlegen).

Wecker

Dieses Gerät kann man nur mit dem Custom Skill bedienen, es wird also nicht im Bereich Smart Home der Alexa App auftauchen. Wir richten einen Dummy ein, wichtig sind wieder die fett gedruckten Zeilen:

define Alexa.Weckzeit dummy
attr Alexa.Weckzeit alexaName weckzeit
attr Alexa.Weckzeit alexaRoom alexaroom
attr Alexa.Weckzeit genericDeviceType clock
attr Alexa.Weckzeit group AlexaGeräte
attr Alexa.Weckzeit homebridgeMapping Weckzeit=state,cmd=+
attr Alexa.Weckzeit room AlexaRoom
attr Alexa.Weckzeit setList Weckzeit:time

Das Attribut genericDeviceTye ist nicht wichtig, weil es ein generisches Device dieser Art gar nicht gibt. Wichtig hingegen ist das Attribut homebridgeMapping

Für das Gerät MyAlexa, das in Abschnitt definiert wurde, muss im Attribut alexaMapping auftauchen

Weckzeit=verb=stelle,valuePrefix=für;auf,values=AMAZON.TIME,valueSuffix=uhr

Darüber hinaus muss der Alexa-Name weckzeit bei den FHEM_Devices auftauchen und die entsprechenden weiteren Slot Types und Example Utterances in der Konfiguration des Custom Skills vorhanden sein (siehe Abschnitt Custom Skill Anlegen).

Der Aufruf dieses Gerätes mit Alexa erfolgt dann z.B. mit den Sätzen

"Alexa, sage <Custom Skill Invocation Name>: Stelle Weckzeit auf Neunzehn Uhr Siebenundzwanzig"
"Alexa, frage <Custom Skill Invocation Name> nach dem Status von Weckzeit"

Dabei ist natürlich der Custom Skill Invocation Name durch den Wert zu ersetzen, den man im Abschnitt Custom Skill Anlegen unter Punkt 2 eingetragen hat.

Zur weiteren Bearbeitung kann man jetzt mit einem DOIF Statusänderungen des Dummies abfangen und durch eine kleine Helperfunktion ins "echte" FHEM weiterleiten.

 define Alexa.Weckzeit.N DOIF (["Alexa.Weckzeit:.*"])({AlexaHelper("Alexa.Weckzeit","$EVENT")})

Die Helperfunktion (z.B. in 99_myUtils.pm) stellt aus der übergebenen Zeit (immer im Format dd:mm) eine sprachkompatible Nachricht $nc und einen mit den FHEM-Zeitangaben kompatiblen String $nt zusammen und reicht beide an eine Routine changeWakeTime weiter (dokumentiert in den Smart Home Hacks).

sub AlexaHelper($$){
 my ($name,$event)=@_;
 if( $name eq "Alexa.Weckzeit" ){ 
   my ($nc,$nt);
   #-- volle Stunde----------------------------------------
   if( $event =~ /(\d+):00/ ){
     $nc=sprintf("%d Uhr",$1);
     $nt=sprintf("%02d:00:00",$1);
   #-- nicht volle Stunde---------------------------------
   }elsif( $event =~ /(\d+):(\d+)/ ){
     $nc=sprintf("%d Uhr %d",$1,$2);
     $nt=sprintf("%02d:%02d:00",$1,$2);
   }
   changeWakeTime(\'GalaxyTab.EG\',\'$nc\',\'$nt\');
 }
}

Lichtszene

Eine Lichtszene wird mit dem Modul LightScene angelegt. Wir gehen davon aus, dass in der Lichtszene die beiden Szenen Alle_An und Alle_Aus, sowie mindestens eine weitere Szene (hier: Sitzgruppe) definiert wurde.

Nachfolgend wird ein Beispiel beschrieben, wie man eine Lichtszene mit dem einfachen SmartHome Skill steuern kann. Die verwendeten Kommandos sind dann

"Alexa, schalte (die) Beleuchtung an" -> LightScene Alle_An wird ausgewählt
"Alexa, schalte (die) Beleuchtungsitzgruppe an" -> LightScene Sitzgruppe wird ausgewählt
...
"Alexa, schalte (die) Beleuchtung aus" -> LightScene Alle_Aus wird ausgewählt

Künftig wird man LightScene mit dem Custom Skill eventuell direkt steuern können - allerdings hat das einen geringeren WAF, als die Steuerung über den SmartHome Skill: Der Einschaltsatz muss dann mindestens lauten

"Alexa, sage <Custom Skill Invocation Name>: schalte (die) Beleuchtung an" -> LightScene Alle_An wird ausgewählt

Im ersten Schritt wird ein Dummy für die Gesamtbeleuchtung eingerichtet:

define Alexa.Beleuchtung dummy 
attr Beleuchtung setList on off
attr Alexa.Beleuchtung alexaName beleuchtung
attr Alexa.Beleuchtung alexaRoom alexaroom
attr Alexa.Beleuchtung GenericDeviceType switch

Anschließend wird für jede vorhandene Lichtszene (außer Alle_An und Alle_Aus) ein weiterer Dummy angelegt:

define Alexa.Beleuchtung.Sitzgruppe dummy 
attr Beleuchtung setList on off
attr Alexa.Beleuchtung.Sitzgruppe alexaName beleuchtungsitzgruppe
attr Alexa.Beleuchtung.Sitzgruppe alexaRoom alexaroom
attr Alexa.Beleuchtung.Sitzgruppe GenericDeviceType switch

Die eigentliche Steuerung übernimmt dann ein DOIF

define Alexa.Beleuchtung.N DOIF
(["Alexa.Beleuchtung.Sitzgruppe:on"])
(set <devicename der Lichtszene> scene Sitzgruppe,
 set Alexa.Beleuchtung off,
  ...<weitere dummies der anderen Szenen werden ebenfalls ausgeschaltet>
)
DOELSIF
... <weitere on-Events der anderen Szenen werden abgefangen>
DOELSEIF
(["Alexa.Beleuchtung:on"])
(set <devicename der Lichtszene> scene Alle_An,
 set Alexa.Beleuchtung.Sitzgruppe off,
 ...<weitere dummies der anderen Szenen werden ebenfalls ausgeschaltet>
)
DOELSEIF
(["Alexa.Beleuchtung:off"])
(set <devicename der Lichtszene> scene Alle_Aus,
 set Alexa.Beleuchtung.Sitzgruppe off,
 ...<weitere dummies der anderen Szenen werden ebenfalls ausgeschaltet>
)

Mit diesem DOIF wird ein Radiobutton simuliert, d.h. wie bei den Stationstasten vor Uralt-Radios sorgt die Auswahl einer Szene immer dafür, dass alle anderen Dummies ausgeschaltet werden. Natürlich kann man das auch mit einem kleinen Perl-Programm erreichen.

Nutzung

Um den Namen zu bestimmen, unter dem ein Gerät mit Alexa angesprochen wird, verwendet Alexa-Fhem mit absteigender Priorität:

das alexaName Attribut
das alias Attribut
das NAME Internal

Damit Alexa ein Gerät eindeutig identifizieren kann, sollten eindeutige Gerätenamen verwendet werden, bestehed möglichst aus einem Wort und ohne Ziffern. Wenn Alexa einen Namen nicht versteht, kann man unter [1] nachsehen was tatsächlich verstanden wurde und den Gerätenamen ggf. anpassen.

SmartHome Skill

Gruppen (Räume) müssen in der Alexa App konfiguriert werden. Über das API lassen sich nur der Name und die Schalteigenschaften übergeben.

Nach erfolgreicher Einrichtung des SmartHome Skills sollte Alexa mit den folgenden Befehlen nutzbar sein:

“alexa, schalte <gerät/gruppe> ein”
“alexa, schalte <gerät/gruppe> aus”
“alexa, stelle <gerät/gruppe> auf <wert> prozent”
“alexa, stelle <gerät/gruppe> auf <anzahl> grad”
“alexa, erhöhe <gerät/gruppe> um <anzahl> prozent”
“alexa, reduziere <gerät/gruppe> um <anzahl> prozent”
“alexa, erhöhe <gerät/gruppe> um <anzahl> grad”
“alexa, reduziere <gerät/gruppe> um <anzahl> grad”

Custom Skill

Der Custom Skill erlaubt im Gegensatz zum SmartHome Skill eine weitreichende Konfiguration der möglichen Kommandos.

Das Prinzip der Kommandokonfiguration ist im Forum beschrieben.

TODO: Abfragen, Attribute (alexaMapping, alexaTypes, fhemIntents, articles, prepositions)

Troubleshooting

Allgemeiner Hinweis

Besonders wichtig ist, dass man sich sehr genau an diese Anleitung hält. Ein häufiger Fehler ist, dass die einfachen Anführungszeichen in der Anleitung unter AWS Lambda Funktion anlegen Punkt 8 einfach weggelassen werden. Diese sind zwingend notwendig. Es darf auch nur der reine Hostname eingetragen werden. Also kein http:// davor. Entweder eine feste IP Adresse oder den Hostnamen, um den Rechner zu erreichen, den ihr über den Port 3000 freigegeben habt. Das sollte dann so aussehen:

const PORT=3000;
const HOST='mein.host.name';

Freigabe von Port 3000

Derzeit müsst ihr über einen echten IPv4 Anschluss verfügen, damit der Amazon Lambda-Server euch erreichen kann. DS-Lite Anschlüsse wie die von UnityMedia z.B. funktionieren derzeit leider nicht. Eine möglicher "Workaround" wird hier beschrieben: https://forum.fhem.de/index.php/topic,60244.msg518276.html#msg518276

Auf dem Router muss der Port 3000 Protokoll TCP freigegeben werden. D.h. von außen muss man wenn man den Port 3000 aufruft, auf dem intern laufenden node.js Alexa-Dienst zugreifen können. Je nach Router gestaltet sich das Portforwarding bzw. die Portumleitung etwas schwieriger.

Bei einem Speedport Router der Telekom beispielsweise, muss der Router komplett neu gestartet werden, wenn die Portfreigabe eingerichtet wurde.

Bei der Fritz!Box ist das nicht nötig, bei dieser finden die Freigabe unter Internet -> Freigaben -> Portfreigaben statt. Dort wählt man dann den Rechner aus und richtet eine neue Freigabe ein. Wichtig hierbei ist, dass man Portfreigabe auswählt und nicht MyFRITZ!-Freigabe. Bei Port von bis trägt man 3000 ein, bei Port extern ebenfalls.

Um die Portweiterleitung zu testen, solltet ihr euch auch nicht im gleichen Netz befinden. Viele Router blockieren den Netzaufruf aus dem gleichen Netz. Am besten testet ihr es, wenn ihr an eurem Mobiltelefon W-LAN deaktiviert und im Browser folgende Seite aufruft: https://mein.hostname:3000. Wenn ihr im Browser dann einen Quellcode von Alexa seht, funktioniert die Portumleitung.

Wenn bis hier alles funktioniert und es läuft dennoch nicht rund, liegt das Problem woanders. Kommt z.B. bei der Gerätesuche kein Request rein (sichtbar auf dem Bildschirm, wenn bin/alexa gestartet wurden), kann evtl. der Lambda-Dienst falsch konfiguriert sein.

Probleme mit node.js - npm install

Falls eine Fehlermeldung auftritt, dass "npm" nicht gefunden werden kann, bitte NodeJS entsprechend der Anleitung im Homebridge-Artikel vorgehen: NodeJS installieren sowie Python, g++, MDNS installieren, siehe auch folgenden Abschnitt.

Es kommen diverse Fehlermeldungen beim Starten von alexa-fhem und es beendet sich

Wenn man auf der Konsole angemeldet ist, den Befehl

node -v

eingeben. Ist die Version niedriger als die geforderte 0.12, muss eine neuere installiert werden. Hier darf man dann im Wiki unter Homebridge_einrichten#NodeJS_installieren nachschauen. NodeJS V4 sollte hierbei schon ausreichen. Solange die node.js Version nicht passt, gar nicht groß rum experimentieren! Bitte beachtet, dass alle Voraussetzungen unter Alexa-Fhem#Voraussetzungen erfüllt sind! Keine Experimente mit Versionen die darunter liegen.

Fehlermeldung NAT-PMP failed: Error: timeout Fehler angezeigt beim Start von alexa-fhem

Wenn ihr dann alexa-fhem über die Konsole startet und bekommt folgenden Fehler: NAT-PMP failed: Error: timeout, lasst euch davon nicht irritieren. Das bedeutet lediglich, dass der Port nicht automatich freigegeben wurde über uPNP. Alternativ prüft, ob die Funktion der Portfreigabe via uPNP auf eurem Router aktiviert ist.

Nach Start auf der Console beendet sich Alexa-FHEM sofort wieder

Unmittelbar nach dem Start von Alexa-FHEM werden ein paar UPNP Fehlermeldungen ausgegeben. Unmittelbar danach beendet sich Alexa-FHEM wieder.

Viele scheinen ein Problem mit UPNP auf dem Raspberry Pi zu haben. Wenn dieses Problem auftritt einfach in der ~/.alexa/config.json die folgenden Zeilen rauslöschen:

        "nat-pmp": "10.0.1.1",
        "nat-upnp": true,

Jetzt erneut Alexa-FHEM starten. Sollte nun laufen.

Was ist zu tun, wenn alexa-fhem keine Geräte findet?

Zunächst müssen die Geräte, die angesprochen werden wollen, unter FHEM ein neues Attribut zugewiesen bekommen. Dazu das Gerät in FHEM öffnen und das Attribut genericDeviceType switch hinzufügen, wenn es ein Schalter mit der Funktiona AN/AUS sein soll. Wenn man will, kann man dem Gerät jetzt noch über das Attribut alias eine besseren Namen geben, mit dem Alexa das Gerät dann auch finden kann. Anschließend muss alexa-fhem neu gestartet werden und die definierten Geräte sollten nun gefunden werden.

Was ist zu tun, wenn Alexa zwar Geräte findet, diese aber nicht angesprochen werden können?

Zuerst die Informationen zum Datenfluss ganz oben ansehen. Dann am besten von hinten nach vorne vorgehen:

wenn nichts bei alexa-fhem ankommt: port forwarding prüfen
wenn lambda.js nichts los wird: im cloudwatch log nachsehen
wenn bei lambda.js nichts ankommt: den trigger prüfen

Zunächst sollte man sich unter http://aws.amazon.com das Logfile seiner erstellten Funktion anschauen. Ist überhaupt ein Logfile vorhanden? Falls nicht, liegt es vermutlich am Trigger. Den solltet ihr überprüfen. Scheinbar kommt es hin und wieder vor, dass dieser nicht gesetzt ist. Dazu einfach auf Triggers klicken und mit Add trigger erneut einen anlegen. Hier muss, wie in der Anleitung unter AWS Lambda Funktion anlegen Punkt 7, die Application Id stehen und der Haken bei Enable trigger gesetzt sein. Dann alexa-fhem neu starten. Wenn ihr Änderugen gemacht habt und den alexa-fhem Dienst noch nicht neu gestartet habt, wäre jetzt der richtige Zeitpunkt.

Was ist zu tun, wenn sich der Alexa-Service nicht starten lässt?

Schaut bitte in das Unterverzeichnis [alexa-fhem (also dort, wo Ihr Alexa-FHEM instelliert habt]/bin. Die dort befindliche Datei alexa muss ausführbar sein. Also z.B. so:

2755327 4 -rwxr-xr-x 1 pi pi  339 Nov 26 23:20 alexa

Sollte dies nicht der Fall sein bitte mit:

chmod +x alexa

die Datei ausführbar machen. Sofern der User "pi" Eigentümer ist, ist kein sudo erforderlich.

Wie kann ich via Alexa-FHEM auf FHEM zugreifen, wenn der Port mit Benutzername/Kennwort geschützt ist?

Hierzu muss die Datei ~/.alexa/config.json geöffnet werden und der Abschnitt "connections" um folgende Zeile ergänzt werden:

        "auth": {"user": "fhem", "pass": "fhempassword"},

Bei Verwendung von SSL bei FHEM muss auch noch

        "ssl": true,

hinzugefügt werden