README.md

IPSymconEchoRemote

Modul für IP-Symcon ab Version 5.0. Ermöglicht die Fernsteuerung mit einem Amazon Echo / Amazon Dot / Amazon Echo Show von IP-Symcon aus.

Dokumentation

Inhaltsverzeichnis

1. Funktionsumfang
2. Voraussetzungen
3. Installation
4. Funktionsreferenz
5. Konfiguration
6. Anhang

1. Funktionsumfang

• Steuerung von Musik:
  • Wiedergabe
  • Pause
  • Stop
  • Weiter
  • Zurück
  • Lautstärke einstellen
  • 30 Sekunden zurückspulen
  • 30 Sekunden vorspulen
  • Titel mischen
  • Titel wiederholen
  • Radio TuneIn Sender auswählen
• Sprachausgabe auf einem Echo (Text to Speech)
• Ausgabe von Sound der Amazon Sound Library auf einem Echo
• Sprachausgabe mit SSML auf einem Echo (Text to Speech) / auch in Kombination mit Sound
• Ankündigungen auf allen Echo Geräten im WLAN (Text to Speech)
• Uhrzeit der nächsten Weckzeit
• Anzeige der Einkaufsliste
• Anzeige der Aufgabenliste
• Wettervorhersage
• Verkehrsmeldungen
• Flash Briefing
• Erzählt ein Funfact
• Erzählt einen Witz
• Guten Morgen
• Singt ein Lied
• Erzählt eine Geschichte
• Startet eine Routine
• Koppeln von Bluetooth Geräten
• Bitte nicht Stören ein-/ ausschalten

2. Voraussetzungen

• IPS 5.0
• Echo / Echo Dot / Echo Show

3. Installation

a. Laden des Moduls

Die Webconsole von IP-Symcon mit http://{IP-Symcon IP}:3777/console/ öffnen.

Anschließend oben rechts auf das Symbol für den Modulstore (IP-Symcon > 5.1) klicken

Im Suchfeld nun

Echo Remote

eingeben

und schließend das Modul auswählen und auf Installieren

drücken.

Alternatives Installieren über Modules Instanz (IP-Symcon < 5.1)

Die Webconsole von IP-Symcon mit http://{IP-Symcon IP}:3777/console/ öffnen.

Anschließend den Objektbaum Öffnen.

Die Instanz 'Modules' unterhalb von Kerninstanzen im Objektbaum von IP-Symcon (>=Ver. 5.x) mit einem Doppelklick öffnen und das Plus Zeichen drücken.

Im Feld die folgende URL eintragen und mit OK bestätigen:

https://github.com/Wolbolar/IPSymconEchoRemote 

Anschließend erscheint ein Eintrag für das Modul in der Liste der Instanz Modules

Es wird im Standard der Zweig (Branch) master geladen, dieser enthält aktuelle Änderungen und Anpassungen. Nur der Zweig master wird aktuell gehalten.

Sollte eine ältere Version von IP-Symcon die kleiner ist als Version 5.1 eingesetzt werden, ist auf das Zahnrad rechts in der Liste zu klicken. Es öffnet sich ein weiteres Fenster,

hier kann man auf einen anderen Zweig wechseln, für ältere Versionen kleiner als 5.1 ist hier Old-Version auszuwählen.

b. Gruppen und Geräte in Amazon App benennen

In der Alexa App alle Geräte benennen.

c. Einrichtung in IP-Symcon

In IP-Symcon nun zunächst mit einem rechten Mausklick auf Konfigurator Instanzen eine neue Instanz mit Objekt hinzufügen -> Instanz (CTRL+1 in der Legacy Konsole) hinzufügen, und Echo auswählen.

Es öffnet sich das Konfigurationsformular.

Hier sind anzugeben:

• Amazon Benutzername
• Amazon Passwort
• Amazon 2FA Code (falls in Amazon die Zwei-Schritt-Verifizierung eingestellt ist)
• Sprache

Vielen Dank an dieser Stelle an ok1982, der die Unterstützung der Zwei-Schritt-Verifizierung ermöglicht hat.

Nutzung der Zwei-Schritt-Verifizierung von Amazon

Um sich einfach bei Amazon authentifizieren zu können, kann optional die Zwei-Schritt-Verifizierung von Amazon aktiviert werden. Dadurch entfällt der Schritt den Cookie zu ermitteln was die Einrichtung einfacher macht. Allerdings ist hierzu zunächst bei Amazon dauerhaft die Zwei-Schritt-Verifizierung dauerhaft zu aktivieren.

Eine Beschreibung, wie die Verfizierung einzurichten ist findet ihr hier:

• Einrichtung der Zwei-Schritt-Verifizierung

Alternativ zu Benutzername und Passwort kann auch ein gültiger Cookie verwendet werden.

