Inhalt

Übersicht

Das Alexa Custom Skill Modul stellt einen IPS WebHook I/O zur Verfügung stellt, über den ein Alexa Custom Skill mit Deiner IP Symcon Installation kommunizieren kann.

Im folgenden Bild siehst Du, wie die Kommunikation zwischen IP Symcon und den Amazon Servern abläuft, und welche Komponenten daran beteiligt sind:

Modul-Informationen

NameAlexa Custom Skill
IPS GUID{F416D335-7D66-4B91-97AA-02C7F4E3D343}
FQCN\AlexaCustomSkill
Funktions-PrefixACSWebHook

Einrichtung

Folge diesen Schritten, um eine Instanz des Moduls für einen eigenen Alexa Custom Skill hinzuzufügen:

Öffne in der IP Symcon Management Console die logische Baumansicht und klicke auf den Abschnitt I/O Instanzen rechts.

Klicke danach auf Objekt hinzufügen und dann auf Instanz hinzufügen:

Ein neues Fenster öffnet sich.

Wähle das "Gerät" Alexa Custom Skill aus und klicke auf den Button Weiter:

Auf der nächsten Seite kannst Du im Feld Name einen eigenen Namen für die Skill Instanz vergeben.

Klicke anschließend auf den Button OK:

IPS legt nun die Instanz an und öffnet die Konfigurationsseite.

Konfiguration

Konfigurationsseite öffnen

Um die Patami Custom Skill Instanz zu konfigurieren, doppelklicke in der IP Symcon Management Console auf die Alexa Custom Skill Instanz bei den I/O Instanzen:

Ein neues Tab öffnet sich:

Zugangsdaten hinterlegen

Beim Aufruf des Custom Skills durch Alexa wird die Applikation ID des Skills und die Amazon User ID, unter der der Skill in der Amazon Developer Console angelegt worden ist, übergeben.

Sowohl die Application ID als auch die User ID sind spezifisch für den Custom Skill, den Du über die Amazon Developer Console angelegt hast.

Insbesondere ist die User ID nicht für alle Deine Custom Skills dieselbe.

Aus Sicherheitsgründen überprüft das Modul diese Informationen, um sicherzustellen, dass keine unautorisierten Zugriffe stattfinden können.

Die entsprechenden Daten musst Du auf der Konfigurationsseite eintragen:

Trage in die beiden Felder die folgenden Informationen ein:

Alexa Custom Skill Applikation ID

Hier musst Du die Application ID des Skills eintragen.

Du findest sie auf der Seite Skill Information in der Konfiguration des Customs Skills in der Amazon Developer Console:

Alexa Custom Skill User ID

Hier musst Du die User ID des Amazon Benutzerkontos eintragen, mit dem der Custom Skill angelegt wurde.

Um die User ID herauszufinden, kannst Du auf der Seite Test in der Konfiguration des Custom Skills in der Amazon Developer Console mit dem Service Simulator eine Anfrage stellen.

Im Feld Service Request findest Du dann die Anfrage der Amazon-Server im JSON-Format. Das Feld userId enthält den gesuchten Wert:


Solange Du in die beiden Felder nichts oder einen ungültigen Wert eingibst, wird die Instanz als fehlerhaft markiert werden. Hierbei erhältst Du entweder Das Format der Application ID ist ungültig oder Das Format der User ID ist ungültig als Fehlermeldung beim Übernehmen der Konfiguration.

Launch Request Intent festlegen

Beim Aufruf eines Custom Skills ohne Intent (z.B. mit Starte Demo) wird ein spezieller Request von den Amazon Servern an die Instanz geschickt, der sogenannte LaunchRequest.

Auf der Konfigurationsseite kannst Du im folgenden Feld eine Alexa Custom Skill Intent Instanz auswählen, die in diesem Fall aufgerufen werden soll:

