Konfiguration - Übersicht

Die Konfiguration der Sprachsteuerung erfolgt durch "Hochladen" eines Textes in JSON-Format (Zeichenkodierung UTF-8) auf den HomeServer. Es wird empfohlen, diesen Text über einen geeigneten Texteditor z.B. Notepad++ zu erstellen bzw. zu editieren und über die Zwischenablage in das Textareafeld auf der Konfigurationsseite zu kopieren. Auf jeden Fall sollte man eine Sicherungskopie (Dateiendung .js) auf der Festplatte speichern.

Edit:zum Umschalten auf den Reiter zum Bearbeiten/Hochladen der JSON-Konfiguration.
Example:zum Umschalten auf den Reiter mit einem ein kurzen Beispiel für eine JSON-Konfiguration.
Upload to HomeServer:zum "Hochladen" (Speichern) des im Editor dargestellten Texts (JSON-Konfiguration) auf den HomeServer.
Bei Auswahl der Checkbox "check group address" wird geprüft, ob die verwendeten Gruppenadressen im HomeServer existieren.
Save to local Disk:zum Speichern des im Editor dargestellten Texts (JSON-Konfiguration) auf ihrer lokalen Festplatte.
Bei Auswahl der Checkbox "strip comments" wird die JSON-Konfiguration ohne evtl. vorkommende JavaScript Kommentare gespeichert.
Meldungszeile:zur Ausgabe von Meldungen wie z.B.: "JSON-Configuration saved successfully!"

Hinweis: Um Ihre Änderungen oder Anpassungen zu aktivieren, muss nach dem "Hochladen"" (Upload to HomeServer) auf den HomeServer mit dem jeweiligen Skill eine Gerätesuche durchgeführt werden.

Beim Smart Home Skill kann dies entweder über die "Alexa App->Smart Home->Geräte->Suche", oder per Sprachkommando "Alexa, suche meine Geräte" geschehen. Beim Custom Skill nur per Sprachkommando "Alexa, sage My Home suche KNX Objekte".

1. JSON-Notation

Die Gerätekonfiguration erfolgt im JSON-Format (siehe auch Wikipedia: JavaScript Object Notation).

Beispiel:
(unter der Annahme der Verwendung einer 3-stufigen Gruppenadresse; Gruppenadressen sind durch eigene Werte zu ersetzen)
{
  "devices": 
  [
    { "room":"Wohnzimmer", "targetTemperature":"2/1/1", "actualTemperature":"2/1/2", "text": "5/1/1",
      "appliances":
      [
        {"name":"Licht", "onOff":"1/1/1", "percent":"1/1/2", "aliases":["Deckenleuchte Wohnzimmer"]},
        {"name":"Stehleuchte", "onOff":"1/1/3"}
      ]
    },
    { "room":"Küche", "targetTemperature":"2/2/1", "actualTemperature":"2/2/2",
      "appliances":
      [
        {"name":"Licht", "onOff":"1/2/1"}
      ]
    }
  ],
  "mappings": {},
  "synonyms": {},
  "replies": {}
}

2. Geräte-Definition

Die Definition der steuerbaren Geräte wird im Abschnitt "devices": [] vorgenommen. Hier wird auch die Verknüpfung der Objektnamen, welche man in einem Sprachkommando verwendet, zu den zugehörigen KNX-Gruppenadressen festgelegt.
Die Konfiguration erfolgt hierbei über zwei Ebenen. Auf der "Ebene 1 - Room" werden die zu verwendenen Räume (Bereiche/Örtlichkeiten) definiert. Darunter auf "Ebene 1.1 - Appliance" werden die, sich in einem Raum befindlichen Geräte (Aktoren, Sensoren, ...) definiert.

Hinweis zum Smart Home Skill: Im Gegensatz zum Custom Skill, hat Amazon bei der Smart Home Skill API leider kein "Raumkonzept" vorgesehen. D.h. es gibt keine eigenständige Information, dass sich ein Gerät in einem bestimmten Raum befindet. Es existiert also nur ein Bezeichner (Name) - der sogenannte "Friendly Name" zur Identifikation eines Gerätes.
Bei Steuerung von Geräten in verschiedenen Räumen, hat man somit nur die Möglichkeit mit einem "Friendly Name" zu arbeiten, der sowohl den Gerätenamen als auch den Raumnamen enthält. Hierbei hat man die Wahl entweder den Raumnamen dem Gerätenamen als Prefix voranzustellen, oder als Suffix (vom Baustein bei Verwendung des "room"-Attributs verwendete Methode) anzuhängen.
Auch wenn Alexa im allgemeinen einen relativ guten Job macht, Formulierungen mit unterschiedlicher Satzstellung aus Raum- und Gerätenamen dem "Friendly Name" zuzuordnen (also z.B. eine Präposition zwischen Gerätename und Raumname zu ignorieren), werden Sprachkommandos bei exakter Verwendung des "Friendly Name" am besten verstanden.