Ermittlung des Cookie

Wenn beim Amazon Konto die Zwei-Schritt-Verifizierung aktiviert ist, dann ist der Anmeldeweg über den Cookie zu wählen, da vom Modul keine Zwei-Schritt-Verifizierung unterstützt wird.

Wie kann der Cookie ermittelt werden?

Im folgenden Beispiel wird gezeigt, wie der Cookie einer aktiven Browser Session ermittelt werden kann.

In dem Beispiel nutzen wir die Entwicklertools von Chrome, andere Browser verfügen aber über ähnliche Werkzeuge. Die Bilder und Anleitung orientiert sich jetzt aber an Chrome.

Wie öffnen also zunächst die Webseite https://alexa.amazon.com und melden uns dort mit dem Amazon Account an auf den auch der Echo / Dot registriert ist.

Nun wechseln wir unter Musik, Videos und Bücher und wählen TuneIn aus. Jetzt öffnen wir die Entwicklertools mit F12: es öffnet sich auf der rechten Seite ein weiteres Fenster.

Nun wählen wir einen Radiosender bei TuneIn mit Doppelklick aus. Der Radiosender sollte nun das Abspielen auf dem Echo beginnen. Gleichzeitig sehen wir im Fenster der Entwicklertools unter Netzwerk einen Eintrag mit queue-and-play.

Wir öffnen jetzt den Eintrag queue-and-play (linke Spalte) mit einem Doppelklick und es öffnen sich ein weiters Fenster (rechte Spalte).

In dem Fenster können wir nun Cookie Eintrag finden, den wir für das Modul benötigen. Im Block Request Headers findet man ihn. Der Cookie ist ziemlich lang und muss komplett kopiert werden.

Benutzung des Konfigurators

Nach der Einrichtung der IO-Instanz können im Konfigurator die Geräte eingelesen werden. Es erscheint eine Liste der verfügbaren Geräte mit Gerätenamen, Gerätetyp, Gerätefamilie, Gerätenummer und InstanzID. Das Gerät ist grün, insofern es noch nicht angelegt worden ist.

Dann das gewünschte Gerät markieren und auf

Erstellen drücken, die Instanz wird dann erzeugt.

Webfront Ansicht

Beispiel zur Einrichtung einer Routine und dem Starten der Routine aus IP-Symcon

Eine Beschreibung, wie eine Routine in der Alexa App eingerichtet werden kann und diese aus IP-Symcon gestartet wird:

• Einrichtung einer Routine in der Alexa App und starten dieser aus IP-Symcon

Beispiel zur Einrichtung von Ankündigungen auf einem Alexa Gerät und Nutzung aus IP-Symcon

Eine Beschreibung, wie Ankündigungen auf einem Echo Gerät einzurichten sind:

• Einrichtung für Ankündigungen auf einem Alexa Geräte

4. Funktionsreferenz

Echo Remote Device:

Play

ECHOREMOTE_Play(int $InstanceID)

Parameter $InstanceID ObjektID des Echo Remote Devices

Pause

ECHOREMOTE_Pause(int $InstanceID)

Parameter $InstanceID ObjektID des Echo Remote Devices

Next

ECHOREMOTE_Next(int $InstanceID)

Parameter $InstanceID ObjektID des Echo Remote Devices

Previous

ECHOREMOTE_Previous(int $InstanceID)

Parameter $InstanceID ObjektID des Echo Remote Devices

SetVolume

ECHOREMOTE_SetVolume(int $InstanceID, int $volume)

Parameter $InstanceID ObjektID des Echo Remote Devices

Parameter $volume Volume des Amazon Echo Dot, min 0 max 100

Mute / Unmute

ECHOREMOTE_Mute(int $InstanceID, bool $mute)

Parameter $InstanceID ObjektID des Echo Remote Devices

Parameter $mute true Setzt Volume des Amazon Echo Dot auf 0, min 0 max 100 Parameter $mute false Setzt Volume des Amazon Echo Dot auf den letzten bekannten Lautstärke Wert

Rewind30s

ECHOREMOTE_Rewind30s(int $InstanceID)

Parameter $InstanceID ObjektID des Echo Remote Devices

Forward30s

ECHOREMOTE_Forward30s(int $InstanceID)

Parameter $InstanceID ObjektID des Echo Remote Devices

Shuffle

ECHOREMOTE_Shuffle(int $InstanceID, bool Shuffle)

Parameter $InstanceID ObjektID des Echo Remote Devices

Repeat

ECHOREMOTE_Repeat(int $InstanceID)

Parameter $InstanceID ObjektID des Echo Remote Devices

GetQueueInformation

ECHOREMOTE_GetPlayerInformation(int $InstanceID)

