Installation

Die Auslieferung der Software für den Gira HS besteht aus zwei Dateien. Einer ".hslz-Datei" mit dem Logikbaustein und einer ZIP-Datei "alexa-knx.zip" mit den vom Baustein benötigten Bibliotheken.

Hinweis bei Durchführung eines Updates:

Falls Sie Ihre Alexa-KNX JSON-Konfiguration noch nicht gesichert haben, sollten sie dies als erstes durchführen!
Bitte beachten Sie, dass sich der Zielordner, in welchen die ZIP-Datei entpackt werden muss, ab der HS-Firmware 4.9 geändert hat.
Mit der Version 1.2.1 des Hauptbausteins haben sich die Ein/Ausgänge geändert. D.h. Sie müssen bitte die Ein/Ausgänge entsprechend neu verbinden (bei Schritt 3 nicht vergessen)!

Alexa-KNX Bibliothek (ZIP-Datei)

Hinweis bei Durchführung eines Updates: Sollten Sie bereits eine Version von Alexa-KNX installiert haben, muss die Alexa-KNX Bibliothek ersetzt werden. D.h. bei Verwendung der HS-Firmare Version < 4.9, bzw. bei Umstieg auf die Firmware 4.9 müssten Sie bitte den, sich im hsupload-Ordner ihres Projekts befindlichen, "alexa-knx"-Order löschen. Sollten Sie mehrere Projekte mit Alexa-KNX verwenden, müssten Sie diesen Schritt bitte für jedes dieser Projekte wiederholen.

Bitte beachten Sie, dass Sie in den nachfolgenden Ausführungen den Ordnernamen z.B. .../HS+FS Experte 4.x/... durch den zu ihrer Installation passenden Ordernamen ersetzen müssen. Also z.B. .../HS+FS Experte 4.10/... wenn sie die Experten Version 4.10 einsetzen.

Entpacken der ZIP-Datei bei Einsatz der HS-Firmware < 4.9

Der in der ZIP Datei enthaltene Ordner "alexa-knx" muss im hsupload-Ordner des zu übertragenden Projekts entpackt werden.
Die dabei entstehende Verzeichnisstruktur muss folgendermaßen aussehen: .../Gira/HS+FS Experte 4.x/Projekte/DEIN_PROJEKTNAME/DEIN_PROJEKTNAME/hsupload/alexa-knx/libs/...

Achtung:

Bitte darauf achten, dass der Name der ZIP-Datei beim Entpacken nicht als zusätzlicher Ordner angelegt wird. Also nicht z.B. .../hsupload/alexa-knx/alexa-knx/libs/... ensteht.
Die Bibliothek muss sich im hsupload-Ordner des zu übertragenden Projekts befinden - also bitte nicht im hsupload-Ordner der Experten Installation unter C:\Programme (x86)\Gira\HS+FS\HS+FS Experte 4.x\hsupload entpacken

Entpacken der ZIP-Datei bei Einsatz der HS-Firmware >= 4.9

Der in der ZIP Datei "alexa-knx_V1.2.1_F4.9.zip" enthaltene Ordner "13626" muss im „öffentlichen“ Logic-Ordner des Experten entpackt werden. Dieser Ordner befindet sich standardmässig unter "> Dieser PC > Lokaler Datenträger (C:) > Benutzer > Öffentlich > Öffentliche Dokumente > Gira > HS+FS Experte 4.x > logic" (C:\Users\Public\Documents\Gira\HS+FS Experte 4.x\logic\).

Achtung: Sollten sie Probleme haben den richtigen Logic-Ordner zu lokalisieren, beachten sie bitte folgende Hinweise:

der gesuchte Ordner mit dem Namen "logic" wird bereits bei der Installation der Experten-Software angelegt
d.h. dieser Ordner muss bereits existieren und darf nicht von ihnen angelegt werden!
in diesem Ordner werden zum einen alle zur Experten Software gehörenden "externen" Logikbausteine und zum anderen durch Sie importierte Logikbausteine (.hsl-Dateien) abgelegt
insbesondere darf der Ordner nicht unter dem auch bereits existierenden ähnlichen Pfad "Dieser PC > Dokumente > Gira > HS+FS Experte 4.x" angelegt werden
nur wenn sie die Alexa-KNX Bibliothek im korrekten Logic-Ordner ablegen, wird diese auch beim Übertragen ihres Projekts mit dem Experten auf den HomeServer transferiert

Eine weitere Möglichkeit den korrekten Logic-Ordner zu finden ist (nach dem Import des Logikbausteins mit dem Experten) mittels des Windows-Explorers nach der Datei "13626_AlexaKNX_V*.hsl" zu suchen. Der zur gefundenen Datei zugehörige Ordner ist der gesuchte Logic-Ordner in dem die Alexa-KNX Bibliothek abzulegen ist.

Die nach dem Entpacken entstandene Verzeichnisstruktur muss folgendermaßen aussehen:

