alexarc4shng

plugin logo

Das Plugin bietet die Möglichkeit, ein Alexa-Echo-Gerät über smartHomeNG fernzusteuern. So ist es möglich, einen TuneIn-Radio-Kanal einzuschalten, Nachrichten über Text2Speech zu senden, wenn ein Ereignis auf dem knx-Bus oder auf der Visu eintritt, etc.

Voraussetzungen

  • Python requests

  • ein gültiges Cookie aus einer Sitzung auf einer alexa.amazon-Webseite

  • „base64“-codierte Anmeldedaten in der etc/plugin.yaml Datei

Anmeldedaten

Nutzername und Passwort können im Web Interface oder via Python entsprechend kodiert werden

import base64
base64.b64encode("user.test@gmail.com:your_pwd".encode("utf-8"))

Konfiguration

Die Informationen zur Konfiguration des Plugins sind unter Plugin ‚alexarc4shng‘ Konfiguration beschrieben.

plugin.yaml

AlexaRc4shNG:
    plugin_name: alexarc4shng
    cookiefile: /usr/local/smarthome/plugins/alexarc4shng/cookies.txt
    host: alexa.amazon.de
    item_2_enable_alexa_rc: <Item zum Aktivieren>
    alexa_credentials: <USER>:<PWD> (kodiert!)
    login_update_cycle: 432000
    mfa_secret: <MFA-Secret>

items.yaml

Sie können bis zu 99 Befehle pro shng-Element angeben. Das Plugin scannt die item.yaml während der Initialisierung nach Befehlen von 01 bis 99.

Wichtig

Bitte starten Sie jedes Mal mit 01 pro Item, also alexa_cmd_01. Die Befehlsnummern müssen fortlaufend sein, vergessen Sie keine. Der Scan der Befehle endet, wenn kein Befehl mit der nächsten Nummer gefunden wird.**

Ein Command ist wie folgt aufgebaut:

alexa_cmd_01: comparison:EchoDevice:Commandlet:Value_to_Send

Unterstützte Vergleiche (comparison):

  • „True“ oder „False“ für boolsche Werte

  • für numerische Werte „<=“, „>=“, „=“, „<“, „>“

Beispiele

Radiostation

alexa_cmd_01: True:EchoDotKueche:StartTuneInStation:s96141
  • Value = True bedeutet, dass das item() „ON“ wird

  • EchodotKueche = Gerätename, an das der Befehl gesendet werden soll

  • StartTuneInStation = Name des Befehls

  • s96141 = Wert der Radiostation als guideID, Stationsnamen werden nicht unterstützt (hier S96141 = baden.fm)

Um die Stations-ID zu finden, suchen Sie nach Ihrer Station auf TuneIn.com. Greifen Sie auf Ihre Seite zu und verwenden Sie die letzten Ziffern der resultierenden URL für die ID. Zum Beispiel: Wenn Ihre TuneIn.com-URL http://tunein.com/radio/tuneinstation-s######/ ist, dann wäre Ihre Stations-ID „s######“.

Text senden

Beispiel zum Senden von Text mit dem im Wert enthaltenen Element basierend auf einem Wert unter 20 Grad:

alexa_cmd_01: <20.0:EchoDotKueche:Text2Speech:Die Temperatur in der Küche ist niedriger als 20 Grad. Die Temperatur ist jetzt #test.testzimmer.temperature.actual/#
  • Value = <20.0 - Befehl senden, wenn der Wert des Elements kleiner als 20.0 wird

  • EchodotKueche = Gerätename, an das der Befehl gesendet werden soll

  • Text2Speech = Name des Befehls

  • Value_to_Send = Die Temperatur in der Küche ist niedriger als 20 Grad. Die Temperatur ist jetzt #test.testzimmer.temperature.actual/#

  • #test.testzimmer.temperature.actual/# = Elementpfad des einzufügenden Werts

Beispiel Itemdefinition

