From b74048459bd3213b5935fdaa8f79cc2d5bcaab16 Mon Sep 17 00:00:00 2001 From: Onkel Andy Date: Mon, 15 Jan 2024 22:54:36 +0100 Subject: [PATCH] alexarc4shng plugin: transfer all README info to user_doc and delete README --- alexarc4shng/README.md | 501 -------------------------------------- alexarc4shng/user_doc.rst | 329 +++++++++++++++++++++++-- 2 files changed, 308 insertions(+), 522 deletions(-) delete mode 100755 alexarc4shng/README.md diff --git a/alexarc4shng/README.md b/alexarc4shng/README.md deleted file mode 100755 index a1e0eaedc..000000000 --- a/alexarc4shng/README.md +++ /dev/null @@ -1,501 +0,0 @@ -# AlexaRc4shNG - -#### Version 1.0.3 - -The plugin gives the possibilty to control an Alexa-Echo-Device remote by smartHomeNG. So its possible to switch on an TuneIn-Radio Channel, send some messages via Text2Speech when an event happens on the knx-bus or on the Visu. On the Web-Interface you can define your own commandlets (functions). The follwing functions are available on the Web-Interface : - -- Store a cookie-file to get access to the Alexa-WebInterface -- manually Login with your credentials (stored in the /etc/plugin.yaml) -- See all available devices, select one to send Test-Functions -- define Commandlets - you can load,store,delete, check and test Commandlets -- the Commandlets can be loaded to the webinterface by clicking on the list -- the Json-Structure can be checked on the WebInterface - -In the API-URL and in the json-payload you have to replace the real values from the Alexa-Webinterface with the following placeholders. For testing functions its not really neccessary to use the placeholders. - -This plugin for smarthomeNG is mainly based on the informations of -[Lötzimmer](https://blog.loetzimmer.de/2017/10/amazon-alexa-hort-auf-die-shell-echo.html) ,[Apollon77](https://github.com/Apollon77/alexa-remote) and the [openhab2](https://community.openhab.org/t/released-openhab2-amazon-echo-control-binding-controlling-alexa-from-openhab2/37844) - -Special thanks to Jonofe from the [Edomi-Forum](https://knx-user-forum.de/forum/projektforen/edomi/1240964-alexa-smarthome-skill-payload-version-3) who spent a nigth and half an evenning to support me with SSML. -#### !! So many thanks for the very good research and development in the past !! - -## table of content - -1. [PlaceHolders](#placeholders) -2. [Change Log](#changelog) -3. [Requirements](#requirements) -4. [Cookie](#cookie) -5. [Configuration](#config) -6. [functions](#functions) -7. [Web-Interface](#webinterface) -8. [How to implement new Commands](#newCommand) -9. [Tips for existing Command-Lets](#tipps) - -### Existing Command-Lets - - -- Play (Plays the last paused Media) -- Pause (pauses the actual media) -- Text2Speech (sends a Text to the echo, echo will speak it) -- StartTuneInStation (starts a TuneInRadiostation with the guideID you send) -- SSML (Speak to Text with [Speech Synthesis Markup Language](https://developer.amazon.com/docs/custom-skills/speech-synthesis-markup-language-ssml-reference.html)) -- VolumeAdj (adjusts the volume during playing some media not working from webinterface test functions) -- VolumeSet (sets the volume to value from 0-100 percent) - - -### Placeholders : -```yaml - = Value to send as alpha - = Value to send as numeric -"#item.path/#" = item-path of the value that should be inserted into text or ssml - = SerialNo. of the device where the command should go to - = device family - = deviceType - = OwnerID of the device -``` -#### !! Please keep in mind to use the "<", ">", "#" and "/#" to qualify the placeholders !! - -## ChangeLog - -#### 2021.02.10 Version 1.0.3 - -- added MFA for Auto-Login -- added new Parameter (mfa_secret) in the etc/plugin.yaml -- added Step by Step Setup in Web-IF for MFA -- added public function to get the ToDo-List -- added public function to get the Shopping-List - -#### 2020.03.20 Version 1.0.2 - -- changed public function "send_cmd_by_curl" to "send_cmd" -- removed pycurl -- changed Communication to Python Requests -- added translation for the Web-Interface -- added public function "get_last_alexa" - -#### 2018.07.26 Version 1.0.1 -- Encoding credentials now possible on the Web-Interface (for security reason use this function to encode you credentials) - -#### 2018.05.20 Version 1.0.1 -- replaced lib.scheduler with self.scheduler_add - -#### 2018.05.19 - Version 1.0.1 -- changed version to 1.0.1 -- changed to lib.item and lib.scheduler -- the credentials have to be stored in base64 encoded -- added Login / LogOff Button to the Web-Interface -- added Auto-Login function - when there is no cookie-file with correct values and credentials are specicified, the plugin automaticaly logs in -- the log-in (the cookie) will be refreshed after the login_update_cycle -- changed methods-names and parameters to lower case and underscore separated names - - -#### 2018.04.30 - Version 1.0.0 -- added CommandLet for SSML-Support -- added CommandLet for Play (Plays the paused media) -- added CommandLet for Pause (pauses media) -- added CommandLet for VolumeAdj (only working while media is playing, not working from test functions on the webinterface) -- added CommandLet for VolumeSet (working all the time) -- added CommandLet for LoadPlayerInfo (right now loaded but nowhere stored) -- added Item to enable AlexaRemoteControl by UZSU - -### Changes Since version 1.x.x - -- no Changes, first Version - - - -## Requirements - - -### Needed software - -* smarthomeNg 1.5.2 and above for the web-interface -* needs Python requests -* a valid [Cookie](#cookie) from an alexa.amazon-Web-Site Session -* if you work with Autologin the credentials have to be entered "base64"-encoded. You can encode you credentials on the web-interface of the plugin "user.test@gmail.com:your_pwd" you will get ```dXNlci50ZXN0QGdtYWlsLmNvbTp5b3VyX3B3ZA==``` . -So please enter ```dXNlci50ZXN0QGdtYWlsLmNvbTp5b3VyX3B3ZA==``` in the /etc/plugin.yaml - -If you don trust the website for encoding you credential, you can do it in the python-console. -Open a terminal and try the following code. - -``` -python3 -import base64 -base64.b64encode('user.test@gmail.com:your_pwd'.encode('utf-8')) - -you will get - -b'dXNlci50ZXN0QGdtYWlsLmNvbTp5b3VyX3B3ZA==' - -use - -dXNlci50ZXN0QGdtYWlsLmNvbTp5b3VyX3B3ZA== - -for your credentials -``` - - - -### Supported Hardware - -* all Amazon Echo-Devices - -## Cookie - -First possibility - without Credentials : - -Plugins are available for most of the common browsers. -After installing the plugin you have to login to your alexa.amazon-Web console. Now Export the cookie by using the plugin. -Open the cookie-file with a Texteditor select all and copy it to the clipboard. -Go to the Webinterface of the plugin and paste the content of the cookie-file to the textarea on Tab "Cookie-Handling". Store the cookie. -When the cookie was successfull stored you can find you Echo-Devices on the Tab with the Alexa-devices. - -Second possibility - with Credentials : - -When the plugin will be started and credentials are found in plugin.yaml, the plugin tests if the informations in the cookie-file are still guilty. If not the plugin tries to login with the credentials himself and stores the informations in the cookie-file. The cookie will updated in the cycle specified in "login_update_cycle" in the plugin.yaml - -## Configuration - -### plugin.yaml - -The plugin needs to be defined in the /etc/plugin.yaml in this way.

