FHEMWiki - Benutzerbeiträge [de]

FHEM Connector für Amazon Alexa

2025-10-14T14:02:44Z

Hapege: /* Was geht alles ? */

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

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

* SONOS Beam und SONOS One

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

Der Thread im Forum zur Software ist hier: {{Link2Forum|Topic=94817}}.
{{Infobox Modul
|ModPurpose=Einfache Anbindung von FHEM an Amazon Assistent Alexa
|ModType=h
|ModCmdRef=alexa
|ModTechName=39_alexa.pm / alexa-fhem
|ModForumArea=Frontends/Sprachsteuerung
|ModOwner=gvzdus, André/ justme1968 ({{Link2FU|430|Forum}} / [[Benutzer Diskussion:Justme|Wiki]])
}}
==Einführung==
===Arbeitsweise und Datenfluss===
Vorläufig ist alexa-fhem im "FHEM Connector-Modus" ein reiner [https://developer.amazon.com/de/docs/smarthome/understand-the-smart-home-skill-api.html SmartHome-Skill].
SmartHome-Skills erhalten weder die Sprachdaten selber noch das, was Amazon in Textform verstanden hat, sondern vielmehr extrahiert Amazon aus dem verstandenen Text Anweisungen und Abfragen für Geräte, die dann an den Skill übermittelt werden. Charmant ist dabei, dass unmittelbar gefragt werden kann "Alexa, wie ist die Temperatur im Wohnzimmer?", während andere Skills zunächst explizit angesprochen werden müssen ("Alexa, frage FHEM nach der Temperatur im Wohnzimmer"). Außerdem kann der Nutzer mehrere Smarthome-Skills installieren, und die Geräte werden zu einer Gesamtmenge zusammengefasst.

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

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

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

==Installation==

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

===node.js installieren===

Ab Jessy liegt NodeJS bereits in einer ausreichend aktuellen Version vor (Stretch und Buster funktionieren ebenfalls). Mit

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

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

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

'''Anmerkung:''' diese Aussage bzgl. node-Version (und Jessie/Stretch) stimmt wohl für alexa-fhem Stand heute (12.06.2020) nicht mehr, siehe https://forum.fhem.de/index.php/topic,112025.msg1063218.html#msg1063218

=== Alexa-FHEM installieren ===

Nun installieren wir Alexa-fhem aus dem offiziellen Repository:

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

Der Vorgang benötigt etwas Zeit.

(Edit: die aktuelle Version 0.5.65 hat ein Problem, wenn ModeController verwendet wird. Wer modes braucht, der sollte die vorherige Version 0.5.64 installieren:
<syntaxhighlight lang="bash" style="width:50%;">
sudo npm install -g alexa-fhem@0.5.64
</syntaxhighlight>

=== Alexa-FHEM aktivieren ===

Wechsele jetzt in FHEM-Web!

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

* Zuerst bitte einfach einmal die Seite neu laden.

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

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

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

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

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

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

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

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

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

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

Du solltest dann folgende Ausgabe erhalten:

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

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

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

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

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

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

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

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

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

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

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

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

Wähle die Geräte aus, rufe sie auf und setze das Attribut "alexaName". Hierbei in Kürze nur der Hinweis:
* Keine Angst vor Leerzeichen und Umlauten, funktioniert.
* Große Angst vor Rechtschreibfehlern (Terrasse, Rollladen) oder komplizierten Wörtern "handgebastelte Martinslaterne im Kinderzimmer Iphigenie-Chantal".
* Mehrere Namen für dasselbe Gerät/Device in fhem werden unterstützt. Mehrere Namen werden durch <s>Strichpunkt</s> Komma getrennt<ref>Feature nicht dokumentiert {{Link2Forum|Topic=74041|LinkText=Forumsthread}}</ref>.
* Das Attribut "alexaRoom" ist NUR FÜR DEN CUSTOM SKILL relevant. Ausnahme: structure und LightScene Devices, siehe: [[FHEM_Connector_f%C3%BCr_Amazon_Alexa#Was_geht_alles_.3F]].

Lade die Geräte neu in die Software, indem Du <code>set <alexa> restart</code> ausführst!
[[Datei:HowToSet alexaName.png|alternativtext=How to set alexaName|ohne|mini|Wie setzt man das Attribut alexaName]]

'''Anmerkungen (weil oft gestellte Fragen im Forum) bzgl. Erkennung von Geräten:'''

* Wichtig ist, dass die Filtereinstellung in der alexa-fhem.cfg (zu finden unter "Edit Files") passt.
Das, was dort eingetragen ist (Standard: alexaName=..* / also es ist ein alexaName vergeben) auch an den entsprechenden Devices in fhem vorhanden ist.
Stimmt das nicht überein, kann alexa-fhem keine Devices von fhem abfragen/finden.
Ob der Filter entsprechend funktioniert kann man wie folgt testen: ''list Filtereinstellung'' beispiel mit Standardfilter: ''list alexaName=..*''

* Hat alexa-fhem per Filter Devices aus fhem "gefunden", geht es weiter mit der "Erkennung". Also um welches Device (Typ und "Fähigkeiten") handelt es sich. Dazu gilt folgendes:
** sind entsprechende Readings beim Device vorhanden (z.B. temperature, state mit on/off, ...) erkennt das alexa-fhem automatisch. Die Liste der automatisch erkannten Readings wächst ständig. Daher erst mal schauen ob das Device bereits entsprechend erkannt (typisiert) wurde. Das kann durch prüfen des alexa-fhem-Logs geschehen (NICHT fhem-log!).
** sind entsprechende "set-Befehle" erkennbar (oft auch durch Readings). Also ist beispielsweise (wie beim Dummy nötig) ein ''setList'' mit entsprechenden Einträgen vorhanden oder entsprechende Readings, z.B. desired-temp zum Stellen der Temperatur etc.
** wird das Device nicht richtig oder "unvollständig" erkannt helfen folgende Attribute:
*** genericDeviceType: hiermit kann alexa-fhem in die gewünschte Richtung "geschubbst" werden. Anmerkung: man kann nicht alles erzwingen, Readings bzw. set-Befehle müssen passen (oder per homebridgeMapping passend gemacht werden). Wenn ein genericDeviceType nicht per "Drop-Down" erscheint, dann kann er auch (wenn bekannt) einfach per WEB-cmd eingegeben werden: ''attr Devicename genericDeviceType media''
*** homebridgeMapping: hierdurch kann alexa-fhem bei der Erkennung von Zuständen und möglichen Einstellungen (also WAS kann das Device) unterstützt werden. Mittels homebridgeMapping können vorhandene Readings (Zustände) auf für alexa-fhem bekannte Zustände gemappt werden. Ebenso können damit Standard-fhem-Kommandos von alexa-fhem auf Device-spezifische gemappt werden. Beispiel: on/off auf Ein/Aus (falls das Device statt on/off eben ein Ein/Aus erwartet). Zum Beispiel: <syntaxhighlight lang="bash" style="width:50%;">
attr <thermostat> homebridgeMapping TargetTemperature=target::target,minValue=18,maxValue=25,minStep=0.5 CurrentTemperature=myTemp:temperature
</syntaxhighlight> [https://github.com/justme-1968/homebridge-fhem/blob/master/README.md weitere Beispiele]

 '''Mehrere Namen für dasselbe Gerät/Device in fhem sind möglich.''' 
Die Namen werden durch <s>Strichpunkt</s> Komma getrennt. 
Beispiel: 
<code>attr dmLampe alexaName Lichtkuppel,Lichtkugel</code>

'''Anmerkung bzgl. genericDeviceType und homebridgeMapping:''' 
* diese Attribute werden von verschiedenen "Sprachsteuerungsmodulen" in fhem verwendet (homebridge [dort wurde es "erfunden"], alexa-fhem, gassistant, ...). Daher ist nicht jedes Mapping für alle "Dienste" verwendbar. Ausprobieren schadet aber nicht.
* ebenso kann man mit diesen Attributen (homebridgeMapping wird gerne so "missbraucht") nichts erzwingen, was seitens Amazon/Alexa nicht unterstützt bzw. verstanden wird! D.h. zunächst ist zu prüfen, ob ein bestimmter (gewünschter) Sprachbefehl seitens Amazon/Alexa unterstützt wird! Aktuelles Beispiel (Stand Jan 2020): "Alexa, fahre den Rollo hoch/runter". Da ist Amazon/Alexa gerade dabei etwas zu tun. Bislang wird das nicht unterstützt, also ist das auch mit einem entsprechenden homebridgeMapping nicht zu erzwingen! Was unterstützt wird kann man bei Amazon nachlesen: [https://developer.amazon.com/es-ES/docs/alexa/device-apis/list-of-interfaces.html]

== Finale: Skill verknüpfen ==
Suche auf der Alexa-App den Skill "FHEM Connector".

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

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

Hier kopierst Du Deinen Anmeldeschlüssel (im Klartext!) hinein, den du mittels "get alexa proxyKey" erhalten hast, und klickst auf Check. Als glücklicher Mensch ist auf der folgenden Statusseite alles grün: 
[[Datei:FHEMlazy_check.png|240px]]

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

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

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

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

'''Als Abschluss muss man nur noch in ein Echo-Gerät seiner Wahl die Anweisung: "''Alexa suche smarte Geräte''" sprechen und schon sollten die oben genannten Geräte gefunden werden und in der APP als Geräte auftauchen.'''

== Was geht alles ? ==

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

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

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

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

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

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

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

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

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

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

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

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

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

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

* Geräte, die sich ein- (und optional) ausschalten lassen als Szene (ab alexa-fhem version 0.5.26)
** Über <code>genericDeviceType</code> scene
** Automatisch: Müssen <code>set on</code> und <code>set off</code> Kommandos haben
** homebridgeMapping On:reading=<reading>,cmdOn=<cmd>[,cmdOff=<cmd>]
** Hinweis: Fehlende Kommandos lassen sich mit cmdalias erzeugen
** Wichtig:
*** Ein Skill darf nur 12 Szenen automatisch erkennen und einbinden.
* Rollläden. Lange ein Problemthema, das nur mit "Schalte auf 0%, schalte auf 100% lief". Wichtig: "alexa-fhem" ab Version 0.5.39 einsetzen. GenericDevice-Type auf "blind" setzen. Nach Restart von alexa-fhem und neuer Gerätesuche sollte folgendes funktionieren:
** "..., öffne <Name> ganz"
** "..., schließe <Name> komplett"
** "hoch" und "runter" (ohne "ganz" oder "komplett") schalten jeweils nur einen bestimmten Prozentsatz hoch oder runter. Dieser kann mit <code>attr <name> homebridgeMapping TargetPosition:minStep=<wert></code>geändert werden. Aber Achtung: In diesem Intervall kann dann auch nur noch ein absoluter Prozentwert per Sprache oder Slider eingestellt werden! Bei z.B. 25% würden 13% zu 25% aufgerundet, 12% zu 0% abgerundet werden.
* Kontaktsensoren (ab alexa-fhem version 0.5.47)
** Automatisch wenn ein Reading <code>motion</code> vorhanden ist oder es sich um einen Zigbee bewgungsmelder an einer HUE oder deCONZ Bridge handelt
** Über <code>genericDeviceType</code> MotionSensor
** homebridgeMapping MotionDetected:reading=<reading>,values=<wert für bewgung>:1;<wert für keine bewegung>:0

* Alarmmelder (noch nicht in Deutschland):
** genericDeviceType Security
** homebridgeMapping Alarm=<reading>[,type=[fireAlarm|waterAlarm|burglaryAlarm|carbonMonoxideAlarm]]
** wenn der type nicht angegeben wird ist fireAlarm der default
** automatisch werden 0, ok und alles was mit no anfängt als OK erkannt. alles andere gilt als ALARM.
*Geräte mit mehrstufigen Modi:
**siehe den zugehörigen Thread im Forum: {{Link2Forum|Topic= 125604}}
**(Funktioniert Stand 10/25 nur mit alexa-fhem v0.5.64, nicht mit der aktuellen 0.5.65, siehe oben)

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

to be continued ...

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

=== Aktiv Routinen starten ===
Routinen (eine Funktionalität, die rein - genauso wie "Räume" - bei Amazon liegt und nicht von FHEM Connector beeinflusst wird) waren lange die ewige Antwort auf die Frage: "Meine Frau möchte aber '''Öffne Rollläden''<nowiki/>' sagen": In der Alexa-App gibt es im Menü den Punkt "Routinen", und hier lässt sich eine gewisse Anzahl von Aktionen (unter optionalen Bedingungen) an ein Sprachkommando knüpfen.

Neu: Routinen können inzwischen auch von Skills getriggert werden, und seit Version 0.5.47 (Februar 2020) auch von FHEM Connector. Das braucht niemand, um die Rollläden hochzufahren, denn das kann FHEM ja selber, aber um z.B. eine Ansage auf einem Alexa-Gerät zu triggern. Dafür gibt es auch das FHEM-Modul "echodevice", aber es erfordert ein paar Klimmzüge. Mit dem aktiven Triggern von Routinen kann FHEM auslösen, dass Alexa ungefragt (!) Dinge wie

''"Die Temperatur in der Tiefkühltruhe hat -16 Grad überschritten"''

in den Raum sagt. Also eine Alternative bzw. Ergänzung zu Alarmen / Erinnerungen per Telegram o.ä.

'''Vorgeschichte''':

Die Smarthome-Skill-API von Amazon sah schon lange das "proactiveReporting" vor: Also z.B. die gemessene Temperatur nicht erst auf Anfrage hin zu übermitteln, sondern laufend aktiv zu pushen. Aber warum Daten an Amazon senden, wenn es dafür keinen Mehrwert gibt? Beim Öffnen z.B. des Thermostaten in der Alexa-App kommen ohnehin laufend Statusabfragen. Warum also einen Datenpool bei Amazon über die Haustemperatur aufbauen und Änderungen pushen, wenn es keinen Mehrwert dafür gibt?

Inzwischen lassen sich (reale oder vermeintliche) Änderungen von ''Bewegungssensoren'' und ''Fensterkontakten'' als Startbedingung an Alexa-Routinen koppeln. Man kann in der Alexa-App (ggf. fiktive) Öffnen eines Fensterkontaktes an das Aufsagen eines freien Textes durch die Hausbutlerin knüpfen.

'''Umsetzung''':
* Jedes Alexa-Device, dessen Status aktiv zu Amazon gepusht werden soll, im Attribut "alexaProactiveEvents" mit einer "1" versehen. Per Default wird ''kein'' Gerät laufend aktiv zu Amazon gepusht!
* das geänderte Device einmal zu Amazon pushen "set <alexa> add <device>" (oder 'Alexa, suche neue Geräte' murmeln)
* Das Gerät sollte jetzt beim Anlegen einer neuen Routine ("Neue Routine", "Wenn Folgendes passiert", "Smart Home") als möglicher Triggerpunkt erscheinen.

==== Dummygeräte: ====
Ein Dummydevice sollte einen Kontaktschalter oder Bewegungssensor simulieren, um dann in FHEM eine beliebige Bedingung als Trigger zu definieren, und eine freie Ansage in Alexa als Routine zu definieren. Hier ein Beispiel:

<syntaxhighlight lang="bash" style="width:90%;">
define voicetrigger1 dummy
attr voicetrigger1 alexaName alle Fenster
attr voicetrigger1 alexaProactiveEvents 1
attr voicetrigger1 genericDeviceType contact
attr voicetrigger1 homebridgeMapping ContactSensorState=state,values=closed:CONTACT_DETECTED;open:CONTACT_NOT_DETECTED
attr voicetrigger1 setList open closed

set alexa add voicetrigger1
set alexa restart
</syntaxhighlight>

'''Fehlersuche:'''

Der Push setzt ein intaktes Push-Token voraus. Sollte im Alexa-Logfile Folgendes erscheinen:

<code>failed to refresh token: invalid_grant: 'The request has an invalid grant parameter : refresh_token'</code>

so ist das Push-Token nicht aktuell. Weil die Auswirkung lange nur war, dass Geräteänderungen nicht aktiv an Amazon gemeldet wurden, gibt es noch keine umfassende Analyse des Problems. Es lässt sich lösen, indem eine oder beide folgenden Aktionen ausgeführt werden:
* Löschen des ".eventToken" im Alexa-Device über "deletereading"
* "FHEM-Connector"-Skill auf "alexa.amazon.de" einmal deaktivieren und dann neu verbinden

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

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

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

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

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

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

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

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

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

Auf der Kommandoshell:

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

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

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

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

== Sicherheitskonzept und Secrets ==

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

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

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

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

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

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

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

== alexa-fhem Updaten bzw. "Upgraden" ==

'''Updaten einer "Connector" Installation:'''
* alexa-fhem über FHEM anhalten (Name des Alexa-Device: alexa):
:<syntaxhighlight lang="perl" style="width:50%;">set alexa stop</syntaxhighlight>

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

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

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

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

'''"Upgraden von einer "Nicht-Connector" Installation (z.B. manuelle Installation per pm-Download):'''
* Daten der aktuellen Installation sichern (v.a. config.json / man weiß ja nie)
* Autostart der aktuellen alexa-fhem Installation deaktivieren:
** Bei initd: Service deaktivieren mittels: <code>sudo update-rc.d -f alexa remove</code> Vorher mittels stoppen: <code>sudo service alexa stop</code> Startscript unter /etc/init.d/ löschen.
** Bei systemd: Service deaktivieren mittels: <code>sudo systemctl disable alexa</code> Vorher mittels stoppen: <code>sudo systemctl alexa stop</code> Startscript unter /etc/systemd/system/ löschen.
* ALLE vorhandenen alexa-fhem Daten LÖSCHEN! Bleiben Dinge zurück und wird dann laut Connector installiert kann es zu Problemen kommen!
* (reboot)
* Installation von alexa-fhem laut Anleitung (Beginn dieses Wiki)
* Falls eigene Dinge von früher genutzt werden wollen/sollen (z.B. Custom Skill), dann die entsprechenden Einträge aus der gesicherten config.json in die neu angelegte alexa-fhem.cfg (zu finden unter "Edit files") übernehmen.
* Werden keine eigenen Dinge verwendet, dann kann der Port (Standard: 3000) geschlossen werden und auch die Daten unter Amazon-Developer können gelöscht werden.

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

==Weitergehende Informationen==
*[[Alexa und Mappings]]
*[[Alexa Tipps und Kniffe]]
*[[FHEM Connector for Amazon Alexa]]
[[Kategorie:HOWTOS]]
[[Kategorie:Sprachsteuerung]]

==Hinweise==
<references />

FHEM Connector für Amazon Alexa

2025-10-14T14:02:17Z

Hapege: /* Was geht alles ? */

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

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

* SONOS Beam und SONOS One

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

Der Thread im Forum zur Software ist hier: {{Link2Forum|Topic=94817}}.
{{Infobox Modul
|ModPurpose=Einfache Anbindung von FHEM an Amazon Assistent Alexa
|ModType=h
|ModCmdRef=alexa
|ModTechName=39_alexa.pm / alexa-fhem
|ModForumArea=Frontends/Sprachsteuerung
|ModOwner=gvzdus, André/ justme1968 ({{Link2FU|430|Forum}} / [[Benutzer Diskussion:Justme|Wiki]])
}}
==Einführung==
===Arbeitsweise und Datenfluss===
Vorläufig ist alexa-fhem im "FHEM Connector-Modus" ein reiner [https://developer.amazon.com/de/docs/smarthome/understand-the-smart-home-skill-api.html SmartHome-Skill].
SmartHome-Skills erhalten weder die Sprachdaten selber noch das, was Amazon in Textform verstanden hat, sondern vielmehr extrahiert Amazon aus dem verstandenen Text Anweisungen und Abfragen für Geräte, die dann an den Skill übermittelt werden. Charmant ist dabei, dass unmittelbar gefragt werden kann "Alexa, wie ist die Temperatur im Wohnzimmer?", während andere Skills zunächst explizit angesprochen werden müssen ("Alexa, frage FHEM nach der Temperatur im Wohnzimmer"). Außerdem kann der Nutzer mehrere Smarthome-Skills installieren, und die Geräte werden zu einer Gesamtmenge zusammengefasst.

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

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

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

==Installation==

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

===node.js installieren===

Ab Jessy liegt NodeJS bereits in einer ausreichend aktuellen Version vor (Stretch und Buster funktionieren ebenfalls). Mit

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

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

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

'''Anmerkung:''' diese Aussage bzgl. node-Version (und Jessie/Stretch) stimmt wohl für alexa-fhem Stand heute (12.06.2020) nicht mehr, siehe https://forum.fhem.de/index.php/topic,112025.msg1063218.html#msg1063218

=== Alexa-FHEM installieren ===

Nun installieren wir Alexa-fhem aus dem offiziellen Repository:

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

Der Vorgang benötigt etwas Zeit.

(Edit: die aktuelle Version 0.5.65 hat ein Problem, wenn ModeController verwendet wird. Wer modes braucht, der sollte die vorherige Version 0.5.64 installieren:
<syntaxhighlight lang="bash" style="width:50%;">
sudo npm install -g alexa-fhem@0.5.64
</syntaxhighlight>

=== Alexa-FHEM aktivieren ===

Wechsele jetzt in FHEM-Web!

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

* Zuerst bitte einfach einmal die Seite neu laden.

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

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

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

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

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

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

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

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

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

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

Du solltest dann folgende Ausgabe erhalten:

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

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

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

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

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

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

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

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

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

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

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

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

Wähle die Geräte aus, rufe sie auf und setze das Attribut "alexaName". Hierbei in Kürze nur der Hinweis:
* Keine Angst vor Leerzeichen und Umlauten, funktioniert.
* Große Angst vor Rechtschreibfehlern (Terrasse, Rollladen) oder komplizierten Wörtern "handgebastelte Martinslaterne im Kinderzimmer Iphigenie-Chantal".
* Mehrere Namen für dasselbe Gerät/Device in fhem werden unterstützt. Mehrere Namen werden durch <s>Strichpunkt</s> Komma getrennt<ref>Feature nicht dokumentiert {{Link2Forum|Topic=74041|LinkText=Forumsthread}}</ref>.
* Das Attribut "alexaRoom" ist NUR FÜR DEN CUSTOM SKILL relevant. Ausnahme: structure und LightScene Devices, siehe: [[FHEM_Connector_f%C3%BCr_Amazon_Alexa#Was_geht_alles_.3F]].

Lade die Geräte neu in die Software, indem Du <code>set <alexa> restart</code> ausführst!
[[Datei:HowToSet alexaName.png|alternativtext=How to set alexaName|ohne|mini|Wie setzt man das Attribut alexaName]]

'''Anmerkungen (weil oft gestellte Fragen im Forum) bzgl. Erkennung von Geräten:'''

* Wichtig ist, dass die Filtereinstellung in der alexa-fhem.cfg (zu finden unter "Edit Files") passt.
Das, was dort eingetragen ist (Standard: alexaName=..* / also es ist ein alexaName vergeben) auch an den entsprechenden Devices in fhem vorhanden ist.
Stimmt das nicht überein, kann alexa-fhem keine Devices von fhem abfragen/finden.
Ob der Filter entsprechend funktioniert kann man wie folgt testen: ''list Filtereinstellung'' beispiel mit Standardfilter: ''list alexaName=..*''

* Hat alexa-fhem per Filter Devices aus fhem "gefunden", geht es weiter mit der "Erkennung". Also um welches Device (Typ und "Fähigkeiten") handelt es sich. Dazu gilt folgendes:
** sind entsprechende Readings beim Device vorhanden (z.B. temperature, state mit on/off, ...) erkennt das alexa-fhem automatisch. Die Liste der automatisch erkannten Readings wächst ständig. Daher erst mal schauen ob das Device bereits entsprechend erkannt (typisiert) wurde. Das kann durch prüfen des alexa-fhem-Logs geschehen (NICHT fhem-log!).
** sind entsprechende "set-Befehle" erkennbar (oft auch durch Readings). Also ist beispielsweise (wie beim Dummy nötig) ein ''setList'' mit entsprechenden Einträgen vorhanden oder entsprechende Readings, z.B. desired-temp zum Stellen der Temperatur etc.
** wird das Device nicht richtig oder "unvollständig" erkannt helfen folgende Attribute:
*** genericDeviceType: hiermit kann alexa-fhem in die gewünschte Richtung "geschubbst" werden. Anmerkung: man kann nicht alles erzwingen, Readings bzw. set-Befehle müssen passen (oder per homebridgeMapping passend gemacht werden). Wenn ein genericDeviceType nicht per "Drop-Down" erscheint, dann kann er auch (wenn bekannt) einfach per WEB-cmd eingegeben werden: ''attr Devicename genericDeviceType media''
*** homebridgeMapping: hierdurch kann alexa-fhem bei der Erkennung von Zuständen und möglichen Einstellungen (also WAS kann das Device) unterstützt werden. Mittels homebridgeMapping können vorhandene Readings (Zustände) auf für alexa-fhem bekannte Zustände gemappt werden. Ebenso können damit Standard-fhem-Kommandos von alexa-fhem auf Device-spezifische gemappt werden. Beispiel: on/off auf Ein/Aus (falls das Device statt on/off eben ein Ein/Aus erwartet). Zum Beispiel: <syntaxhighlight lang="bash" style="width:50%;">
attr <thermostat> homebridgeMapping TargetTemperature=target::target,minValue=18,maxValue=25,minStep=0.5 CurrentTemperature=myTemp:temperature
</syntaxhighlight> [https://github.com/justme-1968/homebridge-fhem/blob/master/README.md weitere Beispiele]

 '''Mehrere Namen für dasselbe Gerät/Device in fhem sind möglich.''' 
Die Namen werden durch <s>Strichpunkt</s> Komma getrennt. 
Beispiel: 
<code>attr dmLampe alexaName Lichtkuppel,Lichtkugel</code>

'''Anmerkung bzgl. genericDeviceType und homebridgeMapping:''' 
* diese Attribute werden von verschiedenen "Sprachsteuerungsmodulen" in fhem verwendet (homebridge [dort wurde es "erfunden"], alexa-fhem, gassistant, ...). Daher ist nicht jedes Mapping für alle "Dienste" verwendbar. Ausprobieren schadet aber nicht.
* ebenso kann man mit diesen Attributen (homebridgeMapping wird gerne so "missbraucht") nichts erzwingen, was seitens Amazon/Alexa nicht unterstützt bzw. verstanden wird! D.h. zunächst ist zu prüfen, ob ein bestimmter (gewünschter) Sprachbefehl seitens Amazon/Alexa unterstützt wird! Aktuelles Beispiel (Stand Jan 2020): "Alexa, fahre den Rollo hoch/runter". Da ist Amazon/Alexa gerade dabei etwas zu tun. Bislang wird das nicht unterstützt, also ist das auch mit einem entsprechenden homebridgeMapping nicht zu erzwingen! Was unterstützt wird kann man bei Amazon nachlesen: [https://developer.amazon.com/es-ES/docs/alexa/device-apis/list-of-interfaces.html]

== Finale: Skill verknüpfen ==
Suche auf der Alexa-App den Skill "FHEM Connector".

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

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

Hier kopierst Du Deinen Anmeldeschlüssel (im Klartext!) hinein, den du mittels "get alexa proxyKey" erhalten hast, und klickst auf Check. Als glücklicher Mensch ist auf der folgenden Statusseite alles grün: 
[[Datei:FHEMlazy_check.png|240px]]

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

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

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

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

'''Als Abschluss muss man nur noch in ein Echo-Gerät seiner Wahl die Anweisung: "''Alexa suche smarte Geräte''" sprechen und schon sollten die oben genannten Geräte gefunden werden und in der APP als Geräte auftauchen.'''

== Was geht alles ? ==

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

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

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

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

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

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

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

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

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

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

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

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

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

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

* Geräte, die sich ein- (und optional) ausschalten lassen als Szene (ab alexa-fhem version 0.5.26)
** Über <code>genericDeviceType</code> scene
** Automatisch: Müssen <code>set on</code> und <code>set off</code> Kommandos haben
** homebridgeMapping On:reading=<reading>,cmdOn=<cmd>[,cmdOff=<cmd>]
** Hinweis: Fehlende Kommandos lassen sich mit cmdalias erzeugen
** Wichtig:
*** Ein Skill darf nur 12 Szenen automatisch erkennen und einbinden.
* Rollläden. Lange ein Problemthema, das nur mit "Schalte auf 0%, schalte auf 100% lief". Wichtig: "alexa-fhem" ab Version 0.5.39 einsetzen. GenericDevice-Type auf "blind" setzen. Nach Restart von alexa-fhem und neuer Gerätesuche sollte folgendes funktionieren:
** "..., öffne <Name> ganz"
** "..., schließe <Name> komplett"
** "hoch" und "runter" (ohne "ganz" oder "komplett") schalten jeweils nur einen bestimmten Prozentsatz hoch oder runter. Dieser kann mit <code>attr <name> homebridgeMapping TargetPosition:minStep=<wert></code>geändert werden. Aber Achtung: In diesem Intervall kann dann auch nur noch ein absoluter Prozentwert per Sprache oder Slider eingestellt werden! Bei z.B. 25% würden 13% zu 25% aufgerundet, 12% zu 0% abgerundet werden.
* Kontaktsensoren (ab alexa-fhem version 0.5.47)
** Automatisch wenn ein Reading <code>motion</code> vorhanden ist oder es sich um einen Zigbee bewgungsmelder an einer HUE oder deCONZ Bridge handelt
** Über <code>genericDeviceType</code> MotionSensor
** homebridgeMapping MotionDetected:reading=<reading>,values=<wert für bewgung>:1;<wert für keine bewegung>:0

* Alarmmelder (noch nicht in Deutschland):
** genericDeviceType Security
** homebridgeMapping Alarm=<reading>[,type=[fireAlarm|waterAlarm|burglaryAlarm|carbonMonoxideAlarm]]
** wenn der type nicht angegeben wird ist fireAlarm der default
** automatisch werden 0, ok und alles was mit no anfängt als OK erkannt. alles andere gilt als ALARM.
*Geräte mit mehrstufigen Modi:
**siehe den zugehörigen Thread im Forum: {{Link2Forum|Topic= 125604}}
**(Funktioniert Stand 10/25 nur mit alexa-fhem v0.5.64, nicht mit der aktuelle 0.5.65, siehe oben)

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

to be continued ...

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

=== Aktiv Routinen starten ===
Routinen (eine Funktionalität, die rein - genauso wie "Räume" - bei Amazon liegt und nicht von FHEM Connector beeinflusst wird) waren lange die ewige Antwort auf die Frage: "Meine Frau möchte aber '''Öffne Rollläden''<nowiki/>' sagen": In der Alexa-App gibt es im Menü den Punkt "Routinen", und hier lässt sich eine gewisse Anzahl von Aktionen (unter optionalen Bedingungen) an ein Sprachkommando knüpfen.

Neu: Routinen können inzwischen auch von Skills getriggert werden, und seit Version 0.5.47 (Februar 2020) auch von FHEM Connector. Das braucht niemand, um die Rollläden hochzufahren, denn das kann FHEM ja selber, aber um z.B. eine Ansage auf einem Alexa-Gerät zu triggern. Dafür gibt es auch das FHEM-Modul "echodevice", aber es erfordert ein paar Klimmzüge. Mit dem aktiven Triggern von Routinen kann FHEM auslösen, dass Alexa ungefragt (!) Dinge wie

''"Die Temperatur in der Tiefkühltruhe hat -16 Grad überschritten"''

in den Raum sagt. Also eine Alternative bzw. Ergänzung zu Alarmen / Erinnerungen per Telegram o.ä.

'''Vorgeschichte''':

Die Smarthome-Skill-API von Amazon sah schon lange das "proactiveReporting" vor: Also z.B. die gemessene Temperatur nicht erst auf Anfrage hin zu übermitteln, sondern laufend aktiv zu pushen. Aber warum Daten an Amazon senden, wenn es dafür keinen Mehrwert gibt? Beim Öffnen z.B. des Thermostaten in der Alexa-App kommen ohnehin laufend Statusabfragen. Warum also einen Datenpool bei Amazon über die Haustemperatur aufbauen und Änderungen pushen, wenn es keinen Mehrwert dafür gibt?

Inzwischen lassen sich (reale oder vermeintliche) Änderungen von ''Bewegungssensoren'' und ''Fensterkontakten'' als Startbedingung an Alexa-Routinen koppeln. Man kann in der Alexa-App (ggf. fiktive) Öffnen eines Fensterkontaktes an das Aufsagen eines freien Textes durch die Hausbutlerin knüpfen.

'''Umsetzung''':
* Jedes Alexa-Device, dessen Status aktiv zu Amazon gepusht werden soll, im Attribut "alexaProactiveEvents" mit einer "1" versehen. Per Default wird ''kein'' Gerät laufend aktiv zu Amazon gepusht!
* das geänderte Device einmal zu Amazon pushen "set <alexa> add <device>" (oder 'Alexa, suche neue Geräte' murmeln)
* Das Gerät sollte jetzt beim Anlegen einer neuen Routine ("Neue Routine", "Wenn Folgendes passiert", "Smart Home") als möglicher Triggerpunkt erscheinen.

==== Dummygeräte: ====
Ein Dummydevice sollte einen Kontaktschalter oder Bewegungssensor simulieren, um dann in FHEM eine beliebige Bedingung als Trigger zu definieren, und eine freie Ansage in Alexa als Routine zu definieren. Hier ein Beispiel:

<syntaxhighlight lang="bash" style="width:90%;">
define voicetrigger1 dummy
attr voicetrigger1 alexaName alle Fenster
attr voicetrigger1 alexaProactiveEvents 1
attr voicetrigger1 genericDeviceType contact
attr voicetrigger1 homebridgeMapping ContactSensorState=state,values=closed:CONTACT_DETECTED;open:CONTACT_NOT_DETECTED
attr voicetrigger1 setList open closed

set alexa add voicetrigger1
set alexa restart
</syntaxhighlight>

'''Fehlersuche:'''

Der Push setzt ein intaktes Push-Token voraus. Sollte im Alexa-Logfile Folgendes erscheinen:

<code>failed to refresh token: invalid_grant: 'The request has an invalid grant parameter : refresh_token'</code>

so ist das Push-Token nicht aktuell. Weil die Auswirkung lange nur war, dass Geräteänderungen nicht aktiv an Amazon gemeldet wurden, gibt es noch keine umfassende Analyse des Problems. Es lässt sich lösen, indem eine oder beide folgenden Aktionen ausgeführt werden:
* Löschen des ".eventToken" im Alexa-Device über "deletereading"
* "FHEM-Connector"-Skill auf "alexa.amazon.de" einmal deaktivieren und dann neu verbinden

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

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

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

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

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

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

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

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

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

Auf der Kommandoshell:

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

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

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

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

== Sicherheitskonzept und Secrets ==

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

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

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

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

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

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

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

== alexa-fhem Updaten bzw. "Upgraden" ==

'''Updaten einer "Connector" Installation:'''
* alexa-fhem über FHEM anhalten (Name des Alexa-Device: alexa):
:<syntaxhighlight lang="perl" style="width:50%;">set alexa stop</syntaxhighlight>

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

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

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

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

'''"Upgraden von einer "Nicht-Connector" Installation (z.B. manuelle Installation per pm-Download):'''
* Daten der aktuellen Installation sichern (v.a. config.json / man weiß ja nie)
* Autostart der aktuellen alexa-fhem Installation deaktivieren:
** Bei initd: Service deaktivieren mittels: <code>sudo update-rc.d -f alexa remove</code> Vorher mittels stoppen: <code>sudo service alexa stop</code> Startscript unter /etc/init.d/ löschen.
** Bei systemd: Service deaktivieren mittels: <code>sudo systemctl disable alexa</code> Vorher mittels stoppen: <code>sudo systemctl alexa stop</code> Startscript unter /etc/systemd/system/ löschen.
* ALLE vorhandenen alexa-fhem Daten LÖSCHEN! Bleiben Dinge zurück und wird dann laut Connector installiert kann es zu Problemen kommen!
* (reboot)
* Installation von alexa-fhem laut Anleitung (Beginn dieses Wiki)
* Falls eigene Dinge von früher genutzt werden wollen/sollen (z.B. Custom Skill), dann die entsprechenden Einträge aus der gesicherten config.json in die neu angelegte alexa-fhem.cfg (zu finden unter "Edit files") übernehmen.
* Werden keine eigenen Dinge verwendet, dann kann der Port (Standard: 3000) geschlossen werden und auch die Daten unter Amazon-Developer können gelöscht werden.

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

==Weitergehende Informationen==
*[[Alexa und Mappings]]
*[[Alexa Tipps und Kniffe]]
*[[FHEM Connector for Amazon Alexa]]
[[Kategorie:HOWTOS]]
[[Kategorie:Sprachsteuerung]]

==Hinweise==
<references />

FHEM Connector für Amazon Alexa

2025-10-14T14:00:46Z

Hapege: /* Alexa-FHEM installieren */

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

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

* SONOS Beam und SONOS One

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

Der Thread im Forum zur Software ist hier: {{Link2Forum|Topic=94817}}.
{{Infobox Modul
|ModPurpose=Einfache Anbindung von FHEM an Amazon Assistent Alexa
|ModType=h
|ModCmdRef=alexa
|ModTechName=39_alexa.pm / alexa-fhem
|ModForumArea=Frontends/Sprachsteuerung
|ModOwner=gvzdus, André/ justme1968 ({{Link2FU|430|Forum}} / [[Benutzer Diskussion:Justme|Wiki]])
}}
==Einführung==
===Arbeitsweise und Datenfluss===
Vorläufig ist alexa-fhem im "FHEM Connector-Modus" ein reiner [https://developer.amazon.com/de/docs/smarthome/understand-the-smart-home-skill-api.html SmartHome-Skill].
SmartHome-Skills erhalten weder die Sprachdaten selber noch das, was Amazon in Textform verstanden hat, sondern vielmehr extrahiert Amazon aus dem verstandenen Text Anweisungen und Abfragen für Geräte, die dann an den Skill übermittelt werden. Charmant ist dabei, dass unmittelbar gefragt werden kann "Alexa, wie ist die Temperatur im Wohnzimmer?", während andere Skills zunächst explizit angesprochen werden müssen ("Alexa, frage FHEM nach der Temperatur im Wohnzimmer"). Außerdem kann der Nutzer mehrere Smarthome-Skills installieren, und die Geräte werden zu einer Gesamtmenge zusammengefasst.

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

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

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

==Installation==

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

===node.js installieren===

Ab Jessy liegt NodeJS bereits in einer ausreichend aktuellen Version vor (Stretch und Buster funktionieren ebenfalls). Mit

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

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

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

'''Anmerkung:''' diese Aussage bzgl. node-Version (und Jessie/Stretch) stimmt wohl für alexa-fhem Stand heute (12.06.2020) nicht mehr, siehe https://forum.fhem.de/index.php/topic,112025.msg1063218.html#msg1063218

=== Alexa-FHEM installieren ===

Nun installieren wir Alexa-fhem aus dem offiziellen Repository:

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

Der Vorgang benötigt etwas Zeit.

(Edit: die aktuelle Version 0.5.65 hat ein Problem, wenn ModeController verwendet wird. Wer modes braucht, der sollte die vorherige Version 0.5.64 installieren:
<syntaxhighlight lang="bash" style="width:50%;">
sudo npm install -g alexa-fhem@0.5.64
</syntaxhighlight>

=== Alexa-FHEM aktivieren ===

Wechsele jetzt in FHEM-Web!

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

* Zuerst bitte einfach einmal die Seite neu laden.

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

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

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

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

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

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

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

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

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

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

Du solltest dann folgende Ausgabe erhalten:

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

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

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

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

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

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

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

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

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

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

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

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

Wähle die Geräte aus, rufe sie auf und setze das Attribut "alexaName". Hierbei in Kürze nur der Hinweis:
* Keine Angst vor Leerzeichen und Umlauten, funktioniert.
* Große Angst vor Rechtschreibfehlern (Terrasse, Rollladen) oder komplizierten Wörtern "handgebastelte Martinslaterne im Kinderzimmer Iphigenie-Chantal".
* Mehrere Namen für dasselbe Gerät/Device in fhem werden unterstützt. Mehrere Namen werden durch <s>Strichpunkt</s> Komma getrennt<ref>Feature nicht dokumentiert {{Link2Forum|Topic=74041|LinkText=Forumsthread}}</ref>.
* Das Attribut "alexaRoom" ist NUR FÜR DEN CUSTOM SKILL relevant. Ausnahme: structure und LightScene Devices, siehe: [[FHEM_Connector_f%C3%BCr_Amazon_Alexa#Was_geht_alles_.3F]].

Lade die Geräte neu in die Software, indem Du <code>set <alexa> restart</code> ausführst!
[[Datei:HowToSet alexaName.png|alternativtext=How to set alexaName|ohne|mini|Wie setzt man das Attribut alexaName]]

'''Anmerkungen (weil oft gestellte Fragen im Forum) bzgl. Erkennung von Geräten:'''

* Wichtig ist, dass die Filtereinstellung in der alexa-fhem.cfg (zu finden unter "Edit Files") passt.
Das, was dort eingetragen ist (Standard: alexaName=..* / also es ist ein alexaName vergeben) auch an den entsprechenden Devices in fhem vorhanden ist.
Stimmt das nicht überein, kann alexa-fhem keine Devices von fhem abfragen/finden.
Ob der Filter entsprechend funktioniert kann man wie folgt testen: ''list Filtereinstellung'' beispiel mit Standardfilter: ''list alexaName=..*''

* Hat alexa-fhem per Filter Devices aus fhem "gefunden", geht es weiter mit der "Erkennung". Also um welches Device (Typ und "Fähigkeiten") handelt es sich. Dazu gilt folgendes:
** sind entsprechende Readings beim Device vorhanden (z.B. temperature, state mit on/off, ...) erkennt das alexa-fhem automatisch. Die Liste der automatisch erkannten Readings wächst ständig. Daher erst mal schauen ob das Device bereits entsprechend erkannt (typisiert) wurde. Das kann durch prüfen des alexa-fhem-Logs geschehen (NICHT fhem-log!).
** sind entsprechende "set-Befehle" erkennbar (oft auch durch Readings). Also ist beispielsweise (wie beim Dummy nötig) ein ''setList'' mit entsprechenden Einträgen vorhanden oder entsprechende Readings, z.B. desired-temp zum Stellen der Temperatur etc.
** wird das Device nicht richtig oder "unvollständig" erkannt helfen folgende Attribute:
*** genericDeviceType: hiermit kann alexa-fhem in die gewünschte Richtung "geschubbst" werden. Anmerkung: man kann nicht alles erzwingen, Readings bzw. set-Befehle müssen passen (oder per homebridgeMapping passend gemacht werden). Wenn ein genericDeviceType nicht per "Drop-Down" erscheint, dann kann er auch (wenn bekannt) einfach per WEB-cmd eingegeben werden: ''attr Devicename genericDeviceType media''
*** homebridgeMapping: hierdurch kann alexa-fhem bei der Erkennung von Zuständen und möglichen Einstellungen (also WAS kann das Device) unterstützt werden. Mittels homebridgeMapping können vorhandene Readings (Zustände) auf für alexa-fhem bekannte Zustände gemappt werden. Ebenso können damit Standard-fhem-Kommandos von alexa-fhem auf Device-spezifische gemappt werden. Beispiel: on/off auf Ein/Aus (falls das Device statt on/off eben ein Ein/Aus erwartet). Zum Beispiel: <syntaxhighlight lang="bash" style="width:50%;">
attr <thermostat> homebridgeMapping TargetTemperature=target::target,minValue=18,maxValue=25,minStep=0.5 CurrentTemperature=myTemp:temperature
</syntaxhighlight> [https://github.com/justme-1968/homebridge-fhem/blob/master/README.md weitere Beispiele]

 '''Mehrere Namen für dasselbe Gerät/Device in fhem sind möglich.''' 
Die Namen werden durch <s>Strichpunkt</s> Komma getrennt. 
Beispiel: 
<code>attr dmLampe alexaName Lichtkuppel,Lichtkugel</code>

'''Anmerkung bzgl. genericDeviceType und homebridgeMapping:''' 
* diese Attribute werden von verschiedenen "Sprachsteuerungsmodulen" in fhem verwendet (homebridge [dort wurde es "erfunden"], alexa-fhem, gassistant, ...). Daher ist nicht jedes Mapping für alle "Dienste" verwendbar. Ausprobieren schadet aber nicht.
* ebenso kann man mit diesen Attributen (homebridgeMapping wird gerne so "missbraucht") nichts erzwingen, was seitens Amazon/Alexa nicht unterstützt bzw. verstanden wird! D.h. zunächst ist zu prüfen, ob ein bestimmter (gewünschter) Sprachbefehl seitens Amazon/Alexa unterstützt wird! Aktuelles Beispiel (Stand Jan 2020): "Alexa, fahre den Rollo hoch/runter". Da ist Amazon/Alexa gerade dabei etwas zu tun. Bislang wird das nicht unterstützt, also ist das auch mit einem entsprechenden homebridgeMapping nicht zu erzwingen! Was unterstützt wird kann man bei Amazon nachlesen: [https://developer.amazon.com/es-ES/docs/alexa/device-apis/list-of-interfaces.html]

== Finale: Skill verknüpfen ==
Suche auf der Alexa-App den Skill "FHEM Connector".

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

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

Hier kopierst Du Deinen Anmeldeschlüssel (im Klartext!) hinein, den du mittels "get alexa proxyKey" erhalten hast, und klickst auf Check. Als glücklicher Mensch ist auf der folgenden Statusseite alles grün: 
[[Datei:FHEMlazy_check.png|240px]]

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

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

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

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

'''Als Abschluss muss man nur noch in ein Echo-Gerät seiner Wahl die Anweisung: "''Alexa suche smarte Geräte''" sprechen und schon sollten die oben genannten Geräte gefunden werden und in der APP als Geräte auftauchen.'''

== Was geht alles ? ==

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

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

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

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

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

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

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

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

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

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

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

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

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

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

* Geräte, die sich ein- (und optional) ausschalten lassen als Szene (ab alexa-fhem version 0.5.26)
** Über <code>genericDeviceType</code> scene
** Automatisch: Müssen <code>set on</code> und <code>set off</code> Kommandos haben
** homebridgeMapping On:reading=<reading>,cmdOn=<cmd>[,cmdOff=<cmd>]
** Hinweis: Fehlende Kommandos lassen sich mit cmdalias erzeugen
** Wichtig:
*** Ein Skill darf nur 12 Szenen automatisch erkennen und einbinden.
* Rollläden. Lange ein Problemthema, das nur mit "Schalte auf 0%, schalte auf 100% lief". Wichtig: "alexa-fhem" ab Version 0.5.39 einsetzen. GenericDevice-Type auf "blind" setzen. Nach Restart von alexa-fhem und neuer Gerätesuche sollte folgendes funktionieren:
** "..., öffne <Name> ganz"
** "..., schließe <Name> komplett"
** "hoch" und "runter" (ohne "ganz" oder "komplett") schalten jeweils nur einen bestimmten Prozentsatz hoch oder runter. Dieser kann mit <code>attr <name> homebridgeMapping TargetPosition:minStep=<wert></code>geändert werden. Aber Achtung: In diesem Intervall kann dann auch nur noch ein absoluter Prozentwert per Sprache oder Slider eingestellt werden! Bei z.B. 25% würden 13% zu 25% aufgerundet, 12% zu 0% abgerundet werden.
* Kontaktsensoren (ab alexa-fhem version 0.5.47)
** Automatisch wenn ein Reading <code>motion</code> vorhanden ist oder es sich um einen Zigbee bewgungsmelder an einer HUE oder deCONZ Bridge handelt
** Über <code>genericDeviceType</code> MotionSensor
** homebridgeMapping MotionDetected:reading=<reading>,values=<wert für bewgung>:1;<wert für keine bewegung>:0

* Alarmmelder (noch nicht in Deutschland):
** genericDeviceType Security
** homebridgeMapping Alarm=<reading>[,type=[fireAlarm|waterAlarm|burglaryAlarm|carbonMonoxideAlarm]]
** wenn der type nicht angegeben wird ist fireAlarm der default
** automatisch werden 0, ok und alles was mit no anfängt als OK erkannt. alles andere gilt als ALARM.
*Geräte mit mehrstufigen Modi:
**siehe den zugehörigen Thread im Forum: {{Link2Forum|Topic= 125604}}

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

to be continued ...

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

=== Aktiv Routinen starten ===
Routinen (eine Funktionalität, die rein - genauso wie "Räume" - bei Amazon liegt und nicht von FHEM Connector beeinflusst wird) waren lange die ewige Antwort auf die Frage: "Meine Frau möchte aber '''Öffne Rollläden''<nowiki/>' sagen": In der Alexa-App gibt es im Menü den Punkt "Routinen", und hier lässt sich eine gewisse Anzahl von Aktionen (unter optionalen Bedingungen) an ein Sprachkommando knüpfen.

Neu: Routinen können inzwischen auch von Skills getriggert werden, und seit Version 0.5.47 (Februar 2020) auch von FHEM Connector. Das braucht niemand, um die Rollläden hochzufahren, denn das kann FHEM ja selber, aber um z.B. eine Ansage auf einem Alexa-Gerät zu triggern. Dafür gibt es auch das FHEM-Modul "echodevice", aber es erfordert ein paar Klimmzüge. Mit dem aktiven Triggern von Routinen kann FHEM auslösen, dass Alexa ungefragt (!) Dinge wie

''"Die Temperatur in der Tiefkühltruhe hat -16 Grad überschritten"''

in den Raum sagt. Also eine Alternative bzw. Ergänzung zu Alarmen / Erinnerungen per Telegram o.ä.

'''Vorgeschichte''':

Die Smarthome-Skill-API von Amazon sah schon lange das "proactiveReporting" vor: Also z.B. die gemessene Temperatur nicht erst auf Anfrage hin zu übermitteln, sondern laufend aktiv zu pushen. Aber warum Daten an Amazon senden, wenn es dafür keinen Mehrwert gibt? Beim Öffnen z.B. des Thermostaten in der Alexa-App kommen ohnehin laufend Statusabfragen. Warum also einen Datenpool bei Amazon über die Haustemperatur aufbauen und Änderungen pushen, wenn es keinen Mehrwert dafür gibt?

Inzwischen lassen sich (reale oder vermeintliche) Änderungen von ''Bewegungssensoren'' und ''Fensterkontakten'' als Startbedingung an Alexa-Routinen koppeln. Man kann in der Alexa-App (ggf. fiktive) Öffnen eines Fensterkontaktes an das Aufsagen eines freien Textes durch die Hausbutlerin knüpfen.

'''Umsetzung''':
* Jedes Alexa-Device, dessen Status aktiv zu Amazon gepusht werden soll, im Attribut "alexaProactiveEvents" mit einer "1" versehen. Per Default wird ''kein'' Gerät laufend aktiv zu Amazon gepusht!
* das geänderte Device einmal zu Amazon pushen "set <alexa> add <device>" (oder 'Alexa, suche neue Geräte' murmeln)
* Das Gerät sollte jetzt beim Anlegen einer neuen Routine ("Neue Routine", "Wenn Folgendes passiert", "Smart Home") als möglicher Triggerpunkt erscheinen.

==== Dummygeräte: ====
Ein Dummydevice sollte einen Kontaktschalter oder Bewegungssensor simulieren, um dann in FHEM eine beliebige Bedingung als Trigger zu definieren, und eine freie Ansage in Alexa als Routine zu definieren. Hier ein Beispiel:

<syntaxhighlight lang="bash" style="width:90%;">
define voicetrigger1 dummy
attr voicetrigger1 alexaName alle Fenster
attr voicetrigger1 alexaProactiveEvents 1
attr voicetrigger1 genericDeviceType contact
attr voicetrigger1 homebridgeMapping ContactSensorState=state,values=closed:CONTACT_DETECTED;open:CONTACT_NOT_DETECTED
attr voicetrigger1 setList open closed

set alexa add voicetrigger1
set alexa restart
</syntaxhighlight>

'''Fehlersuche:'''

Der Push setzt ein intaktes Push-Token voraus. Sollte im Alexa-Logfile Folgendes erscheinen:

<code>failed to refresh token: invalid_grant: 'The request has an invalid grant parameter : refresh_token'</code>

so ist das Push-Token nicht aktuell. Weil die Auswirkung lange nur war, dass Geräteänderungen nicht aktiv an Amazon gemeldet wurden, gibt es noch keine umfassende Analyse des Problems. Es lässt sich lösen, indem eine oder beide folgenden Aktionen ausgeführt werden:
* Löschen des ".eventToken" im Alexa-Device über "deletereading"
* "FHEM-Connector"-Skill auf "alexa.amazon.de" einmal deaktivieren und dann neu verbinden

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

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

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

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

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

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

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

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

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

Auf der Kommandoshell:

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

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

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

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

== Sicherheitskonzept und Secrets ==

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

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

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

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

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

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

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

== alexa-fhem Updaten bzw. "Upgraden" ==

'''Updaten einer "Connector" Installation:'''
* alexa-fhem über FHEM anhalten (Name des Alexa-Device: alexa):
:<syntaxhighlight lang="perl" style="width:50%;">set alexa stop</syntaxhighlight>

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

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

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

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

'''"Upgraden von einer "Nicht-Connector" Installation (z.B. manuelle Installation per pm-Download):'''
* Daten der aktuellen Installation sichern (v.a. config.json / man weiß ja nie)
* Autostart der aktuellen alexa-fhem Installation deaktivieren:
** Bei initd: Service deaktivieren mittels: <code>sudo update-rc.d -f alexa remove</code> Vorher mittels stoppen: <code>sudo service alexa stop</code> Startscript unter /etc/init.d/ löschen.
** Bei systemd: Service deaktivieren mittels: <code>sudo systemctl disable alexa</code> Vorher mittels stoppen: <code>sudo systemctl alexa stop</code> Startscript unter /etc/systemd/system/ löschen.
* ALLE vorhandenen alexa-fhem Daten LÖSCHEN! Bleiben Dinge zurück und wird dann laut Connector installiert kann es zu Problemen kommen!
* (reboot)
* Installation von alexa-fhem laut Anleitung (Beginn dieses Wiki)
* Falls eigene Dinge von früher genutzt werden wollen/sollen (z.B. Custom Skill), dann die entsprechenden Einträge aus der gesicherten config.json in die neu angelegte alexa-fhem.cfg (zu finden unter "Edit files") übernehmen.
* Werden keine eigenen Dinge verwendet, dann kann der Port (Standard: 3000) geschlossen werden und auch die Daten unter Amazon-Developer können gelöscht werden.

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

==Weitergehende Informationen==
*[[Alexa und Mappings]]
*[[Alexa Tipps und Kniffe]]
*[[FHEM Connector for Amazon Alexa]]
[[Kategorie:HOWTOS]]
[[Kategorie:Sprachsteuerung]]

==Hinweise==
<references />

FHEM Connector für Amazon Alexa

2025-10-14T14:00:22Z

Hapege: /* Alexa-FHEM installieren */

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

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

* SONOS Beam und SONOS One

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

Der Thread im Forum zur Software ist hier: {{Link2Forum|Topic=94817}}.
{{Infobox Modul
|ModPurpose=Einfache Anbindung von FHEM an Amazon Assistent Alexa
|ModType=h
|ModCmdRef=alexa
|ModTechName=39_alexa.pm / alexa-fhem
|ModForumArea=Frontends/Sprachsteuerung
|ModOwner=gvzdus, André/ justme1968 ({{Link2FU|430|Forum}} / [[Benutzer Diskussion:Justme|Wiki]])
}}
==Einführung==
===Arbeitsweise und Datenfluss===
Vorläufig ist alexa-fhem im "FHEM Connector-Modus" ein reiner [https://developer.amazon.com/de/docs/smarthome/understand-the-smart-home-skill-api.html SmartHome-Skill].
SmartHome-Skills erhalten weder die Sprachdaten selber noch das, was Amazon in Textform verstanden hat, sondern vielmehr extrahiert Amazon aus dem verstandenen Text Anweisungen und Abfragen für Geräte, die dann an den Skill übermittelt werden. Charmant ist dabei, dass unmittelbar gefragt werden kann "Alexa, wie ist die Temperatur im Wohnzimmer?", während andere Skills zunächst explizit angesprochen werden müssen ("Alexa, frage FHEM nach der Temperatur im Wohnzimmer"). Außerdem kann der Nutzer mehrere Smarthome-Skills installieren, und die Geräte werden zu einer Gesamtmenge zusammengefasst.

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

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

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

==Installation==

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

===node.js installieren===

Ab Jessy liegt NodeJS bereits in einer ausreichend aktuellen Version vor (Stretch und Buster funktionieren ebenfalls). Mit

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

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

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

'''Anmerkung:''' diese Aussage bzgl. node-Version (und Jessie/Stretch) stimmt wohl für alexa-fhem Stand heute (12.06.2020) nicht mehr, siehe https://forum.fhem.de/index.php/topic,112025.msg1063218.html#msg1063218

=== Alexa-FHEM installieren ===

Nun installieren wir Alexa-fhem aus dem offiziellen Repository:

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

Der Vorgang benötigt etwas Zeit.

(Edit: die aktuelle Version 0.5.65 hat ein Problem, wenn ModeController verwendet wird. Wer modes braucht, der sollte die vorherige Version 0.5.64 installieren:
<syntaxhighlight lang="bash" style="width:50%;">
sudo npm install -g alexa-fhem@0.5.64)
</syntaxhighlight>

=== Alexa-FHEM aktivieren ===

Wechsele jetzt in FHEM-Web!

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

* Zuerst bitte einfach einmal die Seite neu laden.

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

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

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

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

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

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

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

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

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

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

Du solltest dann folgende Ausgabe erhalten:

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

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

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

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

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

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

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

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

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

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

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

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

Wähle die Geräte aus, rufe sie auf und setze das Attribut "alexaName". Hierbei in Kürze nur der Hinweis:
* Keine Angst vor Leerzeichen und Umlauten, funktioniert.
* Große Angst vor Rechtschreibfehlern (Terrasse, Rollladen) oder komplizierten Wörtern "handgebastelte Martinslaterne im Kinderzimmer Iphigenie-Chantal".
* Mehrere Namen für dasselbe Gerät/Device in fhem werden unterstützt. Mehrere Namen werden durch <s>Strichpunkt</s> Komma getrennt<ref>Feature nicht dokumentiert {{Link2Forum|Topic=74041|LinkText=Forumsthread}}</ref>.
* Das Attribut "alexaRoom" ist NUR FÜR DEN CUSTOM SKILL relevant. Ausnahme: structure und LightScene Devices, siehe: [[FHEM_Connector_f%C3%BCr_Amazon_Alexa#Was_geht_alles_.3F]].

Lade die Geräte neu in die Software, indem Du <code>set <alexa> restart</code> ausführst!
[[Datei:HowToSet alexaName.png|alternativtext=How to set alexaName|ohne|mini|Wie setzt man das Attribut alexaName]]

'''Anmerkungen (weil oft gestellte Fragen im Forum) bzgl. Erkennung von Geräten:'''

* Wichtig ist, dass die Filtereinstellung in der alexa-fhem.cfg (zu finden unter "Edit Files") passt.
Das, was dort eingetragen ist (Standard: alexaName=..* / also es ist ein alexaName vergeben) auch an den entsprechenden Devices in fhem vorhanden ist.
Stimmt das nicht überein, kann alexa-fhem keine Devices von fhem abfragen/finden.
Ob der Filter entsprechend funktioniert kann man wie folgt testen: ''list Filtereinstellung'' beispiel mit Standardfilter: ''list alexaName=..*''

* Hat alexa-fhem per Filter Devices aus fhem "gefunden", geht es weiter mit der "Erkennung". Also um welches Device (Typ und "Fähigkeiten") handelt es sich. Dazu gilt folgendes:
** sind entsprechende Readings beim Device vorhanden (z.B. temperature, state mit on/off, ...) erkennt das alexa-fhem automatisch. Die Liste der automatisch erkannten Readings wächst ständig. Daher erst mal schauen ob das Device bereits entsprechend erkannt (typisiert) wurde. Das kann durch prüfen des alexa-fhem-Logs geschehen (NICHT fhem-log!).
** sind entsprechende "set-Befehle" erkennbar (oft auch durch Readings). Also ist beispielsweise (wie beim Dummy nötig) ein ''setList'' mit entsprechenden Einträgen vorhanden oder entsprechende Readings, z.B. desired-temp zum Stellen der Temperatur etc.
** wird das Device nicht richtig oder "unvollständig" erkannt helfen folgende Attribute:
*** genericDeviceType: hiermit kann alexa-fhem in die gewünschte Richtung "geschubbst" werden. Anmerkung: man kann nicht alles erzwingen, Readings bzw. set-Befehle müssen passen (oder per homebridgeMapping passend gemacht werden). Wenn ein genericDeviceType nicht per "Drop-Down" erscheint, dann kann er auch (wenn bekannt) einfach per WEB-cmd eingegeben werden: ''attr Devicename genericDeviceType media''
*** homebridgeMapping: hierdurch kann alexa-fhem bei der Erkennung von Zuständen und möglichen Einstellungen (also WAS kann das Device) unterstützt werden. Mittels homebridgeMapping können vorhandene Readings (Zustände) auf für alexa-fhem bekannte Zustände gemappt werden. Ebenso können damit Standard-fhem-Kommandos von alexa-fhem auf Device-spezifische gemappt werden. Beispiel: on/off auf Ein/Aus (falls das Device statt on/off eben ein Ein/Aus erwartet). Zum Beispiel: <syntaxhighlight lang="bash" style="width:50%;">
attr <thermostat> homebridgeMapping TargetTemperature=target::target,minValue=18,maxValue=25,minStep=0.5 CurrentTemperature=myTemp:temperature
</syntaxhighlight> [https://github.com/justme-1968/homebridge-fhem/blob/master/README.md weitere Beispiele]

 '''Mehrere Namen für dasselbe Gerät/Device in fhem sind möglich.''' 
Die Namen werden durch <s>Strichpunkt</s> Komma getrennt. 
Beispiel: 
<code>attr dmLampe alexaName Lichtkuppel,Lichtkugel</code>

'''Anmerkung bzgl. genericDeviceType und homebridgeMapping:''' 
* diese Attribute werden von verschiedenen "Sprachsteuerungsmodulen" in fhem verwendet (homebridge [dort wurde es "erfunden"], alexa-fhem, gassistant, ...). Daher ist nicht jedes Mapping für alle "Dienste" verwendbar. Ausprobieren schadet aber nicht.
* ebenso kann man mit diesen Attributen (homebridgeMapping wird gerne so "missbraucht") nichts erzwingen, was seitens Amazon/Alexa nicht unterstützt bzw. verstanden wird! D.h. zunächst ist zu prüfen, ob ein bestimmter (gewünschter) Sprachbefehl seitens Amazon/Alexa unterstützt wird! Aktuelles Beispiel (Stand Jan 2020): "Alexa, fahre den Rollo hoch/runter". Da ist Amazon/Alexa gerade dabei etwas zu tun. Bislang wird das nicht unterstützt, also ist das auch mit einem entsprechenden homebridgeMapping nicht zu erzwingen! Was unterstützt wird kann man bei Amazon nachlesen: [https://developer.amazon.com/es-ES/docs/alexa/device-apis/list-of-interfaces.html]

== Finale: Skill verknüpfen ==
Suche auf der Alexa-App den Skill "FHEM Connector".

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

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

Hier kopierst Du Deinen Anmeldeschlüssel (im Klartext!) hinein, den du mittels "get alexa proxyKey" erhalten hast, und klickst auf Check. Als glücklicher Mensch ist auf der folgenden Statusseite alles grün: 
[[Datei:FHEMlazy_check.png|240px]]

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

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

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

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

'''Als Abschluss muss man nur noch in ein Echo-Gerät seiner Wahl die Anweisung: "''Alexa suche smarte Geräte''" sprechen und schon sollten die oben genannten Geräte gefunden werden und in der APP als Geräte auftauchen.'''

== Was geht alles ? ==

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

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

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

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

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

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

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

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

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

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

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

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

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

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

* Geräte, die sich ein- (und optional) ausschalten lassen als Szene (ab alexa-fhem version 0.5.26)
** Über <code>genericDeviceType</code> scene
** Automatisch: Müssen <code>set on</code> und <code>set off</code> Kommandos haben
** homebridgeMapping On:reading=<reading>,cmdOn=<cmd>[,cmdOff=<cmd>]
** Hinweis: Fehlende Kommandos lassen sich mit cmdalias erzeugen
** Wichtig:
*** Ein Skill darf nur 12 Szenen automatisch erkennen und einbinden.
* Rollläden. Lange ein Problemthema, das nur mit "Schalte auf 0%, schalte auf 100% lief". Wichtig: "alexa-fhem" ab Version 0.5.39 einsetzen. GenericDevice-Type auf "blind" setzen. Nach Restart von alexa-fhem und neuer Gerätesuche sollte folgendes funktionieren:
** "..., öffne <Name> ganz"
** "..., schließe <Name> komplett"
** "hoch" und "runter" (ohne "ganz" oder "komplett") schalten jeweils nur einen bestimmten Prozentsatz hoch oder runter. Dieser kann mit <code>attr <name> homebridgeMapping TargetPosition:minStep=<wert></code>geändert werden. Aber Achtung: In diesem Intervall kann dann auch nur noch ein absoluter Prozentwert per Sprache oder Slider eingestellt werden! Bei z.B. 25% würden 13% zu 25% aufgerundet, 12% zu 0% abgerundet werden.
* Kontaktsensoren (ab alexa-fhem version 0.5.47)
** Automatisch wenn ein Reading <code>motion</code> vorhanden ist oder es sich um einen Zigbee bewgungsmelder an einer HUE oder deCONZ Bridge handelt
** Über <code>genericDeviceType</code> MotionSensor
** homebridgeMapping MotionDetected:reading=<reading>,values=<wert für bewgung>:1;<wert für keine bewegung>:0

* Alarmmelder (noch nicht in Deutschland):
** genericDeviceType Security
** homebridgeMapping Alarm=<reading>[,type=[fireAlarm|waterAlarm|burglaryAlarm|carbonMonoxideAlarm]]
** wenn der type nicht angegeben wird ist fireAlarm der default
** automatisch werden 0, ok und alles was mit no anfängt als OK erkannt. alles andere gilt als ALARM.
*Geräte mit mehrstufigen Modi:
**siehe den zugehörigen Thread im Forum: {{Link2Forum|Topic= 125604}}

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

to be continued ...

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

=== Aktiv Routinen starten ===
Routinen (eine Funktionalität, die rein - genauso wie "Räume" - bei Amazon liegt und nicht von FHEM Connector beeinflusst wird) waren lange die ewige Antwort auf die Frage: "Meine Frau möchte aber '''Öffne Rollläden''<nowiki/>' sagen": In der Alexa-App gibt es im Menü den Punkt "Routinen", und hier lässt sich eine gewisse Anzahl von Aktionen (unter optionalen Bedingungen) an ein Sprachkommando knüpfen.

Neu: Routinen können inzwischen auch von Skills getriggert werden, und seit Version 0.5.47 (Februar 2020) auch von FHEM Connector. Das braucht niemand, um die Rollläden hochzufahren, denn das kann FHEM ja selber, aber um z.B. eine Ansage auf einem Alexa-Gerät zu triggern. Dafür gibt es auch das FHEM-Modul "echodevice", aber es erfordert ein paar Klimmzüge. Mit dem aktiven Triggern von Routinen kann FHEM auslösen, dass Alexa ungefragt (!) Dinge wie

''"Die Temperatur in der Tiefkühltruhe hat -16 Grad überschritten"''

in den Raum sagt. Also eine Alternative bzw. Ergänzung zu Alarmen / Erinnerungen per Telegram o.ä.

'''Vorgeschichte''':

Die Smarthome-Skill-API von Amazon sah schon lange das "proactiveReporting" vor: Also z.B. die gemessene Temperatur nicht erst auf Anfrage hin zu übermitteln, sondern laufend aktiv zu pushen. Aber warum Daten an Amazon senden, wenn es dafür keinen Mehrwert gibt? Beim Öffnen z.B. des Thermostaten in der Alexa-App kommen ohnehin laufend Statusabfragen. Warum also einen Datenpool bei Amazon über die Haustemperatur aufbauen und Änderungen pushen, wenn es keinen Mehrwert dafür gibt?

Inzwischen lassen sich (reale oder vermeintliche) Änderungen von ''Bewegungssensoren'' und ''Fensterkontakten'' als Startbedingung an Alexa-Routinen koppeln. Man kann in der Alexa-App (ggf. fiktive) Öffnen eines Fensterkontaktes an das Aufsagen eines freien Textes durch die Hausbutlerin knüpfen.

'''Umsetzung''':
* Jedes Alexa-Device, dessen Status aktiv zu Amazon gepusht werden soll, im Attribut "alexaProactiveEvents" mit einer "1" versehen. Per Default wird ''kein'' Gerät laufend aktiv zu Amazon gepusht!
* das geänderte Device einmal zu Amazon pushen "set <alexa> add <device>" (oder 'Alexa, suche neue Geräte' murmeln)
* Das Gerät sollte jetzt beim Anlegen einer neuen Routine ("Neue Routine", "Wenn Folgendes passiert", "Smart Home") als möglicher Triggerpunkt erscheinen.

==== Dummygeräte: ====
Ein Dummydevice sollte einen Kontaktschalter oder Bewegungssensor simulieren, um dann in FHEM eine beliebige Bedingung als Trigger zu definieren, und eine freie Ansage in Alexa als Routine zu definieren. Hier ein Beispiel:

<syntaxhighlight lang="bash" style="width:90%;">
define voicetrigger1 dummy
attr voicetrigger1 alexaName alle Fenster
attr voicetrigger1 alexaProactiveEvents 1
attr voicetrigger1 genericDeviceType contact
attr voicetrigger1 homebridgeMapping ContactSensorState=state,values=closed:CONTACT_DETECTED;open:CONTACT_NOT_DETECTED
attr voicetrigger1 setList open closed

set alexa add voicetrigger1
set alexa restart
</syntaxhighlight>

'''Fehlersuche:'''

Der Push setzt ein intaktes Push-Token voraus. Sollte im Alexa-Logfile Folgendes erscheinen:

<code>failed to refresh token: invalid_grant: 'The request has an invalid grant parameter : refresh_token'</code>

so ist das Push-Token nicht aktuell. Weil die Auswirkung lange nur war, dass Geräteänderungen nicht aktiv an Amazon gemeldet wurden, gibt es noch keine umfassende Analyse des Problems. Es lässt sich lösen, indem eine oder beide folgenden Aktionen ausgeführt werden:
* Löschen des ".eventToken" im Alexa-Device über "deletereading"
* "FHEM-Connector"-Skill auf "alexa.amazon.de" einmal deaktivieren und dann neu verbinden

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

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

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

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

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

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

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

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

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

Auf der Kommandoshell:

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

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

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

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

== Sicherheitskonzept und Secrets ==

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

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

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

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

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

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

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

== alexa-fhem Updaten bzw. "Upgraden" ==

'''Updaten einer "Connector" Installation:'''
* alexa-fhem über FHEM anhalten (Name des Alexa-Device: alexa):
:<syntaxhighlight lang="perl" style="width:50%;">set alexa stop</syntaxhighlight>

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

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

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

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

'''"Upgraden von einer "Nicht-Connector" Installation (z.B. manuelle Installation per pm-Download):'''
* Daten der aktuellen Installation sichern (v.a. config.json / man weiß ja nie)
* Autostart der aktuellen alexa-fhem Installation deaktivieren:
** Bei initd: Service deaktivieren mittels: <code>sudo update-rc.d -f alexa remove</code> Vorher mittels stoppen: <code>sudo service alexa stop</code> Startscript unter /etc/init.d/ löschen.
** Bei systemd: Service deaktivieren mittels: <code>sudo systemctl disable alexa</code> Vorher mittels stoppen: <code>sudo systemctl alexa stop</code> Startscript unter /etc/systemd/system/ löschen.
* ALLE vorhandenen alexa-fhem Daten LÖSCHEN! Bleiben Dinge zurück und wird dann laut Connector installiert kann es zu Problemen kommen!
* (reboot)
* Installation von alexa-fhem laut Anleitung (Beginn dieses Wiki)
* Falls eigene Dinge von früher genutzt werden wollen/sollen (z.B. Custom Skill), dann die entsprechenden Einträge aus der gesicherten config.json in die neu angelegte alexa-fhem.cfg (zu finden unter "Edit files") übernehmen.
* Werden keine eigenen Dinge verwendet, dann kann der Port (Standard: 3000) geschlossen werden und auch die Daten unter Amazon-Developer können gelöscht werden.

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

==Weitergehende Informationen==
*[[Alexa und Mappings]]
*[[Alexa Tipps und Kniffe]]
*[[FHEM Connector for Amazon Alexa]]
[[Kategorie:HOWTOS]]
[[Kategorie:Sprachsteuerung]]

==Hinweise==
<references />

FHEM Connector für Amazon Alexa

2025-10-14T13:59:20Z

Hapege: Bug in alexa-fhem 0.5.65, siehe https://github.com/justme-1968/alexa-fhem/issues/33, deshalb Hinweis auf die Installation der 0.5.64

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

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

* SONOS Beam und SONOS One

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

Der Thread im Forum zur Software ist hier: {{Link2Forum|Topic=94817}}.
{{Infobox Modul
|ModPurpose=Einfache Anbindung von FHEM an Amazon Assistent Alexa
|ModType=h
|ModCmdRef=alexa
|ModTechName=39_alexa.pm / alexa-fhem
|ModForumArea=Frontends/Sprachsteuerung
|ModOwner=gvzdus, André/ justme1968 ({{Link2FU|430|Forum}} / [[Benutzer Diskussion:Justme|Wiki]])
}}
==Einführung==
===Arbeitsweise und Datenfluss===
Vorläufig ist alexa-fhem im "FHEM Connector-Modus" ein reiner [https://developer.amazon.com/de/docs/smarthome/understand-the-smart-home-skill-api.html SmartHome-Skill].
SmartHome-Skills erhalten weder die Sprachdaten selber noch das, was Amazon in Textform verstanden hat, sondern vielmehr extrahiert Amazon aus dem verstandenen Text Anweisungen und Abfragen für Geräte, die dann an den Skill übermittelt werden. Charmant ist dabei, dass unmittelbar gefragt werden kann "Alexa, wie ist die Temperatur im Wohnzimmer?", während andere Skills zunächst explizit angesprochen werden müssen ("Alexa, frage FHEM nach der Temperatur im Wohnzimmer"). Außerdem kann der Nutzer mehrere Smarthome-Skills installieren, und die Geräte werden zu einer Gesamtmenge zusammengefasst.

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

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

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

==Installation==

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

===node.js installieren===

Ab Jessy liegt NodeJS bereits in einer ausreichend aktuellen Version vor (Stretch und Buster funktionieren ebenfalls). Mit

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

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

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

'''Anmerkung:''' diese Aussage bzgl. node-Version (und Jessie/Stretch) stimmt wohl für alexa-fhem Stand heute (12.06.2020) nicht mehr, siehe https://forum.fhem.de/index.php/topic,112025.msg1063218.html#msg1063218

=== Alexa-FHEM installieren ===

Nun installieren wir Alexa-fhem aus dem offiziellen Repository:

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

Der Vorgang benötigt etwas Zeit.

(Edit: die aktuelle Version 0.5.65 hat ein Problem, wenn ModeController verwendet wird. Wer modes braucht, der sollte die vorherige Version 0.5.64 installieren: sudo npm install -g alexa-fhem@0.5.64)

=== Alexa-FHEM aktivieren ===

Wechsele jetzt in FHEM-Web!

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

* Zuerst bitte einfach einmal die Seite neu laden.

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

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

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

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

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

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

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

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

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

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

Du solltest dann folgende Ausgabe erhalten:

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

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

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

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

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

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

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

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

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

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

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

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

Wähle die Geräte aus, rufe sie auf und setze das Attribut "alexaName". Hierbei in Kürze nur der Hinweis:
* Keine Angst vor Leerzeichen und Umlauten, funktioniert.
* Große Angst vor Rechtschreibfehlern (Terrasse, Rollladen) oder komplizierten Wörtern "handgebastelte Martinslaterne im Kinderzimmer Iphigenie-Chantal".
* Mehrere Namen für dasselbe Gerät/Device in fhem werden unterstützt. Mehrere Namen werden durch <s>Strichpunkt</s> Komma getrennt<ref>Feature nicht dokumentiert {{Link2Forum|Topic=74041|LinkText=Forumsthread}}</ref>.
* Das Attribut "alexaRoom" ist NUR FÜR DEN CUSTOM SKILL relevant. Ausnahme: structure und LightScene Devices, siehe: [[FHEM_Connector_f%C3%BCr_Amazon_Alexa#Was_geht_alles_.3F]].

Lade die Geräte neu in die Software, indem Du <code>set <alexa> restart</code> ausführst!
[[Datei:HowToSet alexaName.png|alternativtext=How to set alexaName|ohne|mini|Wie setzt man das Attribut alexaName]]

'''Anmerkungen (weil oft gestellte Fragen im Forum) bzgl. Erkennung von Geräten:'''

* Wichtig ist, dass die Filtereinstellung in der alexa-fhem.cfg (zu finden unter "Edit Files") passt.
Das, was dort eingetragen ist (Standard: alexaName=..* / also es ist ein alexaName vergeben) auch an den entsprechenden Devices in fhem vorhanden ist.
Stimmt das nicht überein, kann alexa-fhem keine Devices von fhem abfragen/finden.
Ob der Filter entsprechend funktioniert kann man wie folgt testen: ''list Filtereinstellung'' beispiel mit Standardfilter: ''list alexaName=..*''

* Hat alexa-fhem per Filter Devices aus fhem "gefunden", geht es weiter mit der "Erkennung". Also um welches Device (Typ und "Fähigkeiten") handelt es sich. Dazu gilt folgendes:
** sind entsprechende Readings beim Device vorhanden (z.B. temperature, state mit on/off, ...) erkennt das alexa-fhem automatisch. Die Liste der automatisch erkannten Readings wächst ständig. Daher erst mal schauen ob das Device bereits entsprechend erkannt (typisiert) wurde. Das kann durch prüfen des alexa-fhem-Logs geschehen (NICHT fhem-log!).
** sind entsprechende "set-Befehle" erkennbar (oft auch durch Readings). Also ist beispielsweise (wie beim Dummy nötig) ein ''setList'' mit entsprechenden Einträgen vorhanden oder entsprechende Readings, z.B. desired-temp zum Stellen der Temperatur etc.
** wird das Device nicht richtig oder "unvollständig" erkannt helfen folgende Attribute:
*** genericDeviceType: hiermit kann alexa-fhem in die gewünschte Richtung "geschubbst" werden. Anmerkung: man kann nicht alles erzwingen, Readings bzw. set-Befehle müssen passen (oder per homebridgeMapping passend gemacht werden). Wenn ein genericDeviceType nicht per "Drop-Down" erscheint, dann kann er auch (wenn bekannt) einfach per WEB-cmd eingegeben werden: ''attr Devicename genericDeviceType media''
*** homebridgeMapping: hierdurch kann alexa-fhem bei der Erkennung von Zuständen und möglichen Einstellungen (also WAS kann das Device) unterstützt werden. Mittels homebridgeMapping können vorhandene Readings (Zustände) auf für alexa-fhem bekannte Zustände gemappt werden. Ebenso können damit Standard-fhem-Kommandos von alexa-fhem auf Device-spezifische gemappt werden. Beispiel: on/off auf Ein/Aus (falls das Device statt on/off eben ein Ein/Aus erwartet). Zum Beispiel: <syntaxhighlight lang="bash" style="width:50%;">
attr <thermostat> homebridgeMapping TargetTemperature=target::target,minValue=18,maxValue=25,minStep=0.5 CurrentTemperature=myTemp:temperature
</syntaxhighlight> [https://github.com/justme-1968/homebridge-fhem/blob/master/README.md weitere Beispiele]

 '''Mehrere Namen für dasselbe Gerät/Device in fhem sind möglich.''' 
Die Namen werden durch <s>Strichpunkt</s> Komma getrennt. 
Beispiel: 
<code>attr dmLampe alexaName Lichtkuppel,Lichtkugel</code>

'''Anmerkung bzgl. genericDeviceType und homebridgeMapping:''' 
* diese Attribute werden von verschiedenen "Sprachsteuerungsmodulen" in fhem verwendet (homebridge [dort wurde es "erfunden"], alexa-fhem, gassistant, ...). Daher ist nicht jedes Mapping für alle "Dienste" verwendbar. Ausprobieren schadet aber nicht.
* ebenso kann man mit diesen Attributen (homebridgeMapping wird gerne so "missbraucht") nichts erzwingen, was seitens Amazon/Alexa nicht unterstützt bzw. verstanden wird! D.h. zunächst ist zu prüfen, ob ein bestimmter (gewünschter) Sprachbefehl seitens Amazon/Alexa unterstützt wird! Aktuelles Beispiel (Stand Jan 2020): "Alexa, fahre den Rollo hoch/runter". Da ist Amazon/Alexa gerade dabei etwas zu tun. Bislang wird das nicht unterstützt, also ist das auch mit einem entsprechenden homebridgeMapping nicht zu erzwingen! Was unterstützt wird kann man bei Amazon nachlesen: [https://developer.amazon.com/es-ES/docs/alexa/device-apis/list-of-interfaces.html]

== Finale: Skill verknüpfen ==
Suche auf der Alexa-App den Skill "FHEM Connector".

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

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

Hier kopierst Du Deinen Anmeldeschlüssel (im Klartext!) hinein, den du mittels "get alexa proxyKey" erhalten hast, und klickst auf Check. Als glücklicher Mensch ist auf der folgenden Statusseite alles grün: 
[[Datei:FHEMlazy_check.png|240px]]

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

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

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

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

'''Als Abschluss muss man nur noch in ein Echo-Gerät seiner Wahl die Anweisung: "''Alexa suche smarte Geräte''" sprechen und schon sollten die oben genannten Geräte gefunden werden und in der APP als Geräte auftauchen.'''

== Was geht alles ? ==

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

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

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

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

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

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

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

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

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

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

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

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

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

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

* Geräte, die sich ein- (und optional) ausschalten lassen als Szene (ab alexa-fhem version 0.5.26)
** Über <code>genericDeviceType</code> scene
** Automatisch: Müssen <code>set on</code> und <code>set off</code> Kommandos haben
** homebridgeMapping On:reading=<reading>,cmdOn=<cmd>[,cmdOff=<cmd>]
** Hinweis: Fehlende Kommandos lassen sich mit cmdalias erzeugen
** Wichtig:
*** Ein Skill darf nur 12 Szenen automatisch erkennen und einbinden.
* Rollläden. Lange ein Problemthema, das nur mit "Schalte auf 0%, schalte auf 100% lief". Wichtig: "alexa-fhem" ab Version 0.5.39 einsetzen. GenericDevice-Type auf "blind" setzen. Nach Restart von alexa-fhem und neuer Gerätesuche sollte folgendes funktionieren:
** "..., öffne <Name> ganz"
** "..., schließe <Name> komplett"
** "hoch" und "runter" (ohne "ganz" oder "komplett") schalten jeweils nur einen bestimmten Prozentsatz hoch oder runter. Dieser kann mit <code>attr <name> homebridgeMapping TargetPosition:minStep=<wert></code>geändert werden. Aber Achtung: In diesem Intervall kann dann auch nur noch ein absoluter Prozentwert per Sprache oder Slider eingestellt werden! Bei z.B. 25% würden 13% zu 25% aufgerundet, 12% zu 0% abgerundet werden.
* Kontaktsensoren (ab alexa-fhem version 0.5.47)
** Automatisch wenn ein Reading <code>motion</code> vorhanden ist oder es sich um einen Zigbee bewgungsmelder an einer HUE oder deCONZ Bridge handelt
** Über <code>genericDeviceType</code> MotionSensor
** homebridgeMapping MotionDetected:reading=<reading>,values=<wert für bewgung>:1;<wert für keine bewegung>:0

* Alarmmelder (noch nicht in Deutschland):
** genericDeviceType Security
** homebridgeMapping Alarm=<reading>[,type=[fireAlarm|waterAlarm|burglaryAlarm|carbonMonoxideAlarm]]
** wenn der type nicht angegeben wird ist fireAlarm der default
** automatisch werden 0, ok und alles was mit no anfängt als OK erkannt. alles andere gilt als ALARM.
*Geräte mit mehrstufigen Modi:
**siehe den zugehörigen Thread im Forum: {{Link2Forum|Topic= 125604}}

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

to be continued ...

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

=== Aktiv Routinen starten ===
Routinen (eine Funktionalität, die rein - genauso wie "Räume" - bei Amazon liegt und nicht von FHEM Connector beeinflusst wird) waren lange die ewige Antwort auf die Frage: "Meine Frau möchte aber '''Öffne Rollläden''<nowiki/>' sagen": In der Alexa-App gibt es im Menü den Punkt "Routinen", und hier lässt sich eine gewisse Anzahl von Aktionen (unter optionalen Bedingungen) an ein Sprachkommando knüpfen.

Neu: Routinen können inzwischen auch von Skills getriggert werden, und seit Version 0.5.47 (Februar 2020) auch von FHEM Connector. Das braucht niemand, um die Rollläden hochzufahren, denn das kann FHEM ja selber, aber um z.B. eine Ansage auf einem Alexa-Gerät zu triggern. Dafür gibt es auch das FHEM-Modul "echodevice", aber es erfordert ein paar Klimmzüge. Mit dem aktiven Triggern von Routinen kann FHEM auslösen, dass Alexa ungefragt (!) Dinge wie

''"Die Temperatur in der Tiefkühltruhe hat -16 Grad überschritten"''

in den Raum sagt. Also eine Alternative bzw. Ergänzung zu Alarmen / Erinnerungen per Telegram o.ä.

'''Vorgeschichte''':

Die Smarthome-Skill-API von Amazon sah schon lange das "proactiveReporting" vor: Also z.B. die gemessene Temperatur nicht erst auf Anfrage hin zu übermitteln, sondern laufend aktiv zu pushen. Aber warum Daten an Amazon senden, wenn es dafür keinen Mehrwert gibt? Beim Öffnen z.B. des Thermostaten in der Alexa-App kommen ohnehin laufend Statusabfragen. Warum also einen Datenpool bei Amazon über die Haustemperatur aufbauen und Änderungen pushen, wenn es keinen Mehrwert dafür gibt?

Inzwischen lassen sich (reale oder vermeintliche) Änderungen von ''Bewegungssensoren'' und ''Fensterkontakten'' als Startbedingung an Alexa-Routinen koppeln. Man kann in der Alexa-App (ggf. fiktive) Öffnen eines Fensterkontaktes an das Aufsagen eines freien Textes durch die Hausbutlerin knüpfen.

'''Umsetzung''':
* Jedes Alexa-Device, dessen Status aktiv zu Amazon gepusht werden soll, im Attribut "alexaProactiveEvents" mit einer "1" versehen. Per Default wird ''kein'' Gerät laufend aktiv zu Amazon gepusht!
* das geänderte Device einmal zu Amazon pushen "set <alexa> add <device>" (oder 'Alexa, suche neue Geräte' murmeln)
* Das Gerät sollte jetzt beim Anlegen einer neuen Routine ("Neue Routine", "Wenn Folgendes passiert", "Smart Home") als möglicher Triggerpunkt erscheinen.

==== Dummygeräte: ====
Ein Dummydevice sollte einen Kontaktschalter oder Bewegungssensor simulieren, um dann in FHEM eine beliebige Bedingung als Trigger zu definieren, und eine freie Ansage in Alexa als Routine zu definieren. Hier ein Beispiel:

<syntaxhighlight lang="bash" style="width:90%;">
define voicetrigger1 dummy
attr voicetrigger1 alexaName alle Fenster
attr voicetrigger1 alexaProactiveEvents 1
attr voicetrigger1 genericDeviceType contact
attr voicetrigger1 homebridgeMapping ContactSensorState=state,values=closed:CONTACT_DETECTED;open:CONTACT_NOT_DETECTED
attr voicetrigger1 setList open closed

set alexa add voicetrigger1
set alexa restart
</syntaxhighlight>

'''Fehlersuche:'''

Der Push setzt ein intaktes Push-Token voraus. Sollte im Alexa-Logfile Folgendes erscheinen:

<code>failed to refresh token: invalid_grant: 'The request has an invalid grant parameter : refresh_token'</code>

so ist das Push-Token nicht aktuell. Weil die Auswirkung lange nur war, dass Geräteänderungen nicht aktiv an Amazon gemeldet wurden, gibt es noch keine umfassende Analyse des Problems. Es lässt sich lösen, indem eine oder beide folgenden Aktionen ausgeführt werden:
* Löschen des ".eventToken" im Alexa-Device über "deletereading"
* "FHEM-Connector"-Skill auf "alexa.amazon.de" einmal deaktivieren und dann neu verbinden

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

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

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

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

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

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

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

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

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

Auf der Kommandoshell:

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

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

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

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

== Sicherheitskonzept und Secrets ==

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

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

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

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

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

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

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

== alexa-fhem Updaten bzw. "Upgraden" ==

'''Updaten einer "Connector" Installation:'''
* alexa-fhem über FHEM anhalten (Name des Alexa-Device: alexa):
:<syntaxhighlight lang="perl" style="width:50%;">set alexa stop</syntaxhighlight>

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

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

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

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

'''"Upgraden von einer "Nicht-Connector" Installation (z.B. manuelle Installation per pm-Download):'''
* Daten der aktuellen Installation sichern (v.a. config.json / man weiß ja nie)
* Autostart der aktuellen alexa-fhem Installation deaktivieren:
** Bei initd: Service deaktivieren mittels: <code>sudo update-rc.d -f alexa remove</code> Vorher mittels stoppen: <code>sudo service alexa stop</code> Startscript unter /etc/init.d/ löschen.
** Bei systemd: Service deaktivieren mittels: <code>sudo systemctl disable alexa</code> Vorher mittels stoppen: <code>sudo systemctl alexa stop</code> Startscript unter /etc/systemd/system/ löschen.
* ALLE vorhandenen alexa-fhem Daten LÖSCHEN! Bleiben Dinge zurück und wird dann laut Connector installiert kann es zu Problemen kommen!
* (reboot)
* Installation von alexa-fhem laut Anleitung (Beginn dieses Wiki)
* Falls eigene Dinge von früher genutzt werden wollen/sollen (z.B. Custom Skill), dann die entsprechenden Einträge aus der gesicherten config.json in die neu angelegte alexa-fhem.cfg (zu finden unter "Edit files") übernehmen.
* Werden keine eigenen Dinge verwendet, dann kann der Port (Standard: 3000) geschlossen werden und auch die Daten unter Amazon-Developer können gelöscht werden.

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

==Weitergehende Informationen==
*[[Alexa und Mappings]]
*[[Alexa Tipps und Kniffe]]
*[[FHEM Connector for Amazon Alexa]]
[[Kategorie:HOWTOS]]
[[Kategorie:Sprachsteuerung]]

==Hinweise==
<references />

Broadlink

2024-05-18T11:18:42Z

Hapege: /* Skripte */

== Beschreibung ==
Die chinesische Firma BroadLink stellt unter Anderem auch Gateways her, die sich per Wifi ansprechen lassen und Infrator (38KHz-IR) bzw. RF (433/315 MHz-RF) Komponenten fernsteuern können (https://www.ibroadlink.com/productinfo/762672.html).

Die Gateways werden mit Hilfe einer Android- oder iOS-App ("Intelligent Home Center for EU (IHC) oder "BroadLink - Universal TV Remote") angelernt.

Danach stellen sie die Möglichkeit bereit,
* Infrarot- (und ggf. RF-) Codes bzw. Code-Sequenzen zu erfassen und via WLAN als Parameter zu übermitteln und
* (gelernte) Codes an kompatible IR- bzw. RF-Empfänger zu versenden.

Die dazugehörige openAPI ist nicht öffentlich und unterliegt einer BroadLink NDA.

Zur praktischen Verwendung gibt es mehrere Schnittstellen:
# die offizielle App (https://www.ibroadlink.com/bleapp), mit der Codes angelernt, in der App gespeichert und im lokalen WLAN über die RM versendet werden können,
# die ''[http://rm-bridge.fun2code.de/ RM Bridge]'' für Android-Geräte, die eine HTTP REST web API auf dem Androidgerät als Webservice bereitstellt,
# die ''Python-Bibliothek [https://github.com/mjg59/python-broadlink python-broadlink]'' von Matthew Garrett (mjg59) für Server, auf denen Python lauffähig ist. Diese kann dann direkt per (Shell-)Skript [https://forum.fhem.de/index.php/topic,54334.15.html aufgerufen werden] aber auch noch schön gekapselt werden:
# ''{{Link2Forum|Topic=38231|Message=581909|LinkText=Webservice für Python fähige Server}}''. In dieser Form sind dann gelernte Sendebefehle elegant als [[HTTPMOD]] Objekte in FHEM integrierbar.

=== BroadLink RM mini ===
{{Infobox Hardware
|Bild=RMmini.png
|Bildbeschreibung= BroadLink RM mini 3
|HWProtocol= Infrarot
|HWType= Gateway
|HWCategory= Infrarot
|HWComm= Infrarot 38 KHz Wifi 2.4GHz b/g/n
|HWChannels= 1
|HWVoltage= 5V
|HWPowerConsumption= max. 2,5W (max. 0,5A) standby ca. 0.85W
|HWPoweredBy= Micro USB
|HWSize= 5.5 x 5.5 x 6.45 cm
|HWDeviceFHEM= Broadlink

|HWManufacturer= [http://www.ibroadlink.com/rmMini3/ BroadLink]

}}

Der BroadLink RM mini 3 (wird nicht mehr hergestellt, evtl. noch bei Amazon / ebay erhätlich) ist ein WLAN zu Infrarot Gateway (ohne RF, vgl. [[#BroadLink RM Pro|RM Pro]]). Im Vergleich zum RM Pro ist die Sendeleistung deutlich schwächer, da nur ein IR-Transmitter verbaut ist.

 

=== BroadLink RM Pro ===
{{Infobox Hardware
|Bild=RMPro.png
|Bildbeschreibung= BroadLink RM Pro
|HWProtocol= Infrarot, RF
|HWType= Gateway
|HWCategory= Infrarot, RF
|HWComm= Infrarot 38 KHz RF 433/315 MHz Wifi 2.4GHz b/g/n
|HWChannels= 2
|HWVoltage= 5V
|HWPowerConsumption= max. 5W (max. 1A) ca. 1W standby
|HWPoweredBy= Micro USB
|HWSize= 11 x 3,5 x 11,5 cm
|HWDeviceFHEM= Broadlink

|HWManufacturer= [http://www.ibroadlink.com/rmPro/ BroadLink]

}}

Der BroadLink RM Pro/RM3 (wird nicht mehr hergestellt, evtl. noch bei Amazon / ebay erhältlich) ist ein WLAN zu Infrarot- und RF Gateway. Der aktuelle Nachfolger ist der RMpro 4 (https://www.ibroadlink.com/productinfo/762672.html).

Der RM Pro verfügt im Vergleich zum [[#BroadLink RM mini|RM mini]] über eine größere Reichweite, da 6+1 (Kreis und Mitte) IR-Transmitter verbaut sind.

(In der Version RM3 soll der unterstützte RF-Bereich inoffiziell sogar 142...1050 MHz betragen.)

Der RM Pro enthält auch einen Temperatursensor, der mindestens über die App ausgelesen und für Aktions-Regeln verwendet werden kann. Der Sensor ist offenbar nicht in allen Versionen verbaut bzw. kann oft nur als externer Sensor angeschlossen werden.

Es gab/gibt Vorgängerversionen:
* RM Home/RM1: "rote Version"; nur IR, ohne RF; schwache Sendeleistung
* RM Pro/RM2: "schwarze Version"; ID 10 002; IR und RF 433/315MHz; verstärkte IR-Sendeleistung (7 IR-Transmitter)
* (OEM Version) RM Plus: schwarz, keine Aufkleber, keine Beschriftungen, gerade, nicht abgerundete Oberseite... (soll intern baugleich mit RM Pro/RM3 sein).

 

== Nutzung in FHEM ==
=== Modul ===
'''Achtung: Das Modul wird offenbar nicht mehr gepflegt und funktioniert bei vielen Nutzern nicht bzw. (nach Rücksetzen des Gateways) nicht mehr. Empfohlen wird aktuell der Einsatz der unten genannten python Module und der dort hinterlegten Skripte.
'''

Es gibt das {{Link2CmdRef|Lang=de|Label=Modul Broadlink|Anker=Broadlink}}, mit dem Broadlink-Geräte in FHEM eingebunden werden können:
* rmpro (RM Pro)
* rmmini (RM mini)
* sp3 (SP3 - Schalter)
* sp3s (SP3S - Schalter mit aktueller Energieverbrauchsmessung)

s.a.: [https://forum.fhem.de/index.php/topic,71972.msg Forenthread]

=== Webservice ===
Es gibt den Ansatz, [https://forum.fhem.de/index.php/topic,38231.msg581909.html#msg581909 auf dem FHEM-Server einen Webservice (pro Gateway) zu installieren] und via [[HTTPMOD]] Befehle abzusetzen.

=== Skripte ===
Auf dem FHEM-Server werden die python Module mit den integrierten Skripten installiert und nur jeweils bei Bedarf angestoßen. So wird keine permanente Systemlast produziert. Die Reaktionsgeschwindigkeit ist nicht überwältigend, aber praxistauglich. (Ca 2-3 sec).

:: '''Credits'''
::
:: Die Python-API ist von [https://github.com/mjg59/python-broadlink dieser Github-Seite].

== Hinweis ==
Mit diesem Vorgehen unterstützt das BroadLink sowohl IR als auch RF.

== Vorgehen (Skripte) ==
=== Installation ===

Zunächst wird der Broadlink mit der App ins eigene Netz eingebunden. Hierzu der Anleitung in der App folgen.

Alternativ und ohne Notwendigkeit die App zu installieren kann der Broadlink auch über die python Skripte ins WLan gebracht werden, siehe https://github.com/mjg59/python-broadlink.

Auf dem FHEM-Rechner (z.B. Raspi) muss python (python3) und am besten git installiert sein. Ggf. muss auch noch simplejson und pip installiert werden.

sudo apt-get install python git pip
sudo pip install simplejson

Verzeichnis erstellen und die Bibliothek installieren
sudo mkdir /opt/BroadLink
sudo chown fhem.dialout /opt/BroadLink
cd /opt/BroadLink
sudo git clone https://github.com/mjg59/python-broadlink.git
cd python-broadlink
sudo python setup.py install
cd ..

== Skripte ==
Die python Module bringen eigene Skripte zum Anlernen und Senden von IR/RF commands mit. Sie liegen im Verzeichnis /opt/BroadLink/python-broadlink/cli. Die Verwendung wird hier beschrieben: https://github.com/mjg59/python-broadlink/tree/master/cli

Anleitung im Forum dazu: https://forum.fhem.de/index.php?topic=71972.msg1313044#msg1313044

'''In a nutshell:'''
Broadlink finden: <syntaxhighlight> broadlink_discovery </syntaxhighlight>
Die Daten des gefundene Gerätes in einem File speichern (siehe Shell Ausgabe), als Beispiel: <syntaxhighlight>rmpro.device</syntaxhighlight>
Command anlernen und in File speichern: <syntaxhighlight>broadlink_cli --device @rmpro.device --rflearn --learnfile TVon</syntaxhighlight>
Command senden: <syntaxhighlight>broadlink_cli --device @rmpro.device --send @TVon</syntaxhighlight>
Integration in notify/DOIF: <syntaxhighlight>{system("/opt/BroadLink/python-broadlink/cli/broadlink_cli --device \@/opt/BroadLink/python-broadlink/cli/rmpro.device --send \@/opt/BroadLink/python-broadlink/cli/TVOn")}</syntaxhighlight>

'''== Die folgenden Skripte bzw der ganze Abschnitt ist veraltet =='''

Die hier zitierten Skripte laufen nicht mehr unter python3. Sie sind auch nicht mehr erforderlich, da die python Module eigene Skripte mitbringen. Diese liegen im Verzeichnis /opt/BroadLink/python-broadlink/cli. Die Verwendung wird hier beschrieben: https://github.com/mjg59/python-broadlink/tree/master/cli

In das Verzeichnis dann noch die vier Skripte kopieren.

1. search-bl.sh
<syntaxhighlight lang="python">
#!/usr/bin/python

#Script to locate Broadlink devices on local network by Graeme Brown Dec 23 2016
#These must be set up using the Broadlink app first!

import broadlink
import time

print "************************************************"
print "Using python library created by Matthew Garrett"
print "https://github.com/mjg59/python-broadlink"
print "************************************************"
print "Scanning network for Broadlink devices...."

mydevices = broadlink.discover(timeout=5)
print "Found " + str(len(mydevices )) + " broadlink devices"
time.sleep(1)
print "..............."

for index, item in enumerate(mydevices):

mydevices[index].auth()

ipadd = mydevices[index].host
ipadd = str(ipadd)
print "Device " + str(index + 1) +" Host address = " + ipadd[1:19]
macadd = ''.join(format(x, '02x') for x in mydevices[index].mac[::-1])
macadd = str(macadd)

mymacadd = macadd[:2] + " " + macadd[2:4] + " " + macadd[4:6] + " " + macadd[6:8] + " " + macadd[8:10] + " " + macadd[10:12]
print "Device " + str(index + 1) +" MAC address = " + mymacadd
print "..............."
</syntaxhighlight>

2. learn-bl.sh
<syntaxhighlight lang="python">
#!/usr/bin/python

import broadlink
import time
import sys

device = broadlink.rm(host=("<your RM3 IP address>",80), mac=bytearray.fromhex("<your RM3 mac>"))

print "Connecting to Broadlink device...."
device.auth()
time.sleep(1)
print "Connected...."

codeName = raw_input("Bitte Namen f. den Code eingeben, z.B. tvOff ")
time.sleep(1)
print "Wenn die LED am Broadlink angeht, innerhalb von 5 Sek die FB-Taste druecken "

device.host
device.enter_learning()
time.sleep(5)
ir_packet = device.check_data()
#convert code to hex
myhex = str(ir_packet).encode('hex');

if ir_packet == None:
print "Kein Code empfangen - Ende"
sys.exit()
else:

# record learned hex code to file
f = open(codeName +".txt",'w')
f.write(myhex)
f.close()

print "Hex code gespeichert unter " + codeName + ".txt"
</syntaxhighlight>

3. send-bl.sh
<syntaxhighlight lang="python">
#!/usr/bin/python

import broadlink
import time
import sys

try:
fileName = sys.argv[1]
except IndexError:
fileName = 'null'

if fileName == 'null':
print "Error - kein Dateiname angegeben"
sys.exit()
else:

device = broadlink.rm(host=("<your RM3 IP address>",80), mac=bytearray.fromhex("<your RM3 mac>"))

print "Connecting to Broadlink device...."
device.auth()
time.sleep(1)
print "Connected...."
time.sleep(1)
device.host

file = open(fileName, 'r')

myhex = file.read()

device.send_data(myhex.decode('hex'))
print "Code Sent...."
</syntaxhighlight>

4. sendmore-bl.sh
<syntaxhighlight lang="python">
#!/usr/bin/python

import broadlink
import time
import sys

try:
fileName = sys.argv[1]
except IndexError:
fileName = 'null'

if fileName == 'null':
print "Error - kein Dateiname angegeben"
sys.exit()
else:
device = broadlink.rm(host=("<your RM3 IP address>",80), mac=bytearray.fromhex("<your RM3 mac>"))

# print "Connecting to Broadlink device...."
device.auth()
time.sleep(1)
# print "Connected...."
device.host

# Pfad aus Aufruf extrahieren und dann den Befehl selbst vom Stapel nehmen
Parameter = sys.argv
# Name des Befehls selbst
filename1 = Parameter[0]
# Gesamtlaenge
FileNameLaenge = len(filename1)
# in Bestandteile aufteilen
filearray = filename1.split("/")
# den letzten identifizieren. Das ist der eigentliche Befehl
splitNo = len(filename1.split("/"))
lastElement = filearray[splitNo-1]
# den vom Aufruf wegschneiden, um den Pfad zu bekommen
FileNameAbzug = len(lastElement)
Ende = FileNameLaenge - FileNameAbzug
Pfad = filename1[0:Ende]
# Befehl aus der Liste loeschen, damit die Parameter bleiben
Parameter.pop(0)

# repeat for each argument
for argument in Parameter:
fileName = Pfad + argument +".txt"
file = open(fileName, 'r')
myhex = file.read()
device.send_data(myhex.decode('hex'))
time.sleep(0.5)
# print "Code Sent...."
sys.exit()
</syntaxhighlight>

Dann in dem Verzeichnis noch die Dateibesitzer wechseln und die Skripte ausführbar machen:

sudo chown fhem.dialout *.sh
sudo chmod 744 *.sh

=== Konfiguration ===

Nun gilt es, die IP und MAC-Adresse des Broadlink herauszufinden. Entweder man schaut im Router nach, benutzt die Android-App FING oder das Script "search-bl.sh". Dazu

sudo ./search-bl.sh

Beispielhaft kommt dann:

************************************************
Using python library created by Matthew Garrett
https://github.com/mjg59/python-broadlink
************************************************
Scanning network for Broadlink devices....
Found 1 broadlink devices
...............
Device 1 Host address = '192.168.1.16', 8
Device 1 MAC address = b4 43 0d aa b3 54
...............

Für später sind die IP Adresse und die MAC Adresse wichtig. Diese müssen im zweiten bis vierten Script eingetragen werden!! Ich benutze da den Editor nano.
sudo nano ./learn-bl.sh
sudo nano ./send-bl.sh
sudo nano ./sendmore-bl.sh

Dabei die doppelten Anführungszeichen stehen lassen und an der passenden Stelle jeweils die IP und an der anderen die MAC-Adresse (mit Leerzeichen anstelle der Doppelpunkte) eintragen. Das erste Script liefert die auch so formatiert. Wenn man sie aber aus dem Router hat oder so, dann eben beachten!

Das zweite Script dient zum Anlernen des Fernbedienungscodes und Abspeichern in jeweils einer txt Datei. Das Script verbindet sich mit dem Broadlink und erwartet einen Namen für den Code. Dann hat man 5 Sec Zeit, um die entsprechende Fernbedienungstaste zu drücken, um den Code anzulernen. Dieser wird dann in eine Datei mit dem Codenamen gespeichert. So kann man alle seine zu verwendenden Codes nacheinander anlernen.

sudo ./learn-bl.sh

zeigt Folgendes an:

Connecting to Broadlink device....
Connected....
Bitte Namen für den Code eingeben, z.B. tvOff test
Wenn die LED am Broadlink angeht, innerhalb von 5 Sek die FB-Taste drücken
Hex code gespeichert unter test.txt

=== Betrieb ===

Mit dem dritten und vierten Script kann man den Code wieder senden. Auch hier wieder die eigene IP Adresse und MAC Adresse des Broadlink von oben eintragen.

Der Aufruf im Terminal ist für das dritte Skript:
sudo /opt/BroadLink/send-bl.sh /opt/BroadLink/test.txt

Wichtig ist bei diesem Skript, für das Textfile den ganzen Pfad anzugeben, und der in test.txt gelernte Befehl wird gesendet.

Aus FHEM heraus kann dann z.B. auf der Eingabezeile gesendet werden:
"/opt/BroadLink/send-bl.sh /opt/BroadLink/test.txt"
Dabei sind die " " wichtig, da es sich um einen Shell-Befehl handelt.

So kann man das dann auch in at-, notify- oder DOIFs verwenden. Hier mal ein Beispiel:

define atAbendsLichtAn at *19:00:00 "/opt/BroadLink/send-bl.sh /opt/BroadLink/FB1An.txt"

Das 4. Skript "sendmore-bl.sh" ist eine Modifikation des Send-Skripts. Die Unterschiede sind:

1. Es sendet auch mehrere Codes nacheinander, also z. B. auch Zahlenfolgen wie "0202".

2. Es nimmt an, dass die Codes als .txt-Dateien im selben Verzeichnis liegen wie das Skript.

3. Das Skript gibt keine Meldungen aus. Die sind beim Aufruf aus FHEM heraus auch unnötig.

Das Skript extrahiert aus dem Befehlsaufruf den Pfad und ergänzt ihn jeweils bei den Parametern sowie um die Dateierweiterung ".txt". Daher kann der Aufruf dann kürzer sein. Angenommen, es sind die Code-Dateien 1.txt, 2.txt, 3.txt usw. im selben Verzeichnis wie die Skripte vorhanden, lautet der Aufruf im Terminal dann z.B. nur noch:

/opt/BroadLink/sendmore-bl.sh 1 2 3 2

Im "define" lautet das oben genannte Beispiel:
define atAbendsLichtAn at *19:00:00 "/opt/BroadLink/sendmore-bl.sh FB1An"

=== Feintuning ===
Im 4. Skript definiert die Zeile (kurz vor Ende)
time.sleep(0.5)
die Wartezeit zwischen zwei gesendeten "Tasten". Bei vielen Geräten funktioniert das auch, wenn man die Zeile auskommentiert oder löscht. Dann werden die Signale schneller hintereinander gesendet.
Man kann hier natürlich auch den Wert 0.5 verändern. Einfach ausprobieren!

== Mehrere Bridges betreiben ==

Um mehrere Bridges nebeneinander zu betreiben, braucht man für jedes Gerät das dritte oder vierte Skript unter eigenem Namen, also z.B. sendmore-bl-WoZi.sh und sendmore-bl-SchlafZi.sh und sendmore-bl-Kueche.sh. In diese müssen die jeweils zugehörenden IP- und MAC-Adressen eingetragen werden. Dann entscheidet man über den Aufruf, welche Bridge den Befehl bekommt. Dabei kann man die gelernten Codes für alle Bridges nutzen und muss sie nicht für jede Bridge neu anlernen.

== Bekannte Probleme ==
Man kann mit dem dritten Skript nur einzelne Tastendrücke senden. Und der Aufruf von mehreren Befehlen nacheinander liegt so weit auseinander, dass das nicht als Folge von Befehlen ankommt, sondern jeweils als Einzelbefehle. Dafür kann man das 4. Skript ausprobieren.

Einige User berichten von diesem Fehler:
Traceback (most recent call last):
File "/opt/BroadLink/send-bl.sh", line 34, in <module>
device.send_data(myhex.decode('hex'))
File "/usr/local/lib/python2.7/dist-packages/broadlink-0.3-py2.7.egg/broadlink/__init__.py", line 455, in send_data
self.send_packet(0x6a, packet)
File "/usr/local/lib/python2.7/dist-packages/broadlink-0.3-py2.7.egg/broadlink/__init__.py", line 250, in send_packet
response = self.cs.recvfrom(1024)
socket.timeout: timed out

Abhilfe schafft, in der Datei "/usr/local/lib/python2.7/dist-packages/broadlink-0.3-py2.7.egg/broadlink/__init__.py" Zeile 249
den Timeout von 1 Sekunde auf z.B. 5 Sekunden zu stellen: self.cs.settimeout(5)

Bei der Einrichtung via Smartphone-App gibt den AP-Modus: in diesem wird im Gateway ein WLAN-AP aktiviert, '''unverschlüsselt''', mit dem sich das Smartphone dann verbindet. Über das für Sniffer offene WLAN wird dann SSID und Passwort des lokalen WLAN übermittelt, worauf sich das Gateway versucht dort anzumelden. '''''Die Einrichtung über diesen Weg legt das WLAN Passwort für Sniffer ohne weiteren Aufwand offen. Das Risiko ist auf diese eine Übertragung begrenzt.'''''

== Hinweis ==
Wenn alles funktioniert, kann man aus dem dritten Skript natürlich die Bildschirmausgaben löschen, da es ja in FHEM im Hintergrund aufgerufen wird. Umgekehrt kann man sie auch im 4. Skript wieder "freischalten", indem man die # vor den "print"-Anweisungen löscht.

Gelegentlich auftretende Fehlermeldungen (die nur im Terminal sichtbar sind), tun der Funktion (bei mir) keinen Abbruch.

[[Kategorie:Infrarot]]

Broadlink

2024-05-18T11:18:07Z

Hapege: Text und Links aktualisiert, Beschreibung und Verwendung der Skripte aktualisiert

== Beschreibung ==
Die chinesische Firma BroadLink stellt unter Anderem auch Gateways her, die sich per Wifi ansprechen lassen und Infrator (38KHz-IR) bzw. RF (433/315 MHz-RF) Komponenten fernsteuern können (https://www.ibroadlink.com/productinfo/762672.html).

Die Gateways werden mit Hilfe einer Android- oder iOS-App ("Intelligent Home Center for EU (IHC) oder "BroadLink - Universal TV Remote") angelernt.

Danach stellen sie die Möglichkeit bereit,
* Infrarot- (und ggf. RF-) Codes bzw. Code-Sequenzen zu erfassen und via WLAN als Parameter zu übermitteln und
* (gelernte) Codes an kompatible IR- bzw. RF-Empfänger zu versenden.

Die dazugehörige openAPI ist nicht öffentlich und unterliegt einer BroadLink NDA.

Zur praktischen Verwendung gibt es mehrere Schnittstellen:
# die offizielle App (https://www.ibroadlink.com/bleapp), mit der Codes angelernt, in der App gespeichert und im lokalen WLAN über die RM versendet werden können,
# die ''[http://rm-bridge.fun2code.de/ RM Bridge]'' für Android-Geräte, die eine HTTP REST web API auf dem Androidgerät als Webservice bereitstellt,
# die ''Python-Bibliothek [https://github.com/mjg59/python-broadlink python-broadlink]'' von Matthew Garrett (mjg59) für Server, auf denen Python lauffähig ist. Diese kann dann direkt per (Shell-)Skript [https://forum.fhem.de/index.php/topic,54334.15.html aufgerufen werden] aber auch noch schön gekapselt werden:
# ''{{Link2Forum|Topic=38231|Message=581909|LinkText=Webservice für Python fähige Server}}''. In dieser Form sind dann gelernte Sendebefehle elegant als [[HTTPMOD]] Objekte in FHEM integrierbar.

=== BroadLink RM mini ===
{{Infobox Hardware
|Bild=RMmini.png
|Bildbeschreibung= BroadLink RM mini 3
|HWProtocol= Infrarot
|HWType= Gateway
|HWCategory= Infrarot
|HWComm= Infrarot 38 KHz Wifi 2.4GHz b/g/n
|HWChannels= 1
|HWVoltage= 5V
|HWPowerConsumption= max. 2,5W (max. 0,5A) standby ca. 0.85W
|HWPoweredBy= Micro USB
|HWSize= 5.5 x 5.5 x 6.45 cm
|HWDeviceFHEM= Broadlink

|HWManufacturer= [http://www.ibroadlink.com/rmMini3/ BroadLink]

}}

Der BroadLink RM mini 3 (wird nicht mehr hergestellt, evtl. noch bei Amazon / ebay erhätlich) ist ein WLAN zu Infrarot Gateway (ohne RF, vgl. [[#BroadLink RM Pro|RM Pro]]). Im Vergleich zum RM Pro ist die Sendeleistung deutlich schwächer, da nur ein IR-Transmitter verbaut ist.

 

=== BroadLink RM Pro ===
{{Infobox Hardware
|Bild=RMPro.png
|Bildbeschreibung= BroadLink RM Pro
|HWProtocol= Infrarot, RF
|HWType= Gateway
|HWCategory= Infrarot, RF
|HWComm= Infrarot 38 KHz RF 433/315 MHz Wifi 2.4GHz b/g/n
|HWChannels= 2
|HWVoltage= 5V
|HWPowerConsumption= max. 5W (max. 1A) ca. 1W standby
|HWPoweredBy= Micro USB
|HWSize= 11 x 3,5 x 11,5 cm
|HWDeviceFHEM= Broadlink

|HWManufacturer= [http://www.ibroadlink.com/rmPro/ BroadLink]

}}

Der BroadLink RM Pro/RM3 (wird nicht mehr hergestellt, evtl. noch bei Amazon / ebay erhältlich) ist ein WLAN zu Infrarot- und RF Gateway. Der aktuelle Nachfolger ist der RMpro 4 (https://www.ibroadlink.com/productinfo/762672.html).

Der RM Pro verfügt im Vergleich zum [[#BroadLink RM mini|RM mini]] über eine größere Reichweite, da 6+1 (Kreis und Mitte) IR-Transmitter verbaut sind.

(In der Version RM3 soll der unterstützte RF-Bereich inoffiziell sogar 142...1050 MHz betragen.)

Der RM Pro enthält auch einen Temperatursensor, der mindestens über die App ausgelesen und für Aktions-Regeln verwendet werden kann. Der Sensor ist offenbar nicht in allen Versionen verbaut bzw. kann oft nur als externer Sensor angeschlossen werden.

Es gab/gibt Vorgängerversionen:
* RM Home/RM1: "rote Version"; nur IR, ohne RF; schwache Sendeleistung
* RM Pro/RM2: "schwarze Version"; ID 10 002; IR und RF 433/315MHz; verstärkte IR-Sendeleistung (7 IR-Transmitter)
* (OEM Version) RM Plus: schwarz, keine Aufkleber, keine Beschriftungen, gerade, nicht abgerundete Oberseite... (soll intern baugleich mit RM Pro/RM3 sein).

 

== Nutzung in FHEM ==
=== Modul ===
'''Achtung: Das Modul wird offenbar nicht mehr gepflegt und funktioniert bei vielen Nutzern nicht bzw. (nach Rücksetzen des Gateways) nicht mehr. Empfohlen wird aktuell der Einsatz der unten genannten python Module und der dort hinterlegten Skripte.
'''

Es gibt das {{Link2CmdRef|Lang=de|Label=Modul Broadlink|Anker=Broadlink}}, mit dem Broadlink-Geräte in FHEM eingebunden werden können:
* rmpro (RM Pro)
* rmmini (RM mini)
* sp3 (SP3 - Schalter)
* sp3s (SP3S - Schalter mit aktueller Energieverbrauchsmessung)

s.a.: [https://forum.fhem.de/index.php/topic,71972.msg Forenthread]

=== Webservice ===
Es gibt den Ansatz, [https://forum.fhem.de/index.php/topic,38231.msg581909.html#msg581909 auf dem FHEM-Server einen Webservice (pro Gateway) zu installieren] und via [[HTTPMOD]] Befehle abzusetzen.

=== Skripte ===
Auf dem FHEM-Server werden die python Module mit den integrierten Skripten installiert und nur jeweils bei Bedarf angestoßen. So wird keine permanente Systemlast produziert. Die Reaktionsgeschwindigkeit ist nicht überwältigend, aber praxistauglich. (Ca 2-3 sec).

:: '''Credits'''
::
:: Die Python-API ist von [https://github.com/mjg59/python-broadlink dieser Github-Seite].

== Hinweis ==
Mit diesem Vorgehen unterstützt das BroadLink sowohl IR als auch RF.

== Vorgehen (Skripte) ==
=== Installation ===

Zunächst wird der Broadlink mit der App ins eigene Netz eingebunden. Hierzu der Anleitung in der App folgen.

Alternativ und ohne Notwendigkeit die App zu installieren kann der Broadlink auch über die python Skripte ins WLan gebracht werden, siehe https://github.com/mjg59/python-broadlink.

Auf dem FHEM-Rechner (z.B. Raspi) muss python (python3) und am besten git installiert sein. Ggf. muss auch noch simplejson und pip installiert werden.

sudo apt-get install python git pip
sudo pip install simplejson

Verzeichnis erstellen und die Bibliothek installieren
sudo mkdir /opt/BroadLink
sudo chown fhem.dialout /opt/BroadLink
cd /opt/BroadLink
sudo git clone https://github.com/mjg59/python-broadlink.git
cd python-broadlink
sudo python setup.py install
cd ..

== Skripte ==
Die python Midule bringen eigene Skripte zum Anlernen und Senden von IR/RF commands mit. Sie liegen im Verzeichnis /opt/BroadLink/python-broadlink/cli. Die Verwendung wird hier beschrieben: https://github.com/mjg59/python-broadlink/tree/master/cli

Anleitung im Forum dazu: https://forum.fhem.de/index.php?topic=71972.msg1313044#msg1313044

'''In a nutshell:'''
Broadlink finden: <syntaxhighlight> broadlink_discovery </syntaxhighlight>
Die Daten des gefundene Gerätes in einem File speichern (siehe Shell Ausgabe), als Beispiel: <syntaxhighlight>rmpro.device</syntaxhighlight>
Command anlernen und in File speichern: <syntaxhighlight>broadlink_cli --device @rmpro.device --rflearn --learnfile TVon</syntaxhighlight>
Command senden: <syntaxhighlight>broadlink_cli --device @rmpro.device --send @TVon</syntaxhighlight>
Integration in notify/DOIF: <syntaxhighlight>{system("/opt/BroadLink/python-broadlink/cli/broadlink_cli --device \@/opt/BroadLink/python-broadlink/cli/rmpro.device --send \@/opt/BroadLink/python-broadlink/cli/TVOn")}</syntaxhighlight>

'''== Die folgenden Skripte bzw der ganze Abschnitt ist veraltet =='''

Die hier zitierten Skripte laufen nicht mehr unter python3. Sie sind auch nicht mehr erforderlich, da die python Module eigene Skripte mitbringen. Diese liegen im Verzeichnis /opt/BroadLink/python-broadlink/cli. Die Verwendung wird hier beschrieben: https://github.com/mjg59/python-broadlink/tree/master/cli

In das Verzeichnis dann noch die vier Skripte kopieren.

1. search-bl.sh
<syntaxhighlight lang="python">
#!/usr/bin/python

#Script to locate Broadlink devices on local network by Graeme Brown Dec 23 2016
#These must be set up using the Broadlink app first!

import broadlink
import time

print "************************************************"
print "Using python library created by Matthew Garrett"
print "https://github.com/mjg59/python-broadlink"
print "************************************************"
print "Scanning network for Broadlink devices...."

mydevices = broadlink.discover(timeout=5)
print "Found " + str(len(mydevices )) + " broadlink devices"
time.sleep(1)
print "..............."

for index, item in enumerate(mydevices):

mydevices[index].auth()

ipadd = mydevices[index].host
ipadd = str(ipadd)
print "Device " + str(index + 1) +" Host address = " + ipadd[1:19]
macadd = ''.join(format(x, '02x') for x in mydevices[index].mac[::-1])
macadd = str(macadd)

mymacadd = macadd[:2] + " " + macadd[2:4] + " " + macadd[4:6] + " " + macadd[6:8] + " " + macadd[8:10] + " " + macadd[10:12]
print "Device " + str(index + 1) +" MAC address = " + mymacadd
print "..............."
</syntaxhighlight>

2. learn-bl.sh
<syntaxhighlight lang="python">
#!/usr/bin/python

import broadlink
import time
import sys

device = broadlink.rm(host=("<your RM3 IP address>",80), mac=bytearray.fromhex("<your RM3 mac>"))

print "Connecting to Broadlink device...."
device.auth()
time.sleep(1)
print "Connected...."

codeName = raw_input("Bitte Namen f. den Code eingeben, z.B. tvOff ")
time.sleep(1)
print "Wenn die LED am Broadlink angeht, innerhalb von 5 Sek die FB-Taste druecken "

device.host
device.enter_learning()
time.sleep(5)
ir_packet = device.check_data()
#convert code to hex
myhex = str(ir_packet).encode('hex');

if ir_packet == None:
print "Kein Code empfangen - Ende"
sys.exit()
else:

# record learned hex code to file
f = open(codeName +".txt",'w')
f.write(myhex)
f.close()

print "Hex code gespeichert unter " + codeName + ".txt"
</syntaxhighlight>

3. send-bl.sh
<syntaxhighlight lang="python">
#!/usr/bin/python

import broadlink
import time
import sys

try:
fileName = sys.argv[1]
except IndexError:
fileName = 'null'

if fileName == 'null':
print "Error - kein Dateiname angegeben"
sys.exit()
else:

device = broadlink.rm(host=("<your RM3 IP address>",80), mac=bytearray.fromhex("<your RM3 mac>"))

print "Connecting to Broadlink device...."
device.auth()
time.sleep(1)
print "Connected...."
time.sleep(1)
device.host

file = open(fileName, 'r')

myhex = file.read()

device.send_data(myhex.decode('hex'))
print "Code Sent...."
</syntaxhighlight>

4. sendmore-bl.sh
<syntaxhighlight lang="python">
#!/usr/bin/python

import broadlink
import time
import sys

try:
fileName = sys.argv[1]
except IndexError:
fileName = 'null'

if fileName == 'null':
print "Error - kein Dateiname angegeben"
sys.exit()
else:
device = broadlink.rm(host=("<your RM3 IP address>",80), mac=bytearray.fromhex("<your RM3 mac>"))

# print "Connecting to Broadlink device...."
device.auth()
time.sleep(1)
# print "Connected...."
device.host

# Pfad aus Aufruf extrahieren und dann den Befehl selbst vom Stapel nehmen
Parameter = sys.argv
# Name des Befehls selbst
filename1 = Parameter[0]
# Gesamtlaenge
FileNameLaenge = len(filename1)
# in Bestandteile aufteilen
filearray = filename1.split("/")
# den letzten identifizieren. Das ist der eigentliche Befehl
splitNo = len(filename1.split("/"))
lastElement = filearray[splitNo-1]
# den vom Aufruf wegschneiden, um den Pfad zu bekommen
FileNameAbzug = len(lastElement)
Ende = FileNameLaenge - FileNameAbzug
Pfad = filename1[0:Ende]
# Befehl aus der Liste loeschen, damit die Parameter bleiben
Parameter.pop(0)

# repeat for each argument
for argument in Parameter:
fileName = Pfad + argument +".txt"
file = open(fileName, 'r')
myhex = file.read()
device.send_data(myhex.decode('hex'))
time.sleep(0.5)
# print "Code Sent...."
sys.exit()
</syntaxhighlight>

Dann in dem Verzeichnis noch die Dateibesitzer wechseln und die Skripte ausführbar machen:

sudo chown fhem.dialout *.sh
sudo chmod 744 *.sh

=== Konfiguration ===

Nun gilt es, die IP und MAC-Adresse des Broadlink herauszufinden. Entweder man schaut im Router nach, benutzt die Android-App FING oder das Script "search-bl.sh". Dazu

sudo ./search-bl.sh

Beispielhaft kommt dann:

************************************************
Using python library created by Matthew Garrett
https://github.com/mjg59/python-broadlink
************************************************
Scanning network for Broadlink devices....
Found 1 broadlink devices
...............
Device 1 Host address = '192.168.1.16', 8
Device 1 MAC address = b4 43 0d aa b3 54
...............

Für später sind die IP Adresse und die MAC Adresse wichtig. Diese müssen im zweiten bis vierten Script eingetragen werden!! Ich benutze da den Editor nano.
sudo nano ./learn-bl.sh
sudo nano ./send-bl.sh
sudo nano ./sendmore-bl.sh

Dabei die doppelten Anführungszeichen stehen lassen und an der passenden Stelle jeweils die IP und an der anderen die MAC-Adresse (mit Leerzeichen anstelle der Doppelpunkte) eintragen. Das erste Script liefert die auch so formatiert. Wenn man sie aber aus dem Router hat oder so, dann eben beachten!

Das zweite Script dient zum Anlernen des Fernbedienungscodes und Abspeichern in jeweils einer txt Datei. Das Script verbindet sich mit dem Broadlink und erwartet einen Namen für den Code. Dann hat man 5 Sec Zeit, um die entsprechende Fernbedienungstaste zu drücken, um den Code anzulernen. Dieser wird dann in eine Datei mit dem Codenamen gespeichert. So kann man alle seine zu verwendenden Codes nacheinander anlernen.

sudo ./learn-bl.sh

zeigt Folgendes an:

Connecting to Broadlink device....
Connected....
Bitte Namen für den Code eingeben, z.B. tvOff test
Wenn die LED am Broadlink angeht, innerhalb von 5 Sek die FB-Taste drücken
Hex code gespeichert unter test.txt

=== Betrieb ===

Mit dem dritten und vierten Script kann man den Code wieder senden. Auch hier wieder die eigene IP Adresse und MAC Adresse des Broadlink von oben eintragen.

Der Aufruf im Terminal ist für das dritte Skript:
sudo /opt/BroadLink/send-bl.sh /opt/BroadLink/test.txt

Wichtig ist bei diesem Skript, für das Textfile den ganzen Pfad anzugeben, und der in test.txt gelernte Befehl wird gesendet.

Aus FHEM heraus kann dann z.B. auf der Eingabezeile gesendet werden:
"/opt/BroadLink/send-bl.sh /opt/BroadLink/test.txt"
Dabei sind die " " wichtig, da es sich um einen Shell-Befehl handelt.

So kann man das dann auch in at-, notify- oder DOIFs verwenden. Hier mal ein Beispiel:

define atAbendsLichtAn at *19:00:00 "/opt/BroadLink/send-bl.sh /opt/BroadLink/FB1An.txt"

Das 4. Skript "sendmore-bl.sh" ist eine Modifikation des Send-Skripts. Die Unterschiede sind:

1. Es sendet auch mehrere Codes nacheinander, also z. B. auch Zahlenfolgen wie "0202".

2. Es nimmt an, dass die Codes als .txt-Dateien im selben Verzeichnis liegen wie das Skript.

3. Das Skript gibt keine Meldungen aus. Die sind beim Aufruf aus FHEM heraus auch unnötig.

Das Skript extrahiert aus dem Befehlsaufruf den Pfad und ergänzt ihn jeweils bei den Parametern sowie um die Dateierweiterung ".txt". Daher kann der Aufruf dann kürzer sein. Angenommen, es sind die Code-Dateien 1.txt, 2.txt, 3.txt usw. im selben Verzeichnis wie die Skripte vorhanden, lautet der Aufruf im Terminal dann z.B. nur noch:

/opt/BroadLink/sendmore-bl.sh 1 2 3 2

Im "define" lautet das oben genannte Beispiel:
define atAbendsLichtAn at *19:00:00 "/opt/BroadLink/sendmore-bl.sh FB1An"

=== Feintuning ===
Im 4. Skript definiert die Zeile (kurz vor Ende)
time.sleep(0.5)
die Wartezeit zwischen zwei gesendeten "Tasten". Bei vielen Geräten funktioniert das auch, wenn man die Zeile auskommentiert oder löscht. Dann werden die Signale schneller hintereinander gesendet.
Man kann hier natürlich auch den Wert 0.5 verändern. Einfach ausprobieren!

== Mehrere Bridges betreiben ==

Um mehrere Bridges nebeneinander zu betreiben, braucht man für jedes Gerät das dritte oder vierte Skript unter eigenem Namen, also z.B. sendmore-bl-WoZi.sh und sendmore-bl-SchlafZi.sh und sendmore-bl-Kueche.sh. In diese müssen die jeweils zugehörenden IP- und MAC-Adressen eingetragen werden. Dann entscheidet man über den Aufruf, welche Bridge den Befehl bekommt. Dabei kann man die gelernten Codes für alle Bridges nutzen und muss sie nicht für jede Bridge neu anlernen.

== Bekannte Probleme ==
Man kann mit dem dritten Skript nur einzelne Tastendrücke senden. Und der Aufruf von mehreren Befehlen nacheinander liegt so weit auseinander, dass das nicht als Folge von Befehlen ankommt, sondern jeweils als Einzelbefehle. Dafür kann man das 4. Skript ausprobieren.

Einige User berichten von diesem Fehler:
Traceback (most recent call last):
File "/opt/BroadLink/send-bl.sh", line 34, in <module>
device.send_data(myhex.decode('hex'))
File "/usr/local/lib/python2.7/dist-packages/broadlink-0.3-py2.7.egg/broadlink/__init__.py", line 455, in send_data
self.send_packet(0x6a, packet)
File "/usr/local/lib/python2.7/dist-packages/broadlink-0.3-py2.7.egg/broadlink/__init__.py", line 250, in send_packet
response = self.cs.recvfrom(1024)
socket.timeout: timed out

Abhilfe schafft, in der Datei "/usr/local/lib/python2.7/dist-packages/broadlink-0.3-py2.7.egg/broadlink/__init__.py" Zeile 249
den Timeout von 1 Sekunde auf z.B. 5 Sekunden zu stellen: self.cs.settimeout(5)

Bei der Einrichtung via Smartphone-App gibt den AP-Modus: in diesem wird im Gateway ein WLAN-AP aktiviert, '''unverschlüsselt''', mit dem sich das Smartphone dann verbindet. Über das für Sniffer offene WLAN wird dann SSID und Passwort des lokalen WLAN übermittelt, worauf sich das Gateway versucht dort anzumelden. '''''Die Einrichtung über diesen Weg legt das WLAN Passwort für Sniffer ohne weiteren Aufwand offen. Das Risiko ist auf diese eine Übertragung begrenzt.'''''

== Hinweis ==
Wenn alles funktioniert, kann man aus dem dritten Skript natürlich die Bildschirmausgaben löschen, da es ja in FHEM im Hintergrund aufgerufen wird. Umgekehrt kann man sie auch im 4. Skript wieder "freischalten", indem man die # vor den "print"-Anweisungen löscht.

Gelegentlich auftretende Fehlermeldungen (die nur im Terminal sichtbar sind), tun der Funktion (bei mir) keinen Abbruch.

[[Kategorie:Infrarot]]

Broadlink

2024-05-18T11:16:59Z

Hapege:

== Beschreibung ==
Die chinesische Firma BroadLink stellt unter Anderem auch Gateways her, die sich per Wifi ansprechen lassen und Infrator (38KHz-IR) bzw. RF (433/315 MHz-RF) Komponenten fernsteuern können (https://www.ibroadlink.com/productinfo/762672.html).

Die Gateways werden mit Hilfe einer Android- oder iOS-App ("Intelligent Home Center for EU (IHC) oder "BroadLink - Universal TV Remote") angelernt.

Danach stellen sie die Möglichkeit bereit,
* Infrarot- (und ggf. RF-) Codes bzw. Code-Sequenzen zu erfassen und via WLAN als Parameter zu übermitteln und
* (gelernte) Codes an kompatible IR- bzw. RF-Empfänger zu versenden.

Die dazugehörige openAPI ist nicht öffentlich und unterliegt einer BroadLink NDA.

Zur praktischen Verwendung gibt es mehrere Schnittstellen:
# die offizielle App (https://www.ibroadlink.com/bleapp), mit der Codes angelernt, in der App gespeichert und im lokalen WLAN über die RM versendet werden können,
# die ''[http://rm-bridge.fun2code.de/ RM Bridge]'' für Android-Geräte, die eine HTTP REST web API auf dem Androidgerät als Webservice bereitstellt,
# die ''Python-Bibliothek [https://github.com/mjg59/python-broadlink python-broadlink]'' von Matthew Garrett (mjg59) für Server, auf denen Python lauffähig ist. Diese kann dann direkt per (Shell-)Skript [https://forum.fhem.de/index.php/topic,54334.15.html aufgerufen werden] aber auch noch schön gekapselt werden:
# ''{{Link2Forum|Topic=38231|Message=581909|LinkText=Webservice für Python fähige Server}}''. In dieser Form sind dann gelernte Sendebefehle elegant als [[HTTPMOD]] Objekte in FHEM integrierbar.

=== BroadLink RM mini ===
{{Infobox Hardware
|Bild=RMmini.png
|Bildbeschreibung= BroadLink RM mini 3
|HWProtocol= Infrarot
|HWType= Gateway
|HWCategory= Infrarot
|HWComm= Infrarot 38 KHz Wifi 2.4GHz b/g/n
|HWChannels= 1
|HWVoltage= 5V
|HWPowerConsumption= max. 2,5W (max. 0,5A) standby ca. 0.85W
|HWPoweredBy= Micro USB
|HWSize= 5.5 x 5.5 x 6.45 cm
|HWDeviceFHEM= Broadlink

|HWManufacturer= [http://www.ibroadlink.com/rmMini3/ BroadLink]

}}

Der BroadLink RM mini 3 (wird nicht mehr hergestellt, evtl. noch bei Amazon / ebay erhätlich) ist ein WLAN zu Infrarot Gateway (ohne RF, vgl. [[#BroadLink RM Pro|RM Pro]]). Im Vergleich zum RM Pro ist die Sendeleistung deutlich schwächer, da nur ein IR-Transmitter verbaut ist.

 

=== BroadLink RM Pro ===
{{Infobox Hardware
|Bild=RMPro.png
|Bildbeschreibung= BroadLink RM Pro
|HWProtocol= Infrarot, RF
|HWType= Gateway
|HWCategory= Infrarot, RF
|HWComm= Infrarot 38 KHz RF 433/315 MHz Wifi 2.4GHz b/g/n
|HWChannels= 2
|HWVoltage= 5V
|HWPowerConsumption= max. 5W (max. 1A) ca. 1W standby
|HWPoweredBy= Micro USB
|HWSize= 11 x 3,5 x 11,5 cm
|HWDeviceFHEM= Broadlink

|HWManufacturer= [http://www.ibroadlink.com/rmPro/ BroadLink]

}}

Der BroadLink RM Pro/RM3 (wird nicht mehr hergestellt, evtl. noch bei Amazon / ebay erhältlich) ist ein WLAN zu Infrarot- und RF Gateway. Der aktuelle Nachfolger ist der RMpro 4 (https://www.ibroadlink.com/productinfo/762672.html).

Der RM Pro verfügt im Vergleich zum [[#BroadLink RM mini|RM mini]] über eine größere Reichweite, da 6+1 (Kreis und Mitte) IR-Transmitter verbaut sind.

(In der Version RM3 soll der unterstützte RF-Bereich inoffiziell sogar 142...1050 MHz betragen.)

Der RM Pro enthält auch einen Temperatursensor, der mindestens über die App ausgelesen und für Aktions-Regeln verwendet werden kann. Der Sensor ist offenbar nicht in allen Versionen verbaut bzw. kann oft nur als externer Sensor angeschlossen werden.

Es gab/gibt Vorgängerversionen:
* RM Home/RM1: "rote Version"; nur IR, ohne RF; schwache Sendeleistung
* RM Pro/RM2: "schwarze Version"; ID 10 002; IR und RF 433/315MHz; verstärkte IR-Sendeleistung (7 IR-Transmitter)
* (OEM Version) RM Plus: schwarz, keine Aufkleber, keine Beschriftungen, gerade, nicht abgerundete Oberseite... (soll intern baugleich mit RM Pro/RM3 sein).

 

== Nutzung in FHEM ==
=== Modul ===
'''Achtung: Das Modul wird offenbar nicht mehr gepflegt und funktioniert bei vielen Nutzern nicht bzw. (nach Rücksetzen des Gateways) nicht mehr. Empfohlen wird aktuell der Einsatz der unten genannten python Module und der dort hinterlegten Skripte.
'''

Es gibt das {{Link2CmdRef|Lang=de|Label=Modul Broadlink|Anker=Broadlink}}, mit dem Broadlink-Geräte in FHEM eingebunden werden können:
* rmpro (RM Pro)
* rmmini (RM mini)
* sp3 (SP3 - Schalter)
* sp3s (SP3S - Schalter mit aktueller Energieverbrauchsmessung)

s.a.: [https://forum.fhem.de/index.php/topic,71972.msg Forenthread]

'''Achtung: Das Modul wird offenbar nicht mehr gepflegt und funktioniert bei vielen Nutzern nicht bzw. (nach Rücksetzen des Gateways) nicht mehr. Empfohlen wird aktuell der Einsatz der unten genannten python Module und der dort hinterlegten Skripte.
'''
=== Webservice ===
Es gibt den Ansatz, [https://forum.fhem.de/index.php/topic,38231.msg581909.html#msg581909 auf dem FHEM-Server einen Webservice (pro Gateway) zu installieren] und via [[HTTPMOD]] Befehle abzusetzen.

=== Skripte ===
Auf dem FHEM-Server werden die python Module mit den integrierten Skripten installiert und nur jeweils bei Bedarf angestoßen. So wird keine permanente Systemlast produziert. Die Reaktionsgeschwindigkeit ist nicht überwältigend, aber praxistauglich. (Ca 2-3 sec).

:: '''Credits'''
::
:: Die Python-API ist von [https://github.com/mjg59/python-broadlink dieser Github-Seite].

== Hinweis ==
Mit diesem Vorgehen unterstützt das BroadLink sowohl IR als auch RF.

== Vorgehen (Skripte) ==
=== Installation ===

Zunächst wird der Broadlink mit der App ins eigene Netz eingebunden. Hierzu der Anleitung in der App folgen.

Alternativ und ohne Notwendigkeit die App zu installieren kann der Broadlink auch über die python Skripte ins WLan gebracht werden, siehe https://github.com/mjg59/python-broadlink.

Auf dem FHEM-Rechner (z.B. Raspi) muss python (python3) und am besten git installiert sein. Ggf. muss auch noch simplejson und pip installiert werden.

sudo apt-get install python git pip
sudo pip install simplejson

Verzeichnis erstellen und die Bibliothek installieren
sudo mkdir /opt/BroadLink
sudo chown fhem.dialout /opt/BroadLink
cd /opt/BroadLink
sudo git clone https://github.com/mjg59/python-broadlink.git
cd python-broadlink
sudo python setup.py install
cd ..

== Skripte ==
Die python Midule bringen eigene Skripte zum Anlernen und Senden von IR/RF commands mit. Sie liegen im Verzeichnis /opt/BroadLink/python-broadlink/cli. Die Verwendung wird hier beschrieben: https://github.com/mjg59/python-broadlink/tree/master/cli

Anleitung im Forum dazu: https://forum.fhem.de/index.php?topic=71972.msg1313044#msg1313044

'''In a nutshell:'''
Broadlink finden: <syntaxhighlight> broadlink_discovery </syntaxhighlight>
Die Daten des gefundene Gerätes in einem File speichern (siehe Shell Ausgabe), als Beispiel: <syntaxhighlight>rmpro.device</syntaxhighlight>
Command anlernen und in File speichern: <syntaxhighlight>broadlink_cli --device @rmpro.device --rflearn --learnfile TVon</syntaxhighlight>
Command senden: <syntaxhighlight>broadlink_cli --device @rmpro.device --send @TVon</syntaxhighlight>
Integration in notify/DOIF: <syntaxhighlight>{system("/opt/BroadLink/python-broadlink/cli/broadlink_cli --device \@/opt/BroadLink/python-broadlink/cli/rmpro.device --send \@/opt/BroadLink/python-broadlink/cli/TVOn")}</syntaxhighlight>

'''== Die folgenden Skripte bzw der ganze Abschnitt ist veraltet =='''

Die hier zitierten Skripte laufen nicht mehr unter python3. Sie sind auch nicht mehr erforderlich, da die python Module eigene Skripte mitbringen. Diese liegen im Verzeichnis /opt/BroadLink/python-broadlink/cli. Die Verwendung wird hier beschrieben: https://github.com/mjg59/python-broadlink/tree/master/cli

In das Verzeichnis dann noch die vier Skripte kopieren.

1. search-bl.sh
<syntaxhighlight lang="python">
#!/usr/bin/python

#Script to locate Broadlink devices on local network by Graeme Brown Dec 23 2016
#These must be set up using the Broadlink app first!

import broadlink
import time

print "************************************************"
print "Using python library created by Matthew Garrett"
print "https://github.com/mjg59/python-broadlink"
print "************************************************"
print "Scanning network for Broadlink devices...."

mydevices = broadlink.discover(timeout=5)
print "Found " + str(len(mydevices )) + " broadlink devices"
time.sleep(1)
print "..............."

for index, item in enumerate(mydevices):

mydevices[index].auth()

ipadd = mydevices[index].host
ipadd = str(ipadd)
print "Device " + str(index + 1) +" Host address = " + ipadd[1:19]
macadd = ''.join(format(x, '02x') for x in mydevices[index].mac[::-1])
macadd = str(macadd)

mymacadd = macadd[:2] + " " + macadd[2:4] + " " + macadd[4:6] + " " + macadd[6:8] + " " + macadd[8:10] + " " + macadd[10:12]
print "Device " + str(index + 1) +" MAC address = " + mymacadd
print "..............."
</syntaxhighlight>

2. learn-bl.sh
<syntaxhighlight lang="python">
#!/usr/bin/python

import broadlink
import time
import sys

device = broadlink.rm(host=("<your RM3 IP address>",80), mac=bytearray.fromhex("<your RM3 mac>"))

print "Connecting to Broadlink device...."
device.auth()
time.sleep(1)
print "Connected...."

codeName = raw_input("Bitte Namen f. den Code eingeben, z.B. tvOff ")
time.sleep(1)
print "Wenn die LED am Broadlink angeht, innerhalb von 5 Sek die FB-Taste druecken "

device.host
device.enter_learning()
time.sleep(5)
ir_packet = device.check_data()
#convert code to hex
myhex = str(ir_packet).encode('hex');

if ir_packet == None:
print "Kein Code empfangen - Ende"
sys.exit()
else:

# record learned hex code to file
f = open(codeName +".txt",'w')
f.write(myhex)
f.close()

print "Hex code gespeichert unter " + codeName + ".txt"
</syntaxhighlight>

3. send-bl.sh
<syntaxhighlight lang="python">
#!/usr/bin/python

import broadlink
import time
import sys

try:
fileName = sys.argv[1]
except IndexError:
fileName = 'null'

if fileName == 'null':
print "Error - kein Dateiname angegeben"
sys.exit()
else:

device = broadlink.rm(host=("<your RM3 IP address>",80), mac=bytearray.fromhex("<your RM3 mac>"))

print "Connecting to Broadlink device...."
device.auth()
time.sleep(1)
print "Connected...."
time.sleep(1)
device.host

file = open(fileName, 'r')

myhex = file.read()

device.send_data(myhex.decode('hex'))
print "Code Sent...."
</syntaxhighlight>

4. sendmore-bl.sh
<syntaxhighlight lang="python">
#!/usr/bin/python

import broadlink
import time
import sys

try:
fileName = sys.argv[1]
except IndexError:
fileName = 'null'

if fileName == 'null':
print "Error - kein Dateiname angegeben"
sys.exit()
else:
device = broadlink.rm(host=("<your RM3 IP address>",80), mac=bytearray.fromhex("<your RM3 mac>"))

# print "Connecting to Broadlink device...."
device.auth()
time.sleep(1)
# print "Connected...."
device.host

# Pfad aus Aufruf extrahieren und dann den Befehl selbst vom Stapel nehmen
Parameter = sys.argv
# Name des Befehls selbst
filename1 = Parameter[0]
# Gesamtlaenge
FileNameLaenge = len(filename1)
# in Bestandteile aufteilen
filearray = filename1.split("/")
# den letzten identifizieren. Das ist der eigentliche Befehl
splitNo = len(filename1.split("/"))
lastElement = filearray[splitNo-1]
# den vom Aufruf wegschneiden, um den Pfad zu bekommen
FileNameAbzug = len(lastElement)
Ende = FileNameLaenge - FileNameAbzug
Pfad = filename1[0:Ende]
# Befehl aus der Liste loeschen, damit die Parameter bleiben
Parameter.pop(0)

# repeat for each argument
for argument in Parameter:
fileName = Pfad + argument +".txt"
file = open(fileName, 'r')
myhex = file.read()
device.send_data(myhex.decode('hex'))
time.sleep(0.5)
# print "Code Sent...."
sys.exit()
</syntaxhighlight>

Dann in dem Verzeichnis noch die Dateibesitzer wechseln und die Skripte ausführbar machen:

sudo chown fhem.dialout *.sh
sudo chmod 744 *.sh

=== Konfiguration ===

Nun gilt es, die IP und MAC-Adresse des Broadlink herauszufinden. Entweder man schaut im Router nach, benutzt die Android-App FING oder das Script "search-bl.sh". Dazu

sudo ./search-bl.sh

Beispielhaft kommt dann:

************************************************
Using python library created by Matthew Garrett
https://github.com/mjg59/python-broadlink
************************************************
Scanning network for Broadlink devices....
Found 1 broadlink devices
...............
Device 1 Host address = '192.168.1.16', 8
Device 1 MAC address = b4 43 0d aa b3 54
...............

Für später sind die IP Adresse und die MAC Adresse wichtig. Diese müssen im zweiten bis vierten Script eingetragen werden!! Ich benutze da den Editor nano.
sudo nano ./learn-bl.sh
sudo nano ./send-bl.sh
sudo nano ./sendmore-bl.sh

Dabei die doppelten Anführungszeichen stehen lassen und an der passenden Stelle jeweils die IP und an der anderen die MAC-Adresse (mit Leerzeichen anstelle der Doppelpunkte) eintragen. Das erste Script liefert die auch so formatiert. Wenn man sie aber aus dem Router hat oder so, dann eben beachten!

Das zweite Script dient zum Anlernen des Fernbedienungscodes und Abspeichern in jeweils einer txt Datei. Das Script verbindet sich mit dem Broadlink und erwartet einen Namen für den Code. Dann hat man 5 Sec Zeit, um die entsprechende Fernbedienungstaste zu drücken, um den Code anzulernen. Dieser wird dann in eine Datei mit dem Codenamen gespeichert. So kann man alle seine zu verwendenden Codes nacheinander anlernen.

sudo ./learn-bl.sh

zeigt Folgendes an:

Connecting to Broadlink device....
Connected....
Bitte Namen für den Code eingeben, z.B. tvOff test
Wenn die LED am Broadlink angeht, innerhalb von 5 Sek die FB-Taste drücken
Hex code gespeichert unter test.txt

=== Betrieb ===

Mit dem dritten und vierten Script kann man den Code wieder senden. Auch hier wieder die eigene IP Adresse und MAC Adresse des Broadlink von oben eintragen.

Der Aufruf im Terminal ist für das dritte Skript:
sudo /opt/BroadLink/send-bl.sh /opt/BroadLink/test.txt

Wichtig ist bei diesem Skript, für das Textfile den ganzen Pfad anzugeben, und der in test.txt gelernte Befehl wird gesendet.

Aus FHEM heraus kann dann z.B. auf der Eingabezeile gesendet werden:
"/opt/BroadLink/send-bl.sh /opt/BroadLink/test.txt"
Dabei sind die " " wichtig, da es sich um einen Shell-Befehl handelt.

So kann man das dann auch in at-, notify- oder DOIFs verwenden. Hier mal ein Beispiel:

define atAbendsLichtAn at *19:00:00 "/opt/BroadLink/send-bl.sh /opt/BroadLink/FB1An.txt"

Das 4. Skript "sendmore-bl.sh" ist eine Modifikation des Send-Skripts. Die Unterschiede sind:

1. Es sendet auch mehrere Codes nacheinander, also z. B. auch Zahlenfolgen wie "0202".

2. Es nimmt an, dass die Codes als .txt-Dateien im selben Verzeichnis liegen wie das Skript.

3. Das Skript gibt keine Meldungen aus. Die sind beim Aufruf aus FHEM heraus auch unnötig.

Das Skript extrahiert aus dem Befehlsaufruf den Pfad und ergänzt ihn jeweils bei den Parametern sowie um die Dateierweiterung ".txt". Daher kann der Aufruf dann kürzer sein. Angenommen, es sind die Code-Dateien 1.txt, 2.txt, 3.txt usw. im selben Verzeichnis wie die Skripte vorhanden, lautet der Aufruf im Terminal dann z.B. nur noch:

/opt/BroadLink/sendmore-bl.sh 1 2 3 2

Im "define" lautet das oben genannte Beispiel:
define atAbendsLichtAn at *19:00:00 "/opt/BroadLink/sendmore-bl.sh FB1An"

=== Feintuning ===
Im 4. Skript definiert die Zeile (kurz vor Ende)
time.sleep(0.5)
die Wartezeit zwischen zwei gesendeten "Tasten". Bei vielen Geräten funktioniert das auch, wenn man die Zeile auskommentiert oder löscht. Dann werden die Signale schneller hintereinander gesendet.
Man kann hier natürlich auch den Wert 0.5 verändern. Einfach ausprobieren!

== Mehrere Bridges betreiben ==

Um mehrere Bridges nebeneinander zu betreiben, braucht man für jedes Gerät das dritte oder vierte Skript unter eigenem Namen, also z.B. sendmore-bl-WoZi.sh und sendmore-bl-SchlafZi.sh und sendmore-bl-Kueche.sh. In diese müssen die jeweils zugehörenden IP- und MAC-Adressen eingetragen werden. Dann entscheidet man über den Aufruf, welche Bridge den Befehl bekommt. Dabei kann man die gelernten Codes für alle Bridges nutzen und muss sie nicht für jede Bridge neu anlernen.

== Bekannte Probleme ==
Man kann mit dem dritten Skript nur einzelne Tastendrücke senden. Und der Aufruf von mehreren Befehlen nacheinander liegt so weit auseinander, dass das nicht als Folge von Befehlen ankommt, sondern jeweils als Einzelbefehle. Dafür kann man das 4. Skript ausprobieren.

Einige User berichten von diesem Fehler:
Traceback (most recent call last):
File "/opt/BroadLink/send-bl.sh", line 34, in <module>
device.send_data(myhex.decode('hex'))
File "/usr/local/lib/python2.7/dist-packages/broadlink-0.3-py2.7.egg/broadlink/__init__.py", line 455, in send_data
self.send_packet(0x6a, packet)
File "/usr/local/lib/python2.7/dist-packages/broadlink-0.3-py2.7.egg/broadlink/__init__.py", line 250, in send_packet
response = self.cs.recvfrom(1024)
socket.timeout: timed out

Abhilfe schafft, in der Datei "/usr/local/lib/python2.7/dist-packages/broadlink-0.3-py2.7.egg/broadlink/__init__.py" Zeile 249
den Timeout von 1 Sekunde auf z.B. 5 Sekunden zu stellen: self.cs.settimeout(5)

Bei der Einrichtung via Smartphone-App gibt den AP-Modus: in diesem wird im Gateway ein WLAN-AP aktiviert, '''unverschlüsselt''', mit dem sich das Smartphone dann verbindet. Über das für Sniffer offene WLAN wird dann SSID und Passwort des lokalen WLAN übermittelt, worauf sich das Gateway versucht dort anzumelden. '''''Die Einrichtung über diesen Weg legt das WLAN Passwort für Sniffer ohne weiteren Aufwand offen. Das Risiko ist auf diese eine Übertragung begrenzt.'''''

== Hinweis ==
Wenn alles funktioniert, kann man aus dem dritten Skript natürlich die Bildschirmausgaben löschen, da es ja in FHEM im Hintergrund aufgerufen wird. Umgekehrt kann man sie auch im 4. Skript wieder "freischalten", indem man die # vor den "print"-Anweisungen löscht.

Gelegentlich auftretende Fehlermeldungen (die nur im Terminal sichtbar sind), tun der Funktion (bei mir) keinen Abbruch.

[[Kategorie:Infrarot]]

Broadlink

2024-05-18T11:16:24Z

Hapege:

== Beschreibung ==
Die chinesische Firma BroadLink stellt unter Anderem auch Gateways her, die sich per Wifi ansprechen lassen und Infrator (38KHz-IR) bzw. RF (433/315 MHz-RF) Komponenten fernsteuern können (https://www.ibroadlink.com/productinfo/762672.html).

Die Gateways werden mit Hilfe einer Android- oder iOS-App ("Intelligent Home Center for EU (IHC) oder "BroadLink - Universal TV Remote") angelernt.

Danach stellen sie die Möglichkeit bereit,
* Infrarot- (und ggf. RF-) Codes bzw. Code-Sequenzen zu erfassen und via WLAN als Parameter zu übermitteln und
* (gelernte) Codes an kompatible IR- bzw. RF-Empfänger zu versenden.

Die dazugehörige openAPI ist nicht öffentlich und unterliegt einer BroadLink NDA.

Zur praktischen Verwendung gibt es mehrere Schnittstellen:
# die offizielle App (https://www.ibroadlink.com/bleapp), mit der Codes angelernt, in der App gespeichert und im lokalen WLAN über die RM versendet werden können,
# die ''[http://rm-bridge.fun2code.de/ RM Bridge]'' für Android-Geräte, die eine HTTP REST web API auf dem Androidgerät als Webservice bereitstellt,
# die ''Python-Bibliothek [https://github.com/mjg59/python-broadlink python-broadlink]'' von Matthew Garrett (mjg59) für Server, auf denen Python lauffähig ist. Diese kann dann direkt per (Shell-)Skript [https://forum.fhem.de/index.php/topic,54334.15.html aufgerufen werden] aber auch noch schön gekapselt werden:
# ''{{Link2Forum|Topic=38231|Message=581909|LinkText=Webservice für Python fähige Server}}''. In dieser Form sind dann gelernte Sendebefehle elegant als [[HTTPMOD]] Objekte in FHEM integrierbar.

=== BroadLink RM mini ===
{{Infobox Hardware
|Bild=RMmini.png
|Bildbeschreibung= BroadLink RM mini 3
|HWProtocol= Infrarot
|HWType= Gateway
|HWCategory= Infrarot
|HWComm= Infrarot 38 KHz Wifi 2.4GHz b/g/n
|HWChannels= 1
|HWVoltage= 5V
|HWPowerConsumption= max. 2,5W (max. 0,5A) standby ca. 0.85W
|HWPoweredBy= Micro USB
|HWSize= 5.5 x 5.5 x 6.45 cm
|HWDeviceFHEM= Broadlink

|HWManufacturer= [http://www.ibroadlink.com/rmMini3/ BroadLink]

}}

Der BroadLink RM mini 3 (wird nicht mehr hergestellt, evtl. noch bei Amazon / ebay erhätlich) ist ein WLAN zu Infrarot Gateway (ohne RF, vgl. [[#BroadLink RM Pro|RM Pro]]). Im Vergleich zum RM Pro ist die Sendeleistung deutlich schwächer, da nur ein IR-Transmitter verbaut ist.

 

=== BroadLink RM Pro ===
{{Infobox Hardware
|Bild=RMPro.png
|Bildbeschreibung= BroadLink RM Pro
|HWProtocol= Infrarot, RF
|HWType= Gateway
|HWCategory= Infrarot, RF
|HWComm= Infrarot 38 KHz RF 433/315 MHz Wifi 2.4GHz b/g/n
|HWChannels= 2
|HWVoltage= 5V
|HWPowerConsumption= max. 5W (max. 1A) ca. 1W standby
|HWPoweredBy= Micro USB
|HWSize= 11 x 3,5 x 11,5 cm
|HWDeviceFHEM= Broadlink

|HWManufacturer= [http://www.ibroadlink.com/rmPro/ BroadLink]

}}

Der BroadLink RM Pro/RM3 (wird nicht mehr hergestellt, evtl. noch bei Amazon / ebay erhältlich) ist ein WLAN zu Infrarot- und RF Gateway. Der aktuelle Nachfolger ist der RMpro 4 (https://www.ibroadlink.com/productinfo/762672.html).

Der RM Pro verfügt im Vergleich zum [[#BroadLink RM mini|RM mini]] über eine größere Reichweite, da 6+1 (Kreis und Mitte) IR-Transmitter verbaut sind.

(In der Version RM3 soll der unterstützte RF-Bereich inoffiziell sogar 142...1050 MHz betragen.)

Der RM Pro enthält auch einen Temperatursensor, der mindestens über die App ausgelesen und für Aktions-Regeln verwendet werden kann. Der Sensor ist offenbar nicht in allen Versionen verbaut bzw. kann oft nur als externer Sensor angeschlossen werden.

Es gab/gibt Vorgängerversionen:
* RM Home/RM1: "rote Version"; nur IR, ohne RF; schwache Sendeleistung
* RM Pro/RM2: "schwarze Version"; ID 10 002; IR und RF 433/315MHz; verstärkte IR-Sendeleistung (7 IR-Transmitter)
* (OEM Version) RM Plus: schwarz, keine Aufkleber, keine Beschriftungen, gerade, nicht abgerundete Oberseite... (soll intern baugleich mit RM Pro/RM3 sein).

 

== Nutzung in FHEM ==
=== Modul ===
Es gibt das {{Link2CmdRef|Lang=de|Label=Modul Broadlink|Anker=Broadlink}}, mit dem Broadlink-Geräte in FHEM eingebunden werden können:
* rmpro (RM Pro)
* rmmini (RM mini)
* sp3 (SP3 - Schalter)
* sp3s (SP3S - Schalter mit aktueller Energieverbrauchsmessung)

s.a.: [https://forum.fhem.de/index.php/topic,71972.msg Forenthread]

'''Achtung: Das Modul wird offenbar nicht mehr gepflegt und funktioniert bei vielen Nutzern nicht bzw. (nach Rücksetzen des Gateways) nicht mehr. Empfohlen wird aktuell der Einsatz der unten genannten python Module und der dort hinterlegten Skripte.
'''
=== Webservice ===
Es gibt den Ansatz, [https://forum.fhem.de/index.php/topic,38231.msg581909.html#msg581909 auf dem FHEM-Server einen Webservice (pro Gateway) zu installieren] und via [[HTTPMOD]] Befehle abzusetzen.

=== Skripte ===
Auf dem FHEM-Server werden die python Module mit den integrierten Skripten installiert und nur jeweils bei Bedarf angestoßen. So wird keine permanente Systemlast produziert. Die Reaktionsgeschwindigkeit ist nicht überwältigend, aber praxistauglich. (Ca 2-3 sec).

:: '''Credits'''
::
:: Die Python-API ist von [https://github.com/mjg59/python-broadlink dieser Github-Seite].

== Hinweis ==
Mit diesem Vorgehen unterstützt das BroadLink sowohl IR als auch RF.

== Vorgehen (Skripte) ==
=== Installation ===

Zunächst wird der Broadlink mit der App ins eigene Netz eingebunden. Hierzu der Anleitung in der App folgen.

Alternativ und ohne Notwendigkeit die App zu installieren kann der Broadlink auch über die python Skripte ins WLan gebracht werden, siehe https://github.com/mjg59/python-broadlink.

Auf dem FHEM-Rechner (z.B. Raspi) muss python (python3) und am besten git installiert sein. Ggf. muss auch noch simplejson und pip installiert werden.

sudo apt-get install python git pip
sudo pip install simplejson

Verzeichnis erstellen und die Bibliothek installieren
sudo mkdir /opt/BroadLink
sudo chown fhem.dialout /opt/BroadLink
cd /opt/BroadLink
sudo git clone https://github.com/mjg59/python-broadlink.git
cd python-broadlink
sudo python setup.py install
cd ..

== Skripte ==
Die python Midule bringen eigene Skripte zum Anlernen und Senden von IR/RF commands mit. Sie liegen im Verzeichnis /opt/BroadLink/python-broadlink/cli. Die Verwendung wird hier beschrieben: https://github.com/mjg59/python-broadlink/tree/master/cli

Anleitung im Forum dazu: https://forum.fhem.de/index.php?topic=71972.msg1313044#msg1313044

'''In a nutshell:'''
Broadlink finden: <syntaxhighlight> broadlink_discovery </syntaxhighlight>
Die Daten des gefundene Gerätes in einem File speichern (siehe Shell Ausgabe), als Beispiel: <syntaxhighlight>rmpro.device</syntaxhighlight>
Command anlernen und in File speichern: <syntaxhighlight>broadlink_cli --device @rmpro.device --rflearn --learnfile TVon</syntaxhighlight>
Command senden: <syntaxhighlight>broadlink_cli --device @rmpro.device --send @TVon</syntaxhighlight>
Integration in notify/DOIF: <syntaxhighlight>{system("/opt/BroadLink/python-broadlink/cli/broadlink_cli --device \@/opt/BroadLink/python-broadlink/cli/rmpro.device --send \@/opt/BroadLink/python-broadlink/cli/TVOn")}</syntaxhighlight>

'''== Die folgenden Skripte bzw der ganze Abschnitt ist veraltet =='''

Die hier zitierten Skripte laufen nicht mehr unter python3. Sie sind auch nicht mehr erforderlich, da die python Module eigene Skripte mitbringen. Diese liegen im Verzeichnis /opt/BroadLink/python-broadlink/cli. Die Verwendung wird hier beschrieben: https://github.com/mjg59/python-broadlink/tree/master/cli

In das Verzeichnis dann noch die vier Skripte kopieren.

1. search-bl.sh
<syntaxhighlight lang="python">
#!/usr/bin/python

#Script to locate Broadlink devices on local network by Graeme Brown Dec 23 2016
#These must be set up using the Broadlink app first!

import broadlink
import time

print "************************************************"
print "Using python library created by Matthew Garrett"
print "https://github.com/mjg59/python-broadlink"
print "************************************************"
print "Scanning network for Broadlink devices...."

mydevices = broadlink.discover(timeout=5)
print "Found " + str(len(mydevices )) + " broadlink devices"
time.sleep(1)
print "..............."

for index, item in enumerate(mydevices):

mydevices[index].auth()

ipadd = mydevices[index].host
ipadd = str(ipadd)
print "Device " + str(index + 1) +" Host address = " + ipadd[1:19]
macadd = ''.join(format(x, '02x') for x in mydevices[index].mac[::-1])
macadd = str(macadd)

mymacadd = macadd[:2] + " " + macadd[2:4] + " " + macadd[4:6] + " " + macadd[6:8] + " " + macadd[8:10] + " " + macadd[10:12]
print "Device " + str(index + 1) +" MAC address = " + mymacadd
print "..............."
</syntaxhighlight>

2. learn-bl.sh
<syntaxhighlight lang="python">
#!/usr/bin/python

import broadlink
import time
import sys

device = broadlink.rm(host=("<your RM3 IP address>",80), mac=bytearray.fromhex("<your RM3 mac>"))

print "Connecting to Broadlink device...."
device.auth()
time.sleep(1)
print "Connected...."

codeName = raw_input("Bitte Namen f. den Code eingeben, z.B. tvOff ")
time.sleep(1)
print "Wenn die LED am Broadlink angeht, innerhalb von 5 Sek die FB-Taste druecken "

device.host
device.enter_learning()
time.sleep(5)
ir_packet = device.check_data()
#convert code to hex
myhex = str(ir_packet).encode('hex');

if ir_packet == None:
print "Kein Code empfangen - Ende"
sys.exit()
else:

# record learned hex code to file
f = open(codeName +".txt",'w')
f.write(myhex)
f.close()

print "Hex code gespeichert unter " + codeName + ".txt"
</syntaxhighlight>

3. send-bl.sh
<syntaxhighlight lang="python">
#!/usr/bin/python

import broadlink
import time
import sys

try:
fileName = sys.argv[1]
except IndexError:
fileName = 'null'

if fileName == 'null':
print "Error - kein Dateiname angegeben"
sys.exit()
else:

device = broadlink.rm(host=("<your RM3 IP address>",80), mac=bytearray.fromhex("<your RM3 mac>"))

print "Connecting to Broadlink device...."
device.auth()
time.sleep(1)
print "Connected...."
time.sleep(1)
device.host

file = open(fileName, 'r')

myhex = file.read()

device.send_data(myhex.decode('hex'))
print "Code Sent...."
</syntaxhighlight>

4. sendmore-bl.sh
<syntaxhighlight lang="python">
#!/usr/bin/python

import broadlink
import time
import sys

try:
fileName = sys.argv[1]
except IndexError:
fileName = 'null'

if fileName == 'null':
print "Error - kein Dateiname angegeben"
sys.exit()
else:
device = broadlink.rm(host=("<your RM3 IP address>",80), mac=bytearray.fromhex("<your RM3 mac>"))

# print "Connecting to Broadlink device...."
device.auth()
time.sleep(1)
# print "Connected...."
device.host

# Pfad aus Aufruf extrahieren und dann den Befehl selbst vom Stapel nehmen
Parameter = sys.argv
# Name des Befehls selbst
filename1 = Parameter[0]
# Gesamtlaenge
FileNameLaenge = len(filename1)
# in Bestandteile aufteilen
filearray = filename1.split("/")
# den letzten identifizieren. Das ist der eigentliche Befehl
splitNo = len(filename1.split("/"))
lastElement = filearray[splitNo-1]
# den vom Aufruf wegschneiden, um den Pfad zu bekommen
FileNameAbzug = len(lastElement)
Ende = FileNameLaenge - FileNameAbzug
Pfad = filename1[0:Ende]
# Befehl aus der Liste loeschen, damit die Parameter bleiben
Parameter.pop(0)

# repeat for each argument
for argument in Parameter:
fileName = Pfad + argument +".txt"
file = open(fileName, 'r')
myhex = file.read()
device.send_data(myhex.decode('hex'))
time.sleep(0.5)
# print "Code Sent...."
sys.exit()
</syntaxhighlight>

Dann in dem Verzeichnis noch die Dateibesitzer wechseln und die Skripte ausführbar machen:

sudo chown fhem.dialout *.sh
sudo chmod 744 *.sh

=== Konfiguration ===

Nun gilt es, die IP und MAC-Adresse des Broadlink herauszufinden. Entweder man schaut im Router nach, benutzt die Android-App FING oder das Script "search-bl.sh". Dazu

sudo ./search-bl.sh

Beispielhaft kommt dann:

************************************************
Using python library created by Matthew Garrett
https://github.com/mjg59/python-broadlink
************************************************
Scanning network for Broadlink devices....
Found 1 broadlink devices
...............
Device 1 Host address = '192.168.1.16', 8
Device 1 MAC address = b4 43 0d aa b3 54
...............

Für später sind die IP Adresse und die MAC Adresse wichtig. Diese müssen im zweiten bis vierten Script eingetragen werden!! Ich benutze da den Editor nano.
sudo nano ./learn-bl.sh
sudo nano ./send-bl.sh
sudo nano ./sendmore-bl.sh

Dabei die doppelten Anführungszeichen stehen lassen und an der passenden Stelle jeweils die IP und an der anderen die MAC-Adresse (mit Leerzeichen anstelle der Doppelpunkte) eintragen. Das erste Script liefert die auch so formatiert. Wenn man sie aber aus dem Router hat oder so, dann eben beachten!

Das zweite Script dient zum Anlernen des Fernbedienungscodes und Abspeichern in jeweils einer txt Datei. Das Script verbindet sich mit dem Broadlink und erwartet einen Namen für den Code. Dann hat man 5 Sec Zeit, um die entsprechende Fernbedienungstaste zu drücken, um den Code anzulernen. Dieser wird dann in eine Datei mit dem Codenamen gespeichert. So kann man alle seine zu verwendenden Codes nacheinander anlernen.

sudo ./learn-bl.sh

zeigt Folgendes an:

Connecting to Broadlink device....
Connected....
Bitte Namen für den Code eingeben, z.B. tvOff test
Wenn die LED am Broadlink angeht, innerhalb von 5 Sek die FB-Taste drücken
Hex code gespeichert unter test.txt

=== Betrieb ===

Mit dem dritten und vierten Script kann man den Code wieder senden. Auch hier wieder die eigene IP Adresse und MAC Adresse des Broadlink von oben eintragen.

Der Aufruf im Terminal ist für das dritte Skript:
sudo /opt/BroadLink/send-bl.sh /opt/BroadLink/test.txt

Wichtig ist bei diesem Skript, für das Textfile den ganzen Pfad anzugeben, und der in test.txt gelernte Befehl wird gesendet.

Aus FHEM heraus kann dann z.B. auf der Eingabezeile gesendet werden:
"/opt/BroadLink/send-bl.sh /opt/BroadLink/test.txt"
Dabei sind die " " wichtig, da es sich um einen Shell-Befehl handelt.

So kann man das dann auch in at-, notify- oder DOIFs verwenden. Hier mal ein Beispiel:

define atAbendsLichtAn at *19:00:00 "/opt/BroadLink/send-bl.sh /opt/BroadLink/FB1An.txt"

Das 4. Skript "sendmore-bl.sh" ist eine Modifikation des Send-Skripts. Die Unterschiede sind:

1. Es sendet auch mehrere Codes nacheinander, also z. B. auch Zahlenfolgen wie "0202".

2. Es nimmt an, dass die Codes als .txt-Dateien im selben Verzeichnis liegen wie das Skript.

3. Das Skript gibt keine Meldungen aus. Die sind beim Aufruf aus FHEM heraus auch unnötig.

Das Skript extrahiert aus dem Befehlsaufruf den Pfad und ergänzt ihn jeweils bei den Parametern sowie um die Dateierweiterung ".txt". Daher kann der Aufruf dann kürzer sein. Angenommen, es sind die Code-Dateien 1.txt, 2.txt, 3.txt usw. im selben Verzeichnis wie die Skripte vorhanden, lautet der Aufruf im Terminal dann z.B. nur noch:

/opt/BroadLink/sendmore-bl.sh 1 2 3 2

Im "define" lautet das oben genannte Beispiel:
define atAbendsLichtAn at *19:00:00 "/opt/BroadLink/sendmore-bl.sh FB1An"

=== Feintuning ===
Im 4. Skript definiert die Zeile (kurz vor Ende)
time.sleep(0.5)
die Wartezeit zwischen zwei gesendeten "Tasten". Bei vielen Geräten funktioniert das auch, wenn man die Zeile auskommentiert oder löscht. Dann werden die Signale schneller hintereinander gesendet.
Man kann hier natürlich auch den Wert 0.5 verändern. Einfach ausprobieren!

== Mehrere Bridges betreiben ==

Um mehrere Bridges nebeneinander zu betreiben, braucht man für jedes Gerät das dritte oder vierte Skript unter eigenem Namen, also z.B. sendmore-bl-WoZi.sh und sendmore-bl-SchlafZi.sh und sendmore-bl-Kueche.sh. In diese müssen die jeweils zugehörenden IP- und MAC-Adressen eingetragen werden. Dann entscheidet man über den Aufruf, welche Bridge den Befehl bekommt. Dabei kann man die gelernten Codes für alle Bridges nutzen und muss sie nicht für jede Bridge neu anlernen.

== Bekannte Probleme ==
Man kann mit dem dritten Skript nur einzelne Tastendrücke senden. Und der Aufruf von mehreren Befehlen nacheinander liegt so weit auseinander, dass das nicht als Folge von Befehlen ankommt, sondern jeweils als Einzelbefehle. Dafür kann man das 4. Skript ausprobieren.

Einige User berichten von diesem Fehler:
Traceback (most recent call last):
File "/opt/BroadLink/send-bl.sh", line 34, in <module>
device.send_data(myhex.decode('hex'))
File "/usr/local/lib/python2.7/dist-packages/broadlink-0.3-py2.7.egg/broadlink/__init__.py", line 455, in send_data
self.send_packet(0x6a, packet)
File "/usr/local/lib/python2.7/dist-packages/broadlink-0.3-py2.7.egg/broadlink/__init__.py", line 250, in send_packet
response = self.cs.recvfrom(1024)
socket.timeout: timed out

Abhilfe schafft, in der Datei "/usr/local/lib/python2.7/dist-packages/broadlink-0.3-py2.7.egg/broadlink/__init__.py" Zeile 249
den Timeout von 1 Sekunde auf z.B. 5 Sekunden zu stellen: self.cs.settimeout(5)

Bei der Einrichtung via Smartphone-App gibt den AP-Modus: in diesem wird im Gateway ein WLAN-AP aktiviert, '''unverschlüsselt''', mit dem sich das Smartphone dann verbindet. Über das für Sniffer offene WLAN wird dann SSID und Passwort des lokalen WLAN übermittelt, worauf sich das Gateway versucht dort anzumelden. '''''Die Einrichtung über diesen Weg legt das WLAN Passwort für Sniffer ohne weiteren Aufwand offen. Das Risiko ist auf diese eine Übertragung begrenzt.'''''

== Hinweis ==
Wenn alles funktioniert, kann man aus dem dritten Skript natürlich die Bildschirmausgaben löschen, da es ja in FHEM im Hintergrund aufgerufen wird. Umgekehrt kann man sie auch im 4. Skript wieder "freischalten", indem man die # vor den "print"-Anweisungen löscht.

Gelegentlich auftretende Fehlermeldungen (die nur im Terminal sichtbar sind), tun der Funktion (bei mir) keinen Abbruch.

[[Kategorie:Infrarot]]