2.1 Ebene 1 - Room

Beispiel:
{ "room":"Wohnzimmer", "targetTemperature":"2/1/1", "actualTemperature":"2/1/2", "text": "5/1/1" }, ...
Diese Ebene unterstützt nachfolgende Attribute:
AttributnameAttributwertDatentypBeispielHinweise
idIDString"WOH" optional - der vergegebene String muss eindeutig innerhalb der "Ebene 1 - Room" sein!
Durch die manuelle Vorgabe eines ID's, kann der per default automatisch generierte Wert überschrieben werden.
roomRaumnameString"Wohnzimmer" Name des Raums (Bereichs/Örtlichkeit).
zur Definition raumübergreifender Objekte kann das Attribut weggelassen werden
targetTemperatureSolltemperaturKNX-Gruppenadresse
16-Bit
(-671088,64..670760,96/EIS 5)
"2/1/1" KNX-Gruppenadresse welche zum Setzen und zur Abfrage der Solltemperatur verwendet werden soll.
Alexa, stelle das Wohnzimmer auf 21 Grad.
Alexa, wie ist das Thermostat im Wohnzimmer eingestellt?
actualTemperatureIsttemperaturKNX-Gruppenadresse
16-Bit
(-671088,64..670760,96/EIS 5)
"2/1/2" KNX-Gruppenadresse welche zur Abfrage der Isttemperatur verwendet werden soll.
Alexa, wie ist die Temperatur im Wohnzimmer?
text¹StatusberichtKNX-Gruppenadresse
14-Byte Text
"5/1/1" KNX-Gruppenadresse welche zur Statusbericht-Abfrage verwendet werden soll.
Alexa, frage My Home nach dem Statusbericht vom Wohnzimmer?
controlAufruf
Sub-Logikbaustein
KNX-Gruppenadresse
14-Byte Text
"5/2/1" Die möglichen Sprachkommandos hängen von dem aufzurufenden Sub-Logikbaustein ab.
appliancesGerätelisteArray[...] leitet die Liste der der "Ebene 1.1 - Appliance" Definitionen ein.
¹ nur für den Custom Skill relevant

2.1.1 Ebene 1.1 - Appliance

Beispiel:
{"name":"Licht", "onOff":"1/1/1", "percent":"1/1/2", "aliases":["Deckenleuchte Wohnzimmer"]}, ...
Diese Ebene unterstützt nachfolgende Attribute:
AttributnameAttributwertDatentypBeispielHinweise
idIDString"LI1" optional - der vergegebene String muss eindeutig innerhalb der "Ebene 1.1 - Appliance" sein!
Durch die manuelle Vorgabe eines ID's, kann der per default automatisch generierte Wert überschrieben werden.
nameGerätename
(Objektname)
String"Licht" Name des Geräts (Objekts). Falls der Raumname (Attribut "room" auf übergeordneter Ebene) nicht leer ist, wird dieser dem Gerätenamen angehängt.
Alexa, schalte das Licht im Wohnzimmer ein.
onOffwird verwendet bei
Einschalt und Ausschalt
Kommando
KNX-Gruppenadresse"1/1/1" KNX-Gruppenadresse, welche für einen Einschaltbefehl auf den Wert "onValue" bzw. bei einem Ausschaltbefehl auf den Wert "offValue" gesetzt wird.
bei Verwendung von onOff werden die beiden nachfolgenden Attribute on bzw. off ignoriert
Alexa, schalte das Licht im Wohnzimmer ein.
Alexa, schalte das Licht im Wohnzimmer aus.
onwird verwendet bei
Einschalt
Kommando
KNX-Gruppenadresse"1/1/1" KNX-Gruppenadresse, welche für einen Einschaltbefehl auf den Wert "onValue" gesetzt wird.
Alexa, schalte das Licht im Wohnzimmer ein.
offwird verwendet bei
Ausschalt
Kommando
KNX-Gruppenadresse"1/1/1" KNX-Gruppenadresse, welche für einen Ausschaltbefehl auf den Wert "offValue" gesetzt wird.
Alexa, schalte das Licht im Wohnzimmer aus.
onValueEinschaltwertNumber"1" Ist der Vorgabewert "1" nicht passend, kann hier der gewünschte Wert angegeben werden.
Die unter "onOff" bzw. "on" angegebene KNX-Gruppenadresse wird bei einem Einschaltbefehl auf diesen Wert gesetzt.
offValueAusschaltwertNumber"0" Ist der Vorgabewert "0" nicht passend, kann hier der gewünschte Wert angegeben werden.
Die unter "onOff" bzw. "off" angegebene KNX-Gruppenadresse wird bei einem Ausschaltbefehl auf diesen Wert gesetzt.
percentprozentuale SteuerungKNX-Gruppenadresse
8-Bit
(0..100%/EIS 6)
"1/1/2" KNX-Gruppenadresse, welche für die Steuerung mit Prozent-Werten verwendet wird.
Alexa, stelle das Licht im Wohnzimmer auf 50 Prozent.
Alexa, dimme das Licht im Wohnzimmer um 10 Prozent.
Alexa, erhöhe das Licht im Wohnzimmer um 10 Prozent.
text¹StatusberichtKNX-Gruppenadresse
14-Byte Text
"5/1/1" KNX-Gruppenadresse, welche zur Statusbericht-Abfrage verwendet wird.
Alexa, frage My Home nach dem Statusbericht der Beleuchtung im Haus?
value¹WertKNX-Gruppenadresse
"X/X/X" KNX-Gruppenadresse, welche bei einer Wertabfrage verwendet wird.
Alexa, frage My Home wie ist die Windstärke?
unit¹Einheit
Format
String
",1 km/h" Möglichkeit der Aufbereitung des vom HomeServer zurückgelieferten Wertes. Ist das erste Zeichen im Formatstring keines der Zeichen "? # . ," wird der Wert einfach angehängt.