...\Gira\HS+FS Experte 4.x\logic\13626\hsupload\
libs
www
version.txt

Gira Experte

Hinweis bei Durchführung eines Updates: Sollten Sie bereits eine Version von Alexa-KNX installiert haben, muss die ".hslx"-Datei ersetzt werden. D.h. sie müssten im logicx-Ordner ihres Projekts bereits befindliche(n), "13626_...AlexaKNX...hslx"-Datei(en) löschen. Sollten Sie mehrere Projekte mit Alexa-KNX verwenden, müssten Sie diesen Schritt bitte für jedes dieser Projekte wiederholen.

Sollte nach dem Übertragen des Projekts auf der HomeServer Debug-Seite unter der Rubrik "Exceptions" die Fehlermeldung "... [13626_AlexaKNX] ... in loadLibs AttributeError: CGUI instance has no attribute 'ExtDatUrl'" ausgegeben werden, deutet dies darauf hin, dass im logicx-Ordner ihres Experten-Projekts noch Reste eines alten Alexa-KNX 13626 Bausteins übriggeblieben sind.

Schritt 1: Logikbaustein importieren

Die .hslz Datei über den Menüpunkt "Logikbausteine->Importieren" importieren und im Anschluss den Experten neu starten.

Hinweis: Beim Import des Logikbausteins erstellt der Gira Experte im aktuellen Projekt Unterordner "logicx" eine ".hslx"-Datei. D.h. bei Einsatz des Bausteins in weiteren Projekten muss der Import ein weiteres mal gemacht, bzw. die ".hslx"-Datei in den entsprechenden "logicx"-Ordner des "neuen" Projektes kopiert werden.
Bei Projektierung mehrerer Kunden innerhalb einer Experten-Installation, muss die kundenspezifische ".hslx"-Datei aus dem Baustein ZIP-File (gelieferte ".hslz"-Datei) verwendet werden. Hierbei muss auch darauf geachtet werden, dass im Eingang E5 die dem Kunden zugehörige AWS-Customer-ID eingetragen ist.

Schritt 2: Projekteinstellungen anpassen bei Firmware >= 4.9 entfällt dieser Schritt

Unter Projekt->Projekteinstellungen->Oberfläche muss entweder der Radio Button ¹Alle ausgewählt
oder der Radio Button ²Benutzerdefiniert ... und die Checkbox ²alexa-knx ausgewählt sein.

Schritt 3: Logikbaustein verbinden

Der Baustein wird im grafischen Logikeditor in der Rubrik „Alexa-KNX“ einsortiert. Ein Arbeitsblatt muss angelegt der Baustein darauf gezogen und die Ein- und Ausgänge des Logikbausteins folgendermaßen belegt werden (Die hier gelisteten KO-Objekte sind entsprechend anzulegen):

Nachfolgende Beschreibung gilt bei Einsatz der Logikbaustein Version <= 1.1.0

