Installation

The email you will receive after purchase will have got two files attached that need to be installed on the Gira HS. One is the .hslz-file with the logic module and a zip-file "alexa-knx.zip" with the libraries required by the logic module.

Preparation

Before starting the installation and configuration in the Gira Expert software please run the following preparatory steps: The content of the "alexa-knx" folder in the decompressed zip-file needs to be copied into the "hsupload" folder of the target project.
The resulting folder structure should look something like this: .../Gira/HS+FS Experte 4.5/Projects/YOUR_PROJECTNAME/YOUR_PROJECTNAME/hsupload/alexa-knx/libs/...

Attention: Please ensure that you do not end up with an additional "alexa-knx" subfolder as in .../hsupload/alexa-knx/alexa-knx/libs/....

Gira Expert

Step 1: Import the Logic Module

Import the .hslz Datei using "Logic Nodes->Import" from the main menu, then close and re-start the Gira Expert application.

Note: As a result of the successful import of the logic module Gira Expert will create a ".hslx" file in the "logicx" subfolder of the active project. Therefore, for use in other projects the import needs to be repeated or - alternatively - the ".hslx" file needs to be copied into the other project's "logicx" folder.
If you use one Gira Expert software installation to handle the projects of multiple clients please ensure you install the customer specific “.hslx”-file into the customer’s project (this is included in the zipped logic module “.hslz”-file). Please check that the correct, customer specific AWS Customer-ID is used for the logic module’s input E5.

Step 2: Project Settings

Under Project->Project Settings->Interface you need to either select the radio button ¹All
or the radio button ²User Defined ... with the check box ²alexa-knx selected.

Step 3: Connect the Logic Module

All Alexa-KNX logic modules are listed under „Alexa-KNX“ in the logic editor. Create a work sheet, drag & drop the imported logic module onto it, then connect the input and outputs as follows:

Input	Type	Default	Description
1	1-bit communication object (KO)	1	(Remanent, Init-Value=1), to start/stop the Alexa interface
2	Number	30000	Network port for the logic module's server component
3	String	""	Access token required to access the configuration pages (to be added to all configuration URLs as parameter accessToken=…)
4	String	"eu-west-1"	Amazon web service region (eu-west-1 is used for Germany/UK/other European countries)
5	String	"..."	Your personal Alexa-KNX user-ID/license key (usually preconfigured when you receive the logic module)
6	8-bit communication object (EIS 2,6)	3	(Init-Value=3), Log level (0-5)
7	1-bit communication object	0	1 at this input resets the log (it is recommended to periodically set this to 1 every few days to keep the log file to a reasonable size)
8	14-byte text object	0	Used to connect one of the Alexa-KNX supporting logic modules

Output	Type	Default	Description
1	16-bit communication object (EIS 10)	0	Unauthorized access counter

Step 4: Transfer the Project

Transfer the project to the Gira HomeServer and wait for the restart of the HomeServer to complete.

Should the transfer of the project fail with

the import of the logic module has failed. In this case please (re-)import/copy the ".hslx" file as described in Step 1.

Step 5: Check Installation Success

If the installation has been successful the HomeServer Debug page (you will usually find this under http://HomeServerIP:HomeServerPort/hslist/lst=debug) should list an "Alexa-KNX" section with the following menu items:

JSON-Configuration edit	Link to the JSON Configuration page on which all devices that can be controlled by Alexa can be added, edited or viewed. Note: The JSON-Configuration page is only available if the Alexa-KNX service has been started successfully and is running.
Logfile show	Link to the web page that shows the log dats for Alexa-KNX.

Please click the link to view the log data and check that it shows an output similar to this:

Note that you may get the information message “Can’t read alexaKNXSSL.cert. Will be using http instead of https.” – this is only to advise you that the access to the configuration in you local network only is not encrypted.
The warning “JSON-Configuration empty” will show if no JSON configuration has been saved yet.

Possible Issues

Library Error

The libraries required by Alexa-KNX could not be found.

Firmware Version Error

The firmware version of the HomeServer is not supported.

Gateway Error

Please check the Gateway settings for the project under Project->Network->Default-Gateway.

DNS Error

Please check the DNS server settings for the project under Project->Network->DNS-Server.

SSL Error

Please check the settings for date and time on the Gira HomeServer. (The recomendation is to use the option: "Project->NTP/Time calibration/Synchronise with NTP server").

SQS Error

Please check the following settings:

date and time on the HomeServer are correct (The recomendation is to use the option: "Project->NTP/Time calibration/Synchronise with NTP server").
the correct value for the input "E5 AWS Customer-ID" is used
the project’s “logicx” folder contains the “.hslx”-file associated with the AWS Customer-ID being used