OG:
    Buero:
        name: Buero
        Licht:
            type: bool
            alexa_name: Licht Büro
            alexa_description: Licht Büro
            alexa_actions: Einschalten Ausschalten
            alexa_icon: LICHT
            alexa_cmd_01: True:EchoDotKueche:StartTuneInStation:s96141
            alexa_cmd_02: True:EchoDotKueche:Text2Speech:Hallo das Licht im Büro ist eingeschaltet
            alexa_cmd_03: False:EchoDotKueche:Text2Speech:Hallo das Licht im Büro ist aus
            alexa_cmd_04: 'False:EchoDotKueche:Pause: '
            visu_acl: rw
            knx_dpt: 1
            knx_listen: 1/1/105
            knx_send: 1/1/105
            enforce_updates: 'true'

Logiken

Beispiellogik, um Items mit Listeninformationen (Todo, Shopping) zu füllen

from datetime import datetime

# get the Todo-List
myList=sh.AlexaRc4shNG.get_list('TO_DO')
for entry in myList:
  if entry['completed'] == True:
    entry['icon'] = 'control_clear'
  else:
    entry['icon'] = 'control_home'
  entry['date'] = datetime.fromtimestamp((entry['updatedDateTime']/1000)).strftime("%d.%m.%Y, %H:%M:%S")

# Write list to Item - type should be list
sh.Alexa_Lists.list.todo(myList)

# get the shopping-List
myList=sh.AlexaRc4shNG.get_list('SHOPPING_LIST')
for entry in myList:
  if entry['completed'] == True:
    entry['icon'] = 'control_clear'
  else:
    entry['icon'] = 'jquery_shop'
  entry['date'] = datetime.fromtimestamp((entry['updatedDateTime']/1000)).strftime("%d.%m.%Y, %H:%M:%S")

# Write list to Item - type should be list
sh.Alexa_Lists.list.shopping(myList)

Einbinden in der smartVISU

status.activelist('','Alexa_Lists.list.todo','value','date','value','info')
status.activelist('','Alexa_Lists.list.shopping','value','date','value','info')
../../_images/Alexa_lists.jpg

Platzhalter

  • <mValue> = Value to send as alpha

  • <nValue> = Value to send as numeric

  • „#item.path/#“ = item-path of the value that should be inserted into text or ssml

  • <serialNumber> = SerialNo. of the device where the command should go to

  • <familiy> = device family

  • <deviceType> = deviceType

  • <deviceOwnerCustomerId> = OwnerID of the device

Wichtig

Platzhalter sind mit „<“, „>“, „#“ und „/#“ kennzuzeichnen!

Kommandos erstellen

Öffnen Sie das Web-Interface für Alexa auf Amazon. Wählen Sie die Seite aus, die Sie überwachen möchten. Bevor Sie auf den Befehl klicken, öffnen Sie den Debugger des Browsers (F12). Wählen Sie den Netzwerk-Tab aus. Wenn Sie auf den Befehl klicken, den Sie überwachen möchten, wird der Netzwerkverkehr im Debugger angezeigt. Hier erhalten Sie alle Informationen, die Sie benötigen. Normalerweise werden Informationen an Amazon gesendet. Konzentrieren Sie sich also auf die Post-Methoden.

Browser Debugger

Als Beispiel zum Überwachen der Station-ID einer TuneIn Radio-Station sehen Sie dies direkt im Kontext, wenn Sie Ihre Maus auf den Post-Befehl bewegen. Sie können die URL in die Zwischenablage kopieren und sie im Plugin verwenden.

Sie können sie auch als cUrl kopieren, in einen Editor einfügen und die Payload im –data-Abschnitt des cUrl finden.

Post Befehl

Für einige Befehle müssen Sie die Payload kennen. Dies können Sie durch Überwachung der Daten herausfinden. Wählen Sie den Netzwerkbefehl aus. Wählen Sie dann den Tab mit den Headern aus. Unten finden Sie die Formulardaten. Sie können die Payload in die Zwischenablage kopieren und sie im Web Interface einfügen.

Header

Vergessen Sie nicht, die Werte für deviceOwnerCustomerId, customerID, serialNumber, family und Werte durch die Platzhalter zu ersetzen

