FHEMWiki - Benutzerbeiträge [de]

HMCCU

2023-08-09T06:22:25Z

DR: /* Inbetriebnahme */

Das Modul HMCCU ermöglicht zusammen mit weiteren Modulen eine Integration der [[HomeMatic]] CCU Zentrale sowie der dort angelernten Geräte in FHEM.
{{Hinweis|Dieser Artikel bezieht sich auf die neue HMCCU Version 5.0}}
{{Infobox Modul
|ModPurpose=Anbindung HomeMatic CCU an FHEM
|ModType=d
|ModCmdRef=HMCCU
|ModForumArea=HomeMatic
|ModTechName=88_HMCCU.pm
|ModOwner=zap ({{Link2FU|10980|Forum}} / [[Benutzer Diskussion:Zap|Wiki]])
}}
==Einführung==
===Übersicht===
Das Modul [[HMCCU]] ermöglicht zusammen mit den Client Modulen → [[HMCCUDEV]], HMCCUCHN und HMCCUPROCRPC eine Integration der [[HomeMatic]] CCU Zentrale sowie der dort angelernten Geräte in FHEM. Im Einzelnen werden folgende Funktionen unterstützt:

* Unterstützt Hard- und Software CCUs inkl. CCU3, YAHM, piVCCU und RaspberryMatic
* Unterstützung der Protokolle BidCos, Wired und [[HomeMatic IP|HM-IP]]
* Unterstützung von CUxD, OSRAM und Philips Hue Devices in der CCU
* Unterstützung von HVL (HomeMatic Virtual Layer)
* Unterstützung von CCU Gerätegruppen bzw. virtuellen Geräten (Heizung, Rauchmelder)
* Automatische Aktualisierung von Gerätezuständen in FHEM per RPC-Server
* Automatische Konvertierung und Skalierung von Werten beim Lesen und Schreiben
* Lesen und Schreiben von CCU Systemvariablen
* Ausführen von CCU Programmen
* Ausführen von HomeMatic Scripts auf der CCU

Die einzelnen Module haben folgende Aufgaben:

* HMCCU: Kommunikation zwischen FHEM und CCU (I/O Device)
* HMCCURPCPROC: RPC-Server zum Empfang von Events der CCU
* HMCCUDEV: Definition von FHEM Devices für HomeMatic Geräte
* HMCCUCHN: Definition von FHEM Devices für einzelne Kanäle von HomeMatic Geräten
* HMCCUConf: Templates mit Default Attributen für bestimmte HomeMatic Gerätetypen

===Geräte, Kanäle und Datenpunkte===
Geräte in der HomeMatic CCU bestehen aus einem oder mehreren Kanälen. Ein Kanal wiederum hat einen oder mehrere Datenpunkte. Über diese Datenpunkte kann ein Gerät gesteuert oder Statusinformationen ausgelesen werden. Sofern ein Datenpunkt lesbar ist, kann er als Reading in einem HMCCUCHN oder HMCCUDEV Device dargestellt werden. Ausgehend von dieser Abbildung in der CCU kann man nun entscheiden, ob man ein CCU Gerät mit HMCCUCHN oder HMCCUDEV definiert.

Der oben beschriebene Aufbau lässt sich am Beispiel einer Steckdose veranschaulichen:<syntaxhighlight lang="Text">
DEV ST-WR-Waschmaschine KEQ0965669 interface=BidCos-RF type=HM-ES-PMSw1-Pl
CHN KEQ0965669:0 ST-WR-Waschmaschine:0
0.UNREACH = false {b} [RE]
0.STICKY_UNREACH = true {b} [RWE]
0.CONFIG_PENDING = false {b} [RE]
0.DUTYCYCLE = false {b} [RE]
0.RSSI_DEVICE = 1 {n} [RE]
0.RSSI_PEER = 214 {n} [RE]
0.DEVICE_IN_BOOTLOADER = false {b} [RE]
0.UPDATE_PENDING = false {b} [RE]
0.AES_KEY = 0 {n} [R]
CHN KEQ0965669:1 ST-WR-Waschmaschine:1
1.STATE = true {b} [RWE]
1.ON_TIME = {f} [W]
1.INHIBIT = false {b} [RWE]
1.INSTALL_TEST = {b} [W]
1.WORKING = false {b} [RE]
CHN KEQ0965669:2 ST-WR-Waschmaschine:2
2.ENERGY_COUNTER = 59348.000000 {f} [RE]
2.POWER = 0.120000 {f} [RE]
2.CURRENT = 45.000000 {f} [RE]
2.VOLTAGE = 233.000000 {f} [RE]
2.FREQUENCY = 49.990000 {f} [RE]
2.BOOT = true {b} [RE]
</syntaxhighlight>
Das Gerät in diesem Beispiel hat 3 nutzbare Kanäle:
* Kanal 0 ist der Maintenance Kanal. Diesen Kanal hat jedes Gerät. Er ist sowohl bei HMCCUCHN als auch bei HMCCUDEV immer vorhanden. Die Datenpunkte werden automatisch auf gebräuchliche Readings wie z.B. "battery" gemappt.
* Kanal 1 ist der Schaltkanal der Steckdose. Er besitzt einen Datenpunkt STATE, über den die Steckdose ein-/ausgeschaltet werden kann. Die Flags "RWE" stehen für '''R'''ead, '''W'''rite, '''E'''vent. Der Datenpunkt ist also beschreibbar, lesbar und wird von der CCU per Event automatisch aktualisiert
* Kanal 2 ist ein reiner Statuskanal. Er besitzt keine beschreibbaren Datenpunkte (nur '''R'''ead und '''E'''vent).
Wenn man das Gerät lediglich schalten möchte und auf die Anzeige der Energiewerte aus Kanal 2 verzichten kann, sollte man ein HMCCUCHN Device für Kanal 1 (KEQ0965669:1) definieren (enthält automatisch auch Kanal 0). Andernfalls definiert man ein HMCCUDEV Device für das Gerät KEQ0965669, das dann alle Kanäle (0-2) enthält.

Es wird empfohlen, für die Definition von FHEM Devices die HMCCU-Befehle '''get createDev''' oder '''get create''' zu verwenden. Sofern ein Gerät von HMCCU unterstützt wird, wird automatisch das richtige Modul ausgewählt.

{{Hinweis|Im Artikel → [[HMCCU Best Practice]] gibt es einige Tipps für den Einstieg inklusive Schritt-für-Schritt Anleitungen (noch nicht an 5.0 angepasst).}}

==Inbetriebnahme==
===Zu beachten===

* In den CCU Gerätenamen dürfen keine Umlaute verwendet werden. Leerzeichen sind zulässig, können aber u.U. bei einigen Funktionen zu Problemen führen.
* Namen in der CCU müssen über alle Objekttypen hinweg eindeutig sein. Beispiel: Ein Gerät und ein Raum dürfen nicht den gleichen Namen haben.
* Nach dem Neustart der CCU muss auch der RPC-Server neu gestartet werden, da die CCU2 bei einem Neustart die registrierten RPC-Server "vergisst".
* Nach Änderung von Attributen der RPC-Server Devices oder von RPC-Attributen im I/O Device müssen die RPC-Server neu gestartet werden, damit die Änderungen berücksichtigt werden.
* Vor der Ausführung eines FHEM Updates oder vor der Installation eines CCU Firmware Updates muss der RPC-Server gestoppt werden.
* Seit der CCU Firmware 2.27.7 sind die Zugriffsmöglichkeiten auf die CCU durch eine Firewall abgesichert. Der Zugriff durch FHEM muss explizit freigeschaltet werden, da HMCCU sonst nicht korrekt funktioniert (s. nächster Abschnitt).

===CCU Firewall Einstellungen===
Ab CCU Firmware 2.27.7 sind auf der CCU über das WebGUI folgende Einstellungen vorzunehmen:
* Menü "Einstellungen > Systemsteuerung" aufrufen
* Button "Firewall konfigurieren" anklicken
* Bei "Firewall-Richtlinie" den Eintrag "Ports offen" auswählen, andernfalls müssen die notwendigen Ports im Feld "Port-Freigabe" explizit angegeben werden
* Die Rechte für "HomeMatic XML-RPC API" und "Remote HomeMatic-Script API" auf "Vollzugriff" setzen.
* Man kann die Rechte auf "Eingeschränkter Zugriff" belassen, muss dann aber im Feld "IP-Adressen für eingeschränkten Zugriff" die IP des FHEM-Servers oder das komplette Subnetz in Subnet-Notation angeben.

Wenn der Zugriff von FHEM auf die CCU ohne Anmeldung erfolgen soll, muss zusätzlich in der Systemsteuerung unter "Sicherheit" die Option "Authentifizierung" deaktiviert werden. Alternativ kann im I/O Device (HMCCU) mit dem Befehl set authentication Benutzername und Passwort der CCU angegeben werden.

===Installation===
Alle HMCCU Module sind Teil von FHEM. HMCCU benötigt die Perl Module RPC::XML::Server und RPC::XML::Client.

Unter debian/raspbian kann das Paket librpc-xml-perl installiert werden oder alternativ CPAN verwendet werden:
<pre>sudo apt-get update && sudo apt-get install -y librpc-xml-perl</pre>

Unter Windows (Strawberry Perl) kann man das Paket RPC::XML mit cpan installieren
<pre>cpan install RPC::XML</pre>
Bei der Installation gemäß [[FHEM Installation Windows]] befindet sich cpan man unter <code><FHEM-Hauptverzeichis>\perl\bin</code>

===Definition I/O Device===
Im ersten Schritt wird ein I/O Device angelegt, das für die Kommunikation zwischen FHEM und der CCU verantwortlich ist. Im folgenden Beispiel wird davon ausgegangen, dass die CCU unter der IP-Adresse 192.168.1.10 erreichbar ist. Das FHEM Device bekommt den Namen „d_ccu“.
<pre>define d_ccu HMCCU 192.168.1.10</pre>
Falls die CCU als Software Service auf dem gleichen Rechner läuft wie FHEM, sollte bei der Definition der Parameter ''ccudelay'' angegeben werden. Die CCU Services brauchen beim Starten länger als FHEM (bis zu 2 Minuten). Durch ''ccudelay'' wird das neu angelegte I/O Device verzögert um die angegebene Anzahl Sekunden initialisiert. Die Vorgabe sind 180 Sekunden. Je nach Installation kann auch ein höherer Wert notwendig sein:
<pre>define d_ccu HMCCU 192.168.1.10 ccudelay=180</pre>
Der Start von FHEM wird dadurch nicht verzögert. Lediglich HMCCU wird verzögert initialisiert. Die verzögerte Initialisierung kann mit dem Parameter ''delayedinit'' erzwungen werden, greift dann also auch, wenn die CCU beim Start von FHEM erreichbar ist

===RPC Server konfigurieren und starten===
Im nächsten Schritt wird der RPC-Server konfiguriert und gestartet. Zunächst werden mit dem Attribut ''rpcinterfaces'' die Schnittstellen bzw. Ports festgelegt, für die sich der RPC-Server bei der CCU registrieren soll. Das Attribut zeigt in einer Auswahlliste die möglichen Schnittstellen an. Nur für die hier ausgewählten Schnittstellen werden automatisch Readings aktualisiert.

Beim ersten Start dieses RPC-Servers über das I/O Device wird automatisch je Schnittstelle ein Device vom Typ HMCCURPCPROC angelegt. Die Attribute "room" und "group" werden vom I/O Device übernommen.

Nun kann der RPC-Server gestartet werden. Dabei wird je RPC-Schnittstelle ein separater fhem.pl Prozess mit eigenem Listening-Port gestartet. Beim ersten Start legt HMCCU für jede unter ''rpcinterfaces'' angegebene Schnittstelle ein Device vom Typ HMCCURPCPROC an. Sofern auf dem FHEM-Server eine Firewall aktiv ist, müssen die Ports (s. Attribut ''rpcserverport'') für den Zugriff der CCU freigegeben werden.

Alle RPC-Server werden über das I/O Device mit einem Befehl gestartet:
<pre>set d_ccu on</pre>
Während des Starts der RPC-Server und der Registrierung bei der CCU kann das I/O Device nur eingeschränkt verwendet werden. Dies wird durch den Status „starting/busy“ angezeigt. Nachdem die RPC-Server gestartet wurden, wechselt der Status zu „running/OK“. Zusätzlich werden im Internal RPCPID die Prozess-IDs der RPC-Server Prozesse gespeichert.
Anschließend sollte man noch das Attribut ''rpcserver'' auf „on“ setzen, damit die RPC-Server beim Start von FHEM automatisch gestartet werden:
<pre>attr d_ccu rpcserver on</pre>

== Migration von HMCCU 4.3 ==
Nachdem FHEM auf HMCCU Version 5.0 aktualisiert und neu gestartet wurde, sollten die definierten Geräte (HMCCUCHN und HMCCUDEV Devices) wie unter Version 4.3 funktionieren. Da die Devices in Version 5.0 jedoch mit deutlich weniger Attributen auskommen bzw. einige Attribute wie z.B. "eventMap" sogar zu doppelten '''set''' Befehlen führen können, sollten die Attribute der Geräte jeweils mit dem Befehl '''set defaults reset''' zurückgesetzt werden. Beim Zurücksetzen der Attribute werden überflüssige Attribute gelöscht.

Wichtig: Nach dem Zurücksetzen der Attribute mit '''set defaults reset''' die Konfiguration speichern und FHEM neu starten.

Je nach Anzahl bereits definierter Devices kann es sinnvoll sein, alle Devices mit der Funktion '''get create''' oder '''get createDev''' neu anzulegen. Für die neu angelegten Geräte wird automatisch das passende Client-Modul (HMCCUDEV oder HMCCUCHN) verwendet.

==Synchronisation mit der CCU==

=== Geräte synchronisieren ===
Das Modul HMCCU bietet Befehle an, um Daten zwischen der CCU und FHEM zu synchronisieren. Der Befehl '''get ccuConfig''' liest alle Geräte aus der CCU. Er sollte immer ausgeführt werden, wenn sich an einer Gerätedefinition in der CCU etwas geändert hat, z.B. ein Gerät oder Kanal wurde umbenannt, ein neues Gerät wurde angelernt, ein Gerät wurde gelöscht. Bei der Definition des I/O Device (z.B. beim Start von FHEM) wird der Befehl automatisch ausgeführt.

Der Befehl '''get ccuDevices''' zeigt eine Liste der in der CCU bekannten Geräte an inklusive einer Liste der Kanalrollen, die von HMCCU automatisch erkannt werden. Daran kann man erkennen, welche CCU-Geräte von den Befehlen '''get create''' und '''get createDev''' unterstützt werden.

=== Datenpunkte (Readings) synchronisieren ===
Eine manuelle Aktualisierung der Datenpunkte sollte nicht notwendig sein. Die Aktualisierung erfolgt automatisch durch die CCU per RPC-Server Verbindung. Der Befehl '''get update''' liest die Datenpunkte aller in FHEM definierten HMCCUDEV und HMCCUCHN Devices aus der CCU und aktualisiert alle Readings aller Client Devices.

==Autocreate von FHEM-Devices für CCU Geräte==
HMCCU bietet eine Möglichkeit, um automatisch Client Devices in FHEM für Geräte oder Kanäle in der CCU anzulegen, sofern HMCCU eine oder mehrere Kanalrollen des betreffenden Gerätetyps unterstützt. Dazu kann entweder der Befehl '''get createDev''' (für ein einzelnes CCU Gerät) oder der Befehl '''get create''' (für mehrere CCU Geräte) verwenden werden.

{{Hinweis|Es wird dringend empfohlen, FHEM Devices für CCU Geräte mit den Befehlen get createDev oder get create anzulegen. Nur wenn Geräte dabei nicht erkannt werden, sollte man auf das klassische define zurückgreifen}}

Die beiden Befehle zur automatischen Erzeugung von HMCCUDEV/HMCCUCHN Devices beziehen sich immer auf CCU-Geräte, nicht deren Kanäle. Bei der Erzeugung der FHEM-Devices entscheidet HMCCU selbständig, ob ein oder mehrere HMCCUDEV oder HMCCUCHN Devices angelegt werden. Nach Ausführung der Befehle werden in einem Fenster die angelegten oder auch nicht erkannten Geräte angezeigt.

