Version History...

Hinweis: Die im Video gezeigte Authentifizierungsmethode über 2-Faktor-Verifizierung funktioniert nicht mehr und wurde durch die Refresh-Token-Methode ersetzt.

In Absprache mit Peter, aktualisiert und überarbeitet für LoxBerry 2.0 von Christian Fenzl

Informationen/Syntax zur Vorgängerversion (<4.0) im bisherigen Wiki-Artikel: Alexa2Lox 3.0 (EOL)

• Die Aufrufssyntax ist NICHT kompatibel zu allen Vorgängerversionen kleiner V4.0.
• Das Plugin installiert sich neben Alexa2Lox V2.x/V3.x als neues Plugin - das alte Plugin bleibt installiert und kann weiter verwendet werden, bis man auf diese Version umgestellt hat.
• Das Plugin testen wir grundsätzlich nur mit der aktuellsten LoxBerry-Version (LoxBerry V3.x). Aktuell sind aber keine Features enthalten, die ausschließlich mit LB3.0 funktionieren würden. Es sollte daher mit LoxBerry V1.4.3 oder LoxBerry V2.2.2 ebenso funktionieren. Versionen unter LB 1.4.3 sollten aber nicht eingesetzt werden.

Repository: https://github.com/christianTF/LoxBerry-Plugin-Alexa2Lox

Master-Download: https://github.com/christianTF/LoxBerry-Plugin-Alexa2Lox/archive/master.zip

Dieses Plugin ermöglicht NICHT, den Loxone Miniserver per Spracheingabe zu steuern. Dieses Plugin ermöglicht: Steuerung von Alexa per Miniserver (Musiksteuerung, Playlisten, Routinen aufrufen), Sprachausgabe via Alexa, Listen von Alexa am Miniserver anzeigen usw.

• Sämtliche Datenübertragungen von Alexa an Loxone erfolgen ausschließlich per MQTT. Es muss auf diesem Loxberry das MQTT Gateway installiert sein. (Profitipp: Dort kann auch ein externer Broker angegeben sein.)
• Der Abruf von Informationen wird immer per Virtuellem Ausgang in Loxone getriggert. Das Plugin sendet von sich aus (z.B. auf Zeitbasis) keine Daten.
• Wie üblich unterdrückt das MQTT Gateway die Übertragung von Daten, die sich nicht geändert haben. Damit Daten an Loxone übermittelt werden, muss sich bei den Werten etwas ändern.

1. Installation des Plugin MQTT Gateway. Sollte dieses bereits auf dem Loxberry installiert sein oder nutzt ihr LoxBerry V3.0, kann dieser Punkt übersprungen werden.
2. Installation des Plugins über die Plugin Verwaltung.
3. LB 1.x: Nach der Installation von Alexa2Lox muss im MQTT Gateway Plugin auf "Restart" gedrückt werden, damit die neue Subscription und die Conversions übernommen werden.
4. LB 2.x/3.x: Das MQTT Gateway erhält von LoxBerry 2.x automatisch die Information über die Plugin-Installation, deswegen werden Subscription und Conversions automatisch übernommen.

Refresh Token Methode

Mittels der Refresh Token Methode wird ein Token erzeugt, der Alexa2Lox ermöglcht, sich bei Amazon mit deinem Amazon-Account anzumelden.

Eine Anleitung, wie Du diesen Token erzeugen musst, findest Du hier: Amazon Refresh-Token erzeugen

Listen-Trennzeichen: Das Plugin erstellt für verschiedene Listen (To-Do-Liste, Einkaufsliste usw.) aus den einzelnen Einträgen einen zusammengefassten Text, um ihn in der Loxone-Visualisierung in einem Block darzustellen. Als Trennzeichen wird das hier konfigurierte Zeichen verwendet. Du kannst alles verwenden, hier ein paar Beispiele (kannst du mit Copy/Paste übernehmen): | • - – ? ? ? ? ? ◊  ? ? ? ?? Du musst selbst probieren, wie das dann in Loxone aussieht. Das Trennzeichen kann auch eine Trenn-Zeichenkette sein! (z.B. ??)

Speichern nicht vergessen!

Nach dem Speichern der Einstellungen werden von deinem Amazon-Konto die verfügbaren Alexa Geräte geladen. Diese werden im Bereich "Gefundene Geräte" angezeigt. Dies sollte in etwa so aussehen:

Sollten keine Geräte angezeigt werden, bitte wie folgt vorgehen:

1. Die Seite des Plugins im Browser neu laden.
2. Überprüfen der Amazon Zugangsdaten - Schaut ins Logfile, ob es dort Hinweise gibt!
3. Überprüfen, ob die Geräte im Amazon Konto aufgelistet sind. 
   1. Alexa App öffnen
   2. Unter Einstellungen → Geräte prüfen, ob das gesuchte Gerät in der Liste steht. Wenn nicht, den Anweisungen zum hinzufügen von Geräten auf der Amazon Seite folgen.