Parameter $InstanceID ObjektID des Echo Remote Devices

Liefert eine Liste mit Informationen zum aktuell abgespielten Titel bzw. zum aktuellen Sender.

GetPlayerInformation

ECHOREMOTE_GetQueueInformation(int $InstanceID)

Parameter $InstanceID ObjektID des Echo Remote Devices

Liefert eine Liste mit den Media Einträgen der aktuellen Abspielliste.

GetNotifications

ECHOREMOTE_GetNotifications(int $InstanceID)

Parameter $InstanceID ObjektID des Echo Remote Devices

Liefert eine Liste mit den aktuellen Weckern.

GetToDos

ECHOREMOTE_GetToDos(int $InstanceID, string $type, bool $completed)

Parameter $InstanceID ObjektID des Echo Remote Devices

Parameter $type gesuchter Itemtyp: 'SHOPPING_ITEM' oder 'TASK'

Parameter $completed null: es werden alle Einträge geliefert, false: es werden die offenen Einträge geliefert, true: es werden die erledigten Einträge geliefert

Liefert eine Liste mit den Einträgen der aktuellen Einkaufsliste oder To-Do-Liste.

JumpToMediaId

ECHOREMOTE_JumpToMediaId(int $InstanceID, string MediaID)

Parameter $InstanceID ObjektID des Echo Remote Devices

Parameter $MediaID MediaID, die innerhalb einer Abspielliste angesprungen werden soll

Springt zu der angegebenen ID der aktuellen Abspielliste.

TuneIn

ECHOREMOTE_TuneIn(int $InstanceID, string $station)

Parameter $InstanceID ObjektID des Echo Remote Devices

Parameter $station Station ID ist die guideId die entsprechend der Anleitung pro Sender einmal ausgelesen werden muss

TuneInPreset

ECHOREMOTE_TuneInPreset(int $InstanceID, int $preset)

Parameter $InstanceID ObjektID des Echo Remote Devices

Parameter $preset Positions ID der Radiostation im Modul

PlayAmazonMusic

ECHOREMOTE_PlayAmazonMusic(integer $InstanceID, string $seedid, string $stationname)

Parameter $InstanceID ObjektID des Echo Remote Devices

Parameter $seedid Seed ID ist die seedId die pro Sender einmal ermittelt werden muss

Parameter $stationname Station Name der stationName der pro Sender ermittelt werden muss

PlayAmazonPrimePlaylist

ECHOREMOTE_PlayAmazonPrimePlaylist(integer $InstanceID, string $asin)

Parameter $InstanceID ObjektID des Echo Remote Devices

Parameter $asin Asin ist die asin die entsprechend der Anleitung pro Sender einmal ausgelesen werden muss

Text to Speech

ECHOREMOTE_TextToSpeech(integer $InstanceID, string $text_to_speech)

Parameter $InstanceID ObjektID des Echo Remote Devices

Parameter $text_to_speech Text der von dem Gerät vorgelesen werden soll

Ankündigung

ECHOREMOTE_Announcement(integer $InstanceID, string $text_to_speech)

Parameter $InstanceID ObjektID des Echo Remote Devices

Parameter $text_to_speech Text der auf allen Echo Geräten im WLAN vorgelesen werden soll, mit Ausnahme aller Echo Geräte, bei denen Bitte nicht stören aktiv ist

Wettervorhersage

ECHOREMOTE_Weather(integer $InstanceID)

Parameter $InstanceID ObjektID des Echo Remote Devices

Liest den Wetterbericht auf dem Gerät vor

Verkehrsmeldungen

ECHOREMOTE_Traffic(integer $InstanceID)

Parameter $InstanceID ObjektID des Echo Remote Devices

Liest Verkehrsmeldungen auf dem Gerät vor

FlashBriefing

ECHOREMOTE_FlashBriefing(integer $InstanceID)

Parameter $InstanceID ObjektID des Echo Remote Devices

Liest ein Flash Briefing auf dem Gerät vor

Guten Morgen

ECHOREMOTE_Goodmorning(integer $InstanceID)

Parameter $InstanceID ObjektID des Echo Remote Devices

Spielt die "Guten Morgen Mitteilung" auf dem Gerät ab

Singt ein Lied

ECHOREMOTE_SingASong(integer $InstanceID)

Parameter $InstanceID ObjektID des Echo Remote Devices

Spielt ein Lied auf dem Gerät ab

Erzählt ein Funfact

ECHOREMOTE_TellFunFact(integer $InstanceID)

Parameter $InstanceID ObjektID des Echo Remote Devices

Spielt ein Funfact auf dem Gerät ab

Erzählt ein Witz

ECHOREMOTE_TellJoke(integer $InstanceID)

Parameter $InstanceID ObjektID des Echo Remote Devices