Das "?" ermöglicht eine Umsetzung der Integer-Werte 0 bzw. 1 auf einen entsprechenden Text.
Syntax: "?TEXT_FUER_0;TEXT_FUER_1"
Beispiele: "?leer;voll", "?unten;oben", ...

Das "#" ermöglicht die Umsetzung einer Reihe von Integer-Werten auf einen entsprechenden Text. Das entsprechende Mapping muss in der Konfiguration unter "mappings" angelegt worden sein.
Syntax: "#MAPPINGNAME"
Beispiel: "#doorWindow2State", ...

Der "." bzw. das "," ermöglicht die Festlegung des zu verwendenden Trennzeichens und die Anzahl der auszusprechenden Nachkommastellen festzulegen.
Syntax: ",X EINHEIT"
Beispiele: ",2" (Aussprache mit Komma und 2 Nachkommastellen), ",1 km/h", ",0 grad", ",0 kilolux", ...
controlAufruf
Sub-Logikbaustein
KNX-Gruppenadresse
14-Byte Text
"5/2/1" Die möglichen Sprachkommandos hängen von dem aufzurufenden Sub-Logikbaustein ab.
aliasesListe der AliasnamenArray[...] Liste der alternativen Namen für dieses Gerät.
Achtung: Der Raumname wird bei Aliasnamen nicht angehängt.
type²GerätetypString"LIGHT" Typ des Geräts (Objekts):
  • LIGHT
  • BLINDS (nur Alexa-KNX interne Verwendung, erscheint in der Alexa-App als OTHER)
  • SMARTPLUG
  • OTHER
Diese Angabe wird bei einem späteren Übergang auf die Smart Home API V3 benutzt, um das Gerät in der Alexa-App entsprechend einzuordnen.
Für die bereits aktuell, durch die Angabe von "type":"BLINDS" bewirkten Änderungen siehe hier.
¹ nur für den Custom Skill relevant
² erst ab Baustein Version 1.1.0

3. Mappings (optional, und nur für den Custom Skill relevant)

Beispiel:
"mappings" : {
    "#doorWindow2State": {
      "0": "geschlossen",
      "1": "offen",
      "2": "gekippt"
    } 
}

4. Synonyme (optional, und nur für den Custom Skill relevant)

Über "synonyms" können Synonyme für Buchstabenfolgen (Wörter, Teilwörter) definiert werden, die für das Matching verwendet werden. Das Matching ist der Mechanismus bei dem versucht wird, für den im Sprachkommando verwendeten Gerätenamen, dass passende Gerät in der JSON-Konfiguration zu finden.

nur bis LBS Version < 1.1.0
Achtung: Es muss eine bestimmte Reihenfolge der zu ersetzenden Wörter für ein Synonym eingehalten werden: Wörter, die in einem anderen Wort komplett enthalten sind, müssen hinter diesem eingereiht werden. So ist z.B. die Reihenfolge "lichtszene", "szene" bzw. "leuchten", "leuchte" einzuhalten. Generell ist der Plural immer zuerst anzugeben. Des Weiteren ist darauf zu achten, dass ein zu ersetzendes Wort in nur einer der Listen verwendet wird.

Beispiel:
"synonyms" : {
  "LHT": ["leuchten", "leuchte",  "lampen", "lampe"],
  "RLL": ["jalousien", "jalousie", "rollladen", "rollo", "raffstores", "raffstore"]
}
Wird z.B. in der JSON-Konfiguration als Gerätename "Stehlampe" verwendet wird dies auf "StehLHT" abgebildet.
Wird z.B. im Sprachkommando "Stehleuchten" verwendet wird dies analog auch auf "StehLHT" abgebildet.
Somit wird in diesem Beispiel auch bei Verwendung des Wortes "Stehleuchten" im Sprachkommando das Gerät "Stehlampe" aus der JSON-Konfiguration verwendet.

Hinweis: Alexa liefert das Wort Rollladen an den Custom Skill manchmal mit zwei "l" und manchmal mit drei. Durch die zwischenzeitlich im Custom Skill implementierte phonetische Suche, wird unabhängig von der in der JSON-Konfiguration verwendeten Schreibweise, das Gerät trotzdem gefunden, solange die phonetische Suche nicht über die "settings"-Einstellung "phoneticSearch":false ausgeschaltet worden ist (Settings sind ab Logikbaustein Version 1.1.0 möglich).

5. Meldungen (optional, und nur für den Custom Skill relevant)

Über "replies" können nachfolgende Custom Skill Meldungen vom Benutzer festgelegt bzw. überschrieben werden:
Aktuell hinterlegte Standardmeldungen:
"replies": {
    "OK_MESSAGE": "Okay",
    "WELCOME_MESSAGE": "Hallo, ich bin zur Steuerung und Abfrage deines Smart Home bereit.",
    "WELCOME_REPROMPT": "Du kannst zum Beispiel sagen, schalte das Licht in der Küche an, oder wie ist die Temperatur im Wohnzimmer?, oder du kannst Beenden sagen, Was soll ich steuern oder abfragen?",
    "HELP_MESSAGE": "Mit diesem Skill können KNX Geräte über den <phoneme alphabet='ipa' ph='gira'/> Homeserver gesteuert und abgefragt werden. Weitere Informationen sind unter www.alexa-knx.de zu finden.",
    "HELP_REPROMPT": "Was soll ich steuern oder abfragen?",
    "STOP_MESSAGE": "Bis dann.",
    "SESSION_REPROMPT": "Was soll ich als nächstes steuern oder abfragen?"
}
Es können für einen Meldungstyp auch mehrere Meldungen in einem Array [] angegeben werden. In diesem Fall wird die auszugebende Meldung zufällig ausgewählt.

Beispiel für Rückmeldungen bei denen standardmäßig "Ok" ausgegeben werden würde:
"replies":{
    "OK_MESSAGE": [
      "<say-as interpret-as='interjection'>alles klar</say-as>", 
      "<say-as interpret-as='interjection'>bingo</say-as>", 
      "<say-as interpret-as='interjection'>okey dokey</say-as>", 
      "<say-as interpret-as='interjection'>tada</say-as>",
      "<say-as interpret-as='interjection'>wie du meinst</say-as>",
      "<say-as interpret-as='interjection'>klar</say-as>"
    ]
}
Beispiel wenn bei Steuerungsbefehlen nur Fehlermeldungen ausgegeben werden sollen:
"replies": {"OK_MESSAGE":"<break time='100ms'/>"}

6. Einstellungen (optional, und erst ab Logikbaustein Version 1.1.0)

"settings": {
    "phoneticSearch":true,
    "smartHome25PercentBlindsHack":false
}
Achtung: die Werte true/false müssen ohne Hochkomma eingegeben werden.

Über die Option "phoneticSearch" kann die phonetische Suche nach Geräte-/Raumnamen ein-(true)/ausgeschaltet(false) werden. Ist diese Option in den Settings nicht vorhanden ist die phonetische Suche standardmäßig eingeschaltet. Hinweis: Eine Änderung dieser Option wird erst mit der nächsten ""Suche nach Geräten/KNX Objekten" wirksam.

Über die Option "smartHome25PercentBlindsHack" kann im Zusammenspiel mit "type":"BLINDS" für den Smart Home Skill der Workaround, zum vollständigen öffnen/schließen von Rollläden/Jalousien, mittels des Kommandos "fahre hoch/runter" ein-(true)/ausgeschaltet(false) werden. Ist diese Option in den Settings nicht vorhanden ist der Workaround standardmäßig ausgeschaltet.