Beispiel: Für das CCU-Gerät "Heizung-Wohnzimmer" soll ein FHEM-Device angelegt werden:
get d_ccu createDev Heizung-Wohnzimmer
Beispiel: Für alle CCU-Geräte, deren Namen mit "Heizung" beginnt, sollen FHEM-Devices angelegt werden:
get d_ccu create Heizung.* room=Homematic group=Heizung
Beim vorherigen Beispiel wird als Gerätename ein regulärer Ausdruck ("Heizung.*) angegeben. Jedes angelegte Gerät bekommt die Attribute "room" und "group" zugewiesen.

Wenn ein CCU-Gerät mehrere identische Kanalrollen besitzt, erzeugt HMCCU für jeden Kanal ein HMCCUCHN-Device. Ein Beispiel für solche CCU-Geräte sind Fernbedienungen, die 2-16 Kanäle der Rolle "KEY" besitzen.

Beispiel: Für die 2-Kanal-Fernbedienung FB-Rollladen werden 2 HMCCUCHN Devices angelegt. Die Namen der Devices werden aus den Kanalnamen der Fernbedienung in der CCU gebildet:
get d_ccu createDev FB-Rollladen
erzeugt die HMCCUCHN Devices: FB-Rollladen-Wohnzimmer, FB-Rollladen-Kueche.

Die Attribute der automatisch angelegten Devices können über die I/O Device Attribute '''ccudef-attributes''' und '''createDeviceGroup''' beeinflusst werden. Um allen neu angelegten Devices das Attribut room=Homematic zuzuweisen, definiert man folgendes Attribut im I/O Device:
<syntaxhighlight lang="Text">
attr d_ccu ccudef-attributes room=Homematic
</syntaxhighlight>
Mit dem Attribut '''createDeviceGroup''' können Einzel-Devices, die alle zu einem CCU-Gerät gehören, automatisch in einer FHEM-Gruppe zusammengefasst werden. Dieses Attribut kommt z.B. zur Anwendung, wenn man get createDev für eine Fernbedienung mit mehreren Kanälen ausführt. In diesem Fall legt HMCCU für jeden Kanal der Fernbedienung ein HMCCUCHN Device an. Mit dem folgenden Attribut im I/O Device werden diese HMCCUCHN Devices alle einer Gruppe zugeordnet, deren Name dem Gerätenamen in der CCU entspricht:
<syntaxhighlight lang="Text">
attr d_ccu createDeviceGroup %n
</syntaxhighlight>
Die möglichen Platzhalter (wie z.B. %n) können der Commandref entnommen werden.

==Weitere Funktionen des Moduls HMCCU==
===Lesen und Ändern von CCU Systemvariablen===
Systemvariablen der CCU können mit den Befehlen '''get vars''' und '''set var''' gelesen und geändert werden. Der Befehl '''get vars''' akzeptiert als Parameter einen regulären Ausdruck. Dadurch können mehrere Systemvariablen auf einmal gelesen werden. Nach dem Auslesen einer Systemvariable wird der Wert in einem Reading im I/O Device gespeichert.

Beispiel: Lesen aller Systemvariablen, die mit A beginnen:
<pre>get d_ccu vars A.*</pre>

Systemvariablen können in regelmäßigen Abständen gelesen werden. Dazu wird mit dem Attribut ccuGetVars ein Intervall und optional ein regulärer Ausdruck für die zu lesenden Systemvariablen festgelegt.

Beispiel: Lesen aller Systemvariablen alle 60 Sekunden. Im zweiten Befehl werden nur Variablen gelesen, die mit "A" beginnen:
<pre>attr d_ccu ccuGetVars 60
attr d_ccu ccuGetVars 60:^A</pre>

Wenn eine Systemvariable bereits in der CCU existiert, kann ihr Wert mit dem Befehl '''set var''' geändert werden.

Beispiel: Setzen der Systemvariablen „Temperatur“ auf den Wert 20.5:
<pre>set d_ccu var Temperatur 20.5</pre>

Mit dem Befehl '''set var''' kann auch eine neue Systemvariable in der CCU angelegt werden. Dazu wird als erster Parameter vor dem Variablennamen der Typ der neuen Variable angegeben. Mögliche Typen sind "bool", "list", "number" oder "text".

Beispiel: Anlegen einer Textvariablen mit dem Namen "Wetter":
<pre>set d_ccu var text Wetter sonnig</pre>

Optional können noch Attribute für eine neue Systemvariable gesetzt werden. Folgende Attribute sind erlaubt:

* unit = Einheit
* desc = Beschreibung
* min = Kleinster erlaubter Wert bei numerischen Variablen
* max = Größter erlaubter Wert bei numerischen Variablen
* list = Durch Komma getrennte Liste mit zulässigen Werten bei Listen-Variablen
* valtrue = Angezeigter Wert bei Variablen vom Typ bool, Default = "ist wahr"
* valfalse = Angezeigter Wert bei Variablen vom Typ bool, Default = "ist falsch"

Beispiel: Anlegen einer numerischen Variablen für Temperaturwerte:
<pre>set d_ccu var number Temperatur 20.5 unit=Grad desc=Aussentemperatur min=-10.0 max=40.0</pre>

===Ausführen von CCU Programmen===
Ein in der CCU2 hinterlegtes Programm kann mit dem Befehl '''set execute''' ausgeführt werden. Einziger Parameter des Befehls ist der Name des Programms. Es spielt keine Rolle, ob das Programm in der CCU aktiv oder inaktiv ist.

Beispiel: Programm mit dem Namen "Schalter_Ein" ausführen:
<pre>set d_ccu execute Schalter_Ein</pre>

===Aggregation von Gerätezuständen===
Hinter diesem etwas kryptischen Begriff verbirgt sich die Zusammenfassung von Zuständen von Client-Devices. Anwendungsbeispiele sind:
* Wieviele und welche Geräte haben einen niedrigen Batteriestand?
* Wieviele und welche Fenster sind geöffnet?
Für die Beantwortung dieser Fragen stellt HMCCU einige Befehle und Attribute bereit. Die Ergebnisse werden in Form von Readings im I/O Device bereitgestellt:
*''Präfix''_count = Anzahl der FHEM Devices, die für die Aggregation ausgewertet wurden.
*''Präfix''_list = Liste der FHEM Devices, die der if Bedingung Aggregationsregel entsprechen.
*''Präfix''_match - Anzahl der FHEM Devices, die der if Bedingung der Aggregationsregel entsprechen.
*''Präfix''_state - Ergebnis der Aggregationsregel (if oder else Wert).
Aggregationen werden automatisch bei Änderung von Readings neu berechnet. Alternativ kann mit dem Befehl '''get aggregation''' eine Aggregation explizit durchgeführt werden. Als Parameter wird der Name der Aggregationsregel oder "all" für alle Aggregationen übergeben:
<pre>get <io-dev> aggregation {all|<name>}</pre>
Die Konfiguration der Aggregationen erfolgt mit Hilfe von Regeln, die über das Attribut ''ccuaggregate'' definiert werden. Dabei werden mehrere Regeln durch ein Semikolon und optional einen Zeilenumbruch getrennt. Eine Aggregationsregel enthält mehrere, durch Komma getrennte Parameter, die das Verhalten einer Aggregation festlegen:
*'''name''':<Name> - Legt den Namen einer Aggregation fest.
*'''filter''':{name|alias|group|room|type}=<Incl-Expr>[!<Excl-Expr>] - Legt fest, welche Geräte in die Aggregation einbezogen werden:
**name: FHEM Device Name
**alias: FHEM Device Alias
**group: FHEM Device ''group'' Attribut
**room: FHEM Device ''room'' Attribut
**type: HomeMatic Gerätetyp
*'''read''':<Read-Expr> - Legt fest, welche Readings für die Aggregation verwendet werden (z.B. state oder LOWBAT).
*'''if''':{any|all}=<Value> - Legt die Bedingung fest, unter der die Aggregationsregel greift:
**any: Regel greift, wenn das Reading mindestens eins der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' hat.
**all: Regel greift, wenn die Readings aller der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' haben.
*'''else''':<Value>
*'''prefix''':{RULE|<Text>} - Legt das Präfix für die Readings fest, die das Ergebnis einer Aggregation beinhalten wobei "RULE" für den Namen der Aggregationsregel steht.
*'''coll''':{NAME|<Attribute>}[!<Default>] - Legt fest, welches Attribut der FHEM Devices, die in die Aggregation einbezogen werden, in das _list Reading aufgenommen werden, sofern sie die if Bedingung erfüllen. Dabei entspricht "NAME" dem FHEM-Devicename. Der optionale Parameter Default legt den Inhalt des _list Readings fest, wenn keines der FHEM Devices die if Bedingung erfüllt. Voreingestellt ist "no match".

Beispiel: Aggregation der Batteriezustände aller HomeMatic Geräte in FHEM (Annahme: Alle gehören zum Raum "Homematic"):
<pre>
attr d_ccu ccuaggregate name:battery,filter:room=Homematic,read:(LOWBAT|LOW_BAT),if:any=yes,else:no,prefix=battery_,coll:alias
</pre>
Diese Aggregationsregel könnte folgende Readings im I/O Device generieren (Annahme: Batterien von 2 Fenstersensoren leer):
<pre>
battery_count: 50
battery_list: Fenster Bad,Fenster Wohnzimmer
battery_match: 2
battery_state: yes
</pre>

===Ausführen von HomeMatic Scripts===
Mit dem Befehl '''set hmscript''' kann ein beliebiges HomeMatic Script an die CCU2 zur Ausführung gesendet werden. Wenn das Script zeilenweise Daten im Format "Parameter=Value" zurück gibt, werden diese als Readings mit dem Namen ''Parameter" im I/O Device gespeichert.''

Beispiel: Das folgende HomeMatic Script wertet alle CCU2 Systemvariablen aus. Das Ergebnis wird als Readings gespeichert (äquivalent zu Befehl '''get vars'''):
<pre>
object osysvar;
string ssysvarid;
foreach (ssysvarid, dom.GetObject(ID_SYSTEM_VARIABLES).EnumUsedIDs())
{
osysvar = dom.GetObject(ssysvarid);
WriteLine (osysvar.Name() # "=" # osysvar.Value());
}
</pre>

Wenn das Script auf dem FHEM-Server unter /opt/fhem/sysvars.scr gespeichert wird, kann es wie folgt ausgeführt werden:

<pre>set d_ccu hmscript /opt/fhem/sysvars.scr</pre>

[[Kategorie:HomeMatic Components]]
[[Kategorie:Interfaces]]

DOIF/Tools und Fehlersuche

2023-08-09T06:20:58Z

DR: nur ein Überschrift in der Zeile, sonst wird er nicht als solcher erkannt

[[Kategorie:Hilfsmodul]]
'''Anmerkung:''' Dieser Artikel wurde {{Link2Forum|Topic=58237|Message=496560|LinkText=aus dem Forum}} übernommen.

Dies ist der Versuch einige Hilfen aufzuzeigen, damit ein fehlerhaftes DOIF selbst korrigiert werden kann und wenn dies nicht zum Ziel führt, notwendige Angaben für eine Anfrage im Forum zusammenzustellen.

== Eine verlässliche Basis zur Fehlereingrenzung schaffen. ==
=== Standardisierte Geräteerstellung und Bearbeitung ===
Im Folgenden wird davon ausgegangen, dass zum Erstellen des DOIF und zur Befehlseingabe die Eingabezeile des Web-Frontends benutzt wird und mit dem DEF-Editor (auf DEF klicken) in der sich öffnenden Geräteübersicht (DeviceOverview) bearbeitet wird, ohne eine cfg-Datei zu editieren.

Nutzung des integrierten DEF-Editors mit Codemirror-Erweiterung, [[Konfiguration#Syntaxhervorhebung | Codemirror einrichten und bedienen]], siehe ergänzend [[DOIF/Tipps zur leichteren Bedienung | DOIF: Tips leichtere Bedienung Syntaxhervorhebung Klammerprüfung Suchen&Ersetzen ]]

=== Strukturierung der Definition ===
Eine einzeilige Definition, die über mehrere Seiten verschoben werden muss oder über mehrere Zeilen umgebrochen wird ist unübersichtlich. Der DEF-Editor bietet die Möglichkeit zur Strukturierung der Definition.
<pre>
## 1
(<Bedingung>)
(<Befehle>)
## 2
DOELSEIF (<Bedingung>)
(<Befehle>)
## 3
DOELSEIF (<Bedingung>)
(<Befehle>)
...
</pre>

=== FHEM aktuell halten ===
{{Randnotiz|RNTyp=y|RNText=Die aktuelle FHEM-Software ist ein "nightly build", es gibt keine ausgewiesene "stable version".

Um Überraschungen zu vermeiden, sollte vor einem Update im Forum nach Fehlerhinweisen zu den genutzten Modulen recherchiert werden.

Die Änderungshinweise sollten beachtet werden, da die Änderungshinweise nicht verpflichtend sind, sollten auch die Hinweise in den {{Link2Forum|Topic=57|LinkText=FHEM Code changes}} gelesen werden.

Nach einem Update sollte immer das Logfile nach neuen Fehler- u. Warnmeldungen untersucht werden.

Eine Automatisierung des Updatevorgangs oder Teile davon ist -gerade auch für Einsteiger- nicht unbedingt empfohlen. Sie sollte nur unter genauer Kenntnis möglicher Folgen eingesetzt werden und geschieht immer auf eigene Gefahr.}}
Die [http://fhem.de/commandref_DE.html#DOIF Befehlsreferenz] im Netz beschreibt die Eigenschaften des aktuellen Moduls. Möchte man die neusten Eigenschaften nutzen, ist eine Aktualisierung durchzuführen. Wird nur das Modul aktualisiert, kann das zu unerwartetem Verhalten des DOIF führen.

Prüfen ob ein Update für DOIF vorliegt mit
<pre>
update check
</pre>

FHEM aktualisieren mit
<pre>
update
</pre>

Nach einem "update" immer ein
<pre>
shutdown restart
</pre>
durchführen.

==== Neustart nach Update automatisieren ====
{{Randnotiz|RNTyp=y|RNText=Durch diese Automatik kann unter anderem die Anzeige der Änderungs-Informationen (CHANGED) zum Update, durch ein Neuladen der Browserseite, sofort wieder ausgeblendet werden, so dass die Änderungs-Informationen im Logfile oder svn/Forum gelesen werden müssen.}}
"shutdown restart" kann man per notify automatisieren mit
<pre>
define shutdown_restart notify global:UPDATE save;shutdown restart
</pre>

==== Modulversionen anzeigen ====
Der Befehl
<pre>
version
</pre>
liefert die "Latest Revision:" und die aktuell geladenen Modulversionen.

== Fehlersuche ==
'''[[DOIFtools]]''' enthält einen Check für DOIF, der einige Dinge erkennt und Hinweise gibt, siehe [[DOIFtools#DOIF_Pr.C3.BCfung_und_Empfehlungen|DOIF_Prüfung_und_Empfehlungen]].

=== Fehler in der Syntax der Definition ===
Diese Fehler werden durch die Benutzung des DEF-Editors mit Codemirror-Erweiterung reduziert.

Der Editor unterstützt:
* farbliche Hervorhebung bekannter Befehle
* Vervollständigung bekannter Begriffe
* eine Prüfung auf unvollständige Klammerpaare
* ggf. Fehlermeldung beim Erstellen einer Definition
* Suchen&Ersetzen
*uvm.

Einige Syntaxfehler werden im Frontend bei der Erstellung des Gerätes oder im globalen Logfile angezeigt. Das globale Logfile ist über den Menüpunkt "Logfile" im Hauptmenü des Frontends zu erreichen.
Fehler oder Warnungen, die erst zur Laufzeit offensichtlich werden, stehen in der Geräteübersicht oder im globalen Logfile.

=== Logische Fehler ===
Diese Fehler werden erst zur Laufzeit sichtbar und das DOIF verhält sich nicht wie erwartet.

Die Fehler entstehen z.B. durch:

* Angabe einer falsche Rangfolge von Operatoren in der Bedingung:
<pre>
[A] and [B] or [C]
</pre>
geschrieben, aber
<pre>
[A] and ([B] or [C])
</pre>
gemeint.
* Nichtbeachtung des unterschiedlichen Verhalten von triggernden und nicht triggernden [[DOIF/Einsteigerleitfaden,_Grundfunktionen_und_Erläuterungen#Ausl.C3.B6ser|Auslöserangaben]].
* Ein unerwartetes Auslösen von DOELSE.
* Unerwartete Ereignisse eines Gerätes, die in einer Bedingung nicht abgefangen werden.
* Falsche Angabe der Events eines beteiligten Gerätes.
* Es wird DOELSE mit einer Bedingung angegeben.

===Besonderheit des Error-Reading===
Das Reading "error" enthält Fehlermeldungen oder Rückgabewerte von Befehlen, die nicht 0, "", undef. also logisch "falsch" entsprechen.
Die Ausführung des Befehls
<pre>({my $var = 1})</pre>
setzt das Error-Reading
<pre>error {my $var =1 }: 1</pre>
Diese falsche Fehlermeldung kann vermieden werden, durch Erzeugen eines Rückgabewertes, der logisch "falsch" entspricht.
<pre>({my $var = 1;; 0})</pre>
Die mit ";; 0" angehängte Null verhindert das Setzen des Error-Readings.

===Adressierung von Arrayelementen===
Die Adressierung von Arrayelementen <code>$myArray[4]</code> kann zu Fehlverhalten führen, weil die eckigen Klammern als DOIF-Syntax interpretiert werden. Das gilt nicht für den Block ''subs'' im Perl-Mode. Altervativ könnte z.B. ein numerierter Hash verwendet werden <code>$myArrayAsHash{4}</code>.

=== Fehler eingrenzen ===
Wenn ein Hinweis in der Fehlermeldung nicht ausreicht, um den Fehler zu beseitigen, empfiehlt es sich die Definition des DOIF Schritt für Schritt neu aufzubauen und die Fehlermeldung zu beobachten, um den Fehlerort einzugrenzen. Der letzte Schritt, der zur Fehlermeldung geführt hat, muss dann genauer untersucht werden. Auch wenn es keine Fehlermeldungen gibt, aber das DOIF sich nicht so verhält wie man es erwartet, kann es hilfreich sein die Bedingung Schritt für Schritt aufzubauen, bis sich ein unerwartetes Verhalten zeigt. Die letzte Änderung müsste dann im im Kontext der restlichen Bedingung genauer analysiert werden.

=== DOIF zum Testen ===
Eine weitere Möglichkeit wäre ein DOIF zum Testen anzulegen. Darin können Befehle, Bedingungen oder Bedingungsteile, verschiedene Schreibweisen oder alternative Operanden verwendet und ausprobiert werden, bis der eine Lösung gefunden wurde.

=== Befehlsteil testen ===
Die Ausführung der Befehle in den einzelnen Befehlszweigen lässt sich über den Set-Befehl anstossen.
set <DOIFname> cmd_<Nr des Befehlszweiges>
Wenn [[DOIFtools]] genutzt wird, dann sollten entsprechende Logeinträge im [[DOIFtools#Erstellen_eines_Debug-Logfile|DOIFtoolsLog]] zu finden sein.

===Bedingungen testen mit dem Befehl [[Trigger|trigger]]===
Manche [[Event|Events]] lassen auf sich warten, um die Bedingung vorher zu testen kann der Befehl [[Trigger|trigger]] verwendet werden.
trigger <[[Gerätename]]> &lang;<Readingname>: &rang;<Wert>
Das funktioniert dort, wo die [http://fhem.de/commandref_DE.html#DOIF_Ereignissteuerung_ueber_Auswertung_von_Events Auslösung über Events] in der Bedingung genutzt wird.

=== Bedingungen testen mit dem Befehl setreading ===
Manche [[Readings]] Aktualisierungen lassen auf sich warten, um die Bedingung vorher zu testen kann der Befehl setreading verwendet werden.
setreading <[[Gerätename]]> <Readingname> <Wert>
Siehe auch {{Link2CmdRef|Anker=setreading|Lang=de}}.

=== Operatoren loggen, die keine Bedingungsprüfung auslösen (triggern) ===
Operatoren, die keine Bedingungsprüfung auslösen, werden im Listing des DOIF nicht angezeigt.
Sie können geloggt werden, durch die Angabe eines Log-Befehls in der Bedingung.
==== Allgemein ====
(<Bedingung>; Log <verbose level>, <content to log>)
==== Vorschlag ====
(<Bedingung>; Log 1, "$SELF:"."\n<name1>:<reading1> ".ReadingsVal("<name1>","<reading1>","<default1>")."\n<name2>:<reading2> ".ReadingsVal("<name2>","<reading2>","<default2>")...)
Siehe auch: {{Link2Forum|Topic=99365|Message=927748|LinkText=alternativer Vorschlag}} oder [[DevelopmentModuleAPI#Log|Log-Befehl]]

== Hilfsmittel zu Fehleranalyse ==
=== Befehlsreferenz ===
Die [http://fhem.de/commandref_DE.html#DOIF Befehlsreferenz zum DOIF] immer wieder problembezogen lesen.

=== Stacktrace ===
Zur Ursachenermittlung von Perl-Warnungen kann das globale Attribut stacktrace auf 1 gesetzt werden.
<pre>
attr global stacktrace 1
</pre>

=== Verboselevel ===
In manchen Fällen bekommt man hilfreiche Informationen, wenn der Verboselevel von betroffenen Geräten erhöht wird.
<pre>
attr <gerätename> verbose 5
</pre>

=== Event-Monitor ===
Der [[Event_monitor|Event-Monitor]] ist über den Menüpunkt "Event monitor" im Hauptmenü des Frontends zu erreichen. Er enthält einen Filter, um die Anzeige der Events zu beschränken, um z.B. nur die [[Event|Events]] eines Gerätes anzuzeigen, etwa des DOIF.

Wenn '''[[DOIFtools]]''' installiert ist. kann der [[Event_monitor|Event-Monitor]] in der Detailansicht des [[DOIF]] angezeigt werden, siehe [[DOIFtools#Zugriff_auf_den_Event-Monitor_in_der_Detailansicht_des_DOIF|Zugriff_auf_den_Event-Monitor_in_der_Detailansicht_des_DOIF]].

Der [[Event_monitor|Event-Monitor]] kann über den [[Readings]] positioniert werden, so können [[Event|Events]] und resultierende Readings-Änderungen gleichzeitig beobachtet werden, siehe [[DOIFtools#Event-Monitor_im_DOIF_direkt_vor_den_Readings_anzeigen|Event-Monitor_im_DOIF_direkt_vor_den_Readings_anzeigen]].

=== Detailansicht des DOIF ===
Das Schaltverhalten des DOIF kann in der Detailansicht (DeviceOverview) des DOIF und/oder im Eventmonitor beobachtet werden.

Bei der Detailansicht ist zu beachten, dass nicht alle sich ändernden Readings aktualisiert werden. Um diese geänderten Readings anzuzeigen, muss die Ansicht im Browser aktualisiert werden.

=== Gerätedefinition ausgeben ===
Eine Gerätedefinition einschliesslich der Attribute kann man sich mit dem Befehl "exportdevice" anzeigen lassen.
<pre>
exportdevice <DOIFname>
</pre>

=== Listing des DOIF ===
Eine Momentaufnahme vom Status des DOIF im Fehlerfall kann man sich mit dem Befehl '''[[List|list]]''' anzeigen lassen oder zum Posten verwenden.
<pre>
list <DOIFname>
</pre>

=== Verhaltensanalyse des DOIF ===
Mit '''[[DOIFtools]]''' kann automatisiert ein detailiertes Logfile erstellt werden, siehe '''[[DOIFtools#Erstellen_eines_Debug-Logfile|DOIFtoolsLog]]'''.

In dem '''DOIFtoolsLog''' kann das Verhalten des DOIF und der dazugehörenden Operanden genau nachvollzogen werden, da auch ein '''[[List|Listing]]''' eingeschlossen werden kann, siehe [[DOIFtools#Listings_in_DOIFtoolsLog_einschliessen|Listings in DOIFtoolsLog einschliessen]].

Wenn Abweichungen zum erwarteten Verhalten erkannt werden, hat man einen Anhaltspunkt für weitere Untersuchungen oder sogar den Auslöser gefunden.

Alternativ kann ein Logfile manuell erstellt werden. Dazu können alle Geräte einbezogen werden, die im DOIF enthalten sind; z.B. als tägliches Logfile.
<pre>
define DOIF_Log FileLog ./log/DOIF_Log-%j.log <DOIFname>:.*|<Gerät 1>:.*|<Gerät 2>:.* ...
</pre>

Mit dem Attribut mseclog lässt sich ein genauerer Zeitstempel einstellen, damit können zusammengehörende Events erkannt werden.
<pre>
attr DOIF_Log mseclog 1
</pre>

=== Bedingungen und Befehle zum aktuellen Zeitpunkt auszuwerten (Dump von DOIF) ===
Mit der Perl-Funktion <syntaxhighlight lang="perl" inline>dumpDevice($devspec)</syntaxhighlight> für die 99_myUtils.pm, kann der Zustand eines oder mehrerer DOIF geloggt werden. Es werden Operanden und Funktionen aufgelöst und deren Inhalte angezeigt. Die genaue Syntax einer Device-Spezifikation ($devspec) ist in der {{Link2CmdRef|Anker=devspec}} erläutert.

Die Funktion kann im Log-Befehl verwendet werden und im Bedingungs- und Ausführungsteil genutzt werden.

<syntaxhighlight lang="perl">(<Bedingungen> ;Log 1, dumpDevice("$SELF"))</syntaxhighlight>
oder
<syntaxhighlight lang="perl">(<Befehle>,{Log 1, dumpDevice("$SELF")})</syntaxhighlight>

Die Funktion wird im Forum bereitgestellt: {{Link2Forum|Topic=85493|LinkText=Debug DOIF via Device Dump}}

== Qualifizierte Angaben zur Anfrage im Forum ==
Dem Helfenden sollten alle zum Problem gehörenden Informationen gegeben werden, die dem Fragenden auch zur Verfügung stehen.

Nicht immer sind alle Angaben notwendig, bei komplexen Problemen schon eher.
* Hinweis, wenn FHEM und DOIF nicht aktuell sind.
* Hinweis, wenn die cfg-Dateien direkt bearbeitet werden.
* genaue Beschreibung des erwarteten Verhalten
* genaue Beschreibung des beobachteten Verhalten
* Alle relevanten Fehlermeldungen
* Darstellen, was man selbst schon versucht hat und mit welchem Ergebnis, dann wird es nicht noch einmal vorgeschlagen.
* Ein für andere ausführbares [[DOIF/Einsteigerleitfaden,_Grundfunktionen_und_Erläuterungen#Beispiel_A.29:_Ereignissteuerung|'''Testszenario''']] für [[Import_von_Code_Snippets|Raw definition]], mit Dummys als Ersatz für Sensoren, Schalter, Aktoren usw.
* Angabe der vollständigen Definition des DOIF (Name, Definition, Attribute) in Code-Tags (das Raute-Zeichen # im Forum-Editor)
* Zusätzlich ein vollständiges '''[[List|Listing]]''' des DOIF
* Die relevanten Stellen aus dem aufgezeichneten [[FileLog]] ,vorzugsweise '''[[DOIFtools#Erstellen_eines_Debug-Logfile|DOIFtoolsLog]]''' mit Kommentar und Markierung der Probleme in Quote-Tags (das Zeichen rechts neben der Raute). In Quote-Tags kann die Zeichenformatierung zum Markieren genutzt werden, in Code-Tags nicht.
* Auszug aus dem [[Event_monitor|Event-Monitor]] mit Kommentar und Markierung der Probleme

==Links==
* [[DOIF]]
* [[DOIFtools]]

[[Kategorie:HOWTOS]]

HMCCU

2020-12-15T20:32:13Z

DR: /* Installation */

Das Modul HMCCU ermöglicht zusammen mit weiteren Modulen eine Integration der [[HomeMatic]] CCU Zentrale sowie der dort angelernten Geräte in FHEM. {{Infobox Modul
|ModPurpose=Anbindung HomeMatic CCU an FHEM
|ModType=d
|ModCmdRef=HMCCU
|ModForumArea=HomeMatic
|ModTechName=88_HMCCU.pm
|ModOwner=zap ({{Link2FU|10980|Forum}} / [[Benutzer Diskussion:Zap|Wiki]])
}}
==Einführung==
===Übersicht===
Das Modul [[HMCCU]] ermöglicht zusammen mit den Client Modulen → [[HMCCUDEV]], HMCCUCHN und HMCCUPROCRPC eine Integration der [[HomeMatic]] CCU Zentrale sowie der dort angelernten Geräte in FHEM. Im Einzelnen werden folgende Funktionen unterstützt:

* Unterstützt Hard- und Software CCUs inkl. CCU3, YAHM, piVCCU und RaspberryMatic
* Unterstützung der Protokolle BidCos, Wired und [[HomeMatic IP|HM-IP]]
* Unterstützung von CUxD, OSRAM und Philips Hue Devices in der CCU
* Unterstützung von HVL (HomeMatic Virtual Layer)
* Unterstützung von CCU Gerätegruppen bzw. virtuellen Geräten (Heizung, Rauchmelder)
* Automatische Aktualisierung von Gerätezuständen in FHEM per RPC-Server
* Automatische Konvertierung und Skalierung von Werten beim Lesen und Schreiben
* Lesen und Schreiben von CCU Systemvariablen
* Ausführen von CCU Programmen
* Ausführen von HomeMatic Scripts auf der CCU

Die einzelnen Module haben folgende Aufgaben:

* HMCCU: Kommunikation zwischen FHEM und CCU (I/O Device)
* HMCCURPCPROC: RPC-Server zum Empfang von Events der CCU
* HMCCUDEV: Definition von FHEM Devices für HomeMatic Geräte
* HMCCUCHN: Definition von FHEM Devices für einzelne Kanäle von HomeMatic Geräten
* HMCCUConf: Templates mit Default Attributen für bestimmte HomeMatic Gerätetypen

===Geräte, Kanäle und Datenpunkte===
Geräte in der HomeMatic CCU bestehen aus einem oder mehreren Kanälen. Ein Kanal wiederum hat einen oder mehrere Datenpunkte. Über diese Datenpunkte kann ein Gerät gesteuert oder Statusinformationen ausgelesen werden. Sofern ein Datenpunkt lesbar ist, kann er als Reading in einem HMCCUCHN oder HMCCUDEV Device dargestellt werden. Ausgehend von dieser Abbildung in der CCU kann man nun entscheiden, ob man ein CCU Gerät mit HMCCUCHN oder HMCCUDEV definiert.

Wenn alle benötigten Datenpunkte eines Gerätes über einen Kanal angesprochen werden können, sollte HMCCUCHN verwendet werden. Mit HMCCUDEV werden alle Kanäle eines Gerätes eingebunden. Außerdem unterstützt HMCCUDEV Rauchmeldergruppen sowie virtuelle Geräte wie z.B. Heizungsgruppen.

Ein Sonderfall ist der Statuskanal 0, der von allen HomeMatic Geräten bereitgestellt wird. Dieser Kanal ist inklusive seiner Datenpunkte sowohl in HMCCUCHN als auch in HMCCUDEV Devices verfügbar.
{{Hinweis|Im Artikel → [[HMCCU Best Practice]] gibt es einige Tipps für den Einstieg inklusive Schritt-für-Schritt Anleitungen.}}

==Inbetriebnahme==
===Zu beachten===

* In den CCU Gerätenamen dürfen keine Umlaute verwendet werden. Leerzeichen sind zulässig, können aber u.U. bei einigen Funktionen zu Problemen führen.
* Namen in der CCU müssen über alle Objekttypen hinweg eindeutig sein. Beispiel: Ein Gerät und ein Raum dürfen nicht den gleichen Namen haben.
* Nach dem Neustart der CCU muss auch der RPC-Server neu gestartet werden, da die CCU2 bei einem Neustart die registrierten RPC-Server "vergisst".
* Vor der Ausführung eines FHEM Updates oder vor der Installation eines CCU Firmware Updates muss der RPC-Server gestoppt werden.
* Seit der CCU Firmware 2.27.7 sind die Zugriffsmöglichkeiten auf die CCU durch eine Firewall abgesichert. Der Zugriff durch FHEM muss explizit freigeschaltet werden, da HMCCU sonst nicht korrekt funktioniert (s. nächster Abschnitt).

===CCU Firewall Einstellungen===
Ab CCU Firmware 2.27.7 sind auf der CCU über das WebGUI folgende Einstellungen vorzunehmen:
* Menü "Einstellungen > Systemsteuerung" aufrufen
* Button "Firewall konfigurieren" anklicken
* Bei "Firewall-Richtlinie" den Eintrag "Ports offen" auswählen, andernfalls müssen die notwendigen Ports im Feld "Port-Freigabe" explizit angegeben werden
* Die Rechte für "HomeMatic XML-RPC API" und "Remote HomeMatic-Script API" auf "Vollzugriff" setzen.
* Man kann die Rechte auf "Eingeschränkter Zugriff" belassen, muss dann aber im Feld "IP-Adressen für eingeschränkten Zugriff" die IP des FHEM-Servers oder das komplette Subnetz in Subnet-Notation angeben.

Zusätzlich muss in der Systemsteuerung unter "Sicherheit" die Option "Authentifizierung" deaktiviert werden, da HMCCU den Zugriff per Username/Password noch nicht unterstützt.

===Installation===
Alle HMCCU Module sind Teil von FHEM. HMCCU benötigt die Perl Module RPC::XML::Server und RPC::XML::Client.

Unter debian/raspbian kann das Paket librpc-xml-perl installiert werden
<pre>sudo apt-get update && sudo apt-get install -y librpc-xml-perl</pre>

Unter Windows (Strawberry Perl) kann man das Paket RPC::XML mit cpan installieren
<syntaxhighlight lang="doscon">
cpan install RPC::XML
</syntaxhighlight >
Bei der Installation gemäß [[FHEM Installation Windows]] befindet sich cpan man unter <code><FHEM-Hauptverzeichis>\perl\bin</code>

Der interne RPC-Server legt für den Datenaustausch zwischen CCU2 und FHEM Dateien im Verzeichnis /tmp an. Der fhem Prozess benötigt daher Schreibrechte für dieses Verzeichnis. Das Verzeichnis kann mit dem Attribut ''rpcqueue'' geändert werden. Der mit dem Modul HMCCURPCPROC bereitgestellte externe RPC-Server verwendet keine temporären Dateien. Der interne RPC-Server wird ab Version 4.4 nicht mehr unterstützt.

===Definition I/O Device===
Im ersten Schritt wird ein I/O Device angelegt, das für die Kommunikation zwischen FHEM und der CCU verantwortlich ist. Im folgenden Beispiel wird davon ausgegangen, dass die CCU unter der IP-Adresse 192.168.1.10 erreichbar ist. Das FHEM Device bekommt den Namen „d_ccu“.
<pre>define d_ccu HMCCU 192.168.1.10</pre>
Falls die CCU als Software Service auf dem gleichen Rechner läuft wie FHEM, sollte bei der Definition der Parameter ''ccudelay'' angegeben werden. Die CCU Services brauchen beim Starten länger als FHEM. Durch ''ccudelay'' wird das neu angelegte I/O Device verzögert um die angegebene Anzahl Sekunden initialisiert. Die Vorgabe sind 180 Sekunden. Je nach Installation kann auch ein höherer Wert notwendig sein:
<pre>define d_ccu HMCCU 192.168.1.10 ccudelay=180</pre>
Der Start von FHEM wird dadurch nicht verzögert. Die verzögerte Initialisierung kann mit dem Parameter ''delayedinit'' erzwungen werden, greift dann also auch, wenn die CCU beim Start von FHEM erreichbar ist

===RPC Server konfigurieren===
Im nächsten Schritt wird der RPC-Server konfiguriert und gestartet. Zunächst werden mit dem Attribut ''rpcinterfaces'' die Schnittstellen bzw. Ports festgelegt, für die sich der RPC-Server bei der CCU registrieren soll. Folgende Angaben sind möglich:
* BidCos-RF
* BidCos-Wired
* HmIP-RF
* CUxD
* Homegear
* HVL
* VirtualDevices
'''Wichtig'''! Die CCU stellt außer BidCos-RF nur die Schnittstellen bereit, für die auch Geräte vorhanden sind. Nicht verwendete Schnittstellen dürfen bei ''rpcinterfaces'' nicht angegeben werden, da sonst der RPC-Server nicht startet. Im Internal "ccuinterfaces" werden nach der Definition des I/O Device alle verfügbaren Schnittstellen angezeigt.

Danach wird durch Setzen des Attributs ''ccuflags'' auf den Wert procrpc der externe RPC-Server aktiviert. Die Verwendung des internen RPC-Servers ist zwar noch möglich, wird jedoch nicht mehr offiziell unterstützt.

'''Externer RPC-Server (HMCCURPCPROC)'''
Beim ersten Start dieses RPC-Servers über das I/O Device wird automatisch je Schnittstelle ein Device vom Typ HMCCURPCPROC angelegt. Die Attribute room und group werden vom I/O Device übernommen.

'''RPC-Server starten'''
Nun kann der RPC-Server gestartet werden. Dabei wird je RPC-Schnittstelle ein separater fhem.pl Prozess mit eigenem Listening-Port gestartet. Beim ersten Start legt HMCCU für jede unter ''rpcinterfaces'' angegebene Schnittstelle ein Device vom Typ HMCCURPCPROC an. Bei aktivierter Firewall müssen die Ports (s. Attribut ''rpcserverport'') geöffnet werden.

Alle RPC-Server werden über das I/O Device mit einem Befehl gestartet:
<pre>set d_ccu rpcserver on</pre>
Während des Starts der RPC-Server und der Registrierung bei der CCU kann das I/O Device nur eingeschränkt verwendet werden. Dies wird durch den Status „starting/busy“ angezeigt. Nachdem die RPC-Server gestartet wurden, wechselt der Status zu „running/OK“. Zusätzlich werden im Internal RPCPID die Prozess-IDs der RPC-Server Prozesse gespeichert.
Anschließend sollte man noch das Attribut ''rpcserver'' auf „on“ setzen, damit die RPC-Server beim Start von FHEM automatisch gestartet werden:
<pre>attr d_ccu rpcserver on</pre>

===Vorgaben für Client Devices===
Im I/O Device stehen einige Attribute zur Verfügung, über die Vorgaben für Attribute in Client-Devices eingestellt werden können:
{| class="wikitable"
|-
! Attribut in HMCCU !! Vorgabe für Attribut in HMCCUDEV/HMCCUCHN !! Default !! Bedeutung
|-
| ccudef-hmstatevals || hmstatevals || '^UNREACH!(1 |true):unreachable;^LOW_?BAT!(1|true):warn_battery' || Legt fest, wie der HomeMatic Status eines Client-Device ermittelt wird.
|-
| ccudef-readingfilter || ccureadingfilter || .* || Legt fest, welche Datenpunkte eines CCU Gerätes als Readings gespeichert werden
|-
| ccudef-readingname || ccureadingname || Kein Default || Ändert den Namen von Readings und/oder ergänzt neue Readings
|-
| ccudef-substitute || substitute || Kein Default || Ersetzt Datenpunktwerte vor der Speicherung in Readings.
|}
Der Inhalt der HMCCU Attribute wird an die Attribute im Client-Device angehängt. In der Datei HMCCUConf.pm ist ein Default-Template für ein HMCCU Device definiert, das über den Befehl '''set defaults''' für das I/O Device angewendet werden kann. Dabei werden die Attribute ''ccudef-*'' auf Werte gesetzt, die Readings und Werte analog zu CUL_HM erzeugen.

Wichtig! Bei der Ausführung von '''set defaults''' für das I/O Device wird der Reading-Filter auf den Wert "^(LOW_?BAT|UNREACH)$" gesetzt. Dies hat zur Folge, dass in den Client-Devices nur diese beiden Datenpunkte als Readings gespeichert werden. Daher muss für jedes Client-Device über das lokale Attribut ''ccureadingfilter'' eine Liste der zusätzlich benötigten Datenpunkte definiert werden.

==Synchronisation mit der CCU==
Das Modul HMCCU bietet Befehle an, um Daten zwischen der CCU und FHEM zu synchronisieren. Der Befehl '''get devicelist''' liest alle Geräte aus der CCU. Er sollte immer ausgeführt werden, wenn sich an einer Gerätedefinition in der CCU etwas geändert hat, z.B. Gerät oder Kanal wurde umbenannt, neues Gerät wurde angelernt, Gerät wurde gelöscht. Bei der Definition des I/O Device wird der Befehl automatisch ausgeführt.

Der Befehl '''get update''' liest die Datenpunkte aller in FHEM definierten HMCCUDEV und HMCCUCHN Devices aus der CCU und aktualisiert alle Readings aller Client Devices.

==Autocreate von Client Devices==
HMCCU bietet eine Möglichkeit, um automatisch Client Devices in FHEM für Geräte oder Kanäle in der CCU anzulegen. Dazu wird der Befehl '''get devicelist''' mit folgender Syntax aufgerufen:
<pre>get <io-dev> devicelist create <dev-expr> [Options ...] [<attr>=<value [...]]</pre>
Der Parameter ''dev-expr'' spezifiziert per regulärem Ausdruck, für welche CCU Geräte oder Kanäle ein Device in FHEM angelegt werden soll. Es ist davon abzuraten, an dieser Stelle ".*" zu verwenden, da so sehr viele (meist unnütze) FHEM Devices angelegt werden.
Folgende ''Options'' sind möglich:
*t={chn|dev|all} - Es werden nur Kanäle (chn) oder Geräte (dev) berücksichtigt (ab 3.6).
*p=<prefix> - Der Text ''prefix'' wird den Namen der neuen FHEM Devices vorangestellt.
*s=<suffix> - Der Text ''suffix'' wird an die Namen der neuen FHEM Devices angehängt.
*f=<format> - Mit ''format'' kann ein Template für die FHEM Devicenamen festgelegt werden. In einem Template können folgende Platzhalter verwendet werden: %n = CCU Geräte- oder Kanalname, %d = CCU Gerätename, %a = CCU Geräte- oder Kanaladresse.
*defattr - Sorgt dafür, dass für die neu definierten FHEM Devices einige Defaultattribute gesetzt werden, sofern für den jeweiligen Gerätetyp vorhanden.
*duplicates - Erlaubt das Anlegen von doppelten Devices. Wenn diese Option fehlt, werden in FHEM vorhandene Geräte nicht neu angelegt.
*save - Nach dem Anlegen der Geräte wird die neue FHEM Konfiguration gespeichert.
An den Befehl kann eine Liste von Attributen angehängt werden, die den neuen FHEM-Devices zugewiesen werden sollen.

Beispiel 1: In FHEM Devices für alle CCU Geräte anlegen, deren Namen mit "HM-KL" beginnt. Alle neuen FHEM Devices beginnen mit "HM_". Sofern vorhanden werden Default Attribute gesetzt. Die Konfiguration wird gespeichert.
<pre>get d_ccu devicelist create ^HM-KL.* t=dev f=HM_%n defattr save room=Homematic</pre>

Beispiel 2: In FHEM Devices für alle CCU Geräte anlegen, deren Namen mit "HM" oder "Hm" (HmIP-Geräte) beginnt. Alle neuen FHEM Devices haben den Namen wie in der CCU und können dann mit dem Attribut "alias" verständlicher benannt werden. Sofern vorhanden, werden default Attribute gesetzt. Die Konfiguration wird gespeichert. Der Room "CCU_HM" ist angelehnt an "CUL_HM".
<pre>get d_ccu devicelist create ^H[M|m].* t=dev f=%n defattr save room=CCU_HM</pre>

==Verwaltung von Default Attributen==
HMCCU bietet für FHEM Devices vom Typ HMCCUCHN und HMCCUDEV bei bestimmten HomeMatic Gerätetypen Default Attribute an. Diese können in den Client Devices mit dem Befehl '''set defaults''' definiert werden. Der Befehl '''get defaults''' zeigt die für einen Gerätetyp vorhandenen Attribute an. HMCCU bietet jedem Benutzer die Möglichkeit, zusätzlich zu den in der Datei HMCCUConf.pm mitgelieferten Attributen eigene Vorlagendateien mit Default Attributen zu definieren.

===Anzeigen der Gerätetypen mit Default Attributen===
Mit dem Befehl '''get defaults''' im I/O Device werden alle HomeMatic Gerätetypen angezeigt, für die Default Attribute vorhanden sind. Dabei werden auch benutzerdefinierte Attribute berücksichtigt.

===Default Attribute exportieren und importieren===
Der Befehl '''get exportdefaults''' schreibt die mitgelieferten Default Attribute aus HMCCUConf.pm in eine Vorlagendatei. Diese Datei kann der Benutzer nach seinen Bedürfnissen anpassen und anschließend mit dem Befehl '''set importdefaults''' in FHEM importieren. Das Anlegen von eigenen Default Attributen könnte so aussehen:
<pre>
get d_ccu exportdefaults /opt/fhem/hmccu_defattr.txt

... Datei /opt/fhem/hmccu_defattr.txt editieren ...

set d_ccu importdefaults /opt/fhem/hmccu_defattr.txt
</pre>
Beim Ausführen des Befehls '''set defaults''' in einem Client Device haben die benutzerdefinierten Attribute Priorität.

===Benutzerdefinierte Attribute löschen===
Mit dem Befehl '''set cleardefaults''' werden alle mit '''set importdefaults''' importierten Default Attribute gelöscht. Danach sind wieder nur die in HMCCUConf.pm enthaltenen Default Attribute verfügbar.

==Weitere Funktionen des Moduls HMCCU==
===Lesen und Ändern von CCU Systemvariablen===
Systemvariablen der CCU können mit den Befehlen '''get vars''' und '''set var''' gelesen und geändert werden. Der Befehl '''get vars''' akzeptiert als Parameter einen regulären Ausdruck. Dadurch können mehrere Systemvariablen auf einmal gelesen werden. Nach dem Auslesen einer Systemvariable wird der Wert in einem Reading im I/O Device gespeichert.

Beispiel: Lesen aller Systemvariablen, die mit A beginnen:
<pre>get d_ccu vars A.*</pre>

Systemvariablen können in regelmäßigen Abständen gelesen werden. Dazu wird mit dem Attribut ccuGetVars ein Intervall und optional ein regulärer Ausdruck für die zu lesenden Systemvariablen festgelegt.

Beispiel: Lesen aller Systemvariablen alle 60 Sekunden. Im zweiten Befehl werden nur Variablen gelesen, die mit "A" beginnen:
<pre>attr d_ccu ccuGetVars 60
attr d_ccu ccuGetVars 60 ^A</pre>

Wenn eine Systemvariable bereits in der CCU existiert, kann ihr Wert mit dem Befehl '''set var''' geändert werden.

Beispiel: Setzen der Systemvariablen „Temperatur“ auf den Wert 20.5:
<pre>set d_ccu var Temperatur 20.5</pre>

Mit dem Befehl '''set var''' kann auch eine neue Systemvariable in der CCU angelegt werden. Dazu wird als erster Parameter vor dem Variablennamen der Typ der neuen Variable angegeben. Mögliche Typen sind "bool", "list", "number" oder "text".

Beispiel: Anlegen einer Textvariablen mit dem Namen "Wetter":
<pre>set d_ccu var text Wetter sonnig</pre>

Optional können noch Attribute für eine neue Systemvariable gesetzt werden. Folgende Attribute sind erlaubt:

* unit = Einheit
* desc = Beschreibung
* min = Kleinster erlaubter Wert bei numerischen Variablen
* max = Größter erlaubter Wert bei numerischen Variablen
* list = Durch Komma getrennte Liste mit zulässigen Werten bei Listen-Variablen
* valtrue = Angezeigter Wert bei Variablen vom Typ bool, Default = "ist wahr"
* valfalse = Angezeigter Wert bei Variablen vom Typ bool, Default = "ist falsch"

Beispiel: Anlegen einer numerischen Variablen für Temperaturwerte:
<pre>set d_ccu var number Temperatur 20.5 unit=Grad desc=Aussentemperatur min=-10.0 max=40.0</pre>

===Ausführen von CCU Programmen===
Ein in der CCU2 hinterlegtes Programm kann mit dem Befehl '''set execute''' ausgeführt werden. Einziger Parameter des Befehls ist der Name des Programms. Es spielt keine Rolle, ob das Programm in der CCU aktiv oder inaktiv ist.

Beispiel: Programm mit dem Namen "Schalter_Ein" ausführen:
<pre>set d_ccu execute Schalter_Ein</pre>

===Aggregation von Gerätezuständen (ab 3.6)===
Hinter diesem etwas kryptischen Begriff verbirgt sich die Zusammenfassung von Zuständen von Client-Devices. Anwendungsbeispiele sind:
* Wieviele und welche Geräte haben einen niedrigen Batteriestand?
* Wieviele und welche Fenster sind geöffnet?
Für die Beantwortung dieser Fragen stellt HMCCU einige Befehle und Attribute bereit. Die Ergebnisse werden in Form von Readings im I/O Device bereitgestellt:
*''Präfix''_count = Anzahl der FHEM Devices, die für die Aggregation ausgewertet wurden.
*''Präfix''_list = Liste der FHEM Devices, die der if Bedingung Aggregationsregel entsprechen.
*''Präfix''_match - Anzahl der FHEM Devices, die der if Bedingung der Aggregationsregel entsprechen.
*''Präfix''_state - Ergebnis der Aggregationsregel (if oder else Wert).
Aggregationen werden automatisch bei Änderung von Readings neu berechnet. Alternativ kann mit dem Befehl '''get aggregation''' eine Aggregation explizit durchgeführt werden. Als Parameter wird der Name der Aggregationsregel oder "all" für alle Aggregationen übergeben:
<pre>get <io-dev> aggregation {all|<name>}</pre>
Die Konfiguration der Aggregationen erfolgt mit Hilfe von Regeln, die über das Attribut ''ccuaggregate'' definiert werden. Dabei werden mehrere Regeln durch ein Semikolon und optional einen Zeilenumbruch getrennt. Eine Aggregationsregel enthält mehrere, durch Komma getrennte Parameter, die das Verhalten einer Aggregation festlegen:
*'''name''':<Name> - Legt den Namen einer Aggregation fest.
*'''filter''':{name|alias|group|room|type}=<Incl-Expr>[!<Excl-Expr>] - Legt fest, welche Geräte in die Aggregation einbezogen werden:
**name: FHEM Device Name
**alias: FHEM Device Alias
**group: FHEM Device ''group'' Attribut
**room: FHEM Device ''room'' Attribut
**type: HomeMatic Gerätetyp
*'''read''':<Read-Expr> - Legt fest, welche Readings für die Aggregation verwendet werden (z.B. state oder LOWBAT).
*'''if''':{any|all}=<Value> - Legt die Bedingung fest, unter der die Aggregationsregel greift:
**any: Regel greift, wenn das Reading mindestens eins der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' hat.
**all: Regel greift, wenn die Readings aller der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' haben.
*'''else''':<Value>
*'''prefix''':{RULE|<Text>} - Legt das Präfix für die Readings fest, die das Ergebnis einer Aggregation beinhalten wobei "RULE" für den Namen der Aggregationsregel steht.
*'''coll''':{NAME|<Attribute>}[!<Default>] - Legt fest, welches Attribut der FHEM Devices, die in die Aggregation einbezogen werden, in das _list Reading aufgenommen werden, sofern sie die if Bedingung erfüllen. Dabei entspricht "NAME" dem FHEM-Devicename. Der optionale Parameter Default legt den Inhalt des _list Readings fest, wenn keines der FHEM Devices die if Bedingung erfüllt. Voreingestellt ist "no match".

Beispiel: Aggregation der Batteriezustände aller HomeMatic Geräte in FHEM (Annahme: Alle gehören zum Raum "Homematic"):
<pre>
attr d_ccu ccuaggregate name:battery,filter:room=Homematic,read:(LOWBAT|LOW_BAT),if:any=yes,else:no,prefix=battery_,coll:alias
</pre>
Diese Aggregationsregel könnte folgende Readings im I/O Device generieren (Annahme: Batterien von 2 Fenstersensoren leer):
<pre>
battery_count: 50
battery_list: Fenster Bad,Fenster Wohnzimmer
battery_match: 2
battery_state: yes
</pre>

===Ausführen von HomeMatic Scripts===
Mit dem Befehl '''set hmscript''' kann ein beliebiges HomeMatic Script an die CCU2 zur Ausführung gesendet werden. Wenn das Script zeilenweise Daten im Format "Parameter=Value" zurück gibt, werden diese als Readings mit dem Namen ''Parameter" im I/O Device gespeichert.''

Beispiel: Das folgende HomeMatic Script wertet alle CCU2 Systemvariablen aus. Das Ergebnis wird als Readings gespeichert (äquivalent zu Befehl '''get vars'''):
<pre>
object osysvar;
string ssysvarid;
foreach (ssysvarid, dom.GetObject(ID_SYSTEM_VARIABLES).EnumUsedIDs())
{
osysvar = dom.GetObject(ssysvarid);
WriteLine (osysvar.Name() # "=" # osysvar.Value());
}
</pre>

Wenn das Script auf dem FHEM-Server unter /opt/fhem/sysvars.scr gespeichert wird, kann es wie folgt ausgeführt werden:

<pre>set d_ccu hmscript /opt/fhem/sysvars.scr</pre>

[[Kategorie:HomeMatic Components]]
[[Kategorie:Interfaces]]

Alexa-Fhem

2017-07-28T06:45:59Z

DR: /* Windows */ typo

'''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 [https://forum.fhem.de/index.php?action=profile;u=430 justme1968] im {{Link2Forum|Topic=60244|LinkText=Forum}} veröffentlicht.
Das ist eine erste Version der Dokumentation zur Installation und Einrichtung, eine Erweiterung wird sicherlich in nächster Zeit noch folgen.
{{Infobox Modul
|ModPurpose=Anbindung von FHEM an Amazon Assistent Alexa
|ModType=x
|ModTechName=
|ModForumArea=Frontends/Sprachsteuerung
|ModOwner=justme1968
}}

==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.{{Randnotiz|RNTyp=r|RNText=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'''.
*Card bezeichnet einen Eintrag in der Alexa-App, der die erkannte Sprachnachricht sowie weiter gehenden Informationen über die Reaktion von Alexa enzthält und Rückmeldung an Amazon erlaubt.
*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===
[[Datei:2gpXyLN.jpg|200px|thumb|right|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 <code>lambda.js</code> code an alexa-fhem weitergeleitet
*alexa-fhem steuert FHEM und sendet ein Antwort-Event zurück
*<code>lambda.js</code> 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-Fhem#Smart_Home|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-Fhem#Custom|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==
{{Randnotiz|RNTyp=[g|Info]|RNText=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:
<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:
<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>

=== Alexa-Fhem installieren ===
'''Aus gegebenem Anlass: Dies ist weder eine Einführung in Linux, noch eine Anfängerdokumentation für FHEM.''' Also erst die Grundlagen lernen, und dann mit Alexa beginnen !

Die aktuelle Version ist jeweils {{Link2Forum|Topic=60244|Message=540117|LinkText=hier}} zu finden.

====Erstinstallation====
Hier wird die Erstinstallation von Alexa-Fhem beschrieben.
===== Linux =====
# Die tgz-Datei unter Linux im Hauptverzeichnis von FHEM (typischerweise <code>/opt/fhem</code>) entpacken (''nicht'' unter Windows, das zerstört die Rechteeinstellungen).<syntaxhighlight lang="bash" style="width:50%;">tar -xvzf dateiname.tgz</syntaxhighlight>
# Das dabei entstandene Verzeichnis ''package'' in ''alexa-fhem'' umbenennen <syntaxhighlight lang="bash" style="width:50%;">mv package alexa-fhem</syntaxhighlight>
# Durch <syntaxhighlight lang="bash" style="width:50%;">cd alexa-fhem</syntaxhighlight> in das Verzeichnis wechseln
# Mit <syntaxhighlight lang="bash" style="width:50%;">npm install</syntaxhighlight> alle Abhängigkeiten installieren (kein sudo!).
# SSL Zertifikat erzeugen durch Aufruf von <syntaxhighlight lang="bash" style="width:50%;">./createKey.sh</syntaxhighlight> (kein sudo!). Hierbei beachten, dass ein Kennwort vergeben werden muss, das mindestens aus 4 Zeichen besteht, dieses Kennwort bitte merken.
# Das Verzeichnis ''.alexa'' anlegen, ''und zwar im Home-Verzeichnis desjenigen Benutzers, unter dem Alexa-Fhem laufen soll.'' Insbesondere ist zu beachten, dass dieser Nutzer u.U. im Startskript explizit gesetzt wird. Mit dem untenstehenden Skript ist das ''nicht'' der User fhem, sondern der User ''pi''. Das Symbol ''~/'' verweist auf das Home-Verzeichnis des Benutzers, der gerade die Installation vornimmt.
# Die Datei ''config-sample.json'' nach ''.alexa/config.json'' kopieren. Achtung: Installiert man alexa-fhem als root-user, zeigt das Symbol ''~/'' auf ''/root'' - und die Konfigurationsdatei 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.
===== Windows =====
''Vor'' der Installation von Alexa-Fhem muss man folgende Anwendungen installieren:
* Node.js (die aktuelle Version findet man unter https://nodejs.org/en/download/)
* OpenSSL (http://slproweb.com/products/Win32OpenSSL.html oder https://www.heise.de/download/product/win32-openssl-47316/download)
Erst dann fängt man mit Alexa-Fhem an.

# Die tgz-Datei im Hauptverzeichnis von FHEM (z.B. <code>С:\Program Files (x86)\fhem</code>) entpacken.
# Das dabei entstandene Verzeichnis ''package'' in ''alexa-fhem'' umbenennen
# Windows-Shell (Kommandozeile, Eingabeaufforderung usw.) öffnen. "Start" -> "Ausführen" (oder [Windows-Taste]+[R]) -> cmd -> Ok. Durch <syntaxhighlight lang="bash" style="width:50%;">cd "<FHEM-Hauptverzeichis>\alexa-fhem"</syntaxhighlight> in das Verzeichnis wechseln. Dabei ist natürlich das <FHEM-Hauptverzeichis> durch den entsprechenden Pfad aus dem Schritt 1 zu ersetzen. Im o.g. Beispiel wäre es <code>cd "С:\Program Files (x86)\fhem\alexa-fhem"</code>
# Mit <syntaxhighlight lang="bash" style="width:50%;">npm install</syntaxhighlight> alle Abhängigkeiten installieren. Bei der Fehlermedlung wie "Der Befehl "npm" ist entweder falsch geschrieben oder konnte nicht gefunden werden." ist die Installation von Node.js zu überprüfen.
# SSL Zertifikat erzeugen. Dafür muss man alle Befehle aus dem Skript ''createKey.sh'' nacheinander manuell ausführen. Hierbei beachten, dass ein Kennwort vergeben werden muss, das mindestens aus 4 Zeichen besteht, dieses Kennwort bitte merken. Der Windows-Welt unbekannter Befehl <code>mv</code> ist durch <code>move /y</code> zu ersetzen:<syntaxhighlight lang="bash" style="width:50%;">openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365</syntaxhighlight><syntaxhighlight lang="bash" style="width:50%;">openssl rsa -in key.pem -out newkey.pem</syntaxhighlight><syntaxhighlight lang="bash" style="width:50%;">move /y newkey.pem key.pem</syntaxhighlight> Eventuelle Fehlermeldung "can't open config file: /usr/local/ssl/openssl.cnf" o.Ä. lässt sich durch Befehl <code>set OPENSSL_CONF=<OpenSSL-Verzeichnis>\bin\openssl.cfg</code> beheben, wobei <OpenSSL-Verzeichnis> durch den entsprechenden Installationspfad (typischerweise <code>c:\OpenSSL-Win32</code>) zu ersetzen ist.
# Das Verzeichnis ''.alexa'' anlegen, ''und zwar im Benutzerverzeichnis desjenigen Benutzers, unter dem Alexa-Fhem laufen soll.'' In aktuellen Versionen von Windows (ab Windows 7 bzw. ab Windows Server 2008 R2) liegt das Verzeichnis unter <code>C:\Users\<Benutzername></code>, also z.B. für Benutzer "Administrator" - unter <code>C:\Users\Administrator</code>. Falls Windows sich weigert das Verzichniss mit dem Punkt am Anfang zu erstellen, kann man das aus der Kommandozeile machen:<syntaxhighlight lang="bash" style="width:50%;">cd "C:\Users\<Benutzername>"</syntaxhighlight><syntaxhighlight lang="bash" style="width:50%;">
mkdir ".alexa"</syntaxhighlight>
# Die Datei ''config-sample.json'' nach ''C:\Users\<Benutzername>\.alexa\config.json'' kopieren.
# Achtung: Ggf. müssen auch die Dateien key.pem und cert.pem ins entsprechende Verzeichnis (<code>"<FHEM-Hauptverzeichis>\alexa-fhem\bin</code>) kopiert werden.

====Update====
Hier wir das Update auf eine neue Version von Alexa-Fhem beschrieben
===== Linux =====
# Das Verzeichnis ''alexa-fhem'' im Hauptverzeichnis von FHEM (typischerweise <code>/opt/fhem</code>) umbenennen in ''alexa-fhem.old''.
# Die tgz-Datei der neuen Alexa-Fhem-Version unter Linux im Hauptverzeichnis von FHEM (typischerweise <code>/opt/fhem</code>) entpacken (''nicht'' unter Windows, das zerstört die Rechteeinstellungen).
# Das dabei entstandene Verzeichnis ''package'' in ''alexa-fhem'' umbenennen, in das Verzeichnis wechseln
# Mit <syntaxhighlight lang="bash" style="width:50%;">npm install</syntaxhighlight> alle Abhängigkeiten installieren (kein sudo!).
# Die Zertifikatsdateien key.pem und cert.pem aus dem alten Verzeichnis ''alexa-fhem.old'' ins neue Verzeichnis ''alexa-fhem'' kopieren.
Natürlich dann den Dienst neu starten, auch müssen selbstredend irgendwelche Modifikationen an der Datei server.js in der neuen Version nachgezogen werden. Wenn alles läuft, kann das alte Verzeichnis ''alexa-fhem.old'' gelöscht werden.
===== Windows =====
# Das Verzeichnis ''alexa-fhem'' im Hauptverzeichnis von FHEM (z.B. <code>С:\Program Files (x86)\fhem</code>) umbenennen in ''alexa-fhem.old''.
# Die tgz-Datei der neuen Alexa-Fhem-Version im Hauptverzeichnis von FHEM entpacken.
# Das dabei entstandene Verzeichnis ''package'' in ''alexa-fhem'' umbenennen
# Windows-Shell (Kommandozeile, Eingabeaufforderung usw.) öffnen. "Start" -> "Ausführen" (oder [Windows-Taste]+[R]) -> cmd -> Ok. Durch <syntaxhighlight lang="bash" style="width:50%;">cd "<FHEM-Hauptverzeichis>\alexa-fhem"</syntaxhighlight> in das Verzeichnis wechseln. Dabei ist natürlich das <FHEM-Hauptverzeichis> durch den entsprechenden Pfad aus dem Schritt 1 zu ersetzen. Im o.g. Beispiel wäre es <code>cd "С:\Program Files (x86)\fhem\alexa-fhem"</code>
# Mit <syntaxhighlight lang="bash" style="width:50%;">npm install</syntaxhighlight> alle Abhängigkeiten installieren.
# Die Zertifikatsdateien key.pem und cert.pem aus dem alten Verzeichnis ''alexa-fhem.old'' ins neue Verzeichnis ''alexa-fhem'' kopieren.
Natürlich dann den Dienst neu starten, auch müssen selbstredend irgendwelche Modifikationen an der Datei server.js in der neuen Version nachgezogen werden. Wenn alles läuft, kann das alte Verzeichnis ''alexa-fhem.old'' gelöscht 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 | Skill Id bestimmen]]
# ''oauthClientID'' -> ''Client ID'' dem Abschnitt [[#Login_with_Amazon | 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"
}
]
}

Mehrere Custom Skills lassen sich mit der folgenden Syntax eintragen
"applicationId": [ "amzn1.ask.skill.1" , "amzn1.ask.skill.2" ],
"oauthClientID": [ "amzn1.application-oa2-client.1" , "amzn1.application-oa2-client.1" ]

Danach durch Aufruf von <syntaxhighlight lang="bash" style="width:50%;">./bin/alexa</syntaxhighlight> den Dienst starten (kein sudo!)

Unter Windows startet man Alexa-Dienst durch <syntaxhighlight lang="bash" style="width:50%;">node alexa</syntaxhighlight> aus der <code>alex-fhem/bin</code> (also erst z.B. durch <code>cd "<FHEM-Hauptverzeichis>\alexa-fhem\bin"</code> ins richtige Verzeichnis kommen)

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 {{Link2Forum|Topic=60244|Message=517271|LinkText=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:
<syntaxhighlight lang="bash" style="width:50%;">sudo chmod 755 /etc/init.d/alexa
sudo update-rc.d alexa defaults</syntaxhighlight>

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

Nun folgende Devices anlegen (ggf. einem Raum zuordnen, z.B. AlexaControl):
<syntaxhighlight lang="bash" style="width:75%;">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 &")})</syntaxhighlight>

==== Alexa-Fhem als Service (systemd) installieren ====
Auf neueren Installationen (z.B. RPi Jessie) wird init.d durch systemd ersetzt. Folgend die Anleitung um alexa-fhem als Service zu installieren auf einem Raspberry Pi mit Jessie.

Zunächst einen neuen Benutzer anlegen unter dem alexa-fhem laufen soll, falls man nicht möchtet dass alexa-fhem z.B. mit dem fhem User ausgeführt wird:

<code lang="bash" style="width:75%;">
sudo useradd -M --system alexa
</code>

Eigentlich braucht der Benutzer keine Gruppen, aber man kann den Benutzer auch der Gruppe <code>dialout</code> hinzufügen (<code>sudo usermod -a -G dialout alexa</code>)

Datei "alexa" unter <code>/etc/default</code> anlegen

# Defaults / Konfigurations Optionen für alexa-fhem
# Wo findet alexa-fhem die config.json Datei?
ALEXA_OPTS=-U /opt/fhem/.alexa

Den Pfad <code>/opt/fhem/.alexa</code> an die Systemgegebenheiten anpassen. Letztendlich kann die config.json irgendwo liegen, hauptsache alexa-fhem weiß wo. Achtung: Natürlich muss der Benutzer auch Zugriff auf das Verzeichnis mit der config als auch das alexa-fhem Verzeichnis haben.

Datei "alexa.service" unter <code>/etc/systemd/system</code> anlegen:

[Unit]
Description=Node.js Alexa Server
After=syslog.target network-online.target

[Service]
Type=simple
User=alexa #oder ein anderer Benutzer wie fhem
EnvironmentFile=/etc/default/alexa
# oder wo auch immer eure alexa-fhem liegt
ExecStart=/opt/fhem/alexa-fhem/bin/alexa $ALEXA_OPTS
Restart=on-failure
RestartSec=10
KillMode=process

[Install]
WantedBy=multi-user.target

Um den Service zu aktiveren und zu starten helfen folgende Befehle:
sudo systemctl daemon-reload
sudo systemctl enable alexa
sudo systemctl start alexa

Status abfragen mit
sudo systemctl status alexa

Log einsehen?
sudo journalctl -u alexa

(mit <code>-f</code> kann man den follow Modus aktivieren, wie <code>tail -f</code>).
Bei einen reboot startet alexa-fhem jetzt automatisch.

==== 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
<code>https://<IP-Adresse des Servers>:3000</code> kann man testen, ob der Alexa-Fhem Service läuft - der Seitenaufruf liefert eine Zeile JSON-Code, beginnend mit
<code>{"header":{"name":"UnsupportedOperationError"...</code>

=== 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:
<syntaxhighlight lang="bash" style="width:70%;">define MyAlexa alexa</syntaxhighlight>

<hr>

=== Alexa Skills ===
Für folgende Schritte muss man unter der Adresse http://developer.amazon.com angemeldet sein
# Anmeldung auswählen [[Datei:Developer.amazon.com-01-login2.png|200px]]
# Anmeldedaten eingeben [[Datei:Developer.amazon.com-02-userpass2.png|200px]]

==== 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'' [[Datei:Developer.amazon.com-03-apps_and_services.png|200px]]
# Anschließend auswählen ''Security Profiles'' [[Datei:Developer.amazon.com-05-apps_and_services_-_security_profiles.png|200px]]
# Auswählen ''Create a New Security Profile'' aus [[Datei:Developer.amazon.com-06-apps_and_services_-_create_a_new_security_profile.png|200px]]
# Dann einen Namen und eine Beschreibung für das Profil eingeben und mit ''Save'' bestätigen [[Datei:Developer.amazon.com-07-apps_and_services_-_security_profile_management.png|200px]]

===== Login with Amazon =====
{{Randnotiz|RNTyp=[g|Info]|RNText=Hier wird beschrieben, wo ''Client Id'' und ''Client Secret'' zu finden sind}}
# Oben rechts auf ''Login with Amazon'' klicken. [[Datei:Developer.amazon.com-08-login_with_amazon.png|200px]]
# Auf der neu geladenen Seite auswählen ''Sign up'' [[Datei:Developer.amazon.com-09-login_with_amazon_-_sign_up.png|200px]]
# Anschließend im Dropdown Menü das vorher angelegte Profil auswählen und mit ''Confirm'' bestätigen [[Datei:Developer.amazon.com-10-login_with_amazon_-_create_new_profile.png|200px]] [[Datei:Developer.amazon.com-11-login_with_amazon_-_create_new_profile2.png|200px]]
# Im folgenden Fenster die Adresse [https://www.amazon.com/gp/help/customer/display.html?nodeId=468496 https://www.amazon.com/gp/help/customer/display.html?nodeId=468496] eingeben und mit ''Save'' bestätigen. '''Todo Erklärungsbedarf: WARUM diese Adresse''' [[Datei:Developer.amazon.com-12-login_with_amazon_-_enter_consent_screen_information.png|200px]]
# Anschließend bei dem neu angelegten Eintrag auf der rechten Seite auf das Zahnrad klicken und ''Web Settings'' auswählen [[Datei:Developer.amazon.com-13-login_with_amazon_-_web_settings.png|200px]]
# Im neu geladenen Fenster anklicken von ''Edit'' [[Datei:Developer.amazon.com-14-login_with_amazon_-_edit.png|200px]]
# Anschließend bei ''Allowed Return URLs'' die folgenden drei Adressen eingeben. ''xxx'' muss hierbei durch den Wert ersetzt werden, der in den beiden Abschnitten [[#SmartHome_Skill_anlegen | SmartHome Skill anlegen]] bzw. [[#Custom_Skill_anlegen | Custom Skill anlegen]] jeweils unter Punkt 4 (Seite ''Configuration'') bei ''Redirect Urls'' am Ende der URLs angezeigt wird
## [https://layla.amazon.co.uk/api/skill/link/xxx https://layla.amazon.co.uk/api/skill/link/xxx]
## [https://pitangui.amazon.com/api/skill/link/xxx https://pitangui.amazon.com/api/skill/link/xxx]
## [https://layla.amazon.com/api/skill/link/xxx https://layla.amazon.com/api/skill/link/xxx]
. [[Datei:Developer.amazon.com-15-login_with_amazon_-_allowed_return_urls.png|200px]]

==== Skills bearbeiten ====
# Im Menü den Punkt ''ALEXA'' auswählen [[Datei:Developer.amazon.com-03-apps_and_services.png|200px]]
# Anschließend im Feld ''Alexa Skills Kit'' auf ''Get started'' klicken [[Datei:Developer.amazon.com-17-alexa_-_alex_skills_kit_-_get_started.png|200px]]

===== SmartHome Skill anlegen =====
# Oben rechts ''Add a New Skill'' auswählen [[Datei:Developer.amazon.com-18-alexa_-_alex_skills_kit_-_add_a_new_skill.png|200px]]
# 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")
#:* ''Payload Version'' -> ''v2 (other devices)'' [[Datei:Developer.amazon.com-19-alexa_-_alex_skills_kit_-_skill_information.png|200px]]
# Die folgende Seite einfach mit ''Next'' überspringen [[Datei:Developer.amazon.com-20-alexa_-_alex_skills_kit_-_interaction_model.png|200px]]
# 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 [[#ARN_der_AWS_Lambda_Funktion_bestimmen | AWS Lambda Funktion]] eintragen.
#:* ''Authorization URL'' -> <code>https://www.amazon.com/ap/oa</code>
#:* ''Client ID'' -> ''Client ID'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1
#:* ''Scope'' -> <code>profile:user_id</code> (wörtlich 1:1 eintragen)
#:* ''Redirect URLs'' - sollten vorbelegt sein
#:* ''Authorization Grant Type'' -> ''Auth Code Grant'' auswählen
#:* ''Access Token URI'' -> <code>https://api.amazon.com/auth/o2/token</code>
#:* ''Client Secret'' -> ''Client Secret'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1
#:* ''Client Authentication Scheme'' -> ''HTTP Basic''
#:* ''Privacy Policy URL'' -> <code>https://www.amazon.com/gp/help/customer/display.html?nodeId=468496</code> 
 [[Datei:Developer.amazon.com-21-alexa_-_alex_skills_kit_-_configuration.png|200px]] [[Datei:Developer.amazon.com-22-alexa_-_alex_skills_kit_-_test.png|200px]]

===== Custom Skill anlegen =====
<ol>
<li> Oben rechts ''Add a New Skill'' auswählen [[Datei:Developer.amazon.com-18-alexa_-_alex_skills_kit_-_add_a_new_skill.png|200px]]</li>
<li> Auf der folgenden Seite (''Skill Information'') die nachstehenden Daten eingeben und dann mit ''Next'' bestätigen:
<ul>
<li> ''Skill Type'' -> ''Custom Interaction Model'' </li>
<li> ''Language'' -> ''German''</li>
<li> ''Name'' -> beliebiger Name, z.B. "MySmartHome Advanced". Dieser wird in der Alexa App unter "Meine Skills" angezeigt.</li>
<li> ''Invocation Name'' -> Aufruf des Skills, unter dem dieser später gestartet wird. Z.B. "Alexa, starte James" [[Datei:CustomSkill_2.PNG|400px]]</li>
</ul></li>
<li>Auf der Seite ''Interaction Model'' folgende Eingaben tätigen und mit ''Next'' abschließen
<ul>
<li>In einem separaten Browserfenster FHEM aufrufen, und für das bereits definierte Alexa-Gerät das Kommando <code>get MyAlexa interactionModel</code> aufrufen. Es erscheint ein Popup-Fenster mit ziemlich vielen Zeilen.
<li>In die Box ''Intent Schema'' kopiert man den ersten Teil dieser FHEM-Ausgabe hinein, also: <blockquote>
{
"intents" : [
<hier ziemlich viele Zeilen>
]
}
</blockquote></li>
<li>Nun die ''Custom Slot Types'' einrichten. Dazu muss aus dem zweiten Teil der FHEM-Ausgabe jeweils der Slot-Type (z.B. <code>FHEM_article</code>) 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.</li>
<li>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 <code>get MyAlexa customSlotTypes</code> ausführen. Auch diese Ausgabe wird, wie oben beschriebeen, in Custom Slot Types eingetragen (erst der TYPE, dann die möglichen Werte)
<li>Anschließend erneut die FHEM-Ausgabe schließen und erneut für das bereits definierte Alexa-Gerät das Kommando <code>get MyAlexa interactionModel</code> aufrufen.
<li>Unter ''Sample Utterances'' nun den Text aus dem dritten Teil dieser FHEM-Ausgabe hineinkopieren [[Datei:CustomSkill_5.PNG|400px]]</li>
</ul></li>
<li>Auf der Seite ''Configuration'' Folgendes eingeben und mit ''Next'' bestätigen:
<ul>
<li>''Service Endpoint Type'' -> ''AWS Lambda'' auswählen</li>
<li>''Geographical Region'' -> ''Europe'' auswählen und im Textfeld den Wert aus Abschnitt [[#AWS_Lambda_Funktion_anlegen | AWS Lambda Funktion anlegen]] (Punkt 12) eintragen. </li>
<li>''Do you allow users to create an account or link to an existing account with you?'' -> ''Yes''</li>
<li>''Authorization URL'' -> <code>https://www.amazon.com/ap/oa</code></li>
<li>''Client ID'' -> ''Client ID'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1</li>
<li>''Scope'' -> <code>profile:user_id</code> (wörtlich 1:1 eintragen)</li>
<li>''Redirect URLs'' - sollten vorbelegt sein</li>
<li>''Authorization Grant Type'' -> ''Auth Code Grant'' auswählen</li>
<li>''Access Token URI'' -> <code>https://api.amazon.com/auth/o2/token</code></li>
<li>''Client Secret'' -> ''Client Secret'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1</li>
<li>''Client Authentication Scheme'' -> ''HTTP Basic''</li>
<li>''Privacy Policy URL'' -> <code>https://www.amazon.com/gp/help/customer/display.html?nodeId=468496</code></li>
</ul>
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 | AWS Lambda Funktion]] nachgetragen werden, dies wird in Abschnitt [[#Trigger_f.C3.BCr_Custom_Skill_hinzuf.C3.BCgen | Trigger für Custom Skill hinzufügen]] beschrieben.
 [[Datei:CustomSkill_6.PNG|400px]] [[Datei:CustomSkill_7.PNG|400px]]</li>

==== 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 | Custom Skill Anlegen]] unter Punkt 2 eingetragen hat.

==== Skill Id bestimmen ====
{{Randnotiz|RNTyp=[g|Info]|RNText=Hier wird beschrieben, wo die ''Alexa Skill Id'' zu finden ist}}
Für das [[#AWS_Lamba_Funktion_anlegen | Anlegen einer ''AWS Lambda Funktion'']] bzw für die [[#Alexa-Fhem_konfigurieren | Konfiguration von Alexa-Fhem]] wird die ''Alexa Skill Id'' benötigt. An diese kommt man wie folgt:
# Anmelden wie unter [[#Alexa_Skills | Alexa Skills]] beschrieben.
# Menüpunkt ''ALEXA'' auswählen, wie [[#Skills_bearbeiten | Skills bearbeiten]] erklärt.
# Beim gewünschten Eintrag auf ''Edit'' klicken [[Datei:Developer.amazon.com-23-alexa_-_alex_skills_kit_-_overview.png|200px]]
# Die Id, die nun oben angezeigt wird, ist die gesuchte. Sie hat typischerweise das Format <code>amzn1.ask.skill.[Zahlen und Bindestriche]</code> [[Datei:Aws.amazon.com-06-configure_triggers2.png|200px]]

<hr>

=== AWS Lambda Funktion ===
Für folgende Schritte muss man unter der Adresse http://aws.amazon.com angemeldet sein
# Anmeldung auswählen [[Datei:Aws.amazon.com-01-site.png|200px]]
# Anmeldedaten eingeben [[Datei:Aws.amazon.com-02-login.png|200px]]
# Den Punkt ''Lambda'' links auf der Startseite auswählen, bzw. im Menü ''Services'' unter ''Compute'' den Menüpunkt ''Lambda'' auswählen [[Datei:Aws.amazon.com-03-lambda.png|200px]]
==== AWS Lambda Funktion anlegen ====
# Für eine erste Lambda-Funktion den Punkt ''Get Started Now'' auswählen [[Datei:Aws.amazon.com-04-get_started_now.png|200px]]
# Den Blueprint ''Blank function'' auswählen [[Datei:Aws.amazon.com-05-select_blueprint.png|200px]]
# Im neuen Fenster dann auf den gestrichelten Kasten klicken und ''Alexa Smart Home'' auswählen und mit ''Next'' bestätigen [[Datei:Aws.amazon.com-06-configure_triggers1.png|200px]]
## 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 | Skill Id bestimmen]] beschrieben wird, den Haken bei ''Enable trigger'' setzen und mit ''Next'' bestätigen [[Datei:Aws.amazon.com-06-configure_triggers3.png|200px]]
# Auf der Konfigurationsseite eingeben:
## ''Name'' -> ''FHEM''
## ''Runtime'' -> Node.js 4.3.
## ''Role'' -> ''Choose an existing role''
### 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_installieren | 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. [[Datei:Aws.amazon.com-07-configure_function.png|200px]]
# Auf der Übersichtsseite dann ''Create function'' anklicken [[Datei:Aws.amazon.com-08-review.png|200px]]

==== 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 [[Datei:Aws.amazon.com-09-go_overview.png|200px]]
# Anschließend den Radiobutton der angelegten Funktion ''FHEM'' markieren und im Menü ''Action'' den Punkt ''Show ARN'' auswählen [[Datei:Aws.amazon.com-10-1-show_arn.png|200px]]
# Es wird nun eine ARN Adresse angezeigt, die für den Abschnitt [[#SmartHome_Skill_anlegen| SmartHome Skill anlegen]] benötigt wird [[Datei:Aws.amazon.com-10-2-arn.png|200px]]

=== Absichern des Zugriffs ===
Natürlich muss der Zugriff auf den von Alexa-Fhem verwendeten Port (default: 3000, Bestandteil des Codes in der AWS Lambda-Funktion) durch die Firewall freigeschaltet werden (auf einer FritzBox unter "Portfreigaben").

==== Absicherung direkt in Alexa-FHEM ====
Die Kommunikation zwischen Amazon AWS und Alexa-FHEM ist auf die folgenden Arten gesichert:
* Die Verbindung erfolgt per HTTPS
* Es werden nur Verbindung angenommen auf denen ein gültiges Alexa-Event gesendet wird.
* Es werden nur Verbindungen angenommen die ein gültiges und noch nicht abgelaufenes OAuth-Token enthalten. Jedes neue Token wird live bei Amazon auf Gültigkeit geprüft.
* Es werden nur Verbindungen mit lokal konfigurierter Skill-ID angenommen.
* Es ist nicht möglich von außen beliebige FHEM Kommandos zu senden. Die FHEM Kommandos werden nur lokal erzeugt.

Wer möchte kann Alexa-FHEM natürlich noch weiter absichern. Es gilt aber, dass nicht jedes zusätzliche Glied in der Kette die Sicherheit sondern unter Umständen nur die Angriffsfläche erhöht. Ein falsch konfigurierter und nach aussen offener Apache (oder anderer ReverseProxy) ist unter Umständen ein größeres Risiko als Alexa-FHEM alleine.

==== Absicherung per ReverseProxy ====
<s>Die Kommunikation zwischen Amazon und FHEM ist wegen der Verwendung von SSL schon verschlüsselt - prinzipiell kann aber jeder von außen mit Alexa-Fhem kommunizieren. Man sollte sich deshalb im Klaren darüber sein, dass dies eine Sicherheitslücke darstellt:</s> Jeder offene Port verleitet zu Angriffen, und mit zunehmender Verbreitung von Alexa steigt auch das Risiko. Es wird deshalb empfohlen, vor den eigentlichen Alexa-Server zur Absicherung einen Apache-Webserver als ReverseProxy zu setzen. Nicht nur ist der Apache eine hervorragend stabile und seit Jahrzehnten getestete Software, sondern die Konfiguration als ReverseProxy erlaubt auch, den Zugriff auf den Alexa-Fhem-Rechner auf die Amazon-Maschinen zu beschränken.

'''Achtung: Dies ist keine allgemeine Anleitung in Sachen Computersicherheit.''' Im Folgenden gehen wir davon aus, dass
* Grundbegriffe wie Firewall, IP-Ports, SSL und Dynamic DNS vertraut sind
* Ein Apache Webserver (idealerweise auf einer zweiten Maschine) bereits installiert ist und die Konfiguration verstanden wurde (wenn nicht: Es gibt im Netz ''tausende'' von Anleitungen dafür...)
* Ein Servername von einem DynDNS-Anbieter - sagen wir ''myhome.is-my-castle.com'' - bereits von ''außen'' auf unser SmartHome zeigt.
* Alexa-Fhem in einer der oben beschriebenen Basiskonfigurationen läuft, d.h. der Zugriff auf <code>https://myhome.is-my-castle.com:3000</code> ergibt, wie im Punkt [[#Alexa-Fhem_testen|Alexa-Fhem testen]] beschrieben, eine Antwort des Node.js Servers.

Als erster Schritt zur Absicherung muss das ReverseProxy Modul für den Apache installiert und mit <code>a2enmod</code> aktiviert werden, hierzu sei auf [https://www.digitalocean.com/community/tutorials/how-to-use-apache-http-server-as-reverse-proxy-using-mod_proxy-extension diese Anleitung] verwiesen. Der zweite Schritt besteht darin, den SSL-Zugriff durch ein Passwort abzusichern. Dazu wird auf dem Apache-Rechner das Programm
htpasswd <passwdfile> <username>
ausgeführt, das Programm fragt dann nach dem gewünschten Passwort. Wir nehmen im Folgenden an, dass das Passwortfile ''/etc/apache2/htpasswd'' ist, der gesetzte Username ''alexa'' lautet und das Passwort ''my_smarthome'' ist.

Im dritten Schritt wird nun in das Apache-Konfigurationsfile die Weiterleitung auf den eigentlichen Alexa-Fhem-Rechner eingetragen. Dazu wählen wir, dass von außen der Standard-SSL-Port 443 benutzt werden soll, sowie als Verzeichnisname ''/alexa''. '''Achtung:''' Dieser Code soll '''nicht''' in die Default-Konfiguration des Apache-Webservers. Sondern in eine separate Datei (Dateiname z.B. "fhem"), die ins Unterverzeichnis /etc/apache2/conf.d gestellt wird.

<VirtualHost *:443>
ServerName myhome.is-my-castle.com
SSLEngine on
SSLProxyEngine on
SSLProxyCheckPeerCN off
SSLProxyCheckPeerName off
SSLCertificateKeyFile /etc/apache2/mycert/server.key
SSLCertificateFile /etc/apache2/mycert/server.crt
<Location /alexa>
AuthType Basic
AuthName "Authentication Required"
AuthUserFile "/etc/apache2/htpasswd"
Require valid-user
ProxyPass https://<hier IP-Adresse des Alexa-Fhem-Rechners>:3000/
ProxyPassReverse https://<hier IP-Adresse des Alexa-Fhem-Rechners>:3000/
Order deny,allow
Allow from All
</Location>
(... Hier eventuell weitere Umleitungen)
</VirtualHost>
Nach einem Neustart des Apache-Servers, dem Schließen des Ports 3000 in der Firewall sowie dem Öffnen des Ports 443 ist der Alexa-Fhem-Rechner von außen nur noch erreichbar durch den Aufruf von <code>https://myhome.is-my-castle.com/alexa</code> und verlangt unmittelbar die Eingabe von Username und Passwort.

Der vierte Schritt ist nun, den Code der AWS Lambda-Funktion an fünf Stellen zu verändern
'''const PORT=443;'''
const HOST='myhome.is-my-castle.com';
'''const PATH='/alexa';'''
'''const AUTH='alexa:my_smarthome';'''
// entry
exports.handler = function(event, context, callback) {
console.log(`EVENT: ${event}`);
console.log(`CONTEXT: ${context}`);
var post_data = JSON.stringify(event);
var options = {
hostname: HOST,
port: PORT,
//family: 6,
'''path: PATH,'''
method: 'POST',
'''auth: AUTH,'''
rejectUnauthorized: false, // accept self-signed
(etc., Rest des Codes wie gehabt)
Natürlich muss der Zugriff getestet werden. Bei Beachtung aller dieser Schritte werden alle un-autorisierten Zugriffe von außen abgewehrt. Eine noch weiter gehende Sicherung ist möglich, dazu kann in der Serverkonfiguration der Zugriff auf die Amazon-Domains beschränkt werden. Das ganze Alexa-System ist aber noch in konstanter Weiterentwicklung, diese Domain-Namen können sich also noch ändern.

== 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 [http://alexa.amazon.de 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 [[Datei:Alexa.amazon.de-01-startseite.png|200px]]
# Oben rechts ''Meine Skills'' bzw. ''Ihre Skills'' auswählen [[Datei:Alexa.amazon.de-03-meine_skills.png|200px]]
# In der Liste der Skills sollte das angelegte FHEM Skill angezeigt werden. Dieses anklicken [[Datei:Alexa.amazon.de-02-liste_skills.png|200px]]
# Oben Rechts in den Details des Skills auf ''Skill aktivieren'' klicken [[Datei:Alexa.amazon.de-04-skill_details.png|200px]]
# In dem neu geöffneten Fenster die Autorisierung bestätigen [[Datei:Alexa.amazon.de-05-amazon_auth.png|200px]]
# Anschließend sollte die Verbindung erfolgreich aufgebaut worden sein [[Datei:Alexa.amazon.de-06-success.png|200px]]

=== Geräte ===
# Auf http://alexa.amazon.de anmelden
# Auf ''Smart Home'' klicken [[Datei:Alexa.amazon.de-01-startseite.png|200px]]
# Anschließend den Punkt ''Geräte suchen'' anklicken [[Datei:Alexa.amazon.de-07-Gerätesuche.png|200px]]
# 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
*** <code><cmd>:<device>:<reading></code>, hier können nicht verwendete Elemente von links nach rechts weg gelassen werden.
*** <code><name>=<value></code>, hier kann <code><value></code> entweder ein Wert oder semikolonseparierte Liste sein.
*** Oder dem schlüsselwort <code>clear</code>, welches alle vorhandenen (default) Parameter dieser Characteristik löscht. <code>clear</code> 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 | 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 | Custom Skill Anlegen]]).

Der Aufruf dieses Gerätes mit Alexa erfolgt dann z.B. mit den Sätzen
<pre style="width:50%;">
"Alexa, sage <Custom Skill Invocation Name>: Stelle Weckzeit auf Neunzehn Uhr Siebenundzwanzig"
"Alexa, frage <Custom Skill Invocation Name> nach dem Status von Weckzeit"
</pre>
Dabei ist natürlich der ''Custom Skill Invocation Name'' durch den Wert zu ersetzen, den man im Abschnitt [[#Custom_Skill_anlegen | 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 [https://www.dpunkt.de/buecher/12387/9783960090120-smarthome-hacks.html 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\');
}
}

<hr>

=== 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
<pre>
"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
</pre>
* 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
<pre>
"Alexa, sage <Custom Skill Invocation Name>: schalte (die) Beleuchtung an" -> LightScene Alle_An wird ausgewählt
</pre>
Dafür wird es aber auch möglich sein direkt die SzenenNamen im gesprochenen Kommando zu verwenden und so auf die Umwege über dummys und ähnliches zu verzichten.

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.

Zwei andere Ansätze Lichtszenen zu schalten die ohne DOIF auskommen sind im Folgenden beschrieben:

* Wenn es von Interesse ist die Steuerung mit einer Darstellung in FTUI zu verbinden: Statt der oben beschriebenen dummy Devices kann man readingsProxy Devices mit passenden setFn und valueFn analog zum [[Harmony#Button_f.C3.BCr_eine_bestimmte_Activity_im_Frontend_und_Homekit_.C3.BCber_readingsProxy|diesem Beispiel für harmony aktivitäten]] verwenden.

* Für jede zu schaltende Szene wird ein dummy angelegt dessen homebridgeMapping direkt auf das LightScene Device zeigt:

define <dummy> dummy
attr <dummy> setList on off
attr <dummy> genericDeviceType switch
attr <dummy> homebridgeMapping On=<light scene>::state,valueOn=<szene>,cmdOn=scene+<szene>,cmdOff=scene+<szene aus>

Bei der zweiten Variante wird davon ausgegangen das der aktuelle status nicht abgefragt oder angezeigt werden soll. Deshalb gibt es keine direkte RadioButton Funktionalität.

== 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 [http://alexa.amazon.de/spa/index.html] 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:
<pre style="width:50%;">
“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”
</pre>

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

Das Prinzip der Kommandokonfiguration ist {{Link2Forum|Topic=60244|Message=532513|LinkText=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:
<pre style="width:50%;">
const PORT=3000;
const HOST='mein.host.name';
</pre>

====Freigabe von Port 3000====
{{Randnotiz|RNTyp=Fehl|RNText=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: [[Homebridge_einrichten#NodeJS_installieren|NodeJS installieren]] sowie [[Homebridge_einrichten#Python.2C_g.2B.2B.2C_MDNS_installieren|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<syntaxhighlight lang="bash" style="width:50%;">node -v</syntaxhighlight>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 <code>~/.alexa/config.json</code> die folgenden Zeilen rauslöschen:

<pre>
"nat-pmp": "10.0.1.1",
"nat-upnp": true,
</pre>

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:
<syntaxhighlight lang="bash" style="width:70%;">2755327 4 -rwxr-xr-x 1 pi pi 339 Nov 26 23:20 alexa</syntaxhighlight>
Sollte dies nicht der Fall sein bitte mit:
<syntaxhighlight lang="bash" style="width:70%;">chmod +x alexa</syntaxhighlight>
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 <code>~/.alexa/config.json</code> geöffnet werden und der Abschnitt "connections" um folgende Zeile ergänzt werden:<pre>
"auth": {"user": "fhem", "pass": "fhempassword"},</pre>
Bei Verwendung von SSL bei FHEM muss auch noch <pre>
"ssl": true,</pre> hinzugefügt werden

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

Alexa-Fhem

2017-07-19T19:28:28Z

DR: +Update für Windows

'''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 [https://forum.fhem.de/index.php?action=profile;u=430 justme1968] im {{Link2Forum|Topic=60244|LinkText=Forum}} veröffentlicht.
Das ist eine erste Version der Dokumentation zur Installation und Einrichtung, eine Erweiterung wird sicherlich in nächster Zeit noch folgen.
{{Infobox Modul
|ModPurpose=Anbindung von FHEM an Amazon Assistent Alexa
|ModType=x
|ModTechName=
|ModForumArea=Frontends/Sprachsteuerung
|ModOwner=justme1968
}}

==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.{{Randnotiz|RNTyp=r|RNText=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'''.
*Card bezeichnet einen Eintrag in der Alexa-App, der die erkannte Sprachnachricht sowie weiter gehenden Informationen über die Reaktion von Alexa enzthält und Rückmeldung an Amazon erlaubt.
*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===
[[Datei:2gpXyLN.jpg|200px|thumb|right|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 <code>lambda.js</code> code an alexa-fhem weitergeleitet
*alexa-fhem steuert FHEM und sendet ein Antwort-Event zurück
*<code>lambda.js</code> 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-Fhem#Smart_Home|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-Fhem#Custom|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==
{{Randnotiz|RNTyp=[g|Info]|RNText=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:
<source lang="bash" style="width:50%;">
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install build-essential libssl-dev</source>

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:
<source lang="bash" style="width:50%;">
curl -sL https://deb.nodesource.com/setup_4.x | sudo -E bash -
sudo apt-get install -y nodejs
</source>

=== Alexa-Fhem installieren ===
'''Aus gegebenem Anlass: Dies ist weder eine Einführung in Linux, noch eine Anfängerdokumentation für FHEM.''' Also erst die Grundlagen lernen, und dann mit Alexa beginnen !

Die aktuelle Version ist jeweils {{Link2Forum|Topic=60244|Message=540117|LinkText=hier}} zu finden.

====Erstinstallation====
Hier wird die Erstinstallation von Alexa-Fhem beschrieben.
===== Linux =====
# Die tgz-Datei unter Linux im Hauptverzeichnis von FHEM (typischerweise <code>/opt/fhem</code>) entpacken (''nicht'' unter Windows, das zerstört die Rechteeinstellungen).
# Das dabei entstandene Verzeichnis ''package'' in ''alexa-fhem'' umbenennen <source lang="bash" style="width:50%;">mv package alexa-fhem</source>
# Durch <source lang="bash" style="width:50%;">cd alexa-fhem</source> in das Verzeichnis wechseln
# Mit <source lang="bash" style="width:50%;">npm install</source> alle Abhängigkeiten installieren (kein sudo!).
# SSL Zertifikat erzeugen durch Aufruf von <source lang="bash" style="width:50%;">./createKey.sh</source> (kein sudo!). Hierbei beachten, dass ein Kennwort vergeben werden muss, das mindestens aus 4 Zeichen besteht, dieses Kennwort bitte merken.
# Das Verzeichnis ''.alexa'' anlegen, ''und zwar im Home-Verzeichnis desjenigen Benutzers, unter dem Alexa-Fhem laufen soll.'' Insbesondere ist zu beachten, dass dieser Nutzer u.U. im Startskript explizit gesetzt wird. Mit dem untenstehenden Skript ist das ''nicht'' der User fhem, sondern der User ''pi''. Das Symbol ''~/'' verweist auf das Home-Verzeichnis des Benutzers, der gerade die Installation vornimmt.
# Die Datei ''config-sample.json'' nach ''.alexa/config.json'' kopieren. Achtung: Installiert man alexa-fhem als root-user, zeigt das Symbol ''~/'' auf ''/root'' - und die Konfigurationsdatei 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.
===== Windows =====
''Vor'' der Installation von Alexa-Fhem muss man folgende Anwendungen installieren:
* Node.js (die aktuelle Version findet man unter https://nodejs.org/en/download/)
* OpenSSL (http://slproweb.com/products/Win32OpenSSL.html oder https://www.heise.de/download/product/win32-openssl-47316/download)
Erst dann fängt man mit Alexa-Fhem an.

# Die tgz-Datei im Hauptverzeichnis von FHEM (z.B. <code>С:\Program Files (x86)\fhem</code>) entpacken.
# Das dabei entstandene Verzeichnis ''package'' in ''alexa-fhem'' umbenennen
# Windows-Shell (Kommandozeile, Eingabeaufforderung usw.) öffnen. "Start" -> "Ausführen" (oder [Windows-Taste]+[R]) -> cmd -> Ok. Durch <source lang="bash" style="width:50%;">cd "<FHEM-Hauptverzeichis>\alexa-fhem"</source> in das Verzeichnis wechseln. Dabei ist natürlich das <FHEM-Hauptverzeichis> durch den entsprechenden Pfad aus dem Schritt 1 zu ersetzen. Im o.g. Beispiel wäre es <code>cd "С:\Program Files (x86)\fhem\alexa-fhem"</code>
# Mit <source lang="bash" style="width:50%;">npm install</source> alle Abhängigkeiten installieren. Bei der Felermedlung wie "Der Befehl "npm" ist entweder falsch geschrieben oder konnte nicht gefunden werden." ist die Installation von Node.js zu überprüfen.
# SSL Zertifikat erzeugen. Dafür muss man alle Befehle aus dem Skript ''createKey.sh'' nacheinander manuell ausführen. Hierbei beachten, dass ein Kennwort vergeben werden muss, das mindestens aus 4 Zeichen besteht, dieses Kennwort bitte merken. Der Windows-Welt unbekannter Befehl <code>mv</code> ist durch <code>move /y</code> zu ersetzen:<source lang="bash" style="width:50%;">openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365</source><source lang="bash" style="width:50%;">openssl rsa -in key.pem -out newkey.pem</source><source lang="bash" style="width:50%;">move /y newkey.pem key.pem</source> Eventuelle Fehlermeldung "can't open config file: /usr/local/ssl/openssl.cnf" o.Ä. lässt sich durch Befehl <code>set OPENSSL_CONF=<OpenSSL-Verzeichnis>\bin\openssl.cfg</code> beheben, wobei <OpenSSL-Verzeichnis> durch den entsprechenden Installationspfad (typischerweise <code>c:\OpenSSL-Win32</code>) zu ersetzen ist.
# Das Verzeichnis ''.alexa'' anlegen, ''und zwar im Benutzerverzeichnis desjenigen Benutzers, unter dem Alexa-Fhem laufen soll.'' In aktuellen Versionen von Windows (ab Windows 7 bzw. ab Windows Server 2008 R2) liegt das Verzeichnis unter <code>C:\Users\<Benutzername></code>, also z.B. für Benutzer "Administrator" - unter <code>C:\Users\Administrator</code>. Falls Windows sich weigert das Verzichniss mit dem Punkt am Anfang zu erstellen, kann man das aus der Kommandozeile machen:<source lang="bash" style="width:50%;">cd "C:\Users\<Benutzername>"</source><source lang="bash" style="width:50%;">
mkdir ".alexa"</source>
# Die Datei ''config-sample.json'' nach ''C:\Users\<Benutzername>\.alexa\config.json'' kopieren.
# Achtung: Ggf. müssen auch die Dateien key.pem und cert.pem ins entsprechende Verzeichnis (<code>"<FHEM-Hauptverzeichis>\alexa-fhem\bin</code>) kopiert werden.

====Update====
Hier wir das Update auf eine neue Version von Alexa-Fhem beschrieben
===== Linux =====
# Das Verzeichnis ''alexa-fhem'' im Hauptverzeichnis von FHEM (typischerweise <code>/opt/fhem</code>) umbenennen in ''alexa-fhem.old''.
# Die tgz-Datei der neuen Alexa-Fhem-Version unter Linux im Hauptverzeichnis von FHEM (typischerweise <code>/opt/fhem</code>) entpacken (''nicht'' unter Windows, das zerstört die Rechteeinstellungen).
# Das dabei entstandene Verzeichnis ''package'' in ''alexa-fhem'' umbenennen, in das Verzeichnis wechseln
# Mit <source lang="bash" style="width:50%;">npm install</source> alle Abhängigkeiten installieren (kein sudo!).
# Die Zertifikatsdateien key.pem und cert.pem aus dem alten Verzeichnis ''alexa-fhem.old'' ins neue Verzeichnis ''alexa-fhem'' kopieren.
Natürlich dann den Dienst neu starten, auch müssen selbstredend irgendwelche Modifikationen an der Datei server.js in der neuen Version nachgezogen werden. Wenn alles läuft, kann das alte Verzeichnis ''alexa-fhem.old'' gelöscht werden.
===== Windows =====
# Das Verzeichnis ''alexa-fhem'' im Hauptverzeichnis von FHEM (z.B. <code>С:\Program Files (x86)\fhem</code>) umbenennen in ''alexa-fhem.old''.
# Die tgz-Datei der neuen Alexa-Fhem-Version im Hauptverzeichnis von FHEM entpacken.
# Das dabei entstandene Verzeichnis ''package'' in ''alexa-fhem'' umbenennen
# Windows-Shell (Kommandozeile, Eingabeaufforderung usw.) öffnen. "Start" -> "Ausführen" (oder [Windows-Taste]+[R]) -> cmd -> Ok. Durch <source lang="bash" style="width:50%;">cd "<FHEM-Hauptverzeichis>\alexa-fhem"</source> in das Verzeichnis wechseln. Dabei ist natürlich das <FHEM-Hauptverzeichis> durch den entsprechenden Pfad aus dem Schritt 1 zu ersetzen. Im o.g. Beispiel wäre es <code>cd "С:\Program Files (x86)\fhem\alexa-fhem"</code>
# Mit <source lang="bash" style="width:50%;">npm install</source> alle Abhängigkeiten installieren.
# Die Zertifikatsdateien key.pem und cert.pem aus dem alten Verzeichnis ''alexa-fhem.old'' ins neue Verzeichnis ''alexa-fhem'' kopieren.
Natürlich dann den Dienst neu starten, auch müssen selbstredend irgendwelche Modifikationen an der Datei server.js in der neuen Version nachgezogen werden. Wenn alles läuft, kann das alte Verzeichnis ''alexa-fhem.old'' gelöscht 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 | Skill Id bestimmen]]
# ''oauthClientID'' -> ''Client ID'' dem Abschnitt [[#Login_with_Amazon | 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"
}
]
}

Mehrere Custom Skills lassen sich mit der folgenden Syntax eintragen
"applicationId": [ "amzn1.ask.skill.1" , "amzn1.ask.skill.2" ],
"oauthClientID": [ "amzn1.application-oa2-client.1" , "amzn1.application-oa2-client.1" ]

Danach durch Aufruf von <source lang="bash" style="width:50%;">./bin/alexa</source> den Dienst starten (kein sudo!)

Unter Windows startet man Alexa-Dienst durch <source lang="bash" style="width:50%;">node alexa</source> aus der <code>alex-fhem/bin</code> (also erst z.B. durch <code>cd "<FHEM-Hauptverzeichis>\alexa-fhem\bin"</code> ins richtige Verzeichnis kommen)

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 {{Link2Forum|Topic=60244|Message=517271|LinkText=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:
<source lang="bash" style="width:50%;">sudo chmod 755 /etc/init.d/alexa
sudo update-rc.d alexa defaults</source>

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

Nun folgende Devices anlegen (ggf. einem Raum zuordnen, z.B. AlexaControl):
<source lang="bash" style="width:75%;">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 &")})</source>

==== Alexa-Fhem als Service (systemd) installieren ====
Auf neueren Installationen (z.B. RPi Jessie) wird init.d durch systemd ersetzt. Folgend die Anleitung um alexa-fhem als Service zu installieren auf einem Raspberry Pi mit Jessie.

Zunächst einen neuen Benutzer anlegen unter dem alexa-fhem laufen soll, falls man nicht möchtet dass alexa-fhem z.B. mit dem fhem User ausgeführt wird:

<code lang="bash" style="width:75%;">
sudo useradd -M --system alexa
</code>

Eigentlich braucht der Benutzer keine Gruppen, aber man kann den Benutzer auch der Gruppe <code>dialout</code> hinzufügen (<code>sudo usermod -a -G dialout alexa</code>)

Datei "alexa" unter <code>/etc/default</code> anlegen

# Defaults / Konfigurations Optionen für alexa-fhem
# Wo findet alexa-fhem die config.json Datei?
ALEXA_OPTS=-U /opt/fhem/.alexa

Den Pfad <code>/opt/fhem/.alexa</code> an die Systemgegebenheiten anpassen. Letztendlich kann die config.json irgendwo liegen, hauptsache alexa-fhem weiß wo. Achtung: Natürlich muss der Benutzer auch Zugriff auf das Verzeichnis mit der config als auch das alexa-fhem Verzeichnis haben.

Datei "alexa.service" unter <code>/etc/systemd/system</code> anlegen:

[Unit]
Description=Node.js Alexa Server
After=syslog.target network-online.target

[Service]
Type=simple
User=alexa #oder ein anderer Benutzer wie fhem
EnvironmentFile=/etc/default/alexa
# oder wo auch immer eure alexa-fhem liegt
ExecStart=/opt/fhem/alexa-fhem/bin/alexa $ALEXA_OPTS
Restart=on-failure
RestartSec=10
KillMode=process

[Install]
WantedBy=multi-user.target

Um den Service zu aktiveren und zu starten helfen folgende Befehle:
sudo systemctl daemon-reload
sudo systemctl enable alexa
sudo systemctl start alexa

Status abfragen mit
sudo systemctl status alexa

Log einsehen?
sudo journalctl -u alexa

(mit <code>-f</code> kann man den follow Modus aktivieren, wie <code>tail -f</code>).
Bei einen reboot startet alexa-fhem jetzt automatisch.

==== 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
<code>https://<IP-Adresse des Servers>:3000</code> kann man testen, ob der Alexa-Fhem Service läuft - der Seitenaufruf liefert eine Zeile JSON-Code, beginnend mit
<code>{"header":{"name":"UnsupportedOperationError"...</code>

=== 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:
<source lang="bash" style="width:70%;">define MyAlexa alexa</source>

<hr>

=== Alexa Skills ===
Für folgende Schritte muss man unter der Adresse http://developer.amazon.com angemeldet sein
# Anmeldung auswählen [[Datei:Developer.amazon.com-01-login2.png|200px]]
# Anmeldedaten eingeben [[Datei:Developer.amazon.com-02-userpass2.png|200px]]

==== 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'' [[Datei:Developer.amazon.com-03-apps_and_services.png|200px]]
# Anschließend auswählen ''Security Profiles'' [[Datei:Developer.amazon.com-05-apps_and_services_-_security_profiles.png|200px]]
# Auswählen ''Create a New Security Profile'' aus [[Datei:Developer.amazon.com-06-apps_and_services_-_create_a_new_security_profile.png|200px]]
# Dann einen Namen und eine Beschreibung für das Profil eingeben und mit ''Save'' bestätigen [[Datei:Developer.amazon.com-07-apps_and_services_-_security_profile_management.png|200px]]

===== Login with Amazon =====
{{Randnotiz|RNTyp=[g|Info]|RNText=Hier wird beschrieben, wo ''Client Id'' und ''Client Secret'' zu finden sind}}
# Oben rechts auf ''Login with Amazon'' klicken. [[Datei:Developer.amazon.com-08-login_with_amazon.png|200px]]
# Auf der neu geladenen Seite auswählen ''Sign up'' [[Datei:Developer.amazon.com-09-login_with_amazon_-_sign_up.png|200px]]
# Anschließend im Dropdown Menü das vorher angelegte Profil auswählen und mit ''Confirm'' bestätigen [[Datei:Developer.amazon.com-10-login_with_amazon_-_create_new_profile.png|200px]] [[Datei:Developer.amazon.com-11-login_with_amazon_-_create_new_profile2.png|200px]]
# Im folgenden Fenster die Adresse [https://www.amazon.com/gp/help/customer/display.html?nodeId=468496 https://www.amazon.com/gp/help/customer/display.html?nodeId=468496] eingeben und mit ''Save'' bestätigen. '''Todo Erklärungsbedarf: WARUM diese Adresse''' [[Datei:Developer.amazon.com-12-login_with_amazon_-_enter_consent_screen_information.png|200px]]
# Anschließend bei dem neu angelegten Eintrag auf der rechten Seite auf das Zahnrad klicken und ''Web Settings'' auswählen [[Datei:Developer.amazon.com-13-login_with_amazon_-_web_settings.png|200px]]
# Im neu geladenen Fenster anklicken von ''Edit'' [[Datei:Developer.amazon.com-14-login_with_amazon_-_edit.png|200px]]
# Anschließend bei ''Allowed Return URLs'' die folgenden drei Adressen eingeben. ''xxx'' muss hierbei durch den Wert ersetzt werden, der in den beiden Abschnitten [[#SmartHome_Skill_anlegen | SmartHome Skill anlegen]] bzw. [[#Custom_Skill_anlegen | Custom Skill anlegen]] jeweils unter Punkt 4 (Seite ''Configuration'') bei ''Redirect Urls'' am Ende der URLs angezeigt wird
## [https://layla.amazon.co.uk/api/skill/link/xxx https://layla.amazon.co.uk/api/skill/link/xxx]
## [https://pitangui.amazon.com/api/skill/link/xxx https://pitangui.amazon.com/api/skill/link/xxx]
## [https://layla.amazon.com/api/skill/link/xxx https://layla.amazon.com/api/skill/link/xxx]
. [[Datei:Developer.amazon.com-15-login_with_amazon_-_allowed_return_urls.png|200px]]

==== Skills bearbeiten ====
# Im Menü den Punkt ''ALEXA'' auswählen [[Datei:Developer.amazon.com-03-apps_and_services.png|200px]]
# Anschließend im Feld ''Alexa Skills Kit'' auf ''Get started'' klicken [[Datei:Developer.amazon.com-17-alexa_-_alex_skills_kit_-_get_started.png|200px]]

===== SmartHome Skill anlegen =====
# Oben rechts ''Add a New Skill'' auswählen [[Datei:Developer.amazon.com-18-alexa_-_alex_skills_kit_-_add_a_new_skill.png|200px]]
# 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")
#:* ''Payload Version'' -> ''v2 (other devices)'' [[Datei:Developer.amazon.com-19-alexa_-_alex_skills_kit_-_skill_information.png|200px]]
# Die folgende Seite einfach mit ''Next'' überspringen [[Datei:Developer.amazon.com-20-alexa_-_alex_skills_kit_-_interaction_model.png|200px]]
# 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 [[#ARN_der_AWS_Lambda_Funktion_bestimmen | AWS Lambda Funktion]] eintragen.
#:* ''Authorization URL'' -> <code>https://www.amazon.com/ap/oa</code>
#:* ''Client ID'' -> ''Client ID'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1
#:* ''Scope'' -> <code>profile:user_id</code> (wörtlich 1:1 eintragen)
#:* ''Redirect URLs'' - sollten vorbelegt sein
#:* ''Authorization Grant Type'' -> ''Auth Code Grant'' auswählen
#:* ''Access Token URI'' -> <code>https://api.amazon.com/auth/o2/token</code>
#:* ''Client Secret'' -> ''Client Secret'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1
#:* ''Client Authentication Scheme'' -> ''HTTP Basic''
#:* ''Privacy Policy URL'' -> <code>https://www.amazon.com/gp/help/customer/display.html?nodeId=468496</code> 
 [[Datei:Developer.amazon.com-21-alexa_-_alex_skills_kit_-_configuration.png|200px]] [[Datei:Developer.amazon.com-22-alexa_-_alex_skills_kit_-_test.png|200px]]

===== Custom Skill anlegen =====
<ol>
<li> Oben rechts ''Add a New Skill'' auswählen [[Datei:Developer.amazon.com-18-alexa_-_alex_skills_kit_-_add_a_new_skill.png|200px]]</li>
<li> Auf der folgenden Seite (''Skill Information'') die nachstehenden Daten eingeben und dann mit ''Next'' bestätigen:
<ul>
<li> ''Skill Type'' -> ''Custom Interaction Model'' </li>
<li> ''Language'' -> ''German''</li>
<li> ''Name'' -> beliebiger Name, z.B. "MySmartHome Advanced". Dieser wird in der Alexa App unter "Meine Skills" angezeigt.</li>
<li> ''Invocation Name'' -> Aufruf des Skills, unter dem dieser später gestartet wird. Z.B. "Alexa, starte James" [[Datei:CustomSkill_2.PNG|400px]]</li>
</ul></li>
<li>Auf der Seite ''Interaction Model'' folgende Eingaben tätigen und mit ''Next'' abschließen
<ul>
<li>In einem separaten Browserfenster FHEM aufrufen, und für das bereits definierte Alexa-Gerät das Kommando <code>get MyAlexa interactionModel</code> aufrufen. Es erscheint ein Popup-Fenster mit ziemlich vielen Zeilen.
<li>In die Box ''Intent Schema'' kopiert man den ersten Teil dieser FHEM-Ausgabe hinein, also: <blockquote>
{
"intents" : [
<hier ziemlich viele Zeilen>
]
}
</blockquote></li>
<li>Nun die ''Custom Slot Types'' einrichten. Dazu muss aus dem zweiten Teil der FHEM-Ausgabe jeweils der Slot-Type (z.B. <code>FHEM_article</code>) 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.</li>
<li>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 <code>get MyAlexa customSlotTypes</code> ausführen. Auch diese Ausgabe wird, wie oben beschriebeen, in Custom Slot Types eingetragen (erst der TYPE, dann die möglichen Werte)
<li>Anschließend erneut die FHEM-Ausgabe schließen und erneut für das bereits definierte Alexa-Gerät das Kommando <code>get MyAlexa interactionModel</code> aufrufen.
<li>Unter ''Sample Utterances'' nun den Text aus dem dritten Teil dieser FHEM-Ausgabe hineinkopieren [[Datei:CustomSkill_5.PNG|400px]]</li>
</ul></li>
<li>Auf der Seite ''Configuration'' Folgendes eingeben und mit ''Next'' bestätigen:
<ul>
<li>''Service Endpoint Type'' -> ''AWS Lambda'' auswählen</li>
<li>''Geographical Region'' -> ''Europe'' auswählen und im Textfeld den Wert aus Abschnitt [[#AWS_Lambda_Funktion_anlegen | AWS Lambda Funktion anlegen]] (Punkt 12) eintragen. </li>
<li>''Do you allow users to create an account or link to an existing account with you?'' -> ''Yes''</li>
<li>''Authorization URL'' -> <code>https://www.amazon.com/ap/oa</code></li>
<li>''Client ID'' -> ''Client ID'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1</li>
<li>''Scope'' -> <code>profile:user_id</code> (wörtlich 1:1 eintragen)</li>
<li>''Redirect URLs'' - sollten vorbelegt sein</li>
<li>''Authorization Grant Type'' -> ''Auth Code Grant'' auswählen</li>
<li>''Access Token URI'' -> <code>https://api.amazon.com/auth/o2/token</code></li>
<li>''Client Secret'' -> ''Client Secret'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1</li>
<li>''Client Authentication Scheme'' -> ''HTTP Basic''</li>
<li>''Privacy Policy URL'' -> <code>https://www.amazon.com/gp/help/customer/display.html?nodeId=468496</code></li>
</ul>
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 | AWS Lambda Funktion]] nachgetragen werden, dies wird in Abschnitt [[#Trigger_f.C3.BCr_Custom_Skill_hinzuf.C3.BCgen | Trigger für Custom Skill hinzufügen]] beschrieben.
 [[Datei:CustomSkill_6.PNG|400px]] [[Datei:CustomSkill_7.PNG|400px]]</li>

==== 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 | Custom Skill Anlegen]] unter Punkt 2 eingetragen hat.

==== Skill Id bestimmen ====
{{Randnotiz|RNTyp=[g|Info]|RNText=Hier wird beschrieben, wo die ''Alexa Skill Id'' zu finden ist}}
Für das [[#AWS_Lamba_Funktion_anlegen | Anlegen einer ''AWS Lambda Funktion'']] bzw für die [[#Alexa-Fhem_konfigurieren | Konfiguration von Alexa-Fhem]] wird die ''Alexa Skill Id'' benötigt. An diese kommt man wie folgt:
# Anmelden wie unter [[#Alexa_Skills | Alexa Skills]] beschrieben.
# Menüpunkt ''ALEXA'' auswählen, wie [[#Skills_bearbeiten | Skills bearbeiten]] erklärt.
# Beim gewünschten Eintrag auf ''Edit'' klicken [[Datei:Developer.amazon.com-23-alexa_-_alex_skills_kit_-_overview.png|200px]]
# Die Id, die nun oben angezeigt wird, ist die gesuchte. Sie hat typischerweise das Format <code>amzn1.ask.skill.[Zahlen und Bindestriche]</code> [[Datei:Aws.amazon.com-06-configure_triggers2.png|200px]]

<hr>

=== AWS Lambda Funktion ===
Für folgende Schritte muss man unter der Adresse http://aws.amazon.com angemeldet sein
# Anmeldung auswählen [[Datei:Aws.amazon.com-01-site.png|200px]]
# Anmeldedaten eingeben [[Datei:Aws.amazon.com-02-login.png|200px]]
# Den Punkt ''Lambda'' links auf der Startseite auswählen, bzw. im Menü ''Services'' unter ''Compute'' den Menüpunkt ''Lambda'' auswählen [[Datei:Aws.amazon.com-03-lambda.png|200px]]
==== AWS Lambda Funktion anlegen ====
# Für eine erste Lambda-Funktion den Punkt ''Get Started Now'' auswählen [[Datei:Aws.amazon.com-04-get_started_now.png|200px]]
# Den Blueprint ''Blank function'' auswählen [[Datei:Aws.amazon.com-05-select_blueprint.png|200px]]
# Im neuen Fenster dann auf den gestrichelten Kasten klicken und ''Alexa Smart Home'' auswählen und mit ''Next'' bestätigen [[Datei:Aws.amazon.com-06-configure_triggers1.png|200px]]
## 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 | Skill Id bestimmen]] beschrieben wird, den Haken bei ''Enable trigger'' setzen und mit ''Next'' bestätigen [[Datei:Aws.amazon.com-06-configure_triggers3.png|200px]]
# Auf der Konfigurationsseite eingeben:
## ''Name'' -> ''FHEM''
## ''Runtime'' -> Node.js 4.3.
## ''Role'' -> ''Choose an existing role''
### 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_installieren | 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. [[Datei:Aws.amazon.com-07-configure_function.png|200px]]
# Auf der Übersichtsseite dann ''Create function'' anklicken [[Datei:Aws.amazon.com-08-review.png|200px]]

==== 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 [[Datei:Aws.amazon.com-09-go_overview.png|200px]]
# Anschließend den Radiobutton der angelegten Funktion ''FHEM'' markieren und im Menü ''Action'' den Punkt ''Show ARN'' auswählen [[Datei:Aws.amazon.com-10-1-show_arn.png|200px]]
# Es wird nun eine ARN Adresse angezeigt, die für den Abschnitt [[#SmartHome_Skill_anlegen| SmartHome Skill anlegen]] benötigt wird [[Datei:Aws.amazon.com-10-2-arn.png|200px]]

=== Absichern des Zugriffs ===
Natürlich muss der Zugriff auf den von Alexa-Fhem verwendeten Port (default: 3000, Bestandteil des Codes in der AWS Lambda-Funktion) durch die Firewall freigeschaltet werden (auf einer FritzBox unter "Portfreigaben").

==== Absicherung direkt in Alexa-FHEM ====
Die Kommunikation zwischen Amazon AWS und Alexa-FHEM ist auf die folgenden Arten gesichert:
* Die Verbindung erfolgt per HTTPS
* Es werden nur Verbindung angenommen auf denen ein gültiges Alexa-Event gesendet wird.
* Es werden nur Verbindungen angenommen die ein gültiges und noch nicht abgelaufenes OAuth-Token enthalten. Jedes neue Token wird live bei Amazon auf Gültigkeit geprüft.
* Es werden nur Verbindungen mit lokal konfigurierter Skill-ID angenommen.
* Es ist nicht möglich von außen beliebige FHEM Kommandos zu senden. Die FHEM Kommandos werden nur lokal erzeugt.

Wer möchte kann Alexa-FHEM natürlich noch weiter absichern. Es gilt aber, dass nicht jedes zusätzliche Glied in der Kette die Sicherheit sondern unter Umständen nur die Angriffsfläche erhöht. Ein falsch konfigurierter und nach aussen offener Apache (oder anderer ReverseProxy) ist unter Umständen ein größeres Risiko als Alexa-FHEM alleine.

==== Absicherung per ReverseProxy ====
<s>Die Kommunikation zwischen Amazon und FHEM ist wegen der Verwendung von SSL schon verschlüsselt - prinzipiell kann aber jeder von außen mit Alexa-Fhem kommunizieren. Man sollte sich deshalb im Klaren darüber sein, dass dies eine Sicherheitslücke darstellt:</s> Jeder offene Port verleitet zu Angriffen, und mit zunehmender Verbreitung von Alexa steigt auch das Risiko. Es wird deshalb empfohlen, vor den eigentlichen Alexa-Server zur Absicherung einen Apache-Webserver als ReverseProxy zu setzen. Nicht nur ist der Apache eine hervorragend stabile und seit Jahrzehnten getestete Software, sondern die Konfiguration als ReverseProxy erlaubt auch, den Zugriff auf den Alexa-Fhem-Rechner auf die Amazon-Maschinen zu beschränken.

'''Achtung: Dies ist keine allgemeine Anleitung in Sachen Computersicherheit.''' Im Folgenden gehen wir davon aus, dass
* Grundbegriffe wie Firewall, IP-Ports, SSL und Dynamic DNS vertraut sind
* Ein Apache Webserver (idealerweise auf einer zweiten Maschine) bereits installiert ist und die Konfiguration verstanden wurde (wenn nicht: Es gibt im Netz ''tausende'' von Anleitungen dafür...)
* Ein Servername von einem DynDNS-Anbieter - sagen wir ''myhome.is-my-castle.com'' - bereits von ''außen'' auf unser SmartHome zeigt.
* Alexa-Fhem in einer der oben beschriebenen Basiskonfigurationen läuft, d.h. der Zugriff auf <code>https://myhome.is-my-castle.com:3000</code> ergibt, wie im Punkt [[#Alexa-Fhem_testen|Alexa-Fhem testen]] beschrieben, eine Antwort des Node.js Servers.

Als erster Schritt zur Absicherung muss das ReverseProxy Modul für den Apache installiert und mit <code>a2enmod</code> aktiviert werden, hierzu sei auf [https://www.digitalocean.com/community/tutorials/how-to-use-apache-http-server-as-reverse-proxy-using-mod_proxy-extension diese Anleitung] verwiesen. Der zweite Schritt besteht darin, den SSL-Zugriff durch ein Passwort abzusichern. Dazu wird auf dem Apache-Rechner das Programm
htpasswd <passwdfile> <username>
ausgeführt, das Programm fragt dann nach dem gewünschten Passwort. Wir nehmen im Folgenden an, dass das Passwortfile ''/etc/apache2/htpasswd'' ist, der gesetzte Username ''alexa'' lautet und das Passwort ''my_smarthome'' ist.

Im dritten Schritt wird nun in das Apache-Konfigurationsfile die Weiterleitung auf den eigentlichen Alexa-Fhem-Rechner eingetragen. Dazu wählen wir, dass von außen der Standard-SSL-Port 443 benutzt werden soll, sowie als Verzeichnisname ''/alexa''. '''Achtung:''' Dieser Code soll '''nicht''' in die Default-Konfiguration des Apache-Webservers. Sondern in eine separate Datei (Dateiname z.B. "fhem"), die ins Unterverzeichnis /etc/apache2/conf.d gestellt wird.

<VirtualHost *:443>
ServerName myhome.is-my-castle.com
SSLEngine on
SSLProxyEngine on
SSLProxyCheckPeerCN off
SSLProxyCheckPeerName off
SSLCertificateKeyFile /etc/apache2/mycert/server.key
SSLCertificateFile /etc/apache2/mycert/server.crt
<Location /alexa>
AuthType Basic
AuthName "Authentication Required"
AuthUserFile "/etc/apache2/htpasswd"
Require valid-user
ProxyPass https://<hier IP-Adresse des Alexa-Fhem-Rechners>:3000/
ProxyPassReverse https://<hier IP-Adresse des Alexa-Fhem-Rechners>:3000/
Order deny,allow
Allow from All
</Location>
(... Hier eventuell weitere Umleitungen)
</VirtualHost>
Nach einem Neustart des Apache-Servers, dem Schließen des Ports 3000 in der Firewall sowie dem Öffnen des Ports 443 ist der Alexa-Fhem-Rechner von außen nur noch erreichbar durch den Aufruf von <code>https://myhome.is-my-castle.com/alexa</code> und verlangt unmittelbar die Eingabe von Username und Passwort.

Der vierte Schritt ist nun, den Code der AWS Lambda-Funktion an fünf Stellen zu verändern
'''const PORT=443;'''
const HOST='myhome.is-my-castle.com';
'''const PATH='/alexa';'''
'''const AUTH='alexa:my_smarthome';'''
// entry
exports.handler = function(event, context, callback) {
console.log(`EVENT: ${event}`);
console.log(`CONTEXT: ${context}`);
var post_data = JSON.stringify(event);
var options = {
hostname: HOST,
port: PORT,
//family: 6,
'''path: PATH,'''
method: 'POST',
'''auth: AUTH,'''
rejectUnauthorized: false, // accept self-signed
(etc., Rest des Codes wie gehabt)
Natürlich muss der Zugriff getestet werden. Bei Beachtung aller dieser Schritte werden alle un-autorisierten Zugriffe von außen abgewehrt. Eine noch weiter gehende Sicherung ist möglich, dazu kann in der Serverkonfiguration der Zugriff auf die Amazon-Domains beschränkt werden. Das ganze Alexa-System ist aber noch in konstanter Weiterentwicklung, diese Domain-Namen können sich also noch ändern.

== 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 [http://alexa.amazon.de 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 [[Datei:Alexa.amazon.de-01-startseite.png|200px]]
# Oben rechts ''Meine Skills'' bzw. ''Ihre Skills'' auswählen [[Datei:Alexa.amazon.de-03-meine_skills.png|200px]]
# In der Liste der Skills sollte das angelegte FHEM Skill angezeigt werden. Dieses anklicken [[Datei:Alexa.amazon.de-02-liste_skills.png|200px]]
# Oben Rechts in den Details des Skills auf ''Skill aktivieren'' klicken [[Datei:Alexa.amazon.de-04-skill_details.png|200px]]
# In dem neu geöffneten Fenster die Autorisierung bestätigen [[Datei:Alexa.amazon.de-05-amazon_auth.png|200px]]
# Anschließend sollte die Verbindung erfolgreich aufgebaut worden sein [[Datei:Alexa.amazon.de-06-success.png|200px]]

=== Geräte ===
# Auf http://alexa.amazon.de anmelden
# Auf ''Smart Home'' klicken [[Datei:Alexa.amazon.de-01-startseite.png|200px]]
# Anschließend den Punkt ''Geräte suchen'' anklicken [[Datei:Alexa.amazon.de-07-Gerätesuche.png|200px]]
# 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
*** <code><cmd>:<device>:<reading></code>, hier können nicht verwendete Elemente von links nach rechts weg gelassen werden.
*** <code><name>=<value></code>, hier kann <code><value></code> entweder ein Wert oder semikolonseparierte Liste sein.
*** Oder dem schlüsselwort <code>clear</code>, welches alle vorhandenen (default) Parameter dieser Characteristik löscht. <code>clear</code> 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 | 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 | Custom Skill Anlegen]]).

Der Aufruf dieses Gerätes mit Alexa erfolgt dann z.B. mit den Sätzen
<pre style="width:50%;">
"Alexa, sage <Custom Skill Invocation Name>: Stelle Weckzeit auf Neunzehn Uhr Siebenundzwanzig"
"Alexa, frage <Custom Skill Invocation Name> nach dem Status von Weckzeit"
</pre>
Dabei ist natürlich der ''Custom Skill Invocation Name'' durch den Wert zu ersetzen, den man im Abschnitt [[#Custom_Skill_anlegen | 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 [https://www.dpunkt.de/buecher/12387/9783960090120-smarthome-hacks.html 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\');
}
}

<hr>

=== 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
<pre>
"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
</pre>
* 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
<pre>
"Alexa, sage <Custom Skill Invocation Name>: schalte (die) Beleuchtung an" -> LightScene Alle_An wird ausgewählt
</pre>
Dafür wird es aber auch möglich sein direkt die SzenenNamen im gesprochenen Kommando zu verwenden und so auf die Umwege über dummys und ähnliches zu verzichten.

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.

Zwei andere Ansätze Lichtszenen zu schalten die ohne DOIF auskommen sind im Folgenden beschrieben:

* Wenn es von Interesse ist die Steuerung mit einer Darstellung in FTUI zu verbinden: Statt der oben beschriebenen dummy Devices kann man readingsProxy Devices mit passenden setFn und valueFn analog zum [[Harmony#Button_f.C3.BCr_eine_bestimmte_Activity_im_Frontend_und_Homekit_.C3.BCber_readingsProxy|diesem Beispiel für harmony aktivitäten]] verwenden.

* Für jede zu schaltende Szene wird ein dummy angelegt dessen homebridgeMapping direkt auf das LightScene Device zeigt:

define <dummy> dummy
attr <dummy> setList on off
attr <dummy> genericDeviceType switch
attr <dummy> homebridgeMapping On=<light scene>::state,valueOn=<szene>,cmdOn=scene+<szene>,cmdOff=scene+<szene aus>

Bei der zweiten Variante wird davon ausgegangen das der aktuelle status nicht abgefragt oder angezeigt werden soll. Deshalb gibt es keine direkte RadioButton Funktionalität.

== 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 [http://alexa.amazon.de/spa/index.html] 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:
<pre style="width:50%;">
“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”
</pre>

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

Das Prinzip der Kommandokonfiguration ist {{Link2Forum|Topic=60244|Message=532513|LinkText=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:
<pre style="width:50%;">
const PORT=3000;
const HOST='mein.host.name';
</pre>

====Freigabe von Port 3000====
{{Randnotiz|RNTyp=Fehl|RNText=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: [[Homebridge_einrichten#NodeJS_installieren|NodeJS installieren]] sowie [[Homebridge_einrichten#Python.2C_g.2B.2B.2C_MDNS_installieren|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<source lang="bash" style="width:50%;">node -v</source>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 <code>~/.alexa/config.json</code> die folgenden Zeilen rauslöschen:

<pre>
"nat-pmp": "10.0.1.1",
"nat-upnp": true,
</pre>

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:
<source lang="bash" style="width:70%;">2755327 4 -rwxr-xr-x 1 pi pi 339 Nov 26 23:20 alexa</source>
Sollte dies nicht der Fall sein bitte mit:
<source lang="bash" style="width:70%;">chmod +x alexa</source>
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 <code>~/.alexa/config.json</code> geöffnet werden und der Abschnitt "connections" um folgende Zeile ergänzt werden:<pre>
"auth": {"user": "fhem", "pass": "fhempassword"},</pre>
Bei Verwendung von SSL bei FHEM muss auch noch <pre>
"ssl": true,</pre> hinzugefügt werden

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

Alexa-Fhem

2017-07-19T11:38:46Z

DR: /* SmartHome Skill anlegen */

'''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 [https://forum.fhem.de/index.php?action=profile;u=430 justme1968] im {{Link2Forum|Topic=60244|LinkText=Forum}} veröffentlicht.
Das ist eine erste Version der Dokumentation zur Installation und Einrichtung, eine Erweiterung wird sicherlich in nächster Zeit noch folgen.
{{Infobox Modul
|ModPurpose=Anbindung von FHEM an Amazon Assistent Alexa
|ModType=x
|ModTechName=
|ModForumArea=Frontends/Sprachsteuerung
|ModOwner=justme1968
}}

==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.{{Randnotiz|RNTyp=r|RNText=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'''.
*Card bezeichnet einen Eintrag in der Alexa-App, der die erkannte Sprachnachricht sowie weiter gehenden Informationen über die Reaktion von Alexa enzthält und Rückmeldung an Amazon erlaubt.
*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===
[[Datei:2gpXyLN.jpg|200px|thumb|right|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 <code>lambda.js</code> code an alexa-fhem weitergeleitet
*alexa-fhem steuert FHEM und sendet ein Antwort-Event zurück
*<code>lambda.js</code> 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-Fhem#Smart_Home|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-Fhem#Custom|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==
{{Randnotiz|RNTyp=[g|Info]|RNText=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:
<source lang="bash" style="width:50%;">
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install build-essential libssl-dev</source>

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:
<source lang="bash" style="width:50%;">
curl -sL https://deb.nodesource.com/setup_4.x | sudo -E bash -
sudo apt-get install -y nodejs
</source>

=== Alexa-Fhem installieren ===
'''Aus gegebenem Anlass: Dies ist weder eine Einführung in Linux, noch eine Anfängerdokumentation für FHEM.''' Also erst die Grundlagen lernen, und dann mit Alexa beginnen !

Die aktuelle Version ist jeweils {{Link2Forum|Topic=60244|Message=540117|LinkText=hier}} zu finden.

====Erstinstallation====
Hier wird die Erstinstallation von Alexa-Fhem beschrieben.
===== Linux =====
# Die tgz-Datei unter Linux im Hauptverzeichnis von FHEM (typischerweise <code>/opt/fhem</code>) entpacken (''nicht'' unter Windows, das zerstört die Rechteeinstellungen).
# Das dabei entstandene Verzeichnis ''package'' in ''alexa-fhem'' umbenennen <source lang="bash" style="width:50%;">mv package alexa-fhem</source>
# Durch <source lang="bash" style="width:50%;">cd alexa-fhem</source> in das Verzeichnis wechseln
# Mit <source lang="bash" style="width:50%;">npm install</source> alle Abhängigkeiten installieren (kein sudo!).
# SSL Zertifikat erzeugen durch Aufruf von <source lang="bash" style="width:50%;">./createKey.sh</source> (kein sudo!). Hierbei beachten, dass ein Kennwort vergeben werden muss, das mindestens aus 4 Zeichen besteht, dieses Kennwort bitte merken.
# Das Verzeichnis ''.alexa'' anlegen, ''und zwar im Home-Verzeichnis desjenigen Benutzers, unter dem Alexa-Fhem laufen soll.'' Insbesondere ist zu beachten, dass dieser Nutzer u.U. im Startskript explizit gesetzt wird. Mit dem untenstehenden Skript ist das ''nicht'' der User fhem, sondern der User ''pi''. Das Symbol ''~/'' verweist auf das Home-Verzeichnis des Benutzers, der gerade die Installation vornimmt.
# Die Datei ''config-sample.json'' nach ''.alexa/config.json'' kopieren. Achtung: Installiert man alexa-fhem als root-user, zeigt das Symbol ''~/'' auf ''/root'' - und die Konfigurationsdatei 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.
===== Windows =====
''Vor'' der Installation von Alexa-Fhem muss man folgende Anwendungen installieren:
* Node.js (die aktuelle Version findet man unter https://nodejs.org/en/download/)
* OpenSSL (http://slproweb.com/products/Win32OpenSSL.html oder https://www.heise.de/download/product/win32-openssl-47316/download)
Erst dann fängt man mit Alexa-Fhem an.

# Die tgz-Datei im Hauptverzeichnis von FHEM (z.B. <code>С:\Program Files (x86)\fhem</code>) entpacken.
# Das dabei entstandene Verzeichnis ''package'' in ''alexa-fhem'' umbenennen
# Windows-Shell (Kommandozeile, Eingabeaufforderung usw.) öffnen. "Start" -> "Ausführen" (oder [Windows-Taste]+[R]) -> cmd -> Ok. Durch <source lang="bash" style="width:50%;">cd "<FHEM-Hauptverzeichis>\alexa-fhem"</source> in das Verzeichnis wechseln. Dabei ist natürlich der <FHEM-Hauptverzeichis> durch den entsprechenden Pfad aus dem Schritt 1 zu ersetzen. Im o.g. Beispiel wäre es <code>cd "С:\Program Files (x86)\fhem\alexa-fhem"</code>
# Mit <source lang="bash" style="width:50%;">npm install</source> alle Abhängigkeiten installieren. Bei der Felermedlung wie "Der Befehl "npm" ist entweder falsch geschrieben oder konnte nicht gefunden werden." ist die Installation von Node.js zu überprüfen.
# SSL Zertifikat erzeugen. Dafür muss man alle Befehle aus dem Skript ''createKey.sh'' nacheinander manuell ausführen. Hierbei beachten, dass ein Kennwort vergeben werden muss, das mindestens aus 4 Zeichen besteht, dieses Kennwort bitte merken. Der Windows-Welt unbekannter Befehl <code>mv</code> ist durch <code>move /y</code> zu ersetzen:<source lang="bash" style="width:50%;">openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365</source><source lang="bash" style="width:50%;">openssl rsa -in key.pem -out newkey.pem</source><source lang="bash" style="width:50%;">move /y newkey.pem key.pem</source> Eventuelle Fehlermeldung "can't open config file: /usr/local/ssl/openssl.cnf" o.Ä. lässt sich durch Befehl <code>set OPENSSL_CONF=<OpenSSL-Verzeichnis>\bin\openssl.cfg</code> beheben, wobei <OpenSSL-Verzeichnis> durch den entsprechenden Installationspfad (typischerweise <code>c:\OpenSSL-Win32</code>) zu ersetzen ist.
# Das Verzeichnis ''.alexa'' anlegen, ''und zwar im Benutzerverzeichnis desjenigen Benutzers, unter dem Alexa-Fhem laufen soll.'' In aktuellen Versionen von Windows (ab Windows 7 bzw. ab Windows Server 2008 R2) liegt das Verzeichnis unter <code>C:\Users\<Benutzername></code>, also z.B. für Benutzer "Administrator" - unter <code>C:\Users\Administrator</code>. Falls Windows sich weigert das Verzichniss mit dem Punkt am Anfang zu erstellen, kann man das aus der Kommandozeile machen:<source lang="bash" style="width:50%;">cd "C:\Users\<Benutzername>"</source><source lang="bash" style="width:50%;">
mkdir ".alexa"</source>
# Die Datei ''config-sample.json'' nach ''C:\Users\<Benutzername>.alexa/config.json'' kopieren.
# Achtung: Ggf. müssen auch die Dateien key.pem und cert.pem ins entsprechende Verzeichnis (<code>"<FHEM-Hauptverzeichis>\alexa-fhem\bin</code>) kopiert werden.

====Update====
Hier wir das Update auf eine neue Version von Alexa-Fhem beschrieben
# Das Verzeichnis ''alexa-fhem'' im Hauptverzeichnis von FHEM (typischerweise <code>/opt/fhem</code>) umbenennen in ''alexa-fhem.old''.
# Die tgz-Datei der neuen Alexa-Fhem-Version unter Linux im Hauptverzeichnis von FHEM (typischerweise <code>/opt/fhem</code>) entpacken (''nicht'' unter Windows, das zerstört die Rechteeinstellungen).
# Das dabei entstandene Verzeichnis ''package'' in ''alexa-fhem'' umbenennen, in das Verzeichnis wechseln
# Mit <source lang="bash" style="width:50%;">npm install</source> alle Abhängigkeiten installieren (kein sudo!).
# Die Zertifikatsdateien key.pem und cert.pem aus dem alten Verzeichnis ''alexa-fhem.old'' ins neue Verzeichnis ''alexa-fhem'' kopieren.
Natürlich dann den Dienst neu starten, auch müssen selbstredend irgendwelche Modifikationen an der Datei server.js in der neuen Version nachgezogen werden. Wenn alles läuft, kann das alte Verzeichnis ''alexa-fhem.old'' gelöscht 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 | Skill Id bestimmen]]
# ''oauthClientID'' -> ''Client ID'' dem Abschnitt [[#Login_with_Amazon | 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"
}
]
}

Mehrere Custom Skills lassen sich mit der folgenden Syntax eintragen
"applicationId": [ "amzn1.ask.skill.1" , "amzn1.ask.skill.2" ],
"oauthClientID": [ "amzn1.application-oa2-client.1" , "amzn1.application-oa2-client.1" ]

Danach durch Aufruf von <source lang="bash" style="width:50%;">./bin/alexa</source> den Dienst starten (kein sudo!)

Unter Windows startet man Alexa-Dienst durch <source lang="bash" style="width:50%;">node alexa</source> aus der <code>alex-fhem/bin</code> (also erst z.B. durch <code>cd "<FHEM-Hauptverzeichis>\alexa-fhem\bin"</code> ins richtige Verzeichnis kommen)

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 {{Link2Forum|Topic=60244|Message=517271|LinkText=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:
<source lang="bash" style="width:50%;">sudo chmod 755 /etc/init.d/alexa
sudo update-rc.d alexa defaults</source>

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

Nun folgende Devices anlegen (ggf. einem Raum zuordnen, z.B. AlexaControl):
<source lang="bash" style="width:75%;">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 &")})</source>

==== Alexa-Fhem als Service (systemd) installieren ====
Auf neueren Installationen (z.B. RPi Jessie) wird init.d durch systemd ersetzt. Folgend die Anleitung um alexa-fhem als Service zu installieren auf einem Raspberry Pi mit Jessie.

Zunächst einen neuen Benutzer anlegen unter dem alexa-fhem laufen soll, falls man nicht möchtet dass alexa-fhem z.B. mit dem fhem User ausgeführt wird:

<code lang="bash" style="width:75%;">
sudo useradd -M --system alexa
</code>

Eigentlich braucht der Benutzer keine Gruppen, aber man kann den Benutzer auch der Gruppe <code>dialout</code> hinzufügen (<code>sudo usermod -a -G dialout alexa</code>)

Datei "alexa" unter <code>/etc/default</code> anlegen

# Defaults / Konfigurations Optionen für alexa-fhem
# Wo findet alexa-fhem die config.json Datei?
ALEXA_OPTS=-U /opt/fhem/.alexa

Den Pfad <code>/opt/fhem/.alexa</code> an die Systemgegebenheiten anpassen. Letztendlich kann die config.json irgendwo liegen, hauptsache alexa-fhem weiß wo. Achtung: Natürlich muss der Benutzer auch Zugriff auf das Verzeichnis mit der config als auch das alexa-fhem Verzeichnis haben.

Datei "alexa.service" unter <code>/etc/systemd/system</code> anlegen:

[Unit]
Description=Node.js Alexa Server
After=syslog.target network-online.target

[Service]
Type=simple
User=alexa #oder ein anderer Benutzer wie fhem
EnvironmentFile=/etc/default/alexa
# oder wo auch immer eure alexa-fhem liegt
ExecStart=/opt/fhem/alexa-fhem/bin/alexa $ALEXA_OPTS
Restart=on-failure
RestartSec=10
KillMode=process

[Install]
WantedBy=multi-user.target

Um den Service zu aktiveren und zu starten helfen folgende Befehle:
sudo systemctl daemon-reload
sudo systemctl enable alexa
sudo systemctl start alexa

Status abfragen mit
sudo systemctl status alexa

Log einsehen?
sudo journalctl -u alexa

(mit <code>-f</code> kann man den follow Modus aktivieren, wie <code>tail -f</code>).
Bei einen reboot startet alexa-fhem jetzt automatisch.

==== 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
<code>https://<IP-Adresse des Servers>:3000</code> kann man testen, ob der Alexa-Fhem Service läuft - der Seitenaufruf liefert eine Zeile JSON-Code, beginnend mit
<code>{"header":{"name":"UnsupportedOperationError"...</code>

=== 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:
<source lang="bash" style="width:70%;">define MyAlexa alexa</source>

<hr>

=== Alexa Skills ===
Für folgende Schritte muss man unter der Adresse http://developer.amazon.com angemeldet sein
# Anmeldung auswählen [[Datei:Developer.amazon.com-01-login2.png|200px]]
# Anmeldedaten eingeben [[Datei:Developer.amazon.com-02-userpass2.png|200px]]

==== 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'' [[Datei:Developer.amazon.com-03-apps_and_services.png|200px]]
# Anschließend auswählen ''Security Profiles'' [[Datei:Developer.amazon.com-05-apps_and_services_-_security_profiles.png|200px]]
# Auswählen ''Create a New Security Profile'' aus [[Datei:Developer.amazon.com-06-apps_and_services_-_create_a_new_security_profile.png|200px]]
# Dann einen Namen und eine Beschreibung für das Profil eingeben und mit ''Save'' bestätigen [[Datei:Developer.amazon.com-07-apps_and_services_-_security_profile_management.png|200px]]

===== Login with Amazon =====
{{Randnotiz|RNTyp=[g|Info]|RNText=Hier wird beschrieben, wo ''Client Id'' und ''Client Secret'' zu finden sind}}
# Oben rechts auf ''Login with Amazon'' klicken. [[Datei:Developer.amazon.com-08-login_with_amazon.png|200px]]
# Auf der neu geladenen Seite auswählen ''Sign up'' [[Datei:Developer.amazon.com-09-login_with_amazon_-_sign_up.png|200px]]
# Anschließend im Dropdown Menü das vorher angelegte Profil auswählen und mit ''Confirm'' bestätigen [[Datei:Developer.amazon.com-10-login_with_amazon_-_create_new_profile.png|200px]] [[Datei:Developer.amazon.com-11-login_with_amazon_-_create_new_profile2.png|200px]]
# Im folgenden Fenster die Adresse [https://www.amazon.com/gp/help/customer/display.html?nodeId=468496 https://www.amazon.com/gp/help/customer/display.html?nodeId=468496] eingeben und mit ''Save'' bestätigen. '''Todo Erklärungsbedarf: WARUM diese Adresse''' [[Datei:Developer.amazon.com-12-login_with_amazon_-_enter_consent_screen_information.png|200px]]
# Anschließend bei dem neu angelegten Eintrag auf der rechten Seite auf das Zahnrad klicken und ''Web Settings'' auswählen [[Datei:Developer.amazon.com-13-login_with_amazon_-_web_settings.png|200px]]
# Im neu geladenen Fenster anklicken von ''Edit'' [[Datei:Developer.amazon.com-14-login_with_amazon_-_edit.png|200px]]
# Anschließend bei ''Allowed Return URLs'' die folgenden drei Adressen eingeben. ''xxx'' muss hierbei durch den Wert ersetzt werden, der in den beiden Abschnitten [[#SmartHome_Skill_anlegen | SmartHome Skill anlegen]] bzw. [[#Custom_Skill_anlegen | Custom Skill anlegen]] jeweils unter Punkt 4 (Seite ''Configuration'') bei ''Redirect Urls'' am Ende der URLs angezeigt wird
## [https://layla.amazon.co.uk/api/skill/link/xxx https://layla.amazon.co.uk/api/skill/link/xxx]
## [https://pitangui.amazon.com/api/skill/link/xxx https://pitangui.amazon.com/api/skill/link/xxx]
## [https://layla.amazon.com/api/skill/link/xxx https://layla.amazon.com/api/skill/link/xxx]
. [[Datei:Developer.amazon.com-15-login_with_amazon_-_allowed_return_urls.png|200px]]

==== Skills bearbeiten ====
# Im Menü den Punkt ''ALEXA'' auswählen [[Datei:Developer.amazon.com-03-apps_and_services.png|200px]]
# Anschließend im Feld ''Alexa Skills Kit'' auf ''Get started'' klicken [[Datei:Developer.amazon.com-17-alexa_-_alex_skills_kit_-_get_started.png|200px]]

===== SmartHome Skill anlegen =====
# Oben rechts ''Add a New Skill'' auswählen [[Datei:Developer.amazon.com-18-alexa_-_alex_skills_kit_-_add_a_new_skill.png|200px]]
# 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")
#:* ''Payload Version'' -> ''v2 (other devices)'' [[Datei:Developer.amazon.com-19-alexa_-_alex_skills_kit_-_skill_information.png|200px]]
# Die folgende Seite einfach mit ''Next'' überspringen [[Datei:Developer.amazon.com-20-alexa_-_alex_skills_kit_-_interaction_model.png|200px]]
# 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 [[#ARN_der_AWS_Lambda_Funktion_bestimmen | AWS Lambda Funktion]] eintragen.
#:* ''Authorization URL'' -> <code>https://www.amazon.com/ap/oa</code>
#:* ''Client ID'' -> ''Client ID'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1
#:* ''Scope'' -> <code>profile:user_id</code> (wörtlich 1:1 eintragen)
#:* ''Redirect URLs'' - sollten vorbelegt sein
#:* ''Authorization Grant Type'' -> ''Auth Code Grant'' auswählen
#:* ''Access Token URI'' -> <code>https://api.amazon.com/auth/o2/token</code>
#:* ''Client Secret'' -> ''Client Secret'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1
#:* ''Client Authentication Scheme'' -> ''HTTP Basic''
#:* ''Privacy Policy URL'' -> <code>https://www.amazon.com/gp/help/customer/display.html?nodeId=468496</code> 
 [[Datei:Developer.amazon.com-21-alexa_-_alex_skills_kit_-_configuration.png|200px]] [[Datei:Developer.amazon.com-22-alexa_-_alex_skills_kit_-_test.png|200px]]

===== Custom Skill anlegen =====
<ol>
<li> Oben rechts ''Add a New Skill'' auswählen [[Datei:Developer.amazon.com-18-alexa_-_alex_skills_kit_-_add_a_new_skill.png|200px]]</li>
<li> Auf der folgenden Seite (''Skill Information'') die nachstehenden Daten eingeben und dann mit ''Next'' bestätigen:
<ul>
<li> ''Skill Type'' -> ''Custom Interaction Model'' </li>
<li> ''Language'' -> ''German''</li>
<li> ''Name'' -> beliebiger Name, z.B. "MySmartHome Advanced". Dieser wird in der Alexa App unter "Meine Skills" angezeigt.</li>
<li> ''Invocation Name'' -> Aufruf des Skills, unter dem dieser später gestartet wird. Z.B. "Alexa, starte James" [[Datei:CustomSkill_2.PNG|400px]]</li>
</ul></li>
<li>Auf der Seite ''Interaction Model'' folgende Eingaben tätigen und mit ''Next'' abschließen
<ul>
<li>In einem separaten Browserfenster FHEM aufrufen, und für das bereits definierte Alexa-Gerät das Kommando <code>get MyAlexa interactionModel</code> aufrufen. Es erscheint ein Popup-Fenster mit ziemlich vielen Zeilen.
<li>In die Box ''Intent Schema'' kopiert man den ersten Teil dieser FHEM-Ausgabe hinein, also: <blockquote>
{
"intents" : [
<hier ziemlich viele Zeilen>
]
}
</blockquote></li>
<li>Nun die ''Custom Slot Types'' einrichten. Dazu muss aus dem zweiten Teil der FHEM-Ausgabe jeweils der Slot-Type (z.B. <code>FHEM_article</code>) 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.</li>
<li>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 <code>get MyAlexa customSlotTypes</code> ausführen. Auch diese Ausgabe wird, wie oben beschriebeen, in Custom Slot Types eingetragen (erst der TYPE, dann die möglichen Werte)
<li>Anschließend erneut die FHEM-Ausgabe schließen und erneut für das bereits definierte Alexa-Gerät das Kommando <code>get MyAlexa interactionModel</code> aufrufen.
<li>Unter ''Sample Utterances'' nun den Text aus dem dritten Teil dieser FHEM-Ausgabe hineinkopieren [[Datei:CustomSkill_5.PNG|400px]]</li>
</ul></li>
<li>Auf der Seite ''Configuration'' Folgendes eingeben und mit ''Next'' bestätigen:
<ul>
<li>''Service Endpoint Type'' -> ''AWS Lambda'' auswählen</li>
<li>''Geographical Region'' -> ''Europe'' auswählen und im Textfeld den Wert aus Abschnitt [[#AWS_Lambda_Funktion_anlegen | AWS Lambda Funktion anlegen]] (Punkt 12) eintragen. </li>
<li>''Do you allow users to create an account or link to an existing account with you?'' -> ''Yes''</li>
<li>''Authorization URL'' -> <code>https://www.amazon.com/ap/oa</code></li>
<li>''Client ID'' -> ''Client ID'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1</li>
<li>''Scope'' -> <code>profile:user_id</code> (wörtlich 1:1 eintragen)</li>
<li>''Redirect URLs'' - sollten vorbelegt sein</li>
<li>''Authorization Grant Type'' -> ''Auth Code Grant'' auswählen</li>
<li>''Access Token URI'' -> <code>https://api.amazon.com/auth/o2/token</code></li>
<li>''Client Secret'' -> ''Client Secret'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1</li>
<li>''Client Authentication Scheme'' -> ''HTTP Basic''</li>
<li>''Privacy Policy URL'' -> <code>https://www.amazon.com/gp/help/customer/display.html?nodeId=468496</code></li>
</ul>
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 | AWS Lambda Funktion]] nachgetragen werden, dies wird in Abschnitt [[#Trigger_f.C3.BCr_Custom_Skill_hinzuf.C3.BCgen | Trigger für Custom Skill hinzufügen]] beschrieben.
 [[Datei:CustomSkill_6.PNG|400px]] [[Datei:CustomSkill_7.PNG|400px]]</li>

==== 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 | Custom Skill Anlegen]] unter Punkt 2 eingetragen hat.

==== Skill Id bestimmen ====
{{Randnotiz|RNTyp=[g|Info]|RNText=Hier wird beschrieben, wo die ''Alexa Skill Id'' zu finden ist}}
Für das [[#AWS_Lamba_Funktion_anlegen | Anlegen einer ''AWS Lambda Funktion'']] bzw für die [[#Alexa-Fhem_konfigurieren | Konfiguration von Alexa-Fhem]] wird die ''Alexa Skill Id'' benötigt. An diese kommt man wie folgt:
# Anmelden wie unter [[#Alexa_Skills | Alexa Skills]] beschrieben.
# Menüpunkt ''ALEXA'' auswählen, wie [[#Skills_bearbeiten | Skills bearbeiten]] erklärt.
# Beim gewünschten Eintrag auf ''Edit'' klicken [[Datei:Developer.amazon.com-23-alexa_-_alex_skills_kit_-_overview.png|200px]]
# Die Id, die nun oben angezeigt wird, ist die gesuchte. Sie hat typischerweise das Format <code>amzn1.ask.skill.[Zahlen und Bindestriche]</code> [[Datei:Aws.amazon.com-06-configure_triggers2.png|200px]]

<hr>

=== AWS Lambda Funktion ===
Für folgende Schritte muss man unter der Adresse http://aws.amazon.com angemeldet sein
# Anmeldung auswählen [[Datei:Aws.amazon.com-01-site.png|200px]]
# Anmeldedaten eingeben [[Datei:Aws.amazon.com-02-login.png|200px]]
# Den Punkt ''Lambda'' links auf der Startseite auswählen, bzw. im Menü ''Services'' unter ''Compute'' den Menüpunkt ''Lambda'' auswählen [[Datei:Aws.amazon.com-03-lambda.png|200px]]
==== AWS Lambda Funktion anlegen ====
# Für eine erste Lambda-Funktion den Punkt ''Get Started Now'' auswählen [[Datei:Aws.amazon.com-04-get_started_now.png|200px]]
# Den Blueprint ''Blank function'' auswählen [[Datei:Aws.amazon.com-05-select_blueprint.png|200px]]
# Im neuen Fenster dann auf den gestrichelten Kasten klicken und ''Alexa Smart Home'' auswählen und mit ''Next'' bestätigen [[Datei:Aws.amazon.com-06-configure_triggers1.png|200px]]
## 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 | Skill Id bestimmen]] beschrieben wird, den Haken bei ''Enable trigger'' setzen und mit ''Next'' bestätigen [[Datei:Aws.amazon.com-06-configure_triggers3.png|200px]]
# Auf der Konfigurationsseite eingeben:
## ''Name'' -> ''FHEM''
## ''Runtime'' -> Node.js 4.3.
## ''Role'' -> ''Choose an existing role''
### 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_installieren | 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. [[Datei:Aws.amazon.com-07-configure_function.png|200px]]
# Auf der Übersichtsseite dann ''Create function'' anklicken [[Datei:Aws.amazon.com-08-review.png|200px]]

==== 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 [[Datei:Aws.amazon.com-09-go_overview.png|200px]]
# Anschließend den Radiobutton der angelegten Funktion ''FHEM'' markieren und im Menü ''Action'' den Punkt ''Show ARN'' auswählen [[Datei:Aws.amazon.com-10-1-show_arn.png|200px]]
# Es wird nun eine ARN Adresse angezeigt, die für den Abschnitt [[#SmartHome_Skill_anlegen| SmartHome Skill anlegen]] benötigt wird [[Datei:Aws.amazon.com-10-2-arn.png|200px]]

=== Absichern des Zugriffs ===
Natürlich muss der Zugriff auf den von Alexa-Fhem verwendeten Port (default: 3000, Bestandteil des Codes in der AWS Lambda-Funktion) durch die Firewall freigeschaltet werden (auf einer FritzBox unter "Portfreigaben").

==== Absicherung direkt in Alexa-FHEM ====
Die Kommunikation zwischen Amazon AWS und Alexa-FHEM ist auf die folgenden Arten gesichert:
* Die Verbindung erfolgt per HTTPS
* Es werden nur Verbindung angenommen auf denen ein gültiges Alexa-Event gesendet wird.
* Es werden nur Verbindungen angenommen die ein gültiges und noch nicht abgelaufenes OAuth-Token enthalten. Jedes neue Token wird live bei Amazon auf Gültigkeit geprüft.
* Es werden nur Verbindungen mit lokal konfigurierter Skill-ID angenommen.
* Es ist nicht möglich von außen beliebige FHEM Kommandos zu senden. Die FHEM Kommandos werden nur lokal erzeugt.

Wer möchte kann Alexa-FHEM natürlich noch weiter absichern. Es gilt aber, dass nicht jedes zusätzliche Glied in der Kette die Sicherheit sondern unter Umständen nur die Angriffsfläche erhöht. Ein falsch konfigurierter und nach aussen offener Apache (oder anderer ReverseProxy) ist unter Umständen ein größeres Risiko als Alexa-FHEM alleine.

==== Absicherung per ReverseProxy ====
<s>Die Kommunikation zwischen Amazon und FHEM ist wegen der Verwendung von SSL schon verschlüsselt - prinzipiell kann aber jeder von außen mit Alexa-Fhem kommunizieren. Man sollte sich deshalb im Klaren darüber sein, dass dies eine Sicherheitslücke darstellt:</s> Jeder offene Port verleitet zu Angriffen, und mit zunehmender Verbreitung von Alexa steigt auch das Risiko. Es wird deshalb empfohlen, vor den eigentlichen Alexa-Server zur Absicherung einen Apache-Webserver als ReverseProxy zu setzen. Nicht nur ist der Apache eine hervorragend stabile und seit Jahrzehnten getestete Software, sondern die Konfiguration als ReverseProxy erlaubt auch, den Zugriff auf den Alexa-Fhem-Rechner auf die Amazon-Maschinen zu beschränken.

'''Achtung: Dies ist keine allgemeine Anleitung in Sachen Computersicherheit.''' Im Folgenden gehen wir davon aus, dass
* Grundbegriffe wie Firewall, IP-Ports, SSL und Dynamic DNS vertraut sind
* Ein Apache Webserver (idealerweise auf einer zweiten Maschine) bereits installiert ist und die Konfiguration verstanden wurde (wenn nicht: Es gibt im Netz ''tausende'' von Anleitungen dafür...)
* Ein Servername von einem DynDNS-Anbieter - sagen wir ''myhome.is-my-castle.com'' - bereits von ''außen'' auf unser SmartHome zeigt.
* Alexa-Fhem in einer der oben beschriebenen Basiskonfigurationen läuft, d.h. der Zugriff auf <code>https://myhome.is-my-castle.com:3000</code> ergibt, wie im Punkt [[#Alexa-Fhem_testen|Alexa-Fhem testen]] beschrieben, eine Antwort des Node.js Servers.

Als erster Schritt zur Absicherung muss das ReverseProxy Modul für den Apache installiert und mit <code>a2enmod</code> aktiviert werden, hierzu sei auf [https://www.digitalocean.com/community/tutorials/how-to-use-apache-http-server-as-reverse-proxy-using-mod_proxy-extension diese Anleitung] verwiesen. Der zweite Schritt besteht darin, den SSL-Zugriff durch ein Passwort abzusichern. Dazu wird auf dem Apache-Rechner das Programm
htpasswd <passwdfile> <username>
ausgeführt, das Programm fragt dann nach dem gewünschten Passwort. Wir nehmen im Folgenden an, dass das Passwortfile ''/etc/apache2/htpasswd'' ist, der gesetzte Username ''alexa'' lautet und das Passwort ''my_smarthome'' ist.

Im dritten Schritt wird nun in das Apache-Konfigurationsfile die Weiterleitung auf den eigentlichen Alexa-Fhem-Rechner eingetragen. Dazu wählen wir, dass von außen der Standard-SSL-Port 443 benutzt werden soll, sowie als Verzeichnisname ''/alexa''. '''Achtung:''' Dieser Code soll '''nicht''' in die Default-Konfiguration des Apache-Webservers. Sondern in eine separate Datei (Dateiname z.B. "fhem"), die ins Unterverzeichnis /etc/apache2/conf.d gestellt wird.

<VirtualHost *:443>
ServerName myhome.is-my-castle.com
SSLEngine on
SSLProxyEngine on
SSLProxyCheckPeerCN off
SSLProxyCheckPeerName off
SSLCertificateKeyFile /etc/apache2/mycert/server.key
SSLCertificateFile /etc/apache2/mycert/server.crt
<Location /alexa>
AuthType Basic
AuthName "Authentication Required"
AuthUserFile "/etc/apache2/htpasswd"
Require valid-user
ProxyPass https://<hier IP-Adresse des Alexa-Fhem-Rechners>:3000/
ProxyPassReverse https://<hier IP-Adresse des Alexa-Fhem-Rechners>:3000/
Order deny,allow
Allow from All
</Location>
(... Hier eventuell weitere Umleitungen)
</VirtualHost>
Nach einem Neustart des Apache-Servers, dem Schließen des Ports 3000 in der Firewall sowie dem Öffnen des Ports 443 ist der Alexa-Fhem-Rechner von außen nur noch erreichbar durch den Aufruf von <code>https://myhome.is-my-castle.com/alexa</code> und verlangt unmittelbar die Eingabe von Username und Passwort.

Der vierte Schritt ist nun, den Code der AWS Lambda-Funktion an fünf Stellen zu verändern
'''const PORT=443;'''
const HOST='myhome.is-my-castle.com';
'''const PATH='/alexa';'''
'''const AUTH='alexa:my_smarthome';'''
// entry
exports.handler = function(event, context, callback) {
console.log(`EVENT: ${event}`);
console.log(`CONTEXT: ${context}`);
var post_data = JSON.stringify(event);
var options = {
hostname: HOST,
port: PORT,
//family: 6,
'''path: PATH,'''
method: 'POST',
'''auth: AUTH,'''
rejectUnauthorized: false, // accept self-signed
(etc., Rest des Codes wie gehabt)
Natürlich muss der Zugriff getestet werden. Bei Beachtung aller dieser Schritte werden alle un-autorisierten Zugriffe von außen abgewehrt. Eine noch weiter gehende Sicherung ist möglich, dazu kann in der Serverkonfiguration der Zugriff auf die Amazon-Domains beschränkt werden. Das ganze Alexa-System ist aber noch in konstanter Weiterentwicklung, diese Domain-Namen können sich also noch ändern.

== 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 [http://alexa.amazon.de 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 [[Datei:Alexa.amazon.de-01-startseite.png|200px]]
# Oben rechts ''Meine Skills'' bzw. ''Ihre Skills'' auswählen [[Datei:Alexa.amazon.de-03-meine_skills.png|200px]]
# In der Liste der Skills sollte das angelegte FHEM Skill angezeigt werden. Dieses anklicken [[Datei:Alexa.amazon.de-02-liste_skills.png|200px]]
# Oben Rechts in den Details des Skills auf ''Skill aktivieren'' klicken [[Datei:Alexa.amazon.de-04-skill_details.png|200px]]
# In dem neu geöffneten Fenster die Autorisierung bestätigen [[Datei:Alexa.amazon.de-05-amazon_auth.png|200px]]
# Anschließend sollte die Verbindung erfolgreich aufgebaut worden sein [[Datei:Alexa.amazon.de-06-success.png|200px]]

=== Geräte ===
# Auf http://alexa.amazon.de anmelden
# Auf ''Smart Home'' klicken [[Datei:Alexa.amazon.de-01-startseite.png|200px]]
# Anschließend den Punkt ''Geräte suchen'' anklicken [[Datei:Alexa.amazon.de-07-Gerätesuche.png|200px]]
# 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
*** <code><cmd>:<device>:<reading></code>, hier können nicht verwendete Elemente von links nach rechts weg gelassen werden.
*** <code><name>=<value></code>, hier kann <code><value></code> entweder ein Wert oder semikolonseparierte Liste sein.
*** Oder dem schlüsselwort <code>clear</code>, welches alle vorhandenen (default) Parameter dieser Characteristik löscht. <code>clear</code> 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 | 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 | Custom Skill Anlegen]]).

Der Aufruf dieses Gerätes mit Alexa erfolgt dann z.B. mit den Sätzen
<pre style="width:50%;">
"Alexa, sage <Custom Skill Invocation Name>: Stelle Weckzeit auf Neunzehn Uhr Siebenundzwanzig"
"Alexa, frage <Custom Skill Invocation Name> nach dem Status von Weckzeit"
</pre>
Dabei ist natürlich der ''Custom Skill Invocation Name'' durch den Wert zu ersetzen, den man im Abschnitt [[#Custom_Skill_anlegen | 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 [https://www.dpunkt.de/buecher/12387/9783960090120-smarthome-hacks.html 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\');
}
}

<hr>

=== 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
<pre>
"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
</pre>
* 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
<pre>
"Alexa, sage <Custom Skill Invocation Name>: schalte (die) Beleuchtung an" -> LightScene Alle_An wird ausgewählt
</pre>
Dafür wird es aber auch möglich sein direkt die SzenenNamen im gesprochenen Kommando zu verwenden und so auf die Umwege über dummys und ähnliches zu verzichten.

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.

Zwei andere Ansätze Lichtszenen zu schalten die ohne DOIF auskommen sind im Folgenden beschrieben:

* Wenn es von Interesse ist die Steuerung mit einer Darstellung in FTUI zu verbinden: Statt der oben beschriebenen dummy Devices kann man readingsProxy Devices mit passenden setFn und valueFn analog zum [[Harmony#Button_f.C3.BCr_eine_bestimmte_Activity_im_Frontend_und_Homekit_.C3.BCber_readingsProxy|diesem Beispiel für harmony aktivitäten]] verwenden.

* Für jede zu schaltende Szene wird ein dummy angelegt dessen homebridgeMapping direkt auf das LightScene Device zeigt:

define <dummy> dummy
attr <dummy> setList on off
attr <dummy> genericDeviceType switch
attr <dummy> homebridgeMapping On=<light scene>::state,valueOn=<szene>,cmdOn=scene+<szene>,cmdOff=scene+<szene aus>

Bei der zweiten Variante wird davon ausgegangen das der aktuelle status nicht abgefragt oder angezeigt werden soll. Deshalb gibt es keine direkte RadioButton Funktionalität.

== 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 [http://alexa.amazon.de/spa/index.html] 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:
<pre style="width:50%;">
“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”
</pre>

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

Das Prinzip der Kommandokonfiguration ist {{Link2Forum|Topic=60244|Message=532513|LinkText=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:
<pre style="width:50%;">
const PORT=3000;
const HOST='mein.host.name';
</pre>

====Freigabe von Port 3000====
{{Randnotiz|RNTyp=Fehl|RNText=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: [[Homebridge_einrichten#NodeJS_installieren|NodeJS installieren]] sowie [[Homebridge_einrichten#Python.2C_g.2B.2B.2C_MDNS_installieren|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<source lang="bash" style="width:50%;">node -v</source>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 <code>~/.alexa/config.json</code> die folgenden Zeilen rauslöschen:

<pre>
"nat-pmp": "10.0.1.1",
"nat-upnp": true,
</pre>

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:
<source lang="bash" style="width:70%;">2755327 4 -rwxr-xr-x 1 pi pi 339 Nov 26 23:20 alexa</source>
Sollte dies nicht der Fall sein bitte mit:
<source lang="bash" style="width:70%;">chmod +x alexa</source>
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 <code>~/.alexa/config.json</code> geöffnet werden und der Abschnitt "connections" um folgende Zeile ergänzt werden:<pre>
"auth": {"user": "fhem", "pass": "fhempassword"},</pre>
Bei Verwendung von SSL bei FHEM muss auch noch <pre>
"ssl": true,</pre> hinzugefügt werden

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

Alexa-Fhem

2017-07-19T11:38:27Z

DR: /* SmartHome Skill anlegen */ + neuer Parameter "Payload Version"

'''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 [https://forum.fhem.de/index.php?action=profile;u=430 justme1968] im {{Link2Forum|Topic=60244|LinkText=Forum}} veröffentlicht.
Das ist eine erste Version der Dokumentation zur Installation und Einrichtung, eine Erweiterung wird sicherlich in nächster Zeit noch folgen.
{{Infobox Modul
|ModPurpose=Anbindung von FHEM an Amazon Assistent Alexa
|ModType=x
|ModTechName=
|ModForumArea=Frontends/Sprachsteuerung
|ModOwner=justme1968
}}

==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.{{Randnotiz|RNTyp=r|RNText=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'''.
*Card bezeichnet einen Eintrag in der Alexa-App, der die erkannte Sprachnachricht sowie weiter gehenden Informationen über die Reaktion von Alexa enzthält und Rückmeldung an Amazon erlaubt.
*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===
[[Datei:2gpXyLN.jpg|200px|thumb|right|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 <code>lambda.js</code> code an alexa-fhem weitergeleitet
*alexa-fhem steuert FHEM und sendet ein Antwort-Event zurück
*<code>lambda.js</code> 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-Fhem#Smart_Home|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-Fhem#Custom|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==
{{Randnotiz|RNTyp=[g|Info]|RNText=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:
<source lang="bash" style="width:50%;">
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install build-essential libssl-dev</source>

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:
<source lang="bash" style="width:50%;">
curl -sL https://deb.nodesource.com/setup_4.x | sudo -E bash -
sudo apt-get install -y nodejs
</source>

=== Alexa-Fhem installieren ===
'''Aus gegebenem Anlass: Dies ist weder eine Einführung in Linux, noch eine Anfängerdokumentation für FHEM.''' Also erst die Grundlagen lernen, und dann mit Alexa beginnen !

Die aktuelle Version ist jeweils {{Link2Forum|Topic=60244|Message=540117|LinkText=hier}} zu finden.

====Erstinstallation====
Hier wird die Erstinstallation von Alexa-Fhem beschrieben.
===== Linux =====
# Die tgz-Datei unter Linux im Hauptverzeichnis von FHEM (typischerweise <code>/opt/fhem</code>) entpacken (''nicht'' unter Windows, das zerstört die Rechteeinstellungen).
# Das dabei entstandene Verzeichnis ''package'' in ''alexa-fhem'' umbenennen <source lang="bash" style="width:50%;">mv package alexa-fhem</source>
# Durch <source lang="bash" style="width:50%;">cd alexa-fhem</source> in das Verzeichnis wechseln
# Mit <source lang="bash" style="width:50%;">npm install</source> alle Abhängigkeiten installieren (kein sudo!).
# SSL Zertifikat erzeugen durch Aufruf von <source lang="bash" style="width:50%;">./createKey.sh</source> (kein sudo!). Hierbei beachten, dass ein Kennwort vergeben werden muss, das mindestens aus 4 Zeichen besteht, dieses Kennwort bitte merken.
# Das Verzeichnis ''.alexa'' anlegen, ''und zwar im Home-Verzeichnis desjenigen Benutzers, unter dem Alexa-Fhem laufen soll.'' Insbesondere ist zu beachten, dass dieser Nutzer u.U. im Startskript explizit gesetzt wird. Mit dem untenstehenden Skript ist das ''nicht'' der User fhem, sondern der User ''pi''. Das Symbol ''~/'' verweist auf das Home-Verzeichnis des Benutzers, der gerade die Installation vornimmt.
# Die Datei ''config-sample.json'' nach ''.alexa/config.json'' kopieren. Achtung: Installiert man alexa-fhem als root-user, zeigt das Symbol ''~/'' auf ''/root'' - und die Konfigurationsdatei 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.
===== Windows =====
''Vor'' der Installation von Alexa-Fhem muss man folgende Anwendungen installieren:
* Node.js (die aktuelle Version findet man unter https://nodejs.org/en/download/)
* OpenSSL (http://slproweb.com/products/Win32OpenSSL.html oder https://www.heise.de/download/product/win32-openssl-47316/download)
Erst dann fängt man mit Alexa-Fhem an.

# Die tgz-Datei im Hauptverzeichnis von FHEM (z.B. <code>С:\Program Files (x86)\fhem</code>) entpacken.
# Das dabei entstandene Verzeichnis ''package'' in ''alexa-fhem'' umbenennen
# Windows-Shell (Kommandozeile, Eingabeaufforderung usw.) öffnen. "Start" -> "Ausführen" (oder [Windows-Taste]+[R]) -> cmd -> Ok. Durch <source lang="bash" style="width:50%;">cd "<FHEM-Hauptverzeichis>\alexa-fhem"</source> in das Verzeichnis wechseln. Dabei ist natürlich der <FHEM-Hauptverzeichis> durch den entsprechenden Pfad aus dem Schritt 1 zu ersetzen. Im o.g. Beispiel wäre es <code>cd "С:\Program Files (x86)\fhem\alexa-fhem"</code>
# Mit <source lang="bash" style="width:50%;">npm install</source> alle Abhängigkeiten installieren. Bei der Felermedlung wie "Der Befehl "npm" ist entweder falsch geschrieben oder konnte nicht gefunden werden." ist die Installation von Node.js zu überprüfen.
# SSL Zertifikat erzeugen. Dafür muss man alle Befehle aus dem Skript ''createKey.sh'' nacheinander manuell ausführen. Hierbei beachten, dass ein Kennwort vergeben werden muss, das mindestens aus 4 Zeichen besteht, dieses Kennwort bitte merken. Der Windows-Welt unbekannter Befehl <code>mv</code> ist durch <code>move /y</code> zu ersetzen:<source lang="bash" style="width:50%;">openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365</source><source lang="bash" style="width:50%;">openssl rsa -in key.pem -out newkey.pem</source><source lang="bash" style="width:50%;">move /y newkey.pem key.pem</source> Eventuelle Fehlermeldung "can't open config file: /usr/local/ssl/openssl.cnf" o.Ä. lässt sich durch Befehl <code>set OPENSSL_CONF=<OpenSSL-Verzeichnis>\bin\openssl.cfg</code> beheben, wobei <OpenSSL-Verzeichnis> durch den entsprechenden Installationspfad (typischerweise <code>c:\OpenSSL-Win32</code>) zu ersetzen ist.
# Das Verzeichnis ''.alexa'' anlegen, ''und zwar im Benutzerverzeichnis desjenigen Benutzers, unter dem Alexa-Fhem laufen soll.'' In aktuellen Versionen von Windows (ab Windows 7 bzw. ab Windows Server 2008 R2) liegt das Verzeichnis unter <code>C:\Users\<Benutzername></code>, also z.B. für Benutzer "Administrator" - unter <code>C:\Users\Administrator</code>. Falls Windows sich weigert das Verzichniss mit dem Punkt am Anfang zu erstellen, kann man das aus der Kommandozeile machen:<source lang="bash" style="width:50%;">cd "C:\Users\<Benutzername>"</source><source lang="bash" style="width:50%;">
mkdir ".alexa"</source>
# Die Datei ''config-sample.json'' nach ''C:\Users\<Benutzername>.alexa/config.json'' kopieren.
# Achtung: Ggf. müssen auch die Dateien key.pem und cert.pem ins entsprechende Verzeichnis (<code>"<FHEM-Hauptverzeichis>\alexa-fhem\bin</code>) kopiert werden.

====Update====
Hier wir das Update auf eine neue Version von Alexa-Fhem beschrieben
# Das Verzeichnis ''alexa-fhem'' im Hauptverzeichnis von FHEM (typischerweise <code>/opt/fhem</code>) umbenennen in ''alexa-fhem.old''.
# Die tgz-Datei der neuen Alexa-Fhem-Version unter Linux im Hauptverzeichnis von FHEM (typischerweise <code>/opt/fhem</code>) entpacken (''nicht'' unter Windows, das zerstört die Rechteeinstellungen).
# Das dabei entstandene Verzeichnis ''package'' in ''alexa-fhem'' umbenennen, in das Verzeichnis wechseln
# Mit <source lang="bash" style="width:50%;">npm install</source> alle Abhängigkeiten installieren (kein sudo!).
# Die Zertifikatsdateien key.pem und cert.pem aus dem alten Verzeichnis ''alexa-fhem.old'' ins neue Verzeichnis ''alexa-fhem'' kopieren.
Natürlich dann den Dienst neu starten, auch müssen selbstredend irgendwelche Modifikationen an der Datei server.js in der neuen Version nachgezogen werden. Wenn alles läuft, kann das alte Verzeichnis ''alexa-fhem.old'' gelöscht 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 | Skill Id bestimmen]]
# ''oauthClientID'' -> ''Client ID'' dem Abschnitt [[#Login_with_Amazon | 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"
}
]
}

Mehrere Custom Skills lassen sich mit der folgenden Syntax eintragen
"applicationId": [ "amzn1.ask.skill.1" , "amzn1.ask.skill.2" ],
"oauthClientID": [ "amzn1.application-oa2-client.1" , "amzn1.application-oa2-client.1" ]

Danach durch Aufruf von <source lang="bash" style="width:50%;">./bin/alexa</source> den Dienst starten (kein sudo!)

Unter Windows startet man Alexa-Dienst durch <source lang="bash" style="width:50%;">node alexa</source> aus der <code>alex-fhem/bin</code> (also erst z.B. durch <code>cd "<FHEM-Hauptverzeichis>\alexa-fhem\bin"</code> ins richtige Verzeichnis kommen)

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 {{Link2Forum|Topic=60244|Message=517271|LinkText=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:
<source lang="bash" style="width:50%;">sudo chmod 755 /etc/init.d/alexa
sudo update-rc.d alexa defaults</source>

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

Nun folgende Devices anlegen (ggf. einem Raum zuordnen, z.B. AlexaControl):
<source lang="bash" style="width:75%;">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 &")})</source>

==== Alexa-Fhem als Service (systemd) installieren ====
Auf neueren Installationen (z.B. RPi Jessie) wird init.d durch systemd ersetzt. Folgend die Anleitung um alexa-fhem als Service zu installieren auf einem Raspberry Pi mit Jessie.

Zunächst einen neuen Benutzer anlegen unter dem alexa-fhem laufen soll, falls man nicht möchtet dass alexa-fhem z.B. mit dem fhem User ausgeführt wird:

<code lang="bash" style="width:75%;">
sudo useradd -M --system alexa
</code>

Eigentlich braucht der Benutzer keine Gruppen, aber man kann den Benutzer auch der Gruppe <code>dialout</code> hinzufügen (<code>sudo usermod -a -G dialout alexa</code>)

Datei "alexa" unter <code>/etc/default</code> anlegen

# Defaults / Konfigurations Optionen für alexa-fhem
# Wo findet alexa-fhem die config.json Datei?
ALEXA_OPTS=-U /opt/fhem/.alexa

Den Pfad <code>/opt/fhem/.alexa</code> an die Systemgegebenheiten anpassen. Letztendlich kann die config.json irgendwo liegen, hauptsache alexa-fhem weiß wo. Achtung: Natürlich muss der Benutzer auch Zugriff auf das Verzeichnis mit der config als auch das alexa-fhem Verzeichnis haben.

Datei "alexa.service" unter <code>/etc/systemd/system</code> anlegen:

[Unit]
Description=Node.js Alexa Server
After=syslog.target network-online.target

[Service]
Type=simple
User=alexa #oder ein anderer Benutzer wie fhem
EnvironmentFile=/etc/default/alexa
# oder wo auch immer eure alexa-fhem liegt
ExecStart=/opt/fhem/alexa-fhem/bin/alexa $ALEXA_OPTS
Restart=on-failure
RestartSec=10
KillMode=process

[Install]
WantedBy=multi-user.target

Um den Service zu aktiveren und zu starten helfen folgende Befehle:
sudo systemctl daemon-reload
sudo systemctl enable alexa
sudo systemctl start alexa

Status abfragen mit
sudo systemctl status alexa

Log einsehen?
sudo journalctl -u alexa

(mit <code>-f</code> kann man den follow Modus aktivieren, wie <code>tail -f</code>).
Bei einen reboot startet alexa-fhem jetzt automatisch.

==== 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
<code>https://<IP-Adresse des Servers>:3000</code> kann man testen, ob der Alexa-Fhem Service läuft - der Seitenaufruf liefert eine Zeile JSON-Code, beginnend mit
<code>{"header":{"name":"UnsupportedOperationError"...</code>

=== 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:
<source lang="bash" style="width:70%;">define MyAlexa alexa</source>

<hr>

=== Alexa Skills ===
Für folgende Schritte muss man unter der Adresse http://developer.amazon.com angemeldet sein
# Anmeldung auswählen [[Datei:Developer.amazon.com-01-login2.png|200px]]
# Anmeldedaten eingeben [[Datei:Developer.amazon.com-02-userpass2.png|200px]]

==== 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'' [[Datei:Developer.amazon.com-03-apps_and_services.png|200px]]
# Anschließend auswählen ''Security Profiles'' [[Datei:Developer.amazon.com-05-apps_and_services_-_security_profiles.png|200px]]
# Auswählen ''Create a New Security Profile'' aus [[Datei:Developer.amazon.com-06-apps_and_services_-_create_a_new_security_profile.png|200px]]
# Dann einen Namen und eine Beschreibung für das Profil eingeben und mit ''Save'' bestätigen [[Datei:Developer.amazon.com-07-apps_and_services_-_security_profile_management.png|200px]]

===== Login with Amazon =====
{{Randnotiz|RNTyp=[g|Info]|RNText=Hier wird beschrieben, wo ''Client Id'' und ''Client Secret'' zu finden sind}}
# Oben rechts auf ''Login with Amazon'' klicken. [[Datei:Developer.amazon.com-08-login_with_amazon.png|200px]]
# Auf der neu geladenen Seite auswählen ''Sign up'' [[Datei:Developer.amazon.com-09-login_with_amazon_-_sign_up.png|200px]]
# Anschließend im Dropdown Menü das vorher angelegte Profil auswählen und mit ''Confirm'' bestätigen [[Datei:Developer.amazon.com-10-login_with_amazon_-_create_new_profile.png|200px]] [[Datei:Developer.amazon.com-11-login_with_amazon_-_create_new_profile2.png|200px]]
# Im folgenden Fenster die Adresse [https://www.amazon.com/gp/help/customer/display.html?nodeId=468496 https://www.amazon.com/gp/help/customer/display.html?nodeId=468496] eingeben und mit ''Save'' bestätigen. '''Todo Erklärungsbedarf: WARUM diese Adresse''' [[Datei:Developer.amazon.com-12-login_with_amazon_-_enter_consent_screen_information.png|200px]]
# Anschließend bei dem neu angelegten Eintrag auf der rechten Seite auf das Zahnrad klicken und ''Web Settings'' auswählen [[Datei:Developer.amazon.com-13-login_with_amazon_-_web_settings.png|200px]]
# Im neu geladenen Fenster anklicken von ''Edit'' [[Datei:Developer.amazon.com-14-login_with_amazon_-_edit.png|200px]]
# Anschließend bei ''Allowed Return URLs'' die folgenden drei Adressen eingeben. ''xxx'' muss hierbei durch den Wert ersetzt werden, der in den beiden Abschnitten [[#SmartHome_Skill_anlegen | SmartHome Skill anlegen]] bzw. [[#Custom_Skill_anlegen | Custom Skill anlegen]] jeweils unter Punkt 4 (Seite ''Configuration'') bei ''Redirect Urls'' am Ende der URLs angezeigt wird
## [https://layla.amazon.co.uk/api/skill/link/xxx https://layla.amazon.co.uk/api/skill/link/xxx]
## [https://pitangui.amazon.com/api/skill/link/xxx https://pitangui.amazon.com/api/skill/link/xxx]
## [https://layla.amazon.com/api/skill/link/xxx https://layla.amazon.com/api/skill/link/xxx]
. [[Datei:Developer.amazon.com-15-login_with_amazon_-_allowed_return_urls.png|200px]]

==== Skills bearbeiten ====
# Im Menü den Punkt ''ALEXA'' auswählen [[Datei:Developer.amazon.com-03-apps_and_services.png|200px]]
# Anschließend im Feld ''Alexa Skills Kit'' auf ''Get started'' klicken [[Datei:Developer.amazon.com-17-alexa_-_alex_skills_kit_-_get_started.png|200px]]

===== SmartHome Skill anlegen =====
# Oben rechts ''Add a New Skill'' auswählen [[Datei:Developer.amazon.com-18-alexa_-_alex_skills_kit_-_add_a_new_skill.png|200px]]
# 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")
#:* ''Payload Version'' -> "v2 (other devices)" [[Datei:Developer.amazon.com-19-alexa_-_alex_skills_kit_-_skill_information.png|200px]]
# Die folgende Seite einfach mit ''Next'' überspringen [[Datei:Developer.amazon.com-20-alexa_-_alex_skills_kit_-_interaction_model.png|200px]]
# 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 [[#ARN_der_AWS_Lambda_Funktion_bestimmen | AWS Lambda Funktion]] eintragen.
#:* ''Authorization URL'' -> <code>https://www.amazon.com/ap/oa</code>
#:* ''Client ID'' -> ''Client ID'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1
#:* ''Scope'' -> <code>profile:user_id</code> (wörtlich 1:1 eintragen)
#:* ''Redirect URLs'' - sollten vorbelegt sein
#:* ''Authorization Grant Type'' -> ''Auth Code Grant'' auswählen
#:* ''Access Token URI'' -> <code>https://api.amazon.com/auth/o2/token</code>
#:* ''Client Secret'' -> ''Client Secret'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1
#:* ''Client Authentication Scheme'' -> ''HTTP Basic''
#:* ''Privacy Policy URL'' -> <code>https://www.amazon.com/gp/help/customer/display.html?nodeId=468496</code> 
 [[Datei:Developer.amazon.com-21-alexa_-_alex_skills_kit_-_configuration.png|200px]] [[Datei:Developer.amazon.com-22-alexa_-_alex_skills_kit_-_test.png|200px]]

===== Custom Skill anlegen =====
<ol>
<li> Oben rechts ''Add a New Skill'' auswählen [[Datei:Developer.amazon.com-18-alexa_-_alex_skills_kit_-_add_a_new_skill.png|200px]]</li>
<li> Auf der folgenden Seite (''Skill Information'') die nachstehenden Daten eingeben und dann mit ''Next'' bestätigen:
<ul>
<li> ''Skill Type'' -> ''Custom Interaction Model'' </li>
<li> ''Language'' -> ''German''</li>
<li> ''Name'' -> beliebiger Name, z.B. "MySmartHome Advanced". Dieser wird in der Alexa App unter "Meine Skills" angezeigt.</li>
<li> ''Invocation Name'' -> Aufruf des Skills, unter dem dieser später gestartet wird. Z.B. "Alexa, starte James" [[Datei:CustomSkill_2.PNG|400px]]</li>
</ul></li>
<li>Auf der Seite ''Interaction Model'' folgende Eingaben tätigen und mit ''Next'' abschließen
<ul>
<li>In einem separaten Browserfenster FHEM aufrufen, und für das bereits definierte Alexa-Gerät das Kommando <code>get MyAlexa interactionModel</code> aufrufen. Es erscheint ein Popup-Fenster mit ziemlich vielen Zeilen.
<li>In die Box ''Intent Schema'' kopiert man den ersten Teil dieser FHEM-Ausgabe hinein, also: <blockquote>
{
"intents" : [
<hier ziemlich viele Zeilen>
]
}
</blockquote></li>
<li>Nun die ''Custom Slot Types'' einrichten. Dazu muss aus dem zweiten Teil der FHEM-Ausgabe jeweils der Slot-Type (z.B. <code>FHEM_article</code>) 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.</li>
<li>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 <code>get MyAlexa customSlotTypes</code> ausführen. Auch diese Ausgabe wird, wie oben beschriebeen, in Custom Slot Types eingetragen (erst der TYPE, dann die möglichen Werte)
<li>Anschließend erneut die FHEM-Ausgabe schließen und erneut für das bereits definierte Alexa-Gerät das Kommando <code>get MyAlexa interactionModel</code> aufrufen.
<li>Unter ''Sample Utterances'' nun den Text aus dem dritten Teil dieser FHEM-Ausgabe hineinkopieren [[Datei:CustomSkill_5.PNG|400px]]</li>
</ul></li>
<li>Auf der Seite ''Configuration'' Folgendes eingeben und mit ''Next'' bestätigen:
<ul>
<li>''Service Endpoint Type'' -> ''AWS Lambda'' auswählen</li>
<li>''Geographical Region'' -> ''Europe'' auswählen und im Textfeld den Wert aus Abschnitt [[#AWS_Lambda_Funktion_anlegen | AWS Lambda Funktion anlegen]] (Punkt 12) eintragen. </li>
<li>''Do you allow users to create an account or link to an existing account with you?'' -> ''Yes''</li>
<li>''Authorization URL'' -> <code>https://www.amazon.com/ap/oa</code></li>
<li>''Client ID'' -> ''Client ID'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1</li>
<li>''Scope'' -> <code>profile:user_id</code> (wörtlich 1:1 eintragen)</li>
<li>''Redirect URLs'' - sollten vorbelegt sein</li>
<li>''Authorization Grant Type'' -> ''Auth Code Grant'' auswählen</li>
<li>''Access Token URI'' -> <code>https://api.amazon.com/auth/o2/token</code></li>
<li>''Client Secret'' -> ''Client Secret'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1</li>
<li>''Client Authentication Scheme'' -> ''HTTP Basic''</li>
<li>''Privacy Policy URL'' -> <code>https://www.amazon.com/gp/help/customer/display.html?nodeId=468496</code></li>
</ul>
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 | AWS Lambda Funktion]] nachgetragen werden, dies wird in Abschnitt [[#Trigger_f.C3.BCr_Custom_Skill_hinzuf.C3.BCgen | Trigger für Custom Skill hinzufügen]] beschrieben.
 [[Datei:CustomSkill_6.PNG|400px]] [[Datei:CustomSkill_7.PNG|400px]]</li>

==== 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 | Custom Skill Anlegen]] unter Punkt 2 eingetragen hat.

==== Skill Id bestimmen ====
{{Randnotiz|RNTyp=[g|Info]|RNText=Hier wird beschrieben, wo die ''Alexa Skill Id'' zu finden ist}}
Für das [[#AWS_Lamba_Funktion_anlegen | Anlegen einer ''AWS Lambda Funktion'']] bzw für die [[#Alexa-Fhem_konfigurieren | Konfiguration von Alexa-Fhem]] wird die ''Alexa Skill Id'' benötigt. An diese kommt man wie folgt:
# Anmelden wie unter [[#Alexa_Skills | Alexa Skills]] beschrieben.
# Menüpunkt ''ALEXA'' auswählen, wie [[#Skills_bearbeiten | Skills bearbeiten]] erklärt.
# Beim gewünschten Eintrag auf ''Edit'' klicken [[Datei:Developer.amazon.com-23-alexa_-_alex_skills_kit_-_overview.png|200px]]
# Die Id, die nun oben angezeigt wird, ist die gesuchte. Sie hat typischerweise das Format <code>amzn1.ask.skill.[Zahlen und Bindestriche]</code> [[Datei:Aws.amazon.com-06-configure_triggers2.png|200px]]

<hr>

=== AWS Lambda Funktion ===
Für folgende Schritte muss man unter der Adresse http://aws.amazon.com angemeldet sein
# Anmeldung auswählen [[Datei:Aws.amazon.com-01-site.png|200px]]
# Anmeldedaten eingeben [[Datei:Aws.amazon.com-02-login.png|200px]]
# Den Punkt ''Lambda'' links auf der Startseite auswählen, bzw. im Menü ''Services'' unter ''Compute'' den Menüpunkt ''Lambda'' auswählen [[Datei:Aws.amazon.com-03-lambda.png|200px]]
==== AWS Lambda Funktion anlegen ====
# Für eine erste Lambda-Funktion den Punkt ''Get Started Now'' auswählen [[Datei:Aws.amazon.com-04-get_started_now.png|200px]]
# Den Blueprint ''Blank function'' auswählen [[Datei:Aws.amazon.com-05-select_blueprint.png|200px]]
# Im neuen Fenster dann auf den gestrichelten Kasten klicken und ''Alexa Smart Home'' auswählen und mit ''Next'' bestätigen [[Datei:Aws.amazon.com-06-configure_triggers1.png|200px]]
## 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 | Skill Id bestimmen]] beschrieben wird, den Haken bei ''Enable trigger'' setzen und mit ''Next'' bestätigen [[Datei:Aws.amazon.com-06-configure_triggers3.png|200px]]
# Auf der Konfigurationsseite eingeben:
## ''Name'' -> ''FHEM''
## ''Runtime'' -> Node.js 4.3.
## ''Role'' -> ''Choose an existing role''
### 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_installieren | 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. [[Datei:Aws.amazon.com-07-configure_function.png|200px]]
# Auf der Übersichtsseite dann ''Create function'' anklicken [[Datei:Aws.amazon.com-08-review.png|200px]]

==== 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 [[Datei:Aws.amazon.com-09-go_overview.png|200px]]
# Anschließend den Radiobutton der angelegten Funktion ''FHEM'' markieren und im Menü ''Action'' den Punkt ''Show ARN'' auswählen [[Datei:Aws.amazon.com-10-1-show_arn.png|200px]]
# Es wird nun eine ARN Adresse angezeigt, die für den Abschnitt [[#SmartHome_Skill_anlegen| SmartHome Skill anlegen]] benötigt wird [[Datei:Aws.amazon.com-10-2-arn.png|200px]]

=== Absichern des Zugriffs ===
Natürlich muss der Zugriff auf den von Alexa-Fhem verwendeten Port (default: 3000, Bestandteil des Codes in der AWS Lambda-Funktion) durch die Firewall freigeschaltet werden (auf einer FritzBox unter "Portfreigaben").

==== Absicherung direkt in Alexa-FHEM ====
Die Kommunikation zwischen Amazon AWS und Alexa-FHEM ist auf die folgenden Arten gesichert:
* Die Verbindung erfolgt per HTTPS
* Es werden nur Verbindung angenommen auf denen ein gültiges Alexa-Event gesendet wird.
* Es werden nur Verbindungen angenommen die ein gültiges und noch nicht abgelaufenes OAuth-Token enthalten. Jedes neue Token wird live bei Amazon auf Gültigkeit geprüft.
* Es werden nur Verbindungen mit lokal konfigurierter Skill-ID angenommen.
* Es ist nicht möglich von außen beliebige FHEM Kommandos zu senden. Die FHEM Kommandos werden nur lokal erzeugt.

Wer möchte kann Alexa-FHEM natürlich noch weiter absichern. Es gilt aber, dass nicht jedes zusätzliche Glied in der Kette die Sicherheit sondern unter Umständen nur die Angriffsfläche erhöht. Ein falsch konfigurierter und nach aussen offener Apache (oder anderer ReverseProxy) ist unter Umständen ein größeres Risiko als Alexa-FHEM alleine.

==== Absicherung per ReverseProxy ====
<s>Die Kommunikation zwischen Amazon und FHEM ist wegen der Verwendung von SSL schon verschlüsselt - prinzipiell kann aber jeder von außen mit Alexa-Fhem kommunizieren. Man sollte sich deshalb im Klaren darüber sein, dass dies eine Sicherheitslücke darstellt:</s> Jeder offene Port verleitet zu Angriffen, und mit zunehmender Verbreitung von Alexa steigt auch das Risiko. Es wird deshalb empfohlen, vor den eigentlichen Alexa-Server zur Absicherung einen Apache-Webserver als ReverseProxy zu setzen. Nicht nur ist der Apache eine hervorragend stabile und seit Jahrzehnten getestete Software, sondern die Konfiguration als ReverseProxy erlaubt auch, den Zugriff auf den Alexa-Fhem-Rechner auf die Amazon-Maschinen zu beschränken.

'''Achtung: Dies ist keine allgemeine Anleitung in Sachen Computersicherheit.''' Im Folgenden gehen wir davon aus, dass
* Grundbegriffe wie Firewall, IP-Ports, SSL und Dynamic DNS vertraut sind
* Ein Apache Webserver (idealerweise auf einer zweiten Maschine) bereits installiert ist und die Konfiguration verstanden wurde (wenn nicht: Es gibt im Netz ''tausende'' von Anleitungen dafür...)
* Ein Servername von einem DynDNS-Anbieter - sagen wir ''myhome.is-my-castle.com'' - bereits von ''außen'' auf unser SmartHome zeigt.
* Alexa-Fhem in einer der oben beschriebenen Basiskonfigurationen läuft, d.h. der Zugriff auf <code>https://myhome.is-my-castle.com:3000</code> ergibt, wie im Punkt [[#Alexa-Fhem_testen|Alexa-Fhem testen]] beschrieben, eine Antwort des Node.js Servers.

Als erster Schritt zur Absicherung muss das ReverseProxy Modul für den Apache installiert und mit <code>a2enmod</code> aktiviert werden, hierzu sei auf [https://www.digitalocean.com/community/tutorials/how-to-use-apache-http-server-as-reverse-proxy-using-mod_proxy-extension diese Anleitung] verwiesen. Der zweite Schritt besteht darin, den SSL-Zugriff durch ein Passwort abzusichern. Dazu wird auf dem Apache-Rechner das Programm
htpasswd <passwdfile> <username>
ausgeführt, das Programm fragt dann nach dem gewünschten Passwort. Wir nehmen im Folgenden an, dass das Passwortfile ''/etc/apache2/htpasswd'' ist, der gesetzte Username ''alexa'' lautet und das Passwort ''my_smarthome'' ist.

Im dritten Schritt wird nun in das Apache-Konfigurationsfile die Weiterleitung auf den eigentlichen Alexa-Fhem-Rechner eingetragen. Dazu wählen wir, dass von außen der Standard-SSL-Port 443 benutzt werden soll, sowie als Verzeichnisname ''/alexa''. '''Achtung:''' Dieser Code soll '''nicht''' in die Default-Konfiguration des Apache-Webservers. Sondern in eine separate Datei (Dateiname z.B. "fhem"), die ins Unterverzeichnis /etc/apache2/conf.d gestellt wird.

<VirtualHost *:443>
ServerName myhome.is-my-castle.com
SSLEngine on
SSLProxyEngine on
SSLProxyCheckPeerCN off
SSLProxyCheckPeerName off
SSLCertificateKeyFile /etc/apache2/mycert/server.key
SSLCertificateFile /etc/apache2/mycert/server.crt
<Location /alexa>
AuthType Basic
AuthName "Authentication Required"
AuthUserFile "/etc/apache2/htpasswd"
Require valid-user
ProxyPass https://<hier IP-Adresse des Alexa-Fhem-Rechners>:3000/
ProxyPassReverse https://<hier IP-Adresse des Alexa-Fhem-Rechners>:3000/
Order deny,allow
Allow from All
</Location>
(... Hier eventuell weitere Umleitungen)
</VirtualHost>
Nach einem Neustart des Apache-Servers, dem Schließen des Ports 3000 in der Firewall sowie dem Öffnen des Ports 443 ist der Alexa-Fhem-Rechner von außen nur noch erreichbar durch den Aufruf von <code>https://myhome.is-my-castle.com/alexa</code> und verlangt unmittelbar die Eingabe von Username und Passwort.

Der vierte Schritt ist nun, den Code der AWS Lambda-Funktion an fünf Stellen zu verändern
'''const PORT=443;'''
const HOST='myhome.is-my-castle.com';
'''const PATH='/alexa';'''
'''const AUTH='alexa:my_smarthome';'''
// entry
exports.handler = function(event, context, callback) {
console.log(`EVENT: ${event}`);
console.log(`CONTEXT: ${context}`);
var post_data = JSON.stringify(event);
var options = {
hostname: HOST,
port: PORT,
//family: 6,
'''path: PATH,'''
method: 'POST',
'''auth: AUTH,'''
rejectUnauthorized: false, // accept self-signed
(etc., Rest des Codes wie gehabt)
Natürlich muss der Zugriff getestet werden. Bei Beachtung aller dieser Schritte werden alle un-autorisierten Zugriffe von außen abgewehrt. Eine noch weiter gehende Sicherung ist möglich, dazu kann in der Serverkonfiguration der Zugriff auf die Amazon-Domains beschränkt werden. Das ganze Alexa-System ist aber noch in konstanter Weiterentwicklung, diese Domain-Namen können sich also noch ändern.

== 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 [http://alexa.amazon.de 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 [[Datei:Alexa.amazon.de-01-startseite.png|200px]]
# Oben rechts ''Meine Skills'' bzw. ''Ihre Skills'' auswählen [[Datei:Alexa.amazon.de-03-meine_skills.png|200px]]
# In der Liste der Skills sollte das angelegte FHEM Skill angezeigt werden. Dieses anklicken [[Datei:Alexa.amazon.de-02-liste_skills.png|200px]]
# Oben Rechts in den Details des Skills auf ''Skill aktivieren'' klicken [[Datei:Alexa.amazon.de-04-skill_details.png|200px]]
# In dem neu geöffneten Fenster die Autorisierung bestätigen [[Datei:Alexa.amazon.de-05-amazon_auth.png|200px]]
# Anschließend sollte die Verbindung erfolgreich aufgebaut worden sein [[Datei:Alexa.amazon.de-06-success.png|200px]]

=== Geräte ===
# Auf http://alexa.amazon.de anmelden
# Auf ''Smart Home'' klicken [[Datei:Alexa.amazon.de-01-startseite.png|200px]]
# Anschließend den Punkt ''Geräte suchen'' anklicken [[Datei:Alexa.amazon.de-07-Gerätesuche.png|200px]]
# 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
*** <code><cmd>:<device>:<reading></code>, hier können nicht verwendete Elemente von links nach rechts weg gelassen werden.
*** <code><name>=<value></code>, hier kann <code><value></code> entweder ein Wert oder semikolonseparierte Liste sein.
*** Oder dem schlüsselwort <code>clear</code>, welches alle vorhandenen (default) Parameter dieser Characteristik löscht. <code>clear</code> 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 | 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 | Custom Skill Anlegen]]).

Der Aufruf dieses Gerätes mit Alexa erfolgt dann z.B. mit den Sätzen
<pre style="width:50%;">
"Alexa, sage <Custom Skill Invocation Name>: Stelle Weckzeit auf Neunzehn Uhr Siebenundzwanzig"
"Alexa, frage <Custom Skill Invocation Name> nach dem Status von Weckzeit"
</pre>
Dabei ist natürlich der ''Custom Skill Invocation Name'' durch den Wert zu ersetzen, den man im Abschnitt [[#Custom_Skill_anlegen | 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 [https://www.dpunkt.de/buecher/12387/9783960090120-smarthome-hacks.html 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\');
}
}

<hr>

=== 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
<pre>
"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
</pre>
* 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
<pre>
"Alexa, sage <Custom Skill Invocation Name>: schalte (die) Beleuchtung an" -> LightScene Alle_An wird ausgewählt
</pre>
Dafür wird es aber auch möglich sein direkt die SzenenNamen im gesprochenen Kommando zu verwenden und so auf die Umwege über dummys und ähnliches zu verzichten.

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.

Zwei andere Ansätze Lichtszenen zu schalten die ohne DOIF auskommen sind im Folgenden beschrieben:

* Wenn es von Interesse ist die Steuerung mit einer Darstellung in FTUI zu verbinden: Statt der oben beschriebenen dummy Devices kann man readingsProxy Devices mit passenden setFn und valueFn analog zum [[Harmony#Button_f.C3.BCr_eine_bestimmte_Activity_im_Frontend_und_Homekit_.C3.BCber_readingsProxy|diesem Beispiel für harmony aktivitäten]] verwenden.

* Für jede zu schaltende Szene wird ein dummy angelegt dessen homebridgeMapping direkt auf das LightScene Device zeigt:

define <dummy> dummy
attr <dummy> setList on off
attr <dummy> genericDeviceType switch
attr <dummy> homebridgeMapping On=<light scene>::state,valueOn=<szene>,cmdOn=scene+<szene>,cmdOff=scene+<szene aus>

Bei der zweiten Variante wird davon ausgegangen das der aktuelle status nicht abgefragt oder angezeigt werden soll. Deshalb gibt es keine direkte RadioButton Funktionalität.

== 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 [http://alexa.amazon.de/spa/index.html] 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:
<pre style="width:50%;">
“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”
</pre>

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

Das Prinzip der Kommandokonfiguration ist {{Link2Forum|Topic=60244|Message=532513|LinkText=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:
<pre style="width:50%;">
const PORT=3000;
const HOST='mein.host.name';
</pre>

====Freigabe von Port 3000====
{{Randnotiz|RNTyp=Fehl|RNText=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: [[Homebridge_einrichten#NodeJS_installieren|NodeJS installieren]] sowie [[Homebridge_einrichten#Python.2C_g.2B.2B.2C_MDNS_installieren|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<source lang="bash" style="width:50%;">node -v</source>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 <code>~/.alexa/config.json</code> die folgenden Zeilen rauslöschen:

<pre>
"nat-pmp": "10.0.1.1",
"nat-upnp": true,
</pre>

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:
<source lang="bash" style="width:70%;">2755327 4 -rwxr-xr-x 1 pi pi 339 Nov 26 23:20 alexa</source>
Sollte dies nicht der Fall sein bitte mit:
<source lang="bash" style="width:70%;">chmod +x alexa</source>
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 <code>~/.alexa/config.json</code> geöffnet werden und der Abschnitt "connections" um folgende Zeile ergänzt werden:<pre>
"auth": {"user": "fhem", "pass": "fhempassword"},</pre>
Bei Verwendung von SSL bei FHEM muss auch noch <pre>
"ssl": true,</pre> hinzugefügt werden

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

Alexa-Fhem

2017-07-17T13:47:09Z

DR: /* Alexa-Fhem installieren */ +Start unter Windows

'''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 [https://forum.fhem.de/index.php?action=profile;u=430 justme1968] im {{Link2Forum|Topic=60244|LinkText=Forum}} veröffentlicht.
Das ist eine erste Version der Dokumentation zur Installation und Einrichtung, eine Erweiterung wird sicherlich in nächster Zeit noch folgen.
{{Infobox Modul
|ModPurpose=Anbindung von FHEM an Amazon Assistent Alexa
|ModType=x
|ModTechName=
|ModForumArea=Frontends/Sprachsteuerung
|ModOwner=justme1968
}}

==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.{{Randnotiz|RNTyp=r|RNText=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'''.
*Card bezeichnet einen Eintrag in der Alexa-App, der die erkannte Sprachnachricht sowie weiter gehenden Informationen über die Reaktion von Alexa enzthält und Rückmeldung an Amazon erlaubt.
*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===
[[Datei:2gpXyLN.jpg|200px|thumb|right|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 <code>lambda.js</code> code an alexa-fhem weitergeleitet
*alexa-fhem steuert FHEM und sendet ein Antwort-Event zurück
*<code>lambda.js</code> 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-Fhem#Smart_Home|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-Fhem#Custom|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==
{{Randnotiz|RNTyp=[g|Info]|RNText=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:
<source lang="bash" style="width:50%;">
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install build-essential libssl-dev</source>

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:
<source lang="bash" style="width:50%;">
curl -sL https://deb.nodesource.com/setup_4.x | sudo -E bash -
sudo apt-get install -y nodejs
</source>

=== Alexa-Fhem installieren ===
'''Aus gegebenem Anlass: Dies ist weder eine Einführung in Linux, noch eine Anfängerdokumentation für FHEM.''' Also erst die Grundlagen lernen, und dann mit Alexa beginnen !

Die aktuelle Version ist jeweils {{Link2Forum|Topic=60244|Message=540117|LinkText=hier}} zu finden.

====Erstinstallation====
Hier wird die Erstinstallation von Alexa-Fhem beschrieben.
===== Linux =====
# Die tgz-Datei unter Linux im Hauptverzeichnis von FHEM (typischerweise <code>/opt/fhem</code>) entpacken (''nicht'' unter Windows, das zerstört die Rechteeinstellungen).
# Das dabei entstandene Verzeichnis ''package'' in ''alexa-fhem'' umbenennen <source lang="bash" style="width:50%;">mv package alexa-fhem</source>
# Durch <source lang="bash" style="width:50%;">cd alexa-fhem</source> in das Verzeichnis wechseln
# Mit <source lang="bash" style="width:50%;">npm install</source> alle Abhängigkeiten installieren (kein sudo!).
# SSL Zertifikat erzeugen durch Aufruf von <source lang="bash" style="width:50%;">./createKey.sh</source> (kein sudo!). Hierbei beachten, dass ein Kennwort vergeben werden muss, das mindestens aus 4 Zeichen besteht, dieses Kennwort bitte merken.
# Das Verzeichnis ''.alexa'' anlegen, ''und zwar im Home-Verzeichnis desjenigen Benutzers, unter dem Alexa-Fhem laufen soll.'' Insbesondere ist zu beachten, dass dieser Nutzer u.U. im Startskript explizit gesetzt wird. Mit dem untenstehenden Skript ist das ''nicht'' der User fhem, sondern der User ''pi''. Das Symbol ''~/'' verweist auf das Home-Verzeichnis des Benutzers, der gerade die Installation vornimmt.
# Die Datei ''config-sample.json'' nach ''.alexa/config.json'' kopieren. Achtung: Installiert man alexa-fhem als root-user, zeigt das Symbol ''~/'' auf ''/root'' - und die Konfigurationsdatei 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.
===== Windows =====
''Vor'' der Installation von Alexa-Fhem muss man folgende Anwendungen installieren:
* Node.js (die aktuelle Version findet man unter https://nodejs.org/en/download/)
* OpenSSL (http://slproweb.com/products/Win32OpenSSL.html oder https://www.heise.de/download/product/win32-openssl-47316/download)
Erst dann fängt man mit Alexa-Fhem an.

# Die tgz-Datei im Hauptverzeichnis von FHEM (z.B. <code>С:\Program Files (x86)\fhem</code>) entpacken.
# Das dabei entstandene Verzeichnis ''package'' in ''alexa-fhem'' umbenennen
# Windows-Shell (Kommandozeile, Eingabeaufforderung usw.) öffnen. "Start" -> "Ausführen" (oder [Windows-Taste]+[R]) -> cmd -> Ok. Durch <source lang="bash" style="width:50%;">cd "<FHEM-Hauptverzeichis>\alexa-fhem"</source> in das Verzeichnis wechseln. Dabei ist natürlich der <FHEM-Hauptverzeichis> durch den entsprechenden Pfad aus dem Schritt 1 zu ersetzen. Im o.g. Beispiel wäre es <code>cd "С:\Program Files (x86)\fhem\alexa-fhem"</code>
# Mit <source lang="bash" style="width:50%;">npm install</source> alle Abhängigkeiten installieren. Bei der Felermedlung wie "Der Befehl "npm" ist entweder falsch geschrieben oder konnte nicht gefunden werden." ist die Installation von Node.js zu überprüfen.
# SSL Zertifikat erzeugen. Dafür muss man alle Befehle aus dem Skript ''createKey.sh'' nacheinander manuell ausführen. Hierbei beachten, dass ein Kennwort vergeben werden muss, das mindestens aus 4 Zeichen besteht, dieses Kennwort bitte merken. Der Windows-Welt unbekannter Befehl <code>mv</code> ist durch <code>move /y</code> zu ersetzen:<source lang="bash" style="width:50%;">openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365</source><source lang="bash" style="width:50%;">openssl rsa -in key.pem -out newkey.pem</source><source lang="bash" style="width:50%;">move /y newkey.pem key.pem</source> Eventuelle Fehlermeldung "can't open config file: /usr/local/ssl/openssl.cnf" o.Ä. lässt sich durch Befehl <code>set OPENSSL_CONF=<OpenSSL-Verzeichnis>\bin\openssl.cfg</code> beheben, wobei <OpenSSL-Verzeichnis> durch den entsprechenden Installationspfad (typischerweise <code>c:\OpenSSL-Win32</code>) zu ersetzen ist.
# Das Verzeichnis ''.alexa'' anlegen, ''und zwar im Benutzerverzeichnis desjenigen Benutzers, unter dem Alexa-Fhem laufen soll.'' In aktuellen Versionen von Windows (ab Windows 7 bzw. ab Windows Server 2008 R2) liegt das Verzeichnis unter <code>C:\Users\<Benutzername></code>, also z.B. für Benutzer "Administrator" - unter <code>C:\Users\Administrator</code>. Falls Windows sich weigert das Verzichniss mit dem Punkt am Anfang zu erstellen, kann man das aus der Kommandozeile machen:<source lang="bash" style="width:50%;">cd "C:\Users\<Benutzername>"</source><source lang="bash" style="width:50%;">
mkdir ".alexa"</source>
# Die Datei ''config-sample.json'' nach ''C:\Users\<Benutzername>.alexa/config.json'' kopieren.
# Achtung: Ggf. müssen auch die Dateien key.pem und cert.pem ins entsprechende Verzeichnis (<code>"<FHEM-Hauptverzeichis>\alexa-fhem\bin</code>) kopiert werden.

====Update====
Hier wir das Update auf eine neue Version von Alexa-Fhem beschrieben
# Das Verzeichnis ''alexa-fhem'' im Hauptverzeichnis von FHEM (typischerweise <code>/opt/fhem</code>) umbenennen in ''alexa-fhem.old''.
# Die tgz-Datei der neuen Alexa-Fhem-Version unter Linux im Hauptverzeichnis von FHEM (typischerweise <code>/opt/fhem</code>) entpacken (''nicht'' unter Windows, das zerstört die Rechteeinstellungen).
# Das dabei entstandene Verzeichnis ''package'' in ''alexa-fhem'' umbenennen, in das Verzeichnis wechseln
# Mit <source lang="bash" style="width:50%;">npm install</source> alle Abhängigkeiten installieren (kein sudo!).
# Die Zertifikatsdateien key.pem und cert.pem aus dem alten Verzeichnis ''alexa-fhem.old'' ins neue Verzeichnis ''alexa-fhem'' kopieren.
Natürlich dann den Dienst neu starten, auch müssen selbstredend irgendwelche Modifikationen an der Datei server.js in der neuen Version nachgezogen werden. Wenn alles läuft, kann das alte Verzeichnis ''alexa-fhem.old'' gelöscht 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 | Skill Id bestimmen]]
# ''oauthClientID'' -> ''Client ID'' dem Abschnitt [[#Login_with_Amazon | 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"
}
]
}

Mehrere Custom Skills lassen sich mit der folgenden Syntax eintragen
"applicationId": [ "amzn1.ask.skill.1" , "amzn1.ask.skill.2" ],
"oauthClientID": [ "amzn1.application-oa2-client.1" , "amzn1.application-oa2-client.1" ]

Danach durch Aufruf von <source lang="bash" style="width:50%;">./bin/alexa</source> den Dienst starten (kein sudo!)

Unter Windows startet man Alexa-Dienst durch <source lang="bash" style="width:50%;">node alexa</source> aus der <code>alex-fhem/bin</code> (also erst z.B. durch <code>cd "<FHEM-Hauptverzeichis>\alexa-fhem\bin"</code> ins richtige Verzeichnis kommen)

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 {{Link2Forum|Topic=60244|Message=517271|LinkText=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:
<source lang="bash" style="width:50%;">sudo chmod 755 /etc/init.d/alexa
sudo update-rc.d alexa defaults</source>

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

Nun folgende Devices anlegen (ggf. einem Raum zuordnen, z.B. AlexaControl):
<source lang="bash" style="width:75%;">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 &")})</source>

==== Alexa-Fhem als Service (systemd) installieren ====
Auf neueren Installationen (z.B. RPi Jessie) wird init.d durch systemd ersetzt. Folgend die Anleitung um alexa-fhem als Service zu installieren auf einem Raspberry Pi mit Jessie.

Zunächst einen neuen Benutzer anlegen unter dem alexa-fhem laufen soll, falls man nicht möchtet dass alexa-fhem z.B. mit dem fhem User ausgeführt wird:

<code lang="bash" style="width:75%;">
sudo useradd -M --system alexa
</code>

Eigentlich braucht der Benutzer keine Gruppen, aber man kann den Benutzer auch der Gruppe <code>dialout</code> hinzufügen (<code>sudo usermod -a -G dialout alexa</code>)

Datei "alexa" unter <code>/etc/default</code> anlegen

# Defaults / Konfigurations Optionen für alexa-fhem
# Wo findet alexa-fhem die config.json Datei?
ALEXA_OPTS=-U /opt/fhem/.alexa

Den Pfad <code>/opt/fhem/.alexa</code> an die Systemgegebenheiten anpassen. Letztendlich kann die config.json irgendwo liegen, hauptsache alexa-fhem weiß wo. Achtung: Natürlich muss der Benutzer auch Zugriff auf das Verzeichnis mit der config als auch das alexa-fhem Verzeichnis haben.

Datei "alexa.service" unter <code>/etc/systemd/system</code> anlegen:

[Unit]
Description=Node.js Alexa Server
After=syslog.target network-online.target

[Service]
Type=simple
User=alexa #oder ein anderer Benutzer wie fhem
EnvironmentFile=/etc/default/alexa
# oder wo auch immer eure alexa-fhem liegt
ExecStart=/opt/fhem/alexa-fhem/bin/alexa $ALEXA_OPTS
Restart=on-failure
RestartSec=10
KillMode=process

[Install]
WantedBy=multi-user.target

Um den Service zu aktiveren und zu starten helfen folgende Befehle:
sudo systemctl daemon-reload
sudo systemctl enable alexa
sudo systemctl start alexa

Status abfragen mit
sudo systemctl status alexa

Log einsehen?
sudo journalctl -u alexa

(mit <code>-f</code> kann man den follow Modus aktivieren, wie <code>tail -f</code>).
Bei einen reboot startet alexa-fhem jetzt automatisch.

==== 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
<code>https://<IP-Adresse des Servers>:3000</code> kann man testen, ob der Alexa-Fhem Service läuft - der Seitenaufruf liefert eine Zeile JSON-Code, beginnend mit
<code>{"header":{"name":"UnsupportedOperationError"...</code>

=== 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:
<source lang="bash" style="width:70%;">define MyAlexa alexa</source>

<hr>

=== Alexa Skills ===
Für folgende Schritte muss man unter der Adresse http://developer.amazon.com angemeldet sein
# Anmeldung auswählen [[Datei:Developer.amazon.com-01-login2.png|200px]]
# Anmeldedaten eingeben [[Datei:Developer.amazon.com-02-userpass2.png|200px]]

==== 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'' [[Datei:Developer.amazon.com-03-apps_and_services.png|200px]]
# Anschließend auswählen ''Security Profiles'' [[Datei:Developer.amazon.com-05-apps_and_services_-_security_profiles.png|200px]]
# Auswählen ''Create a New Security Profile'' aus [[Datei:Developer.amazon.com-06-apps_and_services_-_create_a_new_security_profile.png|200px]]
# Dann einen Namen und eine Beschreibung für das Profil eingeben und mit ''Save'' bestätigen [[Datei:Developer.amazon.com-07-apps_and_services_-_security_profile_management.png|200px]]

===== Login with Amazon =====
{{Randnotiz|RNTyp=[g|Info]|RNText=Hier wird beschrieben, wo ''Client Id'' und ''Client Secret'' zu finden sind}}
# Oben rechts auf ''Login with Amazon'' klicken. [[Datei:Developer.amazon.com-08-login_with_amazon.png|200px]]
# Auf der neu geladenen Seite auswählen ''Sign up'' [[Datei:Developer.amazon.com-09-login_with_amazon_-_sign_up.png|200px]]
# Anschließend im Dropdown Menü das vorher angelegte Profil auswählen und mit ''Confirm'' bestätigen [[Datei:Developer.amazon.com-10-login_with_amazon_-_create_new_profile.png|200px]] [[Datei:Developer.amazon.com-11-login_with_amazon_-_create_new_profile2.png|200px]]
# Im folgenden Fenster die Adresse [https://www.amazon.com/gp/help/customer/display.html?nodeId=468496 https://www.amazon.com/gp/help/customer/display.html?nodeId=468496] eingeben und mit ''Save'' bestätigen. '''Todo Erklärungsbedarf: WARUM diese Adresse''' [[Datei:Developer.amazon.com-12-login_with_amazon_-_enter_consent_screen_information.png|200px]]
# Anschließend bei dem neu angelegten Eintrag auf der rechten Seite auf das Zahnrad klicken und ''Web Settings'' auswählen [[Datei:Developer.amazon.com-13-login_with_amazon_-_web_settings.png|200px]]
# Im neu geladenen Fenster anklicken von ''Edit'' [[Datei:Developer.amazon.com-14-login_with_amazon_-_edit.png|200px]]
# Anschließend bei ''Allowed Return URLs'' die folgenden drei Adressen eingeben. ''xxx'' muss hierbei durch den Wert ersetzt werden, der in den beiden Abschnitten [[#SmartHome_Skill_anlegen | SmartHome Skill anlegen]] bzw. [[#Custom_Skill_anlegen | Custom Skill anlegen]] jeweils unter Punkt 4 (Seite ''Configuration'') bei ''Redirect Urls'' am Ende der URLs angezeigt wird
## [https://layla.amazon.co.uk/api/skill/link/xxx https://layla.amazon.co.uk/api/skill/link/xxx]
## [https://pitangui.amazon.com/api/skill/link/xxx https://pitangui.amazon.com/api/skill/link/xxx]
## [https://layla.amazon.com/api/skill/link/xxx https://layla.amazon.com/api/skill/link/xxx]
. [[Datei:Developer.amazon.com-15-login_with_amazon_-_allowed_return_urls.png|200px]]

==== Skills bearbeiten ====
# Im Menü den Punkt ''ALEXA'' auswählen [[Datei:Developer.amazon.com-03-apps_and_services.png|200px]]
# Anschließend im Feld ''Alexa Skills Kit'' auf ''Get started'' klicken [[Datei:Developer.amazon.com-17-alexa_-_alex_skills_kit_-_get_started.png|200px]]

===== SmartHome Skill anlegen =====
# Oben rechts ''Add a New Skill'' auswählen [[Datei:Developer.amazon.com-18-alexa_-_alex_skills_kit_-_add_a_new_skill.png|200px]]
# 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") [[Datei:Developer.amazon.com-19-alexa_-_alex_skills_kit_-_skill_information.png|200px]]
# Die folgende Seite einfach mit ''Next'' überspringen [[Datei:Developer.amazon.com-20-alexa_-_alex_skills_kit_-_interaction_model.png|200px]]
# 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 [[#ARN_der_AWS_Lambda_Funktion_bestimmen | AWS Lambda Funktion]] eintragen.
#:* ''Authorization URL'' -> <code>https://www.amazon.com/ap/oa</code>
#:* ''Client ID'' -> ''Client ID'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1
#:* ''Scope'' -> <code>profile:user_id</code> (wörtlich 1:1 eintragen)
#:* ''Redirect URLs'' - sollten vorbelegt sein
#:* ''Authorization Grant Type'' -> ''Auth Code Grant'' auswählen
#:* ''Access Token URI'' -> <code>https://api.amazon.com/auth/o2/token</code>
#:* ''Client Secret'' -> ''Client Secret'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1
#:* ''Client Authentication Scheme'' -> ''HTTP Basic''
#:* ''Privacy Policy URL'' -> <code>https://www.amazon.com/gp/help/customer/display.html?nodeId=468496</code> 
 [[Datei:Developer.amazon.com-21-alexa_-_alex_skills_kit_-_configuration.png|200px]] [[Datei:Developer.amazon.com-22-alexa_-_alex_skills_kit_-_test.png|200px]]

===== Custom Skill anlegen =====
<ol>
<li> Oben rechts ''Add a New Skill'' auswählen [[Datei:Developer.amazon.com-18-alexa_-_alex_skills_kit_-_add_a_new_skill.png|200px]]</li>
<li> Auf der folgenden Seite (''Skill Information'') die nachstehenden Daten eingeben und dann mit ''Next'' bestätigen:
<ul>
<li> ''Skill Type'' -> ''Custom Interaction Model'' </li>
<li> ''Language'' -> ''German''</li>
<li> ''Name'' -> beliebiger Name, z.B. "MySmartHome Advanced". Dieser wird in der Alexa App unter "Meine Skills" angezeigt.</li>
<li> ''Invocation Name'' -> Aufruf des Skills, unter dem dieser später gestartet wird. Z.B. "Alexa, starte James" [[Datei:CustomSkill_2.PNG|400px]]</li>
</ul></li>
<li>Auf der Seite ''Interaction Model'' folgende Eingaben tätigen und mit ''Next'' abschließen
<ul>
<li>In einem separaten Browserfenster FHEM aufrufen, und für das bereits definierte Alexa-Gerät das Kommando <code>get MyAlexa interactionModel</code> aufrufen. Es erscheint ein Popup-Fenster mit ziemlich vielen Zeilen.
<li>In die Box ''Intent Schema'' kopiert man den ersten Teil dieser FHEM-Ausgabe hinein, also: <blockquote>
{
"intents" : [
<hier ziemlich viele Zeilen>
]
}
</blockquote></li>
<li>Nun die ''Custom Slot Types'' einrichten. Dazu muss aus dem zweiten Teil der FHEM-Ausgabe jeweils der Slot-Type (z.B. <code>FHEM_article</code>) 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.</li>
<li>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 <code>get MyAlexa customSlotTypes</code> ausführen. Auch diese Ausgabe wird, wie oben beschriebeen, in Custom Slot Types eingetragen (erst der TYPE, dann die möglichen Werte)
<li>Anschließend erneut die FHEM-Ausgabe schließen und erneut für das bereits definierte Alexa-Gerät das Kommando <code>get MyAlexa interactionModel</code> aufrufen.
<li>Unter ''Sample Utterances'' nun den Text aus dem dritten Teil dieser FHEM-Ausgabe hineinkopieren [[Datei:CustomSkill_5.PNG|400px]]</li>
</ul></li>
<li>Auf der Seite ''Configuration'' Folgendes eingeben und mit ''Next'' bestätigen:
<ul>
<li>''Service Endpoint Type'' -> ''AWS Lambda'' auswählen</li>
<li>''Geographical Region'' -> ''Europe'' auswählen und im Textfeld den Wert aus Abschnitt [[#AWS_Lambda_Funktion_anlegen | AWS Lambda Funktion anlegen]] (Punkt 12) eintragen. </li>
<li>''Do you allow users to create an account or link to an existing account with you?'' -> ''Yes''</li>
<li>''Authorization URL'' -> <code>https://www.amazon.com/ap/oa</code></li>
<li>''Client ID'' -> ''Client ID'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1</li>
<li>''Scope'' -> <code>profile:user_id</code> (wörtlich 1:1 eintragen)</li>
<li>''Redirect URLs'' - sollten vorbelegt sein</li>
<li>''Authorization Grant Type'' -> ''Auth Code Grant'' auswählen</li>
<li>''Access Token URI'' -> <code>https://api.amazon.com/auth/o2/token</code></li>
<li>''Client Secret'' -> ''Client Secret'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1</li>
<li>''Client Authentication Scheme'' -> ''HTTP Basic''</li>
<li>''Privacy Policy URL'' -> <code>https://www.amazon.com/gp/help/customer/display.html?nodeId=468496</code></li>
</ul>
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 | AWS Lambda Funktion]] nachgetragen werden, dies wird in Abschnitt [[#Trigger_f.C3.BCr_Custom_Skill_hinzuf.C3.BCgen | Trigger für Custom Skill hinzufügen]] beschrieben.
 [[Datei:CustomSkill_6.PNG|400px]] [[Datei:CustomSkill_7.PNG|400px]]</li>

==== 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 | Custom Skill Anlegen]] unter Punkt 2 eingetragen hat.

==== Skill Id bestimmen ====
{{Randnotiz|RNTyp=[g|Info]|RNText=Hier wird beschrieben, wo die ''Alexa Skill Id'' zu finden ist}}
Für das [[#AWS_Lamba_Funktion_anlegen | Anlegen einer ''AWS Lambda Funktion'']] bzw für die [[#Alexa-Fhem_konfigurieren | Konfiguration von Alexa-Fhem]] wird die ''Alexa Skill Id'' benötigt. An diese kommt man wie folgt:
# Anmelden wie unter [[#Alexa_Skills | Alexa Skills]] beschrieben.
# Menüpunkt ''ALEXA'' auswählen, wie [[#Skills_bearbeiten | Skills bearbeiten]] erklärt.
# Beim gewünschten Eintrag auf ''Edit'' klicken [[Datei:Developer.amazon.com-23-alexa_-_alex_skills_kit_-_overview.png|200px]]
# Die Id, die nun oben angezeigt wird, ist die gesuchte. Sie hat typischerweise das Format <code>amzn1.ask.skill.[Zahlen und Bindestriche]</code> [[Datei:Aws.amazon.com-06-configure_triggers2.png|200px]]

<hr>

=== AWS Lambda Funktion ===
Für folgende Schritte muss man unter der Adresse http://aws.amazon.com angemeldet sein
# Anmeldung auswählen [[Datei:Aws.amazon.com-01-site.png|200px]]
# Anmeldedaten eingeben [[Datei:Aws.amazon.com-02-login.png|200px]]
# Den Punkt ''Lambda'' links auf der Startseite auswählen, bzw. im Menü ''Services'' unter ''Compute'' den Menüpunkt ''Lambda'' auswählen [[Datei:Aws.amazon.com-03-lambda.png|200px]]
==== AWS Lambda Funktion anlegen ====
# Für eine erste Lambda-Funktion den Punkt ''Get Started Now'' auswählen [[Datei:Aws.amazon.com-04-get_started_now.png|200px]]
# Den Blueprint ''Blank function'' auswählen [[Datei:Aws.amazon.com-05-select_blueprint.png|200px]]
# Im neuen Fenster dann auf den gestrichelten Kasten klicken und ''Alexa Smart Home'' auswählen und mit ''Next'' bestätigen [[Datei:Aws.amazon.com-06-configure_triggers1.png|200px]]
## 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 | Skill Id bestimmen]] beschrieben wird, den Haken bei ''Enable trigger'' setzen und mit ''Next'' bestätigen [[Datei:Aws.amazon.com-06-configure_triggers3.png|200px]]
# Auf der Konfigurationsseite eingeben:
## ''Name'' -> ''FHEM''
## ''Runtime'' -> Node.js 4.3.
## ''Role'' -> ''Choose an existing role''
### 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_installieren | 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. [[Datei:Aws.amazon.com-07-configure_function.png|200px]]
# Auf der Übersichtsseite dann ''Create function'' anklicken [[Datei:Aws.amazon.com-08-review.png|200px]]

==== 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 [[Datei:Aws.amazon.com-09-go_overview.png|200px]]
# Anschließend den Radiobutton der angelegten Funktion ''FHEM'' markieren und im Menü ''Action'' den Punkt ''Show ARN'' auswählen [[Datei:Aws.amazon.com-10-1-show_arn.png|200px]]
# Es wird nun eine ARN Adresse angezeigt, die für den Abschnitt [[#SmartHome_Skill_anlegen| SmartHome Skill anlegen]] benötigt wird [[Datei:Aws.amazon.com-10-2-arn.png|200px]]

=== Absichern des Zugriffs ===
Natürlich muss der Zugriff auf den von Alexa-Fhem verwendeten Port (default: 3000, Bestandteil des Codes in der AWS Lambda-Funktion) durch die Firewall freigeschaltet werden (auf einer FritzBox unter "Portfreigaben").

==== Absicherung direkt in Alexa-FHEM ====
Die Kommunikation zwischen Amazon AWS und Alexa-FHEM ist auf die folgenden Arten gesichert:
* Die Verbindung erfolgt per HTTPS
* Es werden nur Verbindung angenommen auf denen ein gültiges Alexa-Event gesendet wird.
* Es werden nur Verbindungen angenommen die ein gültiges und noch nicht abgelaufenes OAuth-Token enthalten. Jedes neue Token wird live bei Amazon auf Gültigkeit geprüft.
* Es werden nur Verbindungen mit lokal konfigurierter Skill-ID angenommen.
* Es ist nicht möglich von außen beliebige FHEM Kommandos zu senden. Die FHEM Kommandos werden nur lokal erzeugt.

Wer möchte kann Alexa-FHEM natürlich noch weiter absichern. Es gilt aber, dass nicht jedes zusätzliche Glied in der Kette die Sicherheit sondern unter Umständen nur die Angriffsfläche erhöht. Ein falsch konfigurierter und nach aussen offener Apache (oder anderer ReverseProxy) ist unter Umständen ein größeres Risiko als Alexa-FHEM alleine.

==== Absicherung per ReverseProxy ====
<s>Die Kommunikation zwischen Amazon und FHEM ist wegen der Verwendung von SSL schon verschlüsselt - prinzipiell kann aber jeder von außen mit Alexa-Fhem kommunizieren. Man sollte sich deshalb im Klaren darüber sein, dass dies eine Sicherheitslücke darstellt:</s> Jeder offene Port verleitet zu Angriffen, und mit zunehmender Verbreitung von Alexa steigt auch das Risiko. Es wird deshalb empfohlen, vor den eigentlichen Alexa-Server zur Absicherung einen Apache-Webserver als ReverseProxy zu setzen. Nicht nur ist der Apache eine hervorragend stabile und seit Jahrzehnten getestete Software, sondern die Konfiguration als ReverseProxy erlaubt auch, den Zugriff auf den Alexa-Fhem-Rechner auf die Amazon-Maschinen zu beschränken.

'''Achtung: Dies ist keine allgemeine Anleitung in Sachen Computersicherheit.''' Im Folgenden gehen wir davon aus, dass
* Grundbegriffe wie Firewall, IP-Ports, SSL und Dynamic DNS vertraut sind
* Ein Apache Webserver (idealerweise auf einer zweiten Maschine) bereits installiert ist und die Konfiguration verstanden wurde (wenn nicht: Es gibt im Netz ''tausende'' von Anleitungen dafür...)
* Ein Servername von einem DynDNS-Anbieter - sagen wir ''myhome.is-my-castle.com'' - bereits von ''außen'' auf unser SmartHome zeigt.
* Alexa-Fhem in einer der oben beschriebenen Basiskonfigurationen läuft, d.h. der Zugriff auf <code>https://myhome.is-my-castle.com:3000</code> ergibt, wie im Punkt [[#Alexa-Fhem_testen|Alexa-Fhem testen]] beschrieben, eine Antwort des Node.js Servers.

Als erster Schritt zur Absicherung muss das ReverseProxy Modul für den Apache installiert und mit <code>a2enmod</code> aktiviert werden, hierzu sei auf [https://www.digitalocean.com/community/tutorials/how-to-use-apache-http-server-as-reverse-proxy-using-mod_proxy-extension diese Anleitung] verwiesen. Der zweite Schritt besteht darin, den SSL-Zugriff durch ein Passwort abzusichern. Dazu wird auf dem Apache-Rechner das Programm
htpasswd <passwdfile> <username>
ausgeführt, das Programm fragt dann nach dem gewünschten Passwort. Wir nehmen im Folgenden an, dass das Passwortfile ''/etc/apache2/htpasswd'' ist, der gesetzte Username ''alexa'' lautet und das Passwort ''my_smarthome'' ist.

Im dritten Schritt wird nun in das Apache-Konfigurationsfile die Weiterleitung auf den eigentlichen Alexa-Fhem-Rechner eingetragen. Dazu wählen wir, dass von außen der Standard-SSL-Port 443 benutzt werden soll, sowie als Verzeichnisname ''/alexa''. '''Achtung:''' Dieser Code soll '''nicht''' in die Default-Konfiguration des Apache-Webservers. Sondern in eine separate Datei (Dateiname z.B. "fhem"), die ins Unterverzeichnis /etc/apache2/conf.d gestellt wird.

<VirtualHost *:443>
ServerName myhome.is-my-castle.com
SSLEngine on
SSLProxyEngine on
SSLProxyCheckPeerCN off
SSLProxyCheckPeerName off
SSLCertificateKeyFile /etc/apache2/mycert/server.key
SSLCertificateFile /etc/apache2/mycert/server.crt
<Location /alexa>
AuthType Basic
AuthName "Authentication Required"
AuthUserFile "/etc/apache2/htpasswd"
Require valid-user
ProxyPass https://<hier IP-Adresse des Alexa-Fhem-Rechners>:3000/
ProxyPassReverse https://<hier IP-Adresse des Alexa-Fhem-Rechners>:3000/
Order deny,allow
Allow from All
</Location>
(... Hier eventuell weitere Umleitungen)
</VirtualHost>
Nach einem Neustart des Apache-Servers, dem Schließen des Ports 3000 in der Firewall sowie dem Öffnen des Ports 443 ist der Alexa-Fhem-Rechner von außen nur noch erreichbar durch den Aufruf von <code>https://myhome.is-my-castle.com/alexa</code> und verlangt unmittelbar die Eingabe von Username und Passwort.

Der vierte Schritt ist nun, den Code der AWS Lambda-Funktion an fünf Stellen zu verändern
'''const PORT=443;'''
const HOST='myhome.is-my-castle.com';
'''const PATH='/alexa';'''
'''const AUTH='alexa:my_smarthome';'''
// entry
exports.handler = function(event, context, callback) {
console.log(`EVENT: ${event}`);
console.log(`CONTEXT: ${context}`);
var post_data = JSON.stringify(event);
var options = {
hostname: HOST,
port: PORT,
//family: 6,
'''path: PATH,'''
method: 'POST',
'''auth: AUTH,'''
rejectUnauthorized: false, // accept self-signed
(etc., Rest des Codes wie gehabt)
Natürlich muss der Zugriff getestet werden. Bei Beachtung aller dieser Schritte werden alle un-autorisierten Zugriffe von außen abgewehrt. Eine noch weiter gehende Sicherung ist möglich, dazu kann in der Serverkonfiguration der Zugriff auf die Amazon-Domains beschränkt werden. Das ganze Alexa-System ist aber noch in konstanter Weiterentwicklung, diese Domain-Namen können sich also noch ändern.

== 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 [http://alexa.amazon.de 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 [[Datei:Alexa.amazon.de-01-startseite.png|200px]]
# Oben rechts ''Meine Skills'' bzw. ''Ihre Skills'' auswählen [[Datei:Alexa.amazon.de-03-meine_skills.png|200px]]
# In der Liste der Skills sollte das angelegte FHEM Skill angezeigt werden. Dieses anklicken [[Datei:Alexa.amazon.de-02-liste_skills.png|200px]]
# Oben Rechts in den Details des Skills auf ''Skill aktivieren'' klicken [[Datei:Alexa.amazon.de-04-skill_details.png|200px]]
# In dem neu geöffneten Fenster die Autorisierung bestätigen [[Datei:Alexa.amazon.de-05-amazon_auth.png|200px]]
# Anschließend sollte die Verbindung erfolgreich aufgebaut worden sein [[Datei:Alexa.amazon.de-06-success.png|200px]]

=== Geräte ===
# Auf http://alexa.amazon.de anmelden
# Auf ''Smart Home'' klicken [[Datei:Alexa.amazon.de-01-startseite.png|200px]]
# Anschließend den Punkt ''Geräte suchen'' anklicken [[Datei:Alexa.amazon.de-07-Gerätesuche.png|200px]]
# 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
*** <code><cmd>:<device>:<reading></code>, hier können nicht verwendete Elemente von links nach rechts weg gelassen werden.
*** <code><name>=<value></code>, hier kann <code><value></code> entweder ein Wert oder semikolonseparierte Liste sein.
*** Oder dem schlüsselwort <code>clear</code>, welches alle vorhandenen (default) Parameter dieser Characteristik löscht. <code>clear</code> 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 | 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 | Custom Skill Anlegen]]).

Der Aufruf dieses Gerätes mit Alexa erfolgt dann z.B. mit den Sätzen
<pre style="width:50%;">
"Alexa, sage <Custom Skill Invocation Name>: Stelle Weckzeit auf Neunzehn Uhr Siebenundzwanzig"
"Alexa, frage <Custom Skill Invocation Name> nach dem Status von Weckzeit"
</pre>
Dabei ist natürlich der ''Custom Skill Invocation Name'' durch den Wert zu ersetzen, den man im Abschnitt [[#Custom_Skill_anlegen | 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 [https://www.dpunkt.de/buecher/12387/9783960090120-smarthome-hacks.html 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\');
}
}

<hr>

=== 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
<pre>
"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
</pre>
* 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
<pre>
"Alexa, sage <Custom Skill Invocation Name>: schalte (die) Beleuchtung an" -> LightScene Alle_An wird ausgewählt
</pre>
Dafür wird es aber auch möglich sein direkt die SzenenNamen im gesprochenen Kommando zu verwenden und so auf die Umwege über dummys und ähnliches zu verzichten.

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.

Zwei andere Ansätze Lichtszenen zu schalten die ohne DOIF auskommen sind im Folgenden beschrieben:

* Wenn es von Interesse ist die Steuerung mit einer Darstellung in FTUI zu verbinden: Statt der oben beschriebenen dummy Devices kann man readingsProxy Devices mit passenden setFn und valueFn analog zum [[Harmony#Button_f.C3.BCr_eine_bestimmte_Activity_im_Frontend_und_Homekit_.C3.BCber_readingsProxy|diesem Beispiel für harmony aktivitäten]] verwenden.

* Für jede zu schaltende Szene wird ein dummy angelegt dessen homebridgeMapping direkt auf das LightScene Device zeigt:

define <dummy> dummy
attr <dummy> setList on off
attr <dummy> genericDeviceType switch
attr <dummy> homebridgeMapping On=<light scene>::state,valueOn=<szene>,cmdOn=scene+<szene>,cmdOff=scene+<szene aus>

Bei der zweiten Variante wird davon ausgegangen das der aktuelle status nicht abgefragt oder angezeigt werden soll. Deshalb gibt es keine direkte RadioButton Funktionalität.

== 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 [http://alexa.amazon.de/spa/index.html] 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:
<pre style="width:50%;">
“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”
</pre>

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

Das Prinzip der Kommandokonfiguration ist {{Link2Forum|Topic=60244|Message=532513|LinkText=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:
<pre style="width:50%;">
const PORT=3000;
const HOST='mein.host.name';
</pre>

====Freigabe von Port 3000====
{{Randnotiz|RNTyp=Fehl|RNText=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: [[Homebridge_einrichten#NodeJS_installieren|NodeJS installieren]] sowie [[Homebridge_einrichten#Python.2C_g.2B.2B.2C_MDNS_installieren|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<source lang="bash" style="width:50%;">node -v</source>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 <code>~/.alexa/config.json</code> die folgenden Zeilen rauslöschen:

<pre>
"nat-pmp": "10.0.1.1",
"nat-upnp": true,
</pre>

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:
<source lang="bash" style="width:70%;">2755327 4 -rwxr-xr-x 1 pi pi 339 Nov 26 23:20 alexa</source>
Sollte dies nicht der Fall sein bitte mit:
<source lang="bash" style="width:70%;">chmod +x alexa</source>
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 <code>~/.alexa/config.json</code> geöffnet werden und der Abschnitt "connections" um folgende Zeile ergänzt werden:<pre>
"auth": {"user": "fhem", "pass": "fhempassword"},</pre>
Bei Verwendung von SSL bei FHEM muss auch noch <pre>
"ssl": true,</pre> hinzugefügt werden

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

Alexa-Fhem

2017-07-17T13:42:24Z

DR: /* Erstinstallation */ + Installation unter Windows

'''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 [https://forum.fhem.de/index.php?action=profile;u=430 justme1968] im {{Link2Forum|Topic=60244|LinkText=Forum}} veröffentlicht.
Das ist eine erste Version der Dokumentation zur Installation und Einrichtung, eine Erweiterung wird sicherlich in nächster Zeit noch folgen.
{{Infobox Modul
|ModPurpose=Anbindung von FHEM an Amazon Assistent Alexa
|ModType=x
|ModTechName=
|ModForumArea=Frontends/Sprachsteuerung
|ModOwner=justme1968
}}

==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.{{Randnotiz|RNTyp=r|RNText=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'''.
*Card bezeichnet einen Eintrag in der Alexa-App, der die erkannte Sprachnachricht sowie weiter gehenden Informationen über die Reaktion von Alexa enzthält und Rückmeldung an Amazon erlaubt.
*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===
[[Datei:2gpXyLN.jpg|200px|thumb|right|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 <code>lambda.js</code> code an alexa-fhem weitergeleitet
*alexa-fhem steuert FHEM und sendet ein Antwort-Event zurück
*<code>lambda.js</code> 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-Fhem#Smart_Home|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-Fhem#Custom|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==
{{Randnotiz|RNTyp=[g|Info]|RNText=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:
<source lang="bash" style="width:50%;">
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install build-essential libssl-dev</source>

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:
<source lang="bash" style="width:50%;">
curl -sL https://deb.nodesource.com/setup_4.x | sudo -E bash -
sudo apt-get install -y nodejs
</source>

=== Alexa-Fhem installieren ===
'''Aus gegebenem Anlass: Dies ist weder eine Einführung in Linux, noch eine Anfängerdokumentation für FHEM.''' Also erst die Grundlagen lernen, und dann mit Alexa beginnen !

Die aktuelle Version ist jeweils {{Link2Forum|Topic=60244|Message=540117|LinkText=hier}} zu finden.

====Erstinstallation====
Hier wird die Erstinstallation von Alexa-Fhem beschrieben.
==== Linux ====
# Die tgz-Datei unter Linux im Hauptverzeichnis von FHEM (typischerweise <code>/opt/fhem</code>) entpacken (''nicht'' unter Windows, das zerstört die Rechteeinstellungen).
# Das dabei entstandene Verzeichnis ''package'' in ''alexa-fhem'' umbenennen <source lang="bash" style="width:50%;">mv package alexa-fhem</source>
# Durch <source lang="bash" style="width:50%;">cd alexa-fhem</source> in das Verzeichnis wechseln
# Mit <source lang="bash" style="width:50%;">npm install</source> alle Abhängigkeiten installieren (kein sudo!).
# SSL Zertifikat erzeugen durch Aufruf von <source lang="bash" style="width:50%;">./createKey.sh</source> (kein sudo!). Hierbei beachten, dass ein Kennwort vergeben werden muss, das mindestens aus 4 Zeichen besteht, dieses Kennwort bitte merken.
# Das Verzeichnis ''.alexa'' anlegen, ''und zwar im Home-Verzeichnis desjenigen Benutzers, unter dem Alexa-Fhem laufen soll.'' Insbesondere ist zu beachten, dass dieser Nutzer u.U. im Startskript explizit gesetzt wird. Mit dem untenstehenden Skript ist das ''nicht'' der User fhem, sondern der User ''pi''. Das Symbol ''~/'' verweist auf das Home-Verzeichnis des Benutzers, der gerade die Installation vornimmt.
# Die Datei ''config-sample.json'' nach ''.alexa/config.json'' kopieren. Achtung: Installiert man alexa-fhem als root-user, zeigt das Symbol ''~/'' auf ''/root'' - und die Konfigurationsdatei 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.
==== Windows ====
''Vor'' der Installation von Alexa-Fhem muss man folgende Anwendungen installieren:
* Node.js (die aktuelle Version findet man unter https://nodejs.org/en/download/)
* OpenSSL (http://slproweb.com/products/Win32OpenSSL.html oder https://www.heise.de/download/product/win32-openssl-47316/download)
Erst dann fängt man mit Alexa-Fhem an.

# Die tgz-Datei im Hauptverzeichnis von FHEM (z.B. <code>С:\Program Files (x86)\fhem</code>) entpacken.
# Das dabei entstandene Verzeichnis ''package'' in ''alexa-fhem'' umbenennen
# Windows-Shell (Kommandozeile, Eingabeaufforderung usw.) öffnen. "Start" -> "Ausführen" (oder [Windows-Taste]+[R]) -> cmd -> Ok. Durch <source lang="bash" style="width:50%;">cd "<FHEM-Hauptverzeichis>\alexa-fhem"</source> in das Verzeichnis wechseln. Dabei ist natürlich der <FHEM-Hauptverzeichis> durch den entsprechenden Pfad aus dem Schritt 1 zu ersetzen. Im o.g. Beispiel wäre es <code>cd "С:\Program Files (x86)\fhem\alexa-fhem"</code>
# Mit <source lang="bash" style="width:50%;">npm install</source> alle Abhängigkeiten installieren. Bei der Felermedlung wie "Der Befehl "npm" ist entweder falsch geschrieben oder konnte nicht gefunden werden." ist die Installation von Node.js zu überprüfen.
# SSL Zertifikat erzeugen. Dafür muss man alle Befehle aus dem Skript ''createKey.sh'' nacheinander manuell ausführen. Hierbei beachten, dass ein Kennwort vergeben werden muss, das mindestens aus 4 Zeichen besteht, dieses Kennwort bitte merken. Der Windows-Welt unbekannter Befehl <code>mv</code> ist durch <code>move /y</code> zu ersetzen:<source lang="bash" style="width:50%;">openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365</source><source lang="bash" style="width:50%;">openssl rsa -in key.pem -out newkey.pem</source><source lang="bash" style="width:50%;">move /y newkey.pem key.pem</source> Eventuelle Fehlermeldung "can't open config file: /usr/local/ssl/openssl.cnf" o.Ä. lässt sich durch Befehl <code>set OPENSSL_CONF=<OpenSSL-Verzeichnis>\bin\openssl.cfg</code> beheben, wobei <OpenSSL-Verzeichnis> durch den entsprechenden Installationspfad (typischerweise <code>c:\OpenSSL-Win32</code>) zu ersetzen ist.
# Das Verzeichnis ''.alexa'' anlegen, ''und zwar im Benutzerverzeichnis desjenigen Benutzers, unter dem Alexa-Fhem laufen soll.'' In aktuellen Versionen von Windows (ab Windows 7 bzw. ab Windows Server 2008 R2) liegt das Verzeichnis unter <code>C:\Users\<Benutzername></code>, also z.B. für Benutzer "Administrator" - unter <code>C:\Users\Administrator</code>. Falls Windows sich weigert das Verzichniss mit dem Punkt am Anfang zu erstellen, kann man das aus der Kommandozeile machen:<source lang="bash" style="width:50%;">cd "C:\Users\<Benutzername>"</source><source lang="bash" style="width:50%;">
mkdir ".alexa"</source>
# Die Datei ''config-sample.json'' nach ''C:\Users\<Benutzername>.alexa/config.json'' kopieren.
# Achtung: Ggf. müssen auch die Dateien key.pem und cert.pem ins entsprechende Verzeichnis (<code>"<FHEM-Hauptverzeichis>\alexa-fhem\bin</code>) kopiert werden.

====Update====
Hier wir das Update auf eine neue Version von Alexa-Fhem beschrieben
# Das Verzeichnis ''alexa-fhem'' im Hauptverzeichnis von FHEM (typischerweise <code>/opt/fhem</code>) umbenennen in ''alexa-fhem.old''.
# Die tgz-Datei der neuen Alexa-Fhem-Version unter Linux im Hauptverzeichnis von FHEM (typischerweise <code>/opt/fhem</code>) entpacken (''nicht'' unter Windows, das zerstört die Rechteeinstellungen).
# Das dabei entstandene Verzeichnis ''package'' in ''alexa-fhem'' umbenennen, in das Verzeichnis wechseln
# Mit <source lang="bash" style="width:50%;">npm install</source> alle Abhängigkeiten installieren (kein sudo!).
# Die Zertifikatsdateien key.pem und cert.pem aus dem alten Verzeichnis ''alexa-fhem.old'' ins neue Verzeichnis ''alexa-fhem'' kopieren.
Natürlich dann den Dienst neu starten, auch müssen selbstredend irgendwelche Modifikationen an der Datei server.js in der neuen Version nachgezogen werden. Wenn alles läuft, kann das alte Verzeichnis ''alexa-fhem.old'' gelöscht 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 | Skill Id bestimmen]]
# ''oauthClientID'' -> ''Client ID'' dem Abschnitt [[#Login_with_Amazon | 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"
}
]
}

Mehrere Custom Skills lassen sich mit der folgenden Syntax eintragen
"applicationId": [ "amzn1.ask.skill.1" , "amzn1.ask.skill.2" ],
"oauthClientID": [ "amzn1.application-oa2-client.1" , "amzn1.application-oa2-client.1" ]

Danach durch Aufruf von <source lang="bash" style="width:50%;">./bin/alexa</source> 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 {{Link2Forum|Topic=60244|Message=517271|LinkText=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:
<source lang="bash" style="width:50%;">sudo chmod 755 /etc/init.d/alexa
sudo update-rc.d alexa defaults</source>

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

Nun folgende Devices anlegen (ggf. einem Raum zuordnen, z.B. AlexaControl):
<source lang="bash" style="width:75%;">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 &")})</source>

==== Alexa-Fhem als Service (systemd) installieren ====
Auf neueren Installationen (z.B. RPi Jessie) wird init.d durch systemd ersetzt. Folgend die Anleitung um alexa-fhem als Service zu installieren auf einem Raspberry Pi mit Jessie.

Zunächst einen neuen Benutzer anlegen unter dem alexa-fhem laufen soll, falls man nicht möchtet dass alexa-fhem z.B. mit dem fhem User ausgeführt wird:

<code lang="bash" style="width:75%;">
sudo useradd -M --system alexa
</code>

Eigentlich braucht der Benutzer keine Gruppen, aber man kann den Benutzer auch der Gruppe <code>dialout</code> hinzufügen (<code>sudo usermod -a -G dialout alexa</code>)

Datei "alexa" unter <code>/etc/default</code> anlegen

# Defaults / Konfigurations Optionen für alexa-fhem
# Wo findet alexa-fhem die config.json Datei?
ALEXA_OPTS=-U /opt/fhem/.alexa

Den Pfad <code>/opt/fhem/.alexa</code> an die Systemgegebenheiten anpassen. Letztendlich kann die config.json irgendwo liegen, hauptsache alexa-fhem weiß wo. Achtung: Natürlich muss der Benutzer auch Zugriff auf das Verzeichnis mit der config als auch das alexa-fhem Verzeichnis haben.

Datei "alexa.service" unter <code>/etc/systemd/system</code> anlegen:

[Unit]
Description=Node.js Alexa Server
After=syslog.target network-online.target

[Service]
Type=simple
User=alexa #oder ein anderer Benutzer wie fhem
EnvironmentFile=/etc/default/alexa
# oder wo auch immer eure alexa-fhem liegt
ExecStart=/opt/fhem/alexa-fhem/bin/alexa $ALEXA_OPTS
Restart=on-failure
RestartSec=10
KillMode=process

[Install]
WantedBy=multi-user.target

Um den Service zu aktiveren und zu starten helfen folgende Befehle:
sudo systemctl daemon-reload
sudo systemctl enable alexa
sudo systemctl start alexa

Status abfragen mit
sudo systemctl status alexa

Log einsehen?
sudo journalctl -u alexa

(mit <code>-f</code> kann man den follow Modus aktivieren, wie <code>tail -f</code>).
Bei einen reboot startet alexa-fhem jetzt automatisch.

==== 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
<code>https://<IP-Adresse des Servers>:3000</code> kann man testen, ob der Alexa-Fhem Service läuft - der Seitenaufruf liefert eine Zeile JSON-Code, beginnend mit
<code>{"header":{"name":"UnsupportedOperationError"...</code>

=== 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:
<source lang="bash" style="width:70%;">define MyAlexa alexa</source>

<hr>

=== Alexa Skills ===
Für folgende Schritte muss man unter der Adresse http://developer.amazon.com angemeldet sein
# Anmeldung auswählen [[Datei:Developer.amazon.com-01-login2.png|200px]]
# Anmeldedaten eingeben [[Datei:Developer.amazon.com-02-userpass2.png|200px]]

==== 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'' [[Datei:Developer.amazon.com-03-apps_and_services.png|200px]]
# Anschließend auswählen ''Security Profiles'' [[Datei:Developer.amazon.com-05-apps_and_services_-_security_profiles.png|200px]]
# Auswählen ''Create a New Security Profile'' aus [[Datei:Developer.amazon.com-06-apps_and_services_-_create_a_new_security_profile.png|200px]]
# Dann einen Namen und eine Beschreibung für das Profil eingeben und mit ''Save'' bestätigen [[Datei:Developer.amazon.com-07-apps_and_services_-_security_profile_management.png|200px]]

===== Login with Amazon =====
{{Randnotiz|RNTyp=[g|Info]|RNText=Hier wird beschrieben, wo ''Client Id'' und ''Client Secret'' zu finden sind}}
# Oben rechts auf ''Login with Amazon'' klicken. [[Datei:Developer.amazon.com-08-login_with_amazon.png|200px]]
# Auf der neu geladenen Seite auswählen ''Sign up'' [[Datei:Developer.amazon.com-09-login_with_amazon_-_sign_up.png|200px]]
# Anschließend im Dropdown Menü das vorher angelegte Profil auswählen und mit ''Confirm'' bestätigen [[Datei:Developer.amazon.com-10-login_with_amazon_-_create_new_profile.png|200px]] [[Datei:Developer.amazon.com-11-login_with_amazon_-_create_new_profile2.png|200px]]
# Im folgenden Fenster die Adresse [https://www.amazon.com/gp/help/customer/display.html?nodeId=468496 https://www.amazon.com/gp/help/customer/display.html?nodeId=468496] eingeben und mit ''Save'' bestätigen. '''Todo Erklärungsbedarf: WARUM diese Adresse''' [[Datei:Developer.amazon.com-12-login_with_amazon_-_enter_consent_screen_information.png|200px]]
# Anschließend bei dem neu angelegten Eintrag auf der rechten Seite auf das Zahnrad klicken und ''Web Settings'' auswählen [[Datei:Developer.amazon.com-13-login_with_amazon_-_web_settings.png|200px]]
# Im neu geladenen Fenster anklicken von ''Edit'' [[Datei:Developer.amazon.com-14-login_with_amazon_-_edit.png|200px]]
# Anschließend bei ''Allowed Return URLs'' die folgenden drei Adressen eingeben. ''xxx'' muss hierbei durch den Wert ersetzt werden, der in den beiden Abschnitten [[#SmartHome_Skill_anlegen | SmartHome Skill anlegen]] bzw. [[#Custom_Skill_anlegen | Custom Skill anlegen]] jeweils unter Punkt 4 (Seite ''Configuration'') bei ''Redirect Urls'' am Ende der URLs angezeigt wird
## [https://layla.amazon.co.uk/api/skill/link/xxx https://layla.amazon.co.uk/api/skill/link/xxx]
## [https://pitangui.amazon.com/api/skill/link/xxx https://pitangui.amazon.com/api/skill/link/xxx]
## [https://layla.amazon.com/api/skill/link/xxx https://layla.amazon.com/api/skill/link/xxx]
. [[Datei:Developer.amazon.com-15-login_with_amazon_-_allowed_return_urls.png|200px]]

==== Skills bearbeiten ====
# Im Menü den Punkt ''ALEXA'' auswählen [[Datei:Developer.amazon.com-03-apps_and_services.png|200px]]
# Anschließend im Feld ''Alexa Skills Kit'' auf ''Get started'' klicken [[Datei:Developer.amazon.com-17-alexa_-_alex_skills_kit_-_get_started.png|200px]]

===== SmartHome Skill anlegen =====
# Oben rechts ''Add a New Skill'' auswählen [[Datei:Developer.amazon.com-18-alexa_-_alex_skills_kit_-_add_a_new_skill.png|200px]]
# 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") [[Datei:Developer.amazon.com-19-alexa_-_alex_skills_kit_-_skill_information.png|200px]]
# Die folgende Seite einfach mit ''Next'' überspringen [[Datei:Developer.amazon.com-20-alexa_-_alex_skills_kit_-_interaction_model.png|200px]]
# 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 [[#ARN_der_AWS_Lambda_Funktion_bestimmen | AWS Lambda Funktion]] eintragen.
#:* ''Authorization URL'' -> <code>https://www.amazon.com/ap/oa</code>
#:* ''Client ID'' -> ''Client ID'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1
#:* ''Scope'' -> <code>profile:user_id</code> (wörtlich 1:1 eintragen)
#:* ''Redirect URLs'' - sollten vorbelegt sein
#:* ''Authorization Grant Type'' -> ''Auth Code Grant'' auswählen
#:* ''Access Token URI'' -> <code>https://api.amazon.com/auth/o2/token</code>
#:* ''Client Secret'' -> ''Client Secret'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1
#:* ''Client Authentication Scheme'' -> ''HTTP Basic''
#:* ''Privacy Policy URL'' -> <code>https://www.amazon.com/gp/help/customer/display.html?nodeId=468496</code> 
 [[Datei:Developer.amazon.com-21-alexa_-_alex_skills_kit_-_configuration.png|200px]] [[Datei:Developer.amazon.com-22-alexa_-_alex_skills_kit_-_test.png|200px]]

===== Custom Skill anlegen =====
<ol>
<li> Oben rechts ''Add a New Skill'' auswählen [[Datei:Developer.amazon.com-18-alexa_-_alex_skills_kit_-_add_a_new_skill.png|200px]]</li>
<li> Auf der folgenden Seite (''Skill Information'') die nachstehenden Daten eingeben und dann mit ''Next'' bestätigen:
<ul>
<li> ''Skill Type'' -> ''Custom Interaction Model'' </li>
<li> ''Language'' -> ''German''</li>
<li> ''Name'' -> beliebiger Name, z.B. "MySmartHome Advanced". Dieser wird in der Alexa App unter "Meine Skills" angezeigt.</li>
<li> ''Invocation Name'' -> Aufruf des Skills, unter dem dieser später gestartet wird. Z.B. "Alexa, starte James" [[Datei:CustomSkill_2.PNG|400px]]</li>
</ul></li>
<li>Auf der Seite ''Interaction Model'' folgende Eingaben tätigen und mit ''Next'' abschließen
<ul>
<li>In einem separaten Browserfenster FHEM aufrufen, und für das bereits definierte Alexa-Gerät das Kommando <code>get MyAlexa interactionModel</code> aufrufen. Es erscheint ein Popup-Fenster mit ziemlich vielen Zeilen.
<li>In die Box ''Intent Schema'' kopiert man den ersten Teil dieser FHEM-Ausgabe hinein, also: <blockquote>
{
"intents" : [
<hier ziemlich viele Zeilen>
]
}
</blockquote></li>
<li>Nun die ''Custom Slot Types'' einrichten. Dazu muss aus dem zweiten Teil der FHEM-Ausgabe jeweils der Slot-Type (z.B. <code>FHEM_article</code>) 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.</li>
<li>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 <code>get MyAlexa customSlotTypes</code> ausführen. Auch diese Ausgabe wird, wie oben beschriebeen, in Custom Slot Types eingetragen (erst der TYPE, dann die möglichen Werte)
<li>Anschließend erneut die FHEM-Ausgabe schließen und erneut für das bereits definierte Alexa-Gerät das Kommando <code>get MyAlexa interactionModel</code> aufrufen.
<li>Unter ''Sample Utterances'' nun den Text aus dem dritten Teil dieser FHEM-Ausgabe hineinkopieren [[Datei:CustomSkill_5.PNG|400px]]</li>
</ul></li>
<li>Auf der Seite ''Configuration'' Folgendes eingeben und mit ''Next'' bestätigen:
<ul>
<li>''Service Endpoint Type'' -> ''AWS Lambda'' auswählen</li>
<li>''Geographical Region'' -> ''Europe'' auswählen und im Textfeld den Wert aus Abschnitt [[#AWS_Lambda_Funktion_anlegen | AWS Lambda Funktion anlegen]] (Punkt 12) eintragen. </li>
<li>''Do you allow users to create an account or link to an existing account with you?'' -> ''Yes''</li>
<li>''Authorization URL'' -> <code>https://www.amazon.com/ap/oa</code></li>
<li>''Client ID'' -> ''Client ID'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1</li>
<li>''Scope'' -> <code>profile:user_id</code> (wörtlich 1:1 eintragen)</li>
<li>''Redirect URLs'' - sollten vorbelegt sein</li>
<li>''Authorization Grant Type'' -> ''Auth Code Grant'' auswählen</li>
<li>''Access Token URI'' -> <code>https://api.amazon.com/auth/o2/token</code></li>
<li>''Client Secret'' -> ''Client Secret'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1</li>
<li>''Client Authentication Scheme'' -> ''HTTP Basic''</li>
<li>''Privacy Policy URL'' -> <code>https://www.amazon.com/gp/help/customer/display.html?nodeId=468496</code></li>
</ul>
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 | AWS Lambda Funktion]] nachgetragen werden, dies wird in Abschnitt [[#Trigger_f.C3.BCr_Custom_Skill_hinzuf.C3.BCgen | Trigger für Custom Skill hinzufügen]] beschrieben.
 [[Datei:CustomSkill_6.PNG|400px]] [[Datei:CustomSkill_7.PNG|400px]]</li>

==== 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 | Custom Skill Anlegen]] unter Punkt 2 eingetragen hat.

==== Skill Id bestimmen ====
{{Randnotiz|RNTyp=[g|Info]|RNText=Hier wird beschrieben, wo die ''Alexa Skill Id'' zu finden ist}}
Für das [[#AWS_Lamba_Funktion_anlegen | Anlegen einer ''AWS Lambda Funktion'']] bzw für die [[#Alexa-Fhem_konfigurieren | Konfiguration von Alexa-Fhem]] wird die ''Alexa Skill Id'' benötigt. An diese kommt man wie folgt:
# Anmelden wie unter [[#Alexa_Skills | Alexa Skills]] beschrieben.
# Menüpunkt ''ALEXA'' auswählen, wie [[#Skills_bearbeiten | Skills bearbeiten]] erklärt.
# Beim gewünschten Eintrag auf ''Edit'' klicken [[Datei:Developer.amazon.com-23-alexa_-_alex_skills_kit_-_overview.png|200px]]
# Die Id, die nun oben angezeigt wird, ist die gesuchte. Sie hat typischerweise das Format <code>amzn1.ask.skill.[Zahlen und Bindestriche]</code> [[Datei:Aws.amazon.com-06-configure_triggers2.png|200px]]

<hr>

=== AWS Lambda Funktion ===
Für folgende Schritte muss man unter der Adresse http://aws.amazon.com angemeldet sein
# Anmeldung auswählen [[Datei:Aws.amazon.com-01-site.png|200px]]
# Anmeldedaten eingeben [[Datei:Aws.amazon.com-02-login.png|200px]]
# Den Punkt ''Lambda'' links auf der Startseite auswählen, bzw. im Menü ''Services'' unter ''Compute'' den Menüpunkt ''Lambda'' auswählen [[Datei:Aws.amazon.com-03-lambda.png|200px]]
==== AWS Lambda Funktion anlegen ====
# Für eine erste Lambda-Funktion den Punkt ''Get Started Now'' auswählen [[Datei:Aws.amazon.com-04-get_started_now.png|200px]]
# Den Blueprint ''Blank function'' auswählen [[Datei:Aws.amazon.com-05-select_blueprint.png|200px]]
# Im neuen Fenster dann auf den gestrichelten Kasten klicken und ''Alexa Smart Home'' auswählen und mit ''Next'' bestätigen [[Datei:Aws.amazon.com-06-configure_triggers1.png|200px]]
## 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 | Skill Id bestimmen]] beschrieben wird, den Haken bei ''Enable trigger'' setzen und mit ''Next'' bestätigen [[Datei:Aws.amazon.com-06-configure_triggers3.png|200px]]
# Auf der Konfigurationsseite eingeben:
## ''Name'' -> ''FHEM''
## ''Runtime'' -> Node.js 4.3.
## ''Role'' -> ''Choose an existing role''
### 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_installieren | 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. [[Datei:Aws.amazon.com-07-configure_function.png|200px]]
# Auf der Übersichtsseite dann ''Create function'' anklicken [[Datei:Aws.amazon.com-08-review.png|200px]]

==== 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 [[Datei:Aws.amazon.com-09-go_overview.png|200px]]
# Anschließend den Radiobutton der angelegten Funktion ''FHEM'' markieren und im Menü ''Action'' den Punkt ''Show ARN'' auswählen [[Datei:Aws.amazon.com-10-1-show_arn.png|200px]]
# Es wird nun eine ARN Adresse angezeigt, die für den Abschnitt [[#SmartHome_Skill_anlegen| SmartHome Skill anlegen]] benötigt wird [[Datei:Aws.amazon.com-10-2-arn.png|200px]]

=== Absichern des Zugriffs ===
Natürlich muss der Zugriff auf den von Alexa-Fhem verwendeten Port (default: 3000, Bestandteil des Codes in der AWS Lambda-Funktion) durch die Firewall freigeschaltet werden (auf einer FritzBox unter "Portfreigaben").

==== Absicherung direkt in Alexa-FHEM ====
Die Kommunikation zwischen Amazon AWS und Alexa-FHEM ist auf die folgenden Arten gesichert:
* Die Verbindung erfolgt per HTTPS
* Es werden nur Verbindung angenommen auf denen ein gültiges Alexa-Event gesendet wird.
* Es werden nur Verbindungen angenommen die ein gültiges und noch nicht abgelaufenes OAuth-Token enthalten. Jedes neue Token wird live bei Amazon auf Gültigkeit geprüft.
* Es werden nur Verbindungen mit lokal konfigurierter Skill-ID angenommen.
* Es ist nicht möglich von außen beliebige FHEM Kommandos zu senden. Die FHEM Kommandos werden nur lokal erzeugt.

Wer möchte kann Alexa-FHEM natürlich noch weiter absichern. Es gilt aber, dass nicht jedes zusätzliche Glied in der Kette die Sicherheit sondern unter Umständen nur die Angriffsfläche erhöht. Ein falsch konfigurierter und nach aussen offener Apache (oder anderer ReverseProxy) ist unter Umständen ein größeres Risiko als Alexa-FHEM alleine.

==== Absicherung per ReverseProxy ====
<s>Die Kommunikation zwischen Amazon und FHEM ist wegen der Verwendung von SSL schon verschlüsselt - prinzipiell kann aber jeder von außen mit Alexa-Fhem kommunizieren. Man sollte sich deshalb im Klaren darüber sein, dass dies eine Sicherheitslücke darstellt:</s> Jeder offene Port verleitet zu Angriffen, und mit zunehmender Verbreitung von Alexa steigt auch das Risiko. Es wird deshalb empfohlen, vor den eigentlichen Alexa-Server zur Absicherung einen Apache-Webserver als ReverseProxy zu setzen. Nicht nur ist der Apache eine hervorragend stabile und seit Jahrzehnten getestete Software, sondern die Konfiguration als ReverseProxy erlaubt auch, den Zugriff auf den Alexa-Fhem-Rechner auf die Amazon-Maschinen zu beschränken.

'''Achtung: Dies ist keine allgemeine Anleitung in Sachen Computersicherheit.''' Im Folgenden gehen wir davon aus, dass
* Grundbegriffe wie Firewall, IP-Ports, SSL und Dynamic DNS vertraut sind
* Ein Apache Webserver (idealerweise auf einer zweiten Maschine) bereits installiert ist und die Konfiguration verstanden wurde (wenn nicht: Es gibt im Netz ''tausende'' von Anleitungen dafür...)
* Ein Servername von einem DynDNS-Anbieter - sagen wir ''myhome.is-my-castle.com'' - bereits von ''außen'' auf unser SmartHome zeigt.
* Alexa-Fhem in einer der oben beschriebenen Basiskonfigurationen läuft, d.h. der Zugriff auf <code>https://myhome.is-my-castle.com:3000</code> ergibt, wie im Punkt [[#Alexa-Fhem_testen|Alexa-Fhem testen]] beschrieben, eine Antwort des Node.js Servers.

Als erster Schritt zur Absicherung muss das ReverseProxy Modul für den Apache installiert und mit <code>a2enmod</code> aktiviert werden, hierzu sei auf [https://www.digitalocean.com/community/tutorials/how-to-use-apache-http-server-as-reverse-proxy-using-mod_proxy-extension diese Anleitung] verwiesen. Der zweite Schritt besteht darin, den SSL-Zugriff durch ein Passwort abzusichern. Dazu wird auf dem Apache-Rechner das Programm
htpasswd <passwdfile> <username>
ausgeführt, das Programm fragt dann nach dem gewünschten Passwort. Wir nehmen im Folgenden an, dass das Passwortfile ''/etc/apache2/htpasswd'' ist, der gesetzte Username ''alexa'' lautet und das Passwort ''my_smarthome'' ist.

Im dritten Schritt wird nun in das Apache-Konfigurationsfile die Weiterleitung auf den eigentlichen Alexa-Fhem-Rechner eingetragen. Dazu wählen wir, dass von außen der Standard-SSL-Port 443 benutzt werden soll, sowie als Verzeichnisname ''/alexa''. '''Achtung:''' Dieser Code soll '''nicht''' in die Default-Konfiguration des Apache-Webservers. Sondern in eine separate Datei (Dateiname z.B. "fhem"), die ins Unterverzeichnis /etc/apache2/conf.d gestellt wird.

<VirtualHost *:443>
ServerName myhome.is-my-castle.com
SSLEngine on
SSLProxyEngine on
SSLProxyCheckPeerCN off
SSLProxyCheckPeerName off
SSLCertificateKeyFile /etc/apache2/mycert/server.key
SSLCertificateFile /etc/apache2/mycert/server.crt
<Location /alexa>
AuthType Basic
AuthName "Authentication Required"
AuthUserFile "/etc/apache2/htpasswd"
Require valid-user
ProxyPass https://<hier IP-Adresse des Alexa-Fhem-Rechners>:3000/
ProxyPassReverse https://<hier IP-Adresse des Alexa-Fhem-Rechners>:3000/
Order deny,allow
Allow from All
</Location>
(... Hier eventuell weitere Umleitungen)
</VirtualHost>
Nach einem Neustart des Apache-Servers, dem Schließen des Ports 3000 in der Firewall sowie dem Öffnen des Ports 443 ist der Alexa-Fhem-Rechner von außen nur noch erreichbar durch den Aufruf von <code>https://myhome.is-my-castle.com/alexa</code> und verlangt unmittelbar die Eingabe von Username und Passwort.

Der vierte Schritt ist nun, den Code der AWS Lambda-Funktion an fünf Stellen zu verändern
'''const PORT=443;'''
const HOST='myhome.is-my-castle.com';
'''const PATH='/alexa';'''
'''const AUTH='alexa:my_smarthome';'''
// entry
exports.handler = function(event, context, callback) {
console.log(`EVENT: ${event}`);
console.log(`CONTEXT: ${context}`);
var post_data = JSON.stringify(event);
var options = {
hostname: HOST,
port: PORT,
//family: 6,
'''path: PATH,'''
method: 'POST',
'''auth: AUTH,'''
rejectUnauthorized: false, // accept self-signed
(etc., Rest des Codes wie gehabt)
Natürlich muss der Zugriff getestet werden. Bei Beachtung aller dieser Schritte werden alle un-autorisierten Zugriffe von außen abgewehrt. Eine noch weiter gehende Sicherung ist möglich, dazu kann in der Serverkonfiguration der Zugriff auf die Amazon-Domains beschränkt werden. Das ganze Alexa-System ist aber noch in konstanter Weiterentwicklung, diese Domain-Namen können sich also noch ändern.

== 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 [http://alexa.amazon.de 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 [[Datei:Alexa.amazon.de-01-startseite.png|200px]]
# Oben rechts ''Meine Skills'' bzw. ''Ihre Skills'' auswählen [[Datei:Alexa.amazon.de-03-meine_skills.png|200px]]
# In der Liste der Skills sollte das angelegte FHEM Skill angezeigt werden. Dieses anklicken [[Datei:Alexa.amazon.de-02-liste_skills.png|200px]]
# Oben Rechts in den Details des Skills auf ''Skill aktivieren'' klicken [[Datei:Alexa.amazon.de-04-skill_details.png|200px]]
# In dem neu geöffneten Fenster die Autorisierung bestätigen [[Datei:Alexa.amazon.de-05-amazon_auth.png|200px]]
# Anschließend sollte die Verbindung erfolgreich aufgebaut worden sein [[Datei:Alexa.amazon.de-06-success.png|200px]]

=== Geräte ===
# Auf http://alexa.amazon.de anmelden
# Auf ''Smart Home'' klicken [[Datei:Alexa.amazon.de-01-startseite.png|200px]]
# Anschließend den Punkt ''Geräte suchen'' anklicken [[Datei:Alexa.amazon.de-07-Gerätesuche.png|200px]]
# 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
*** <code><cmd>:<device>:<reading></code>, hier können nicht verwendete Elemente von links nach rechts weg gelassen werden.
*** <code><name>=<value></code>, hier kann <code><value></code> entweder ein Wert oder semikolonseparierte Liste sein.
*** Oder dem schlüsselwort <code>clear</code>, welches alle vorhandenen (default) Parameter dieser Characteristik löscht. <code>clear</code> 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 | 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 | Custom Skill Anlegen]]).

Der Aufruf dieses Gerätes mit Alexa erfolgt dann z.B. mit den Sätzen
<pre style="width:50%;">
"Alexa, sage <Custom Skill Invocation Name>: Stelle Weckzeit auf Neunzehn Uhr Siebenundzwanzig"
"Alexa, frage <Custom Skill Invocation Name> nach dem Status von Weckzeit"
</pre>
Dabei ist natürlich der ''Custom Skill Invocation Name'' durch den Wert zu ersetzen, den man im Abschnitt [[#Custom_Skill_anlegen | 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 [https://www.dpunkt.de/buecher/12387/9783960090120-smarthome-hacks.html 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\');
}
}

<hr>

=== 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
<pre>
"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
</pre>
* 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
<pre>
"Alexa, sage <Custom Skill Invocation Name>: schalte (die) Beleuchtung an" -> LightScene Alle_An wird ausgewählt
</pre>
Dafür wird es aber auch möglich sein direkt die SzenenNamen im gesprochenen Kommando zu verwenden und so auf die Umwege über dummys und ähnliches zu verzichten.

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.

Zwei andere Ansätze Lichtszenen zu schalten die ohne DOIF auskommen sind im Folgenden beschrieben:

* Wenn es von Interesse ist die Steuerung mit einer Darstellung in FTUI zu verbinden: Statt der oben beschriebenen dummy Devices kann man readingsProxy Devices mit passenden setFn und valueFn analog zum [[Harmony#Button_f.C3.BCr_eine_bestimmte_Activity_im_Frontend_und_Homekit_.C3.BCber_readingsProxy|diesem Beispiel für harmony aktivitäten]] verwenden.

* Für jede zu schaltende Szene wird ein dummy angelegt dessen homebridgeMapping direkt auf das LightScene Device zeigt:

define <dummy> dummy
attr <dummy> setList on off
attr <dummy> genericDeviceType switch
attr <dummy> homebridgeMapping On=<light scene>::state,valueOn=<szene>,cmdOn=scene+<szene>,cmdOff=scene+<szene aus>

Bei der zweiten Variante wird davon ausgegangen das der aktuelle status nicht abgefragt oder angezeigt werden soll. Deshalb gibt es keine direkte RadioButton Funktionalität.

== 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 [http://alexa.amazon.de/spa/index.html] 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:
<pre style="width:50%;">
“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”
</pre>

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

Das Prinzip der Kommandokonfiguration ist {{Link2Forum|Topic=60244|Message=532513|LinkText=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:
<pre style="width:50%;">
const PORT=3000;
const HOST='mein.host.name';
</pre>

====Freigabe von Port 3000====
{{Randnotiz|RNTyp=Fehl|RNText=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: [[Homebridge_einrichten#NodeJS_installieren|NodeJS installieren]] sowie [[Homebridge_einrichten#Python.2C_g.2B.2B.2C_MDNS_installieren|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<source lang="bash" style="width:50%;">node -v</source>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 <code>~/.alexa/config.json</code> die folgenden Zeilen rauslöschen:

<pre>
"nat-pmp": "10.0.1.1",
"nat-upnp": true,
</pre>

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:
<source lang="bash" style="width:70%;">2755327 4 -rwxr-xr-x 1 pi pi 339 Nov 26 23:20 alexa</source>
Sollte dies nicht der Fall sein bitte mit:
<source lang="bash" style="width:70%;">chmod +x alexa</source>
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 <code>~/.alexa/config.json</code> geöffnet werden und der Abschnitt "connections" um folgende Zeile ergänzt werden:<pre>
"auth": {"user": "fhem", "pass": "fhempassword"},</pre>
Bei Verwendung von SSL bei FHEM muss auch noch <pre>
"ssl": true,</pre> hinzugefügt werden

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