4. Die Seite des Plugins im Browser neu laden.

Alexa Remote Control aktualisieren: Das Plugin basiert zum Großteil auf Erkenntnisse und Funktionen des "Lötzimmer Alexa"-Scripts, das von Alexander Noack gepflegt wird. Das Plugin zeigt an, welche Version gerade auf deinem LoxBerry installiert ist, außerdem kannst du auf den letzten Stand aktualisieren. Beachte: Bei Entwicklungen/Korrekturen in Beta-Version (z.B. 0.15b) ändert sich nicht zwangsläufig die Versionsnummer, obwohl ein neuer Stand installiert wurde.

Dieser Bereich ist bereits unter Konfiguration beschrieben.

Hier werden alle Geräte und deren Online-Status angezeigt. Beachte, dass die Geräteliste zwischengespeichert wird, deswegen könnte insbesondere der Online-Status nicht aktuell sein.

Alexa2Lox überträgt alle Daten per MQTT. Dafür muss das MQTT Gateway Plugin installiert sein. Es ist in Alexa2Lox keine weitere Konfiguration notwendig - alles weitere macht das Plugin. Im MQTT Gateway musst du die Übertragungsweise konfigurieren. Bitte schau in die Anleitung des MQTT Gateway Plugins. 

Das Basis-Topic von Alexa2Lox ist alexa2lox/#. Diese Subscription sowie notwendige Conversions werden vom Alexa2Lox Plugin direkt im MQTT Gateway gesetzt.

Sämtliche Funktionen müssen von Loxone aus getriggert werden. Als Vorbereitung für alle weiteren Anleitungen wird ein Virtueller Ausgang benötigt.

Die Antwort des Abrufs wird immer per MQTT übertragen. Öffne zum Prüfen der Daten die Incoming Overview im MQTT Gateway Plugin. Bitte folge der Anleitung des MQTT Gateway Plugins, wie du diese Daten in den Loxone Miniserver bekommst.

Adresse: http://<user>:<pass>@loxberry

<user> und <pass> sind die Anmeldedaten bei LoxBerry. Solltest du den LoxBerry umbenannt haben, oder lieber die IP-Adresse verwenden, musst du den Hostnamen loxberry entsprechend anpassen.

Allgemeiner Aufruf: /admin/plugins/alexa2lox/alexa.php?parameter1&parameter2=value&parameter3 usw.

Parameter können als Übergabe eines Wertes dienen (parameter2=value), oder als Schalter ohne zusätzlichem Wert (parameter1). Die Reihenfolge der Parameter ist beliebig, außer bei original (siehe unten).

Die Parameter werden in einer Kette abgearbeitet. Das heißt, wird als Parameter übergeben todolist&shoppinglist, werden beide Funktionen ausgeführt. 

Befehl bei EIN: /admin/plugins/alexa2lox/alexa.php?device=Büro&playerstate

Kurzversion: /admin/plugins/alexa2lox/alexa.php?d=Büro&ps

Befehl bei EIN: /admin/plugins/alexa2lox/alexa.php?notifications

Befehl bei EIN: /admin/plugins/alexa2lox/alexa.php?shoppinglist

Befehl bei EIN: /admin/plugins/alexa2lox/alexa.php?todolist

Mit dem Parameter execute (bzw. Kurzversion e) können Befehle an Alexa übergeben werden. Die möglichen Befehle sind äquivalent zu jenen vom Lötzimmer-Script (konkret wird in der Routine das Original-Script alexa_remote_control.sh aufgerufen). Werden also im Originalscript neue Befehle aufgenommen, funktionieren diese auch automatisch mit dem execute-Kommando.

Die execute-Routine von Alexa2Lox ruft nach dem Aufruf zusätzlich den aktuellen playerstate ab.

pause | play | next | prev | fwd | rwd | shuffle | repeat | vol:<0-100>

weather | traffic | flashbriefing | goodmorning | singasong | tellstory | speak:'<text/ssml>' | automation:'<routine name>' | sound:<soundeffect_name> | textcommand:'<anything you would otherwise say to Alexa>' | playmusic:<channel> e.g. TUNEIN, AMAZON_MUSIC>:'<music name>'

Hier findet ihr den aktuellsten Stand: https://github.com/thorsten-gehrig/alexa-remote-control

Player starten, pausieren, Lautstärke

Befehl bei EIN: /admin/plugins/alexa2lox/alexa.php?device=Wohnzimmer&execute=play

Befehl bei EIN: /admin/plugins/alexa2lox/alexa.php?device=Wohnzimmer&execute=pause

Befehl bei EIN: /admin/plugins/alexa2lox/alexa.php?device=Wohnzimmer&execute=vol:50

