Skip to end of metadata
Go to start of metadata
Autor
Logo

Status

BETA

Version4.0.0
Min. LB Version

LB 1.4.3

DownloadALPHA: https://github.com/christianTF/LoxBerry-Plugin-Alexa2Lox/archive/master.zip
ZweckSteuerung und Sprachausgabe von Amazon Echo Geräten
LanguagesDE
Diskussion

https://www.loxforum.com/forum/projektforen/loxberry/plugins/233526-plugin-alexa2lox-v4-x

 Version History...

Versionen vor 4.0

Siehe Alexa2Lox 3.0 (EOL)

Version 4.0.0

  • Generalüberarbeitung / Update 
  • ACHTUNG - Das Plugin wird als neues Plugin neben der Vorgängerversion angelegt! Die Vorgängerversion kann deinstalliert werden.

Inhalt



Über Version 4.x

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)

Kompatibilität

  • Die Aufrufssyntax ist NICHT kompatibel zu allen Vorgängerversionen kleiner V4.0.
  • Das Plugin installiert sich als 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 V2.x). Aktuell sind aber keine Features enthalten, die ausschließlich mit LB2.0 funktionieren würden. Es sollte daher mit LoxBerry V1.4.3 ebenso funktionieren. Versionen unter LB 1.4.3 sollten aber nicht eingesetzt werden.

Download

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

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

Allgemeines

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 etwas ändern.

Installation

  1. Installation des Plugin MQTT Gateway. Sollte dieses bereits auf dem Loxberry installiert sein, 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.
    LB 2.x: Das MQTT Gateway erhält von LoxBerry 2.x automatisch die Information über die Plugin-Installation, deswegen werden Subscription und Conversions automatisch übernommen.

Konfiguration

Amazon Zugangsdaten 

Zwei-Schritt-Verifizierung oder Benutzer+Passwort:

Amazon fordert regelmäßig eine Neu-Authentifizierung an.

Wird nur Benutzer+Passwort verwendet, fordert Amazon dabei sogenannte Captcha's (Bilder mit Zeichen, die man eingeben muss) an. Das Plugin kann diese nicht lösen, und funktioniert nach einer derartigen Anfrage nicht mehr. 

Wird Zwei-Schritt-Verifizierung bei Amazon eingestellt, wird statt eines Captcha's von Amazon ein Einmal-Code angefordert. Diesen Einmal-Code kann auch das Plugin berechnen und gibt diesen automatisch mit. Damit ist die Funktion des Plugins immer gewährleistet. Die Zwei-Schritt-Verifizierung kann allerdings nur für den gesamten Amazon-Account eingerichtet werden. Deswegen muss bei Amazon zusätzlich die Handy-Nummer hinterlegt werden. Während das Plugin den Einmal-Code dann automatisch eingibt, musst du ab und zu den Einmal-Code auf der Amazon-Webseite eingeben, den dir Amazon per SMS sendet.

Amazon E-Mail-Adresse: Dein Amazon-Benutzeraccount

Amazon Passwort: Dein Amazon-Kennwort

Wenn 2-Schritt-Verifizierung gewählt ist, musst du zusätzlich den Amazon Token angeben. Bitte folge dieser Anleitung: Alexa2Lox - Zwei-Schritt-Verifizierung einrichten.

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!

Überprüfen der Konfiguration

Nach dem speichern der Einstellungen werden von dem 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 
  3. Überprüfen, ob die Geräte im Amazon Konto aufgelistet sind. 
    1. Alexa Webinterface ö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.

Die Konfiguration des Plugins ist abgeschlossen. Es kann nun verwendet werden.

Beschreibung der Bereiche des Plugins

Bereich "Amazon Alexa"

Alexa Webinterface öffnen: Öffnet die Alexa-Seite im Webbrowser.

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.

Amazon Zugangsdaten 

Dieser Bereich ist bereits unter Konfiguration beschrieben.

Bereich "Gefundene Geräte"

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.

Bereich "MQTT"

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.

Verwendung in der Loxone Config

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.

Virtueller Ausgang

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.

Datenabruf-Funktionen (Kommando-Referenz) Virtueller Ausgang Befehl (VQ)

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. 

ParameterKurze VersionWertBeschreibung
deviced<Alexaname>Der Name des Geräts. Der Name ist nicht case-sensitive, und es können Leerzeichen verwendet werden.
playerstateps
Abfrage des Status des Devices (<device> erforderlich)
notificationsnl

NICHT FERTIG Abfrage anstehender Benachrichtigungen, auch Command wird sich vermutlich noch ändern

shoppinglistsl
Abfrage der Einkaufsliste
todolisttl
Abfrage der To-Do Liste
executee<command>
print

Druckt irgendwas (weiß ich noch nicht, muss Peter dokumentieren (smile) )
originalo
Dieser Parameter übergibt alle nachfolgenden Parameter direkt an das Lötzimmer Originalscript alexa_remote_control.sh

Beispiele

Player-Status eines Geräts abrufen

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

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

Benachrichtigungen abrufen

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

Einkaufsliste abrufen

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

To-Do Liste abrufen

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

Steuerung von Alexa (execute) Virtueller Ausgang Befehl (VQ)

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.

Auszug der Befehle von alexa_remote_control.sh (V0.15b)

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

weather | traffic | flashbriefing | goodmorning | singasong | tellstory | speak:'<text>' | automation:'<routine name>'

Beispiele

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

Sprachausgabe - Text-To-Speech

Virtueller Ausgang Befehl

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.

ParameterKurze Version

device=<Gerätename1>,<Gerätename2>,...

device=ALL

d=<Gerätename>,...

d=ALL

Der Name des Echo. Groß/Kleinschreibung egal, Leerzeichen im Namen sind erlaubt. Der Parameter device erlaubt auch die Angabe mehrerer Geräte mit Komma getrennt: device=wohnzimmer,büro

ALL ist das Schlüsselwort, um die Sprachausgabe bei allen Geräten auszuführen.

text=<Mein Text>t=<Mein Text>Der Text, der gesprochen werden soll. Leerzeichen, Sonderzeichen usw. können ganz gewöhnlich geschrieben werden.
vol=<1...100>
optional. Die Lautstärke der Sprachausgabe.

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.

Originalscript alexa_remote_control.sh (Lötzimmer) einsetzen

Das Alexa2Lox Plugin kann deine Befehle, die du via alexa.php sendest, direkt an das Originalscript übergeben. Damit sind alle Routinen von Alexa2Lox abgeschalten, 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!

Beispiel

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

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

Was noch kommt

  • 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  

Feedback

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!).