Eingang	Typ	Default	Beschreibung
1	1-Bit KO-Objekt	1	(Remanent, Init-Wert=1), zum Starten/Stoppen der Alexa-Anbindung
2	Number	30000	gewünschter Server Port des Bausteins
3	String	""	gewünschtes Access Token als Zugriffsschutz auf die Konfigurationsseite (in der URL als Parameter accessToken=… mitzugeben)
4	String	"eu-west-1"	Amazon Webservice Region (eu-west-1 für Deutschland)
5	String	"..."	ihre Alexa-KNX spezifische Benutzerkennung (vorab bereits im Baustein eingetragen)
6	8-Bit KO-Objekt (EIS 2,6)	3	(Init-Wert=3), zur Festlegung des Log-Levels 0-5
7	1-Bit KO-Objekt	0	zum Reset des Logs (an diesen Eingang sollte periodisch alle X-Tage eine 1 gesendet werden
8	14-Byte Text	0	nur bei Verwendung weiterer Alexa-KNX Sub-Logikbausteine zu belegen

Ausgang	Typ	Default	Beschreibung
1	16-Bit KO-Objekt (EIS 10)	0	Unauthorized Access Zähler

Nachfolgende Beschreibung gilt bei Einsatz der Logikbaustein Version >= 1.2.1

Eingang	Typ	Default	Beschreibung
1	1-Bit KO-Objekt	1	(Remanent, Init-Wert=1), zum Starten/Stoppen der Alexa-Anbindung
2	Number	30000	gewünschter Server Port des Bausteins
3	String	""	gewünschtes Access Token als Zugriffsschutz auf die Konfigurationsseite (in der URL als Parameter accessToken=… mitzugeben)
4	8-Bit KO-Objekt (EIS 2,6)	3	(Init-Wert=3), zur Festlegung des Log-Levels 0-5
5	1-Bit KO-Objekt	0	zum Reset des Logs (an diesen Eingang sollte periodisch alle X-Tage eine 1 gesendet werden
6	14-Byte Text	0	nur bei Verwendung weiterer Alexa-KNX Sub-Logikbausteine zu belegen

Ausgang	Typ	Beschreibung
1	1-Bit KO-Objekt	Start/Stop Status
2	16-Bit KO-Objekt (EIS 10)	Unauthorized Access Zähler
3	1-Bit KO-Objekt	Event Gateway Overflow

Schritt 4: Projekt übertragen

Projekt auf den Gira HS übertragen und Neustart des HomeServers abwarten.

Sollte das Übertragen des Projekts aufgrund des Fehlers

fehlschlagen, muss der Baustein zuerst in das aktuelle Projekt importiert bzw. die zugehörige ".hslx"-Datei aus dem Projekt, in welchem der Baustein ursprünglich importiert wurde, kopiert werden.

Schritt 5: Installation überprüfen

Hinweis: aktuell wird ab der Firmware Version 4.12 der HTML-Code zur Darstellung der Alexa-KNX Links „escaped“ und somit als Text ausgegeben. D.h. die Verlinkung der „Logausgabe“, „JSON-Configuration“ und „CustomSkill Slot Types“ über die Debug-Seite funktioniert nicht mehr. Als Workaround muss bitte die im href-Attribute angegebene URL verwendet werden.

Bei fehlerfreier Installation sollte auf der Debug-Seite (standardmäßig zu finden unter http://HomeServerIP:HomeServerPort/hslist?lst=debug) unter der Rubrik "Alexa-KNX" nachfolgende Ausgabe erscheinen:

Version	Version der installierten Software
Port	Portnummer auf dem der Alexa-KNX Webserver läuft
JSON-Configuration edit	Link zur JSON-Konfigurationseite auf der, die durch Alexa steuerbaren/abfragbaren Geräte editiert bzw. eingesehen werden können.
Logfile show	Link zum Log-Viewer mit den Log-Ausgaben des Bausteins.

Hinweis: Bei einem HomeServer neustart, wird der Alexa-KNX Webserver ca. 10 Sekunden zeitverzögert gestartet. D.h. die hier aufgeführten Links funktionieren erst nach Start des Alexa-KNX Webservers.

Die Logausgabe sollte, bei erfolgreichem Start der Alexa-KNX Verbindung, ähnlich wie nachfolgend aussehen:

Die WARN-Meldung "JSON-Configuration is empty" ist nur ein Hinweis, dass die, für die Sprachsteuerung benötigte, JSON-Konfiguration noch nicht erstellt wurde.

Sollte in der Logausgabe eine Zeile mit der Meldung "Alexa-KNX Service not started ...", ähnlich wie nachfolgend ausgegeben werden:

So stellen sie bitte sicher, dass am Eingang "E1 Start/Stop" des Bausteins auch wirklich eine 1 zum Starten der Alexa-KNX Verbindung anliegt.

Mögliche auftretende Fehler

"LBS-Version < 1.2.1 - bei Einsatz der HS-Firmware >= 4.9" - Error

Es wird für die HS-Firmware 4.9 eine alte Alexa-KNX LBS-Version (< 1.2.1) verwendet.
(siehe Hinweis bei Durchführung eines Updates)

Library Error - HS-Firmware <4.9

Die vom Baustein benötigten Bibliotheken wurden nicht gefunden.

Library Error - HS-Firmware>=4.9

Die vom Baustein benötigten Bibliotheken wurden nicht gefunden.
Bitte stellen sie sicher, dass sie die Alexa-KNX Bibliothek korrekt unter dem zu ihrer Installation passenden Ordner entpackt haben.

Firmware Version Error

Die Firmware des Homeservers wird leider nicht unterstützt.

Gateway/Internet Error

Bitte die Einstellung unter Projekt->Netzwerk->Default-Gateway bzw. die Internetverbindung am Netzwerkanschluß des HomeServers prüfen.
Hinweis: Sollte beim Einschalten/Neustart des HomeServers (noch) keine Internetverbindung möglich sein wird vom Baustein kein automatischer, kontinuierlicher Reconnect versucht. D.h. in diesem Fall bitte den Baustein über den Eingang "E1 Start/Stop" zeitverzögert automatisch bzw. manuell starten.

DNS Error (Errno=-2; Errno=-5)

Bitte die Einstellung unter Projekt->Netzwerk->DNS-Server prüfen.

SSL Error

Bitte die Einstellung für Datum und Uhrzeit am HomeServer prüfen (Option: "Projekt->NTP/Zeitabgleicht/Mit NTP-Server synchronisieren" nutzen).

SQS Error

Bitte folgende Einstellung prüfen:

korrektes Datum und Uhrzeit am HomeServer (Option: "Projekt->NTP/Zeitabgleicht/Mit NTP-Server synchronisieren" nutzen)
Eingang "E5 AWS Customer-ID" ist korrekt
im "logicx" Ordner des Projekts wird die zur Customer-ID zugehörige "hslx"-Datei verwendet