Spielt ein Witz auf dem Gerät ab

Erzählt Geschichte

ECHOREMOTE_TellStory(integer $InstanceID)

Parameter $InstanceID ObjektID des Echo Remote Devices

Spielt ein kurze Geschichte auf dem Gerät ab

Ermitteln die Bluetooth Verbindungen

array ECHOREMOTE_ListPairedBluetoothDevices(integer $InstanceID)

Parameter $InstanceID ObjektID des Echo Remote Devices

Es werden die für das Gerät angelegten Bluetooth Verbindungen ermittelt. Hinweis: die Bluetootheinrichtung selber hat mit der Amazon App oder im Dialog zu erfolgen.

Beispiel:

$devices = ECHOREMOTE_ListPairedBluetoothDevices(47111);

var_dump($devices);

Es wird eine Liste der eingerichteten Bluetooth Verbindungen und deren Eigenschaften ausgegeben:

array(1) {
  [0]=>
  array(5) {
    ["address"]=>
    string(17) "00:16:94:25:7B:93"
    ["connected"]=>
    bool(false)
    ["deviceClass"]=>
    string(5) "OTHER"
    ["friendlyName"]=>
    string(7) "PXC 550"
    ["profiles"]=>
    array(2) {
      [0]=>
      string(9) "A2DP-SINK"
      [1]=>
      string(5) "AVRCP"
    }
  }
}

Verbinden eines Bluetooth Gerätes

ECHOREMOTE_ConnectBluetooth(integer $InstanceID, string $bluetooth_address)

Parameter $InstanceID: ObjektID des Echo Remote Devices.

Parameter $bluetooth_address: Adresse des zu verbindenden Gerätes

Es wird der Verbindungsaufbau zu dem angegeben Gerät initiiert.

Beispiel:

ECHOREMOTE_ConnectBluetooth(47111, '00:16:94:25:7B:93');

Trennen einer Bluetooth Verbindung

ECHOREMOTE_DisconnectBluetooth(integer $InstanceID)

Parameter $InstanceID ObjektID des Echo Remote Devices

Es wird eine bestehende Bluetooth Verbindung getrennt.

Starten einer Routine

boolean ECHOREMOTE_StartAlexaRoutine(integer $InstanceID, string $utterance)

Parameter $InstanceID: ObjektID des Echo Remote Devices.

Parameter $utterance: 'Sprachausdruck' der zu startenden Routine. Routinen können in der Alexa App definiert, konfiguriert und aktiviert werden.

Es wird die zum Sprachausdruck passende Routine gestartet. Im Fehlerfall wird false zurückgegeben.

Beispiel:

ECHOREMOTE_StartAlexaRoutine(47111, 'Starte meinen Tag');

Bitte nicht Stören einschalten

ECHOREMOTE_DoNotDisturb(integer $InstanceID, bool true)

Parameter $InstanceID ObjektID des Echo Remote Devices

Bitte nicht stören wird am Gerät aktiviert.

Bitte nicht Stören ausschalten

ECHOREMOTE_DoNotDisturb(integer $InstanceID, bool false)

Parameter $InstanceID ObjektID des Echo Remote Devices

Bitte nicht stören wird am Gerät deaktiviert.

AmazonEchoIO:

Anmelden

boolean ECHOIO_LogIn(integer $InstanceID)

Parameter $InstanceID: ObjektID der EchoIO Instanz.

Abmelden

boolean ECHOIO_LogOff(integer $InstanceID)

Parameter $InstanceID: ObjektID der EchoIO Instanz.

Anmeldestatus überprüfen

boolean ECHOIO_CheckLoginStatus(integer $InstanceID)

Parameter $InstanceID: ObjektID der EchoIO Instanz.

5. Konfiguration:

Echo Remote:

Eigenschaft	Typ	Standardwert	Funktion
Devicetype	string	-	Typ des Geräts
Devicenumber	string	-	Device Nummer des Geräts (Seriennummer)
TuneInStations	array	Liste von ausgewählten Sendern mit den Attributen 'position', 'station' und 'station_id'	Liste der im Webfront angebotenen Sender
UpdateIntervall	integer	0	Intervall in Sekunden, in dem die Daten vom Gerät geholt werden und die Statusvariablen aktualisiert werden
ExtendedInfo	boolean	false	Auswahl, ob erweiterte Statusvariablen (Titel, Subtitel_1, Subtitel_2) sowie das MediaImage 'MediaImageCover' zur Verfügung gestellt werden sollen
AlarmInfo	boolean	false	Auswahl, ob Weckzeiten (nextAlarmTime, lastAlarmTime) in Statusvariablen abgebildet werden sollen

6. Anhang

Echo Remote Device:

GUID: {496AB8B5-396A-40E4-AF41-32F4C48AC90D}