-The attributes are :
-plugin_name -> fix AlexaRc4shNG
- -cookiefile -> the path to the cookie-file. Here it will stored from the Web-Interfache. Take care that you have write-permissions
-host -> the adress of you Alexa-WebInterface
-Item2EnableAlexaRC->Item controlled by UZSU or something else which enables the communication to Alexa-Amazon-devices. if you leave it blank the communication is enabled all the time 24/7. This item is only checked during update_item in smarthomeNG. If you use the API directly from a logic or from the Webinterface the item will not be checked. In logics you have to check it yourself.

AlexaCredentials->User and Password for the Amazon-Alex-WebSite for automtic login
-alexa_credentials-> user:pwd (base64 encoded)
-item_2_enable_alexa_rc -> Item to allow smarthomeNG to send Commands to Echo's
-login_update_cycle->seconds to wait for automatic Login in to refresh the cookie -mfa_secret-> The MFA-Secret you got from Amazon-Website (fill it out with the Web-Interface) - - -```yaml -AlexaRc4shNG: - plugin_name: alexarc4shng - cookiefile: /usr/local/smarthome/plugins/alexarc4shng/cookies.txt - host: alexa.amazon.de - item_2_enable_alexa_rc: Item_to_enable_Alexaremote - alexa_credentials: : - login_update_cycle: 432000 - mfa_secret: -``` - - - -### items.yaml - -The configuration of the item are done in the following way : -