Befehl bei EIN: /admin/plugins/alexa2lox/tts.php?device=<Gerätename>&text=<Mein Text>&vol=<1...100>

Kurze Variante: /admin/plugins/alexa2lox/tts.php?d=<Gerätename>&t=<Mein Text>&vol=<1...100>

Die Reihenfolge der Parameter ist beliebig.

Bei der Angabe mehrerer Geräte oder ALL wird versucht, die Sprachausgabe gleichzeitig auszuführen. Es ist deswegen aber keinesfalls syncron, sondern um ca. eine halbe Sekunde versetzt. 

Text- und Zeichenersetzung

Es werden automatisch folgende Zeichenketten umgewandelt, damit sie richtig ausgesprochen werden:

• °C → Grad
• ° → Grad

Vorschläge für weitere Ersetzungen bitte mit Satzbeispiel benennen.

MQTT-Übertragung

Der Text der Sprachausgabe und die Zeit wird auch per MQTT übertragen (um sie beispielsweise in der Loxone-Visualisierung anzuzeigen):

alexa2lox/<Gerätename>/lastTTStext … Der ausgegebene Text

alexa2lox/<Gerätename>/lastTTStime … Die Ausgabezeit im "menschenlesbaren" Zeitformat.

alexa2lox/<Gerätename>/lastTTSloxtime … Die Ausgabezeit im Loxone Zeitformat.

Hinweise:

• Die Sprachausgabe kann auch im Webbrowser aufgerufen werden (z.B. zum Testen). Alle Meldungen erscheinen im Browser.
• Aufgrund des Amazon-Cloud-Aufrufs kann die Sprachausgabe nicht gequeued werden, weil es von Amazon keine Rückmeldung gibt, wann der Text tatsächlich fertig gesprochen wurde. Werden daher mehrere Texte zeitgleich gesendet, "würgen" sie sich gegenseitig ab (der zuletzt gesendete Text wird dabei fertig gesprochen).
• Es gibt Filter, welche Geräte bei der Sprachausgabe übersprungen werden. Wenn dein Gerät nicht ansprechbar ist, melde dich im LoxForum.

Das Alexa2Lox Plugin kann deine Befehle, die du via alexa.php sendest, direkt an das Originalscript übergeben. Damit sind alle Routinen von Alexa2Lox abgeschaltet, es wird jedoch die im Plugin konfigurierte Authentifizierung verwendet. Die Ausgabe des Originalscripts erfolgt nur im Response, d.h. es wird auch nichts per MQTT übertragen.

Befehl bei EIN: /admin/plugins/alexa2lox/alexa.php?original&<Parameter an alexa_remote_control>&<Parameter an alexa_remote_control>&...

Kurzversion: /admin/plugins/alexa2lox/alexa.php?o&<Parameter an alexa_remote_control>&<Parameter an alexa_remote_control>&...

Wenn der erste Parameter original (bzw. die Kurzform o) ist, werden alle weiteren Parameter 1:1 übergeben an alexa_remote_control.sh. Es müssen dabei dann auch die Options-Striche mit übergeben werden!

alexa.php?original&-d=Wohnzimmer&-e=weather

In der Ausgabe des Aufrufs wird angezeigt, wie das Original-Script aufgerufen wird.

• Erinnerungen, Wecker, Timer: Hier wird noch eine Auflistung dieser Erinnerungsfunktionen kommen, gemeinsam und aufgetrennt auf diese drei Arten.
• Noch eine generelle Überarbeitung bezüglich der Amazon-Locations und Sprachen (amazon.de, amazon.co.uk usw.), sowie die Sprache, die Alexa verwendet (z.B. bei TTS)
• Multi-Language des Plugins
• Eine Idee, deren sinnvolle Umsetzung noch zu prüfen ist: Setzen von Erinnerungen/Wecker/Timer vom Miniserver aus
• Ebenso: Erinnerungen/Wecker/Timer, die per Webinterface/Spracheingabe (oder per MS) gesetzt wurden, bei Erreichen einen Trigger per MQTT auslösen lassen  

Bitte im oben angegebenen Thread Feedback geben, oder als Issue bei GitHub: https://github.com/christianTF/LoxBerry-Plugin-Alexa2Lox/issues

Das Plugin ist noch BETA - aktiv getestet haben Peter, Christian, Mario und Jörg - und es gibt vielleicht dort und da noch Sonderfälle, die wir nicht ausreichend getestet haben, z.B.

• Neustart von LoxBerry (geht noch alles?)
• Hinzufügen neuer Echo-Geräte
• Verschiedenste Echo-Geräte (gehen alle Geräte aus dem Echo-Sortiment?)
• Alles mit Sonderzeichen und Leerzeichen

Wenn euch bei diesen Sachen, oder bei irgendeiner anderen Funktion etwas auffällt, dann bitte melden. Bitte so viele Infos wie möglich mitgeben (Screenshots!).