<deviceOwnerCustomerIdcustomerID>
<serialNumber>
<serialNumber>
<family>
<mValue> (für Alpha-Werte)
<nValue> (für numerische Werte)

Web Interface

Funktionen

Auf dem Web-Interface können eigene Commandlets (Funktionen) definiert werden. Die folgenden Funktionen sind auf dem Web-Interface verfügbar:

  • Speichern einer Cookie-Datei, um Zugang zum Alexa-Web-Interface zu erhalten

  • Manuelles Login mit Ihren Zugangsdaten (gespeichert in der /etc/plugin.yaml)

  • Sehen Sie alle verfügbaren Geräte, wählen Sie eines aus um Test-Funktionen zu senden

  • Commandlets definieren - Sie können Commandlets laden, speichern, löschen, prüfen und testen

  • die Commandlets können mit einem Klick auf die Liste in das Webinterface geladen werden

  • die Json-Struktur kann auf dem WebInterface geprüft werden

In der API-URL und im JSON-Payload müssen die echten Werte aus dem Alexa-Webinterface durch Platzhalter ersetzt werden, siehe oben. Für Testfunktionen ist die Verwendung der Platzhalter nicht unbedingt notwendig.

Cookies

Im ersten Tab kann das Cookie File gespeichert werden.

../../_images/webif1.jpg

Exportieren Sie es mit einem Cookie.txt-Add-On Ihres Browsers. Kopieren Sie es in die Zwischenablage. Fügen Sie es in das Textfeld in der Web-Benutzeroberfläche ein und speichern Sie es ab. Nun werden die verfügbaren Geräte aus Ihrem Alexa-Konto erkannt und auf dem zweiten Tab angezeigt.

Geräte

Im zweiten Tab werden die verfügbaren Geräte angezeigt - Durch click auf ein Gerät wird dieses selektiert und steht für Tests zur Verfügung:

../../_images/webif2.jpg

Kommandos verwalten

Im dritten Tab werden die Commandlets verwaltet - mit Klick auf die Liste der Commandlets wird dieses ins WebIF geladen:

../../_images/webif3.jpg

Bestehende Commandlets

  • Play (Spielt das zuletzt pausierte Medium ab)

  • Pause (Pausiert das aktuelle Medium)

  • Text2Speech (Sendet einen Text an das Echo, das Echo spricht ihn)

  • StartTuneInStation (Startet eine TuneIn-Radiostation mit der angegebenen GuideID, siehe auch Beispiele weiter oben)

  • SSML (Sprachausgabe von Text mit Speech Synthesis Markup Language)

  • VolumeAdj (Regelt die Lautstärke während der Wiedergabe einiger Medien; funktioniert nicht über die Testfunktionen der Web-Benutzeroberfläche)

  • VolumeSet (Setzt die Lautstärke auf einen Wert zwischen 0 und 100 Prozent)

Sie können Testwerte im Feld für die Werte eingeben. Drücken Sie „Test“, und der Befehl wird an das Gerät gesendet. Sie erhalten den HTTP-Status der Anfrage zurück.

Wichtig

Für Tests sollten Sie die Payload nicht ändern, sondern einfach das Testwert-Feld verwenden.

SSML Hinweise

Auszugebender Text ist in <speak></speak> Tags einzubetten.

Beispiel

<speak>
I want to tell you a secret.<amazon:effect name="whispered">I am not a real human.</amazon:effect>.
    Can you believe it?
</speak>

Außerdem können SpeechCons wie folgt genutzt werden.

<speak>
    Here is an example of a speechcon.
    <say-as interpret-as="interjection">ach du liebe zeit.</say-as>.
</speak>

Weitere Infos: SSML und SpeechCons

Danksagung

Disclaimer

TuneIn, Amazon Echo, Amazon Echo Spot, Amazon Echo Show, Amazon Music, Amazon Prime, Alexa und alle anderen Produkte und Unternehmen von Amazon, TuneIn und anderen sind Marken™ oder eingetragene® Marken ihrer jeweiligen Inhaber. Die Verwendung bedeutet nicht, dass eine Verbindung zu ihnen besteht oder dass sie sie unterstützen.