-alexa_cmd_01: comparison:EchoDevice:Commandlet:Value_to_Send - - -### supported comparisons are : - -"True", "False" and for numeric values "<=",">=","=","<",">" - -#### Sample to switch on a Radiostation by using TuneIN

-```yaml -Value = True means the item() becomes "ON" -EchodotKueche = Devicename where the Command should be send to StartTuneInStaion = Name of the Commandlet -s96141 = Value of the Radiostation (here S96141 = baden.fm) -``` - -example: -` -alexa_cmd_01: True:EchoDotKueche:StartTuneInStation:s96141 -` -#### Sample to send Text with item-value included based on value lower then 20 degrees

- -```yaml -Value = <20.0 - send command when value of the item becomes less then 20.0 -EchodotKueche = Devicename where the Command should be send to -Text2Speech = Name of the Commandlet -Value_to_Send = Die Temperatur in der Kueche ist niedriger als 20 Grad Die Temperatur ist jetzt #test.testzimmer.temperature.actual/# Grad -``` - -```yaml -#test.testzimmer.temperature.actual/# = item-path of the value that should be inserted -``` -example:
 -` -alexa_cmd_01: <20.0:EchoDotKueche:Text2Speech:Die Temperatur in der Kueche ist niedriger als 20 Grad Die Temperatur ist jetzt #test.testzimmer.temperature.actual/# Grad -` - -You can find the paths of the items on the backend-WebInterface - section items. - -#### alexa_cmd_XX - -You can specify up to 99 Commands per shng-item. The plugin scanns the item.conf/item.yaml during initialization for commands starting with 01 up to 99. - -Please start all the time with 01 per item, the command-numbers must be serial, dont forget one. The scan of commands stops when there is no command found with the next number - -#### Example - -Example for settings in an item.yaml file : - -```yaml -# items/my.yaml -%YAML 1.1 ---- - -OG: - - Buero: - name: Buero - Licht: - type: bool - alexa_name: Licht Büro - alexa_description: Licht Büro - alexa_actions: TurnOn TurnOff - alexa_icon: LIGHT - alexa_cmd_01: True:EchoDotKueche:StartTuneInStation:s96141 - alexa_cmd_02: True:EchoDotKueche:Text2Speech:Hallo das Licht im Buero ist eingeschalten - alexa_cmd_03: False:EchoDotKueche:Text2Speech:Hallo das Licht im Buero 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' - -``` -Example for settings in an item.conf file : - -```yaml -# items/my.conf - -[OG] - [[Buero]] - name = Buero - [[[Licht]]] - type = bool - alexa_name = "Licht Büro" - alexa_description = "Licht Büro" - alexa_actions = "TurnOn TurnOff" - alexa_icon = "LIGHT" - alexa_cmd_01 = '"True:EchoDotKueche:StartTuneInStation:s96141" - alexa_cmd_02 ="True:EchoDotKueche:Text2Speech:Hallo das Licht im Buero ist eingeschalten" - alexa_cmd_03 = "False:EchoDotKueche:Text2Speech:Hallo das Licht im Buero 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 - -``` - -### logic.yaml -Right now no logics are implemented. But you can trigger the functions by your own logic - - -## Plugin-functions - -The plugin provides the following publich functions. You can use it for example in logics. - -### send_cmd(dvName:str, cmdName:str, mValue:str) - -example how to use in logics: - -```yaml -sh.AlexaRc4shNG.send_cmd("yourDevice", "Text2Speech", "yourValue") ---- -sh.AlexaRc4shNG.send_cmd('Kueche','Text2Speech','Der Sensor der Hebenlage signalisiert ein Problem.') -``` -Sends a command to the device. "dvName" is the name of the device, "cmdName" is the name of the CommandLet, mValue is the value you would send. -You can find all this informations on the Web-Interface. -You can also use the [placeholders](#placeholders) - -- the result will be the HTTP-Status of the request as string (str) - -### get_last_alexa() - -This function returns the Device-Name of the last Echo Device which got a voice command. You can use it in logics to trigger events based on the last used Echo device. - -```yaml -myLastDevice = sh.AlexaRc4shNG.get_last_alexa() - -``` - -### get_list(type:str) - -This function returns the ToDo or the Shopping list - depending on "type" as dict