Du kannst hier natürlich erst eine Intent Instanz auswählen, nachdem Du eine angelegt hast. Hier findest Du eine Anleitung, was dafür zu tun ist.

Solange keine Instanz hinterlegt ist, wird Alexa bei einem Launch Request mit einer Fehlermeldung antworten, die von der Custom Skill Instanz generiert wird.

Beachte bitte, dass bei einem LaunchRequest keine Slots übergeben werden. Falls der ausgewählte Intent zwingend einen Slot voraussetzt, wird ein Fehler auftreten.

Standardsprache auswählen

Die Amazon-Server übermitteln bei einem Request die Sprache, in der die Anfrage durch den Benutzer gestellt wurde.

Hierbei können nur Sprachen (bzw. Locales) vorkommen, die in der Konfiguration des Custom Skills in der Amazon Developer Console festgelegt worden sind.

Kommt es bei der Verarbeitung der Anfrage durch die Instanz zu einem Fehler, und die Sprache kann nicht aus den übermittelten Daten ermittelt werden, dann antwortet der Skill in der hier konfigurierten Standardsprache.

Auf der Konfigurationsseite kannst Du im folgenden Feld die Standardsprache für diesen Fall festlegen:

Beim Erstellen der Instanz wird hier standardmäßig die Sprache der IP Symcon-Installation vorausgewählt.

WebHook Pfad festlegen

Die Amazon-Server kommunizieren mit dem Custom Skill über den IPS WebHook-Dienst.

Der Instanz registriert selbst einen WebHook, wobei Du den entsprechenden Pfad-Teil der von Amazon verwendeten URL selbst konfigurieren kannst und musst.

Auf der Konfigurationsseite kannst Du im folgenden Feld den Pfad festlegen:

Der in diesem Beispiel konfigurierte Pfad entspricht der URL https://deinsymconhostname/hook/alexa/custom.

Der Pfad darf nicht mit einem / (Forward Slash) beginnen.

Nach dem Übernehmen der Konfiguration wird der WebHook registriert. Sollte vorher ein anderer Pfad konfiguriert gewesen sein, wird die Registrierung entsprechend angepasst.

Für die Konfiguration des Custom Skills in der Amazon Developer Console wirst Du die WebHook URL des Skills benötigen. Im Formular gibt es einen Button, der die URL anzeigt. Weitere Informationen findest Du in diesem Abschnitt.

Rückmeldungen der Built-In Intents festlegen

Im Intent-Schema von Custom Skills können von Amazon vordefinierte, sogenannte Built-In Intents verwendet werden.

Der Custom Skill unterstützt ohne weitere Konfiguration drei dieser Built-In Intents, und zwar:

Intent-NameBeschreibungBeispiel-Sätze
AMAZON.CancelIntentBeendet die Alexa-Session.

abbrechen

abbreche

vergiss es

AMAZON.StopIntentBeendet die Alexa-Session.

stopp

hör endlich auf

aufhören

AMAZON.RepeatIntentWiederholt die letzte Antwort des Skills in der Alexa-Session.

wiederhole (bitte)

wiederhole das (bitte)

sage das noch mal (bitte)

Während der AMAZON.RepeatIntent einfach die letzte Ausgabe wiederholt und somit keine weitere Konfiguration benötigt, kannst Du bei den beiden anderen Intents festlegen, welche Antwort der Skill geben soll.

Die Antwort kannst Du hierbei über die folgenden Felder im Konfigurationsformular festlegen:

In den Eingabefeldern kannst Du für jede vom Skill unterstützte Sprache den Text der Antwort eingeben, die der Skill beim Aufruf des jeweiligen Intents geben soll.

Über das Dropdown kannst Du außerdem auswählen, ob der Text als einfacher Text (d.h. ohne weitere Auszeichnung) oder als Speech Synthesis Markup Language (SSML) interpretiert werden soll.

