• Overview • Logic Sub-Modules • Examples • Custom Skill Lists

Configuration - Overview

The configuration of the voice control interface is done by uploading a text file in JSON format (UTF-8 character encoding) to the GIRA HomeServer. It is recommended to create or edit the configuration file using a text editor like Notepad++ and to copy/paste it into the input text area of the configuration page of the HomeServer.
Please remember to always keep a backup copy of the configuration file in a separate location (file extension .js) on your local drive.

• Edit: to edit/upload the configuration.
• Show: shows the configuration without comments to allow you to check the syntax with JSON-Lint, in case of problems.
• Example: shows an example configuration.

Note: To activate changes to the configuration file it is necessary to search for devices (run discovery) in the respective skill after uploading/saving the configuration (click 'Save JSON-Configuration') to the GIRA HomeServer.
In the Smart Home Skill this can be done through "Alexa App->Smart Home->Devices->Search" or with the voice command "Alexa, start discovery".
In the Custom Skill this can only be done with the voice command "Alexa, ask My Home to start disovery".

1. JSON-Notation

The configuration of devices is done in JSON-Format (also refer to Wikipedia: JavaScript Object Notation).

Example:

(Assuming the use of '3-level' group adresses, group addresses need to be replaced with your own values, of course.)

{
  "devices": 
  [
    { "room":"Living Room", "targetTemperature":"2/1/1", "actualTemperature":"2/1/2", "text": "5/1/1",
      "appliances":
      [
        {"name":"Ceiling Light", "onOff":"1/1/1", "percent":"1/1/2", "aliases":["Living Room Light"]},
        {"name":"Floor Lamp", "onOff":"1/1/3"}
      ]
    },
    { "room":"Kitchen", "targetTemperature":"2/2/1", "actualTemperature":"2/2/2",
      "appliances":
      [
        {"name":"Light", "onOff":"1/2/1"}
      ]
    }
  ],
  "mappings": {},
  "synonyms": {},
  "replies": {}
}

2. Device-Definition

Controlable devices are configured in the "devices": [] section of the configuration file. Here you also link the objects used in the voice commands to the respective KNX objects' group addresses.
The configuration has two levels: "Level 1 - Room" defines the room labels (denoting rooms, areas or localities) used in the voice commands. In sublevel "Level 1.1 - Appliances" you define the devices/appliances (actors, sensors, ...) in a specific room.

2.1 Level 1 - Room

Example:

{ "room":"Living Room", "targetTemperature":"2/1/1", "actualTemperature":"2/1/2", "text": "5/1/1" }, ...

The following attributes are supported for this level:

Attribute Name	Attribute Value	Data Type	Example	Notes
id	ID	String	"LR"	Optional - the provided string must be unique within "Level 1 - Room". By providing a manual ID the automatically generated value can be overridden.
room	Room Name	String	"Living Room"	Name of the room/area/locality. If you would like to define global/non-location specific objects omit this attribute.
targetTemperature	Target Temperature	KNX group address 16-Bit (-671088,64..670760,96/EIS 5)	"2/1/1"	KNX group address to set and retrieve the target/setpoint temperature - note that some room controllers require two separate KNX objects for this - this is not supported at the moment but you may be able to set the target value's read attribute in ETS to work around this issue. Also, no decimal temperature values are supported by Alexa in English language, only whole numbers. Alexa, set the Living Room to 21 degrees. Alexa, what is the thermostat in the Living Room set to?
actualTemperature	Current Temperature	KNX group address 16-Bit (-671088,64..670760,96/EIS 5)	"2/1/2"	KNX group address to check the current temperature in the room. Alexa, what is the temperature in the Living Room.
text¹	Status Report	KNX group address 14-Byte Text	"5/1/1"	KNX group address to request a (room) status report. Alexa, ask My Home for the status of the Living Room?
control	Call logic sub-module	KNX group address 14-Byte Text	"5/2/1"	The possible voice commands depend on the supporting logic sub-module.
appliances	List of devices	Array	[...]	Initiates the definitions section for "Level 1.1 - Appliances".

¹ applies to Custom Skill only

2.1.1 Level 1.1 - Appliances

Example:

{"name":"Ceiling Light", "onOff":"1/1/1", "percent":"1/1/2", "aliases":["Living Room Light"]}, ...

This level supports the following attributes:

Attribute Name	Attribute Value	Data Type	Example	Notes
id	ID	String	"LI1"	Optional - the provided string must be unique within "Level 1.1 - Appliances". By providing a manual ID the automatically generated value can be overridden.
name	Device Name (object name)	String	"Light"	Name of the device/appliance (object). If the Room Name (attribute "room" in the level above) is not empty it will be appended to the Device Name. Alexa, turn on the Ceiling Light in the Living Room.
onOff	used for turn on/off command	KNX group address	"1/1/1"	KNX group address that will be set to "onValue" when switching on and to "offValue" when switching off. When using onOff the two subsequent attributes are ignored. Alexa, turn on the Ceiling Light in the Living Room. Alexa, turn off the Ceiling Light in the Living Room.
on	used for turn on command	KNX group address	"1/1/1"	KNX group address that will be set to "onValue" when switching on. Alexa, turn on the Ceiling Light in the Living Room.
off	used for turn off command	KNX group address	"1/1/1"	KNX group address that will be set to "offValue" when switching off. Alexa, turn off the Ceiling Light in the Living Room.
onValue	On Value	Number	"1"	If the default value of "1" is not suitable it can be changed here. The KNX groupp address set under "onOff" or "on" will be set to this value for a turn on command.
offValue	Off Value	Number	"0"	If the default value of "0" is not suitable it can be changed here. The KNX groupp address set under "onOff" or "off" will be set to this value for a turn off command.
percent	Percentage Control	KNX group address 8-Bit (0..100%/EIS 6)	"1/1/2"	KNX group address used for the percentage control of the device. Alexa, set the Ceiling Light in the Living Room to 50 percent. Alexa, dim the Ceiling Light in the Living Room by 10 percent. Alexa, increase the Ceiling Light in the Living Room by 10 percent.
text¹	Status Report	KNX group address 14-Byte Text	"5/1/1"	KNX group address to request a status report. Alexa, ask My Home for the status report for the lights in the house.
value¹	Value	KNX group address	"X/X/X"	KNX group address used to request a value. Alexa, ask My Home what is the brightness?
unit¹	Unit Format	String	".1 km/h"	Option to format the values provided by the HomeServer. If the first character in the format string is not one of "? # . ," the value will just be appended. "?" allows to translate the integer values 0/1 into corresponding texts. Syntax: "?TEXT_FOR_0;TEXT_FOR_1" Examples: "?empty;full", "?down;up", ... "#" allows to translate a list of integer values into corresponding texts. The mapping must be defined in the configuration's "mappings" section. Syntax: "#MAPPINGNAME" Example: "#doorWindow2State", ... "." or "," are used to define the decimal character and the number of decimals to be spoken in the response. Syntax: ".X UNIT" Example: ".2" (response will be spoken using 'point' and two decimals), ".1 km/h", ".0 degrees", ".0 kilolux", ...
control	Call logic sub-module	KNX group address 14-Byte Text	"5/2/1"	The possible voice commands depend on the respective logic sub-module.
aliases	List of Aliases	Array	[...]	List of alternative names for this device. Caution: The room name is NOT appended to alias names!
type²	Device Type	String	"LIGHT"	Typ of device (Object): LIGHT BLINDS (only used Alexa-KNX internal, displayed as OTHER in the Alexa-App) SMARTPLUG OTHER This information will be used in a later transition to the Smart Home API V3 to properly classify the device in the Alexa app. For the changes already made by specifying "type": "BLINDS" see here.

¹ applies to Custom Skill only

3. Mappings (optional, applies to Custom Skill only)

Example:

"mappings" : {
    "#doorWindow2State": {
      "0": "closed",
      "1": "open",
      "2": "tilted"
    } 
}

4. Synonyms (applies to Custom Skill only)

"Synonyms" allows to define synonyms for character sequences (words, partial words) that will be used for the "matching". Matching is the mechanism that is used to try to find the device name in the JSON configuration that matches the device name used in the voice command.

Note: It is necessary to keep the replacement words for a synonym in a specific order: Words that are completely contained in another word need to be listed behind such word. For example, the correct orders would be "light scene", "scene" and "lamps", "lamp". Generelly, therefore, plural forms need to be listed first. Also, ensure that each replacement word is only used in one of the lists.

Example:

"synonyms" : {
  "LHT": ["lights", "light",  "lamps", "lamp"],
  "BLD": ["blackout blinds", "blinds", "blind", "shutters", "shutter"],
  "SCN": ["light scene", "scene"]
}

This mapping is done in both the JSON configuration and the voice commands. So, the term "ceiling lights" in the JSON configuration will will be mapped to "ceiling LHT". If the voice command uses "ceiling lamps" this would also be mapped to "ceiling LHT". As a result, in this example, using "ceiling lamps" in the voice command would lead to the device "ceiling lights" in the JSON configuration to be used.

5. Messages (optional, applies to Custom Skill only)

Using "replies" the following Custom Skill messages can be defined or replaced by the user (the default messages are shown below):

"replies" : {
    "OK_MESSAGE": "Okay",
    "WELCOME_MESSAGE": "Hello, I am ready to control your smart home.",
    "WELCOME_REPROMPT": "You could tell me switch on the light in the kitchen, or what is the temperature in the lounge?, or you can say stop. What would you like me to do or check?",
    "HELP_MESSAGE": "This skill allows you to control and check KNX devices using the <phoneme alphabet='ipa' ph='gira'/> Homeserver or Facility Server. For further information please go to www.alexa-knx.de.",
    "HELP_REPROMPT": "What would you like me to do or check?",
    "STOP_MESSAGE": "Goodbye.",
    "SESSION_REPROMPT": "What would you like me to do or check next?"
}

You can also define multiple messages for a specific message type in an array []. In this case, the resulting message will be chosen randomly.

Example for responses that would use "okay" by default:

"replies" : {
    "OK_MESSAGE": [
      "<say-as interpret-as='interjection'>allright</say-as>", 
      "<say-as interpret-as='interjection'>sure</say-as>", 
      "<say-as interpret-as='interjection'>okey dokey</say-as>", 
      "<say-as interpret-as='interjection'>tada</say-as>",
      "<say-as interpret-as='interjection'>done</say-as>",
      "<say-as interpret-as='interjection'>as you wish</say-as>"
    ]
}

The following example describes how you can avoid responses for all non-error cases:

"replies" : {"OK_MESSAGE":"<break time='100ms'/>"}

6. Settings (optional, only available from Logic Module version 1.1.0)

"settings": {
    "phoneticSearch":true,
    "smartHome25PercentBlindsHack":false
}

Note: the values true/false must be entered without quotes.

With the option "phoneticSearch" the phonetic search for device/room names can be switched on(true)/off(false). If this option is not provided in the settings, the phonetic search is switched on by default. Note: Changing this option will only take effect with the next "Search for devices/KNX objects".

Using the option "smartHome25PercentBlindsHack" in conjunction with "type": "BLINDS" for the smart home skill, the workaround to fully open/close shutters/blinds by using the command "move up/down" can be enabled(true)/disabled(false). If this option is not used in the settings, the workaround is switched off by default.