- -valid types are : -```yaml - 'SHOPPING_LIST' - 'TO_DO' -``` - - -```yaml -sh.AlexaRc4shNG.get_list(type:str) -``` -## Example logic to fill Items with List-Infos - -
-
-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)
-
-
- -## Example to show lists in smartVisu with status.activelist -
-
-status.activelist('','Alexa_Lists.list.todo','value','date','value','info')
-
-status.activelist('','Alexa_Lists.list.shopping','value','date','value','info')
-
-
- -### Ergebnis : -![PlaceHolder](./assets/Alexa_lists.jpg "jpg") - - - -# Web-Interface - -The Webinterface is reachable on you smarthomeNG server here :
- -http://yourserver:8383/plugins/alexarc4shng/ - -## Cookie-Handling - -On the Webinterface you can store you cookie-file to the shng-Server. -Export it with a cookie.txt AddOn from the browser. Copy it to the clipboard. -Paste it to the textarea in the Web-Interface and Store it. - -Now the available devices from your alexa-account will be discoverd an shown on the second tab. - -You can also login / logoff when credentials are available. Please see results in the textarea on the right. Please refresh page manually after successfull login via the Web-Interface. - -![PlaceHolder](./assets/webif1.jpg "jpg") - -## Alexa devices - -By click on one device the device will be selected as acutal device for tests. -![PlaceHolder](./assets/webif2.jpg "jpg") - -## Command-Handling - -The Web-Interface gives help to define new Command-Lets. How you get the informations for new Commands see [section New Commands](#newCommand) - -Here you can define new Command-Lets, test them, save and delete them. -You can check the JSON-Structure of you payload. - -When you click on an existing Command-Let it will be load to the Web-Interface. - -You can enter test values in the field for the values. Press Test and the command will be send to the device. You get back the HTTP-Status of the Request. - -For test dont modify the payload, just use the test-value-field - -![PlaceHolder](./assets/webif3.jpg "jpg") -
- -## How to create new Command-Lets (spy out the Amazon-Web-Interface) - -#### This documentation is based on Google-Chrome, but it's also possible to do this with other browsers. - -Open the Web-Interface for Alexa on Amazon. Select the page you want to spy out. Before click the command open the Debugger of the browser (F12). Select the network tab. -When you click the command that you want to spy out the network traffic will be displayed in the debugger. Here you can get all the informations you need. -Normally information will be send to amazon. So you have to concentrate on Post - Methods. - - -![PlaceHolder](./assets/pic1.jpg "jpg") -
-
-As example to spy out the station-id of a TuneIn Radio Station-ID you will it see it directly on context when you move your mouse to the post-command. -You can copy the URL to the Clipboard an use is it in the AlexaRc4shNG. - -You can also copy it as cUrl Paste it into an editor and can find the payload in the --data section of the curl - -
-
- -![PlaceHolder](./assets/pic2.jpg "jpg") - -For some commands you need to now the payload. You can get this by spying out the data. You have to select the network command. Then select the tab with Headers. In the bottom you will find the form-data. You can copy the payload to the clipboard an paste it into the AlexaRcshNG-WebInterface. - - -![PlaceHolder](./assets/pic3.jpg "jpg") - -#### !! Dont forget to replace the values for deviceOwnerCustomerIdcustomerID serialNumber, serialNumber, family with the placeholders !! -``` - - - - - -!! for the Values !! - - (for alpha Values) - (for numeric Values ) - -``` - -## Tips for existing Command-Lets : - -#### TuneIn -You have to specify the guideID from Amazom as stationID "mValue". Station-Names are not supported right now. -for example try the following: - -To locate your station ID, search for your station on TuneIn.com. Access your page and use the last set of digits of the resulting URL for your ID. For example: -If your TuneIn.com URL is 'http://tunein.com/radio/tuneinstation-s######/', then your station ID would be 's######' -(https://help.tunein.com/what-is-my-station-or-program-id-SJbg90quwz) - -#### SSML -You have to put the SSML-Values into -``` - -``` - -Find complete documentation to SSML [here](https://developer.amazon.com/docs/custom-skills/speech-synthesis-markup-language-ssml-reference.html) - -example : -``` - -I want to tell you a secret.I am not a real human.. - Can you believe it? - -``` - -You can also use [SpeechCons](https://developer.amazon.com/docs/custom-skills/speechcon-reference-interjections-german.html#including-a-speechcon-in-the-text-to-speech-response) - -example -``` - - Here is an example of a speechcon. - ach du liebe zeit.. - -``` -## Credits - -The idea for writing this plugin came from henfri. Got most of the informations from : http://blog.loetzimmer.de/2017/10/amazon-alexa-hort-auf-die-shell-echo.html (German). Thank you Alex! A lot of code came from Ingo. He has done the alexa iobrokern implementation https://github.com/Apollon77 Thank you Ingo ! Also a lot of informations come from for the open-hab2 implemenation! Thank you [Michael](https://community.openhab.org/t/released-openhab2-amazon-echo-control-binding-controlling-alexa-from-openhab2/37844) - -Special thanks to Jonofe from the Edomi-Forum who spent a nigth and half an evenning to support my with SSML. Thank you Andre. -#### !! So many thanks for the very good research and development) -## Trademark Disclaimer - -TuneIn, Amazon Echo, Amazon Echo Spot, Amazon Echo Show, Amazon Music, Amazon Prime, Alexa and all other products and Amazon, TuneIn and other companies are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them. diff --git a/alexarc4shng/user_doc.rst b/alexarc4shng/user_doc.rst index 73f3f6089..482055d9a 100755 --- a/alexarc4shng/user_doc.rst +++ b/alexarc4shng/user_doc.rst @@ -9,13 +9,50 @@ alexarc4shng .. image:: webif/static/img/plugin_logo.png :alt: plugin logo - :width: 300px - :height: 300px + :width: 650px + :height: 350px :scale: 50 % :align: left -Plugin zur Steuerung von Amazon Echo Geräten Zugriff via Web-Browser API und Cookie. +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 + +Cookie +------ + +Erste Möglichkeit - ohne Anmeldedaten: + +Es gibt Plugins für die meisten gängigen Browser. Nach der Installation des Plugins müssen Sie sich in Ihrer alexa.amazon-Webkonsole anmelden. +Exportieren Sie nun das Cookie mithilfe des Plugins. Öffnen Sie die Cookie-Datei mit einem Texteditor, +markieren Sie alles und kopieren Sie es in die Zwischenablage. Gehen Sie zur Web-Benutzeroberfläche des Plugins +und fügen Sie den Inhalt der Cookie-Datei in das Textfeld auf dem Tab "Cookie-Handling" ein. Speichern Sie das Cookie. +Wenn das Cookie erfolgreich gespeichert wurde, finden Sie Ihre Echo-Geräte im Tab mit den Alexa-Geräten. + +Zweite Möglichkeit - mit Anmeldedaten: + +Wenn das Plugin gestartet wird und Anmeldedaten in der plugin.yaml gefunden werden, überprüft das Plugin, +ob die Informationen in der Cookie-Datei noch gültig sind. Falls nicht, versucht das Plugin, sich selbst mit den +Anmeldedaten anzumelden und speichert die Informationen in der Cookie-Datei. Das Cookie wird im unter "login_update_cycle" +in der plugin.yaml angegebenen Zyklus aktualisiert. + +Anmeldedaten +------------ + +Nutzername und Passwort können im Web Interface oder via Python entsprechend kodiert werden + +.. code-block:: python + + import base64 + base64.b64encode("user.test@gmail.com:your_pwd".encode("utf-8")) Konfiguration @@ -23,49 +60,299 @@ Konfiguration Die Informationen zur Konfiguration des Plugins sind unter :doc:`/plugins_doc/config/alexarc4shng` beschrieben. +plugin.yaml +----------- -Web Interface -============= +.. code-block:: yaml -Das AlexaRc4shNG Plugin verfügt über ein Webinterface.Hier werden die Zugangsdaten zur Amazon-Web-Api (Cookie) gepflegt. -Es können neue Kommandos erstellt werden + AlexaRc4shNG: + plugin_name: alexarc4shng + cookiefile: /usr/local/smarthome/plugins/alexarc4shng/cookies.txt + host: alexa.amazon.de + item_2_enable_alexa_rc: + alexa_credentials: : (kodiert!) + login_update_cycle: 432000 + mfa_secret: -.. important:: +items.yaml +---------- - Das Webinterface des Plugins kann mit SmartHomeNG v1.5.2 und davor **nicht** genutzt werden. - Es wird dann nicht geladen. Diese Einschränkung gilt nur für das Webinterface. Ansonsten gilt - für das Plugin die in den Metadaten angegebene minimale SmartHomeNG Version. +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. +.. important:: + 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: -Aufruf des Webinterfaces ------------------------- +.. code-block:: yaml -Das Plugin kann aus dem backend aufgerufen werden. Dazu auf der Seite Plugins in der entsprechenden -Zeile das Icon in der Spalte **Web Interface** anklicken. + alexa_cmd_01: comparison:EchoDevice:Commandlet:Value_to_Send -Außerdem kann das Webinterface direkt über ``http://smarthome.local:8383/plugins/alexarc4shng`` aufgerufen werden. +Unterstützte Vergleiche (comparison): +- "True" oder "False" für boolsche Werte +- für numerische Werte "<=", ">=", "=", "<", ">" Beispiele ---------- +========= + +Radiostation +------------ + +.. code-block:: yaml + + 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: + +.. code-block:: yaml + + 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 +----------------------- + +.. code-block:: yaml + + 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 + +.. code-block:: Python + + 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 + +.. code-block:: HTML + + status.activelist('','Alexa_Lists.list.todo','value','date','value','info') + status.activelist('','Alexa_Lists.list.shopping','value','date','value','info') + +.. image:: assets/Alexa_lists.jpg + :class: screenshot + + +Platzhalter +=========== -Folgende Informationen können im Webinterface angezeigt werden: +- = Value to send as alpha +- = Value to send as numeric +- "#item.path/#" = item-path of the value that should be inserted into text or ssml +- = SerialNo. of the device where the command should go to +- = device family +- = deviceType +- = OwnerID of the device -Oben rechts werden allgemeine Parameter zum Plugin angezeigt. +.. important:: + + 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. + +.. image:: assets/pic1.jpg + :alt: Browser Debugger + :class: screenshot + +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. + +.. image:: assets/pic2.jpg + :alt: Post Befehl + :class: screenshot + +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. + +.. image:: assets/pic3.jpg + :alt: Header + :class: screenshot + +Vergessen Sie nicht, die Werte für deviceOwnerCustomerId, customerID, serialNumber, family und Werte durch die Platzhalter zu ersetzen + +.. code-block:: text + + + + + + (für Alpha-Werte) + (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 -Im ersten Tab kann das Cookie File gespeichert werden - in die Textarea via Cut & Paste einfügen und speichern: +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. .. image:: assets/webif1.jpg :class: screenshot +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: .. image:: assets/webif2.jpg :class: screenshot -Im dritten Tab werden die Commandlets verwaltet - mit Click auf die Liste der Commandlets wird dieses ins WebIF geladen: +Kommandos verwalten +------------------- + +Im dritten Tab werden die Commandlets verwaltet - mit Klick auf die Liste der Commandlets wird dieses ins WebIF geladen: .. image:: assets/webif3.jpg :class: screenshot +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. + +.. important:: + + Für Tests sollten Sie die Payload nicht ändern, sondern einfach das Testwert-Feld verwenden. + +SSML Hinweise +^^^^^^^^^^^^^ + +Auszugebender Text ist in Tags einzubetten. + +Beispiel + +.. code-block:: + + + I want to tell you a secret.I am not a real human.. + Can you believe it? + + +Außerdem können SpeechCons wie folgt genutzt werden. + +.. code-block:: + + + Here is an example of a speechcon. + ach du liebe zeit.. + + +Weitere Infos: `SSML `_ und `SpeechCons `_ + +Danksagung +========== + +- `Alex von Loetzimmer `_ +- `Ingo `_ +- `Michael, OpenHAB2 `_ +- Jonofe vom Edomi-Forum + +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.