Du kannst das vordefinierte Verhalten dieser im Custom Skill eingebauten Intents verändern, indem Du eigene Intent Instanzen mit demselben Intent-Namen anlegst Du dort ein anderes Verhalten konfigurierst. Von Dir angelegte Intents mit demselben Intent-Namen werden immer bevorzugt.

Sonstiges

In der Testumgebung am Ende des Konfigurationsformular wird die aktuelle Version des Custom Skill Moduls anzeigt.

Um das Modul zu aktualisieren, musst Du auf der Konfigurationsseite der Patami Framework Instanz das Patami Framework aktualisieren.

Außerdem stehen hier einige Buttons zur Verfügung:

URL anzeigen

Mit diesem Button kannst Du die URL des Skills ganz einfach ermitteln, falls Du den IP-Symcon Connect Dienst nutzt:

Nachdem Du auf den Button geklickt hast, wird IPS ein neues Browserfenster öffnen und zur URL des Skills navigieren:

Du kannst nun die URL aus der Adresszeile des Browsers in die Zwischenablage kopieren und diese für die Konfiguration des Custom Skills in der Amazon Developer Console verwenden.

Die Fehlermeldung des Skills im Browserfenster kannst Du ignorieren, da bei dieser Art des Zugriffs keine gültigen Daten an den Skill übermittelt werden (können).

Du kannst den IP-Symcon Connect Dienst nur verwenden, wenn Du eine aktive IPS Subscription hast.

Solltest Du keine Subscription haben, kannst Du diese im Shop der Symcon GmbH kaufen.

Natürlich kannst Du stattdessen auch ein NAT oder PAT auf Deinem Internet Router konfigurieren oder einen eigenen Reverse Proxy Dienst verwenden. HIerbei ist jedoch darauf zu achten, dass die Amazon Server nur mit Endpunkten kommunizieren, die ein gültiges, von einer öffentlichen und von Amazon vertrauten Zertifizierungsstelle signiertes SSL Zertifikat haben bzw. wenn Du ein eigenes Zertifikat in der Konfiguration des Skills in der Amazon Developer Console hochlädst. Was hierfür genau zu tun ist, wird in dieser Dokumentation nicht näher beschrieben, aber wenn Du das so machst, ist davon auszugehen, dass Du die notwendigen technischen Kenntnisse hast, um das selbst zu konfigurieren. Ansonsten lässt Du es wohl besser sein und gibst das Geld für die Subscription aus (Zwinkern)

Issue erstellen

Beim Klick auf den Button wird ein neues Issue im Issue Tracker des Patami Frameworks geöffnet. Hier kannst Du Fehler melden oder ein neues Feature vorschlagen.

Lizenz anzeigen

Beim Klick auf den Button wird die Lizenz des Frameworks geöffnet.

Dokumentation anzeigen

Beim Klick auf den Button wird diese Dokumentation-Seite geöffnet.

Versionhinweise anzeigen

Beim Klick auf den Button werden die Versionshinweise des Frameworks geöffnet.

Funktionen

Die folgenden Funktionen werden von IPS als globale Modulfunktionen mit dem Prefix ACSWebHook registriert:

Aus technischen Gründen hat die Modul-Klasse weitere Public-Methoden, die ebenfalls von IPS als globale Funktionen registriert werden.

Sie sind jedoch für interne Zwecke gedacht und sollten nicht verwendet werden.

Fehlerbehandlung

Beim Entwickeln eigener Custom Skills ist es hilfreich, detaillierte technische Informationen zur Verfügung zu haben, um Fehler eingrenzen bzw. beheben zu können.

Hierfür bietet das Framework einige Möglichkeiten:

Debugging aktivieren

Die Custom Skill Instanz protokolliert im Debug Log der Instanz zahlreiche nützliche Informationen.

Um das Debug Log der Instanz zu öffnen, klicke auf den Button Debug auf der Konfigurationsseite der Instanz:

Ein neues Tab öffnet sich, in dem bei einer Anfrage der Amazon Server zahlreiche Informationen protokolliert werden.

Der folgende Screenshot enthält das Debug Log für einen Launch Request an das System Information Beispiel (es wurde gesagt: Alexa, frage System Informationen). Der GetInformation Intent hat den Benutzer begrüsst und stellte die Frage nach dem Objekttyp. Der Benutzer hat nicht geantwortet. Nach dem Reprompt und dem Timeout wurde die Session von Alexa geschlossen. Die entsprechende Benachrichtigung durch den Session Ended Request wurde ebenfalls protokolliert (inklusive dem Grund, wieso die Session durch Alexa beendet wurde).

PHP Fehler und Ausnahmen protokollieren

Bei bestimmten Fehlern in Deinen Execute() Skripten (oder auch bei Programmierfehlern im Framework) kann es passieren, dass das Framework nicht in der Lage ist, eine aussagekräftige Fehlermeldung als Sprachausgabe über Alexa auszugeben oder im Debug Log zu protokollieren.

In diesem Fall ist es nützlich, wenn Du das erweiterte Fehler-Logging durch das Patami Framework aktivierst. Folge hierzu dieser Anleitung.

Prüfe dann das IPS Systemlog (Tab Meldungen in der IP Symcon Management Console), ob Fehler protokolliert werden.

Endet die Ausgabe einer Anfrage an den Custom Skill mit einer Execute Function Start Meldung, so ist wahrscheinlich ein fataler Fehler im PHP Code Deiner Execute() Funktion enthalten.

Das Skript in der IP Symcon Management Console auszuführen ist normalerweise eine gute Möglichkeit, Fehler in Skripten zu finden. Dies funktioniert aber hier nicht, da sich Dein Code innerhalb einer Funktion befindet. Das IPS Systemlog wird jedoch wahrscheinlich Hinweise auf die Fehlerursache enthalten, wenn Du die Protokollierung von PHP Fehlern und Ausnahmen wie hier beschrieben aktivierst.

Aufrufe über den Service Simulator

Über den Service Simulator in der Amazon Developer Console kannst Du Anfragen an den Custom Skill stellen, ohne mit einem Alexa Gerät sprechen zu müssen.

Navigiere dazu auf die Seite Test der Konfiguration des Custom Skills:

Trage im Eingabefeld Enter Utterance die Anfrage ein, die Du stellen möchtest, und drücke dann die Eingabetaste.

Die von den Amazon Servern gestellte Anfrage findest Du im Feld Service Request. Die Antwort des IP Symcon Servers erscheint im Feld Service Response.

Der Service Simulator ist auch dann nützlich, wenn die Anfrage von Alexa an Deinen Custom Skill fehlschlägt. Unter Umständen kannst Du im Feld Service Response Hinweise auf die Fehlerursache finden.

Aufrufe über ein HTTP Request Tool

Sollte eine Abfrage über den Service Simulator keinen brauchbaren Hinweis auf die Fehlerursache liefern, so kannst Du mit einem Online HTTP Request Tool, wie z.B. Hurl.it, weitere Tests machen.

Führe dazu folgende Schritte aus:

Öffne ein Browserfenster und navigiere zu Hurl.it:

Führe die folgenden Schritte aus:

  1. Wähle im Dropdown POST aus.
  2. Füge die IP Symcon Connect URL des WebHooks ein. Folge dieser Anleitung, um die URL zu ermitteln.
  3. Klicke auf den Button + Add Body.

Ein Eingabefeld wird eingeblendet:

Führe nun die folgenden Schritte aus:

  1. Kopiere den Inhalt des Feldes Service Request aus dem Service Simulator in der Amazon Developer Console in das Eingabefeld.
  2. Klicke auf die Checkbox, um das Captcha zu lösen.
  3. Klicke den Button Launch Request, um die Anfrage abzusenden.

Die Anfrage wird ausgeführt und die Antwort (oder eventuell Fehlermeldungen) werden angezeigt: