Ich hatte kürzlich einen Ausfall meines Systems, weshalb ich die XXAPI neu installieren musste. Bei der Gelegenheit habe ich mich nochmal mit der gesamten Installationsmimik beschäftigen müssen. Weil mir selber wieder nicht alles auf Anhieb klar war, habe ich den Installationsvorgang und ein paar erläuternde Bemerkungen zusammengeschrieben.

Komponenten

Grundsätzlich beruht die XXAPI Mimik darauf, dass man im Explorer nicht seine Visu-Startseite direkt aufruft, sondern erst eine interne html-Seite namens start.htm. Diese liegt im Ordner hsav und startet die ganze Mimik, die alle nötigen Installationen vornimmt und alle Erweiterungen startet.

So ein Aufruf sieht im Browser zum Beispiel so aus: http://192.168.254.230/opt/hsav/start.htm.

Das ist aber noch nicht alles. Die Startseite der Visu muss gleichfalls geändert werden. Diese neue Startseite (sie heist xxAPI-INIT) ist für den Benutzer nicht sichtbar. Eigentlich wird dort nur ein Button namens T 14-Byte Textanzeige/xxAPI gebraucht, der die eigentliche Visu startet und eine Variable (namens xxAPI, was sonst?) bereitstellt, welche den XXAPI Programmcode bereithält. Hört sich kompliziert an, ist aber simpel.

Die dritte Komponente ist eine Webabfrage namens xxAPI (wie sonst?), welche den Server von knx-user-forum abfragt, ob es eine neue Version der XXAPI gibt. Wenn man XXAPI installiert, dann hat man auf seinem Installationsrecher die XXAPI Version 1.0. Diese wird in den HS übertragen und dort remanent abgelegt, d.h. sie überlebt auch neue Programmversionen. Beim Starten des Visu wird jedesmal diese Webabfrage gestartet. Sollte es auf dem Server eine neue Version der XXAPI geben, dann wird die Remanentspeicher-Version damit überschrieben. Und man arbeitet fortan mit der neuen XXAPI. Sollte der Remanentspeicher gelöscht werden, dann wird durch das nächste Übertragen wieder die Version 1.0 aufgespielt.

Das ist der Mechanismus, die XXAPI immer aktuell zu halten, ohne dass man das Projekt wieder neu übertragen müsste. Ein dynamisches Update für den HS. Vor einem Jahr hat es noch regelmässig Updates gegeben, danach aber gab es immer nur Version 1.0. Wer diesem Service misstraut oder nicht will, dass bei sich oder bei einem Kunden einfach so eine neue XXAPI Version aufgespielt wird, der kann die Webabfrage auch einfach deaktivieren und fortan nur noch mit Version 1.0 arbeiten. Sollte es mal eine neue Version geben, kann man diese dann leicht auf den Installationsrecher kopieren und muss danach nur noch das Projekt neu übertragen.


Links und Downloads

Die zentrale Seite zu Installation ist:
HS/FS xxAPI v1.0 erweiterte Ajax-Visu - KNX-User-Forum

Die Downloads sind hier:
KNX-User-Forum

Eine bebilderte Installationsanleitung ist hier:
XXAPI - HS/FS - Lexikon - KNX-User-Forum

Ich selber hatte Anfangs zu knabbern, um die Installation zu verstehen, deshalb hier nochmal meine Version, so wie ich sie verstehe.


Die Installation

Zunächst lädt man sich die Dateien xxAPI.v1.00.zip und xxAPI-GlobaleBibliothek.v.099.hslib.zip herunter und entpackt sie jeweils in einen Ordner. Von der Versionsnummer v.099 braucht man sich nicht beirren zu lassen, es passt schon. Wenn man beim Download statt einer .zip Datei nur eine Datei namens projectattachment.php erhält, dann hat man auf seinem Rechner einen sogenannten Download-Manager installiert, der die Downloads beschleunigen soll. Der funktioniert in diesem Fall nicht. Also Downloadmanager deaktivieren und nur mit dem einfachen Explorer-Standarddownload runterladen.

Damit wir im folgenden wissen, wovon wir reden, hier ein die Namenskonventionen:

MeinStart ist IHRE erste Visu-Seite, die Sie angezeigt bekommen wollen. Sie kann aber auch irgendwie anders heissen, und es ist nicht nötig, das Sie bereits XXAPI Befehle verwenden. Es kann auch die Startseite ihres bisherigen Projektes sein. So können Sie sich langsam in die XXAPI hineinschaffen (wie wir Schwaben sagen...)

xxAPI-INIT ist eine neue Startseite, die von der .hslib Datei mitinstalliert wird. Diese ist nicht weiter sichtbar und dient nur zum Start des Systems.


1. Die hslib importieren

Sie müssen mit dem Experten unter "Globale Bibliothek/Importieren" die Datei xxAPI-GlobaleBibliothek.v.099.hslib importieren. Damit wird die Webabfrage xxapi und auch alle notwendigen Variablen installiert. Und auch automatisch die Seite xxAPI-INIT:

Klicke auf die Grafik für eine vergrößerte Ansicht

Name: xxapi lib1.JPG
Ansichten: 1
Größe: 49,0 KB
ID: 3197

Geben sie als Namen immer xxAPI ein (der Einfachheit halber). Als Hintergundbild wählen Sie Unsichtbar oder Blanko oder BG Transparent oder wie es sonst heissen mag. Wenn Sie noch keinen einfachen Hintergrund haben, erschaffen Sie sich einfach einen.

Im Reiter Verweise müssen Sie noch angeben, wie Ihr Startbildschirm heisst. Wenn das ganze mal installiert ist, können Sie ihn natürlich nachträglich ändern:

Klicke auf die Grafik für eine vergrößerte Ansicht

Name: xxapi lib2.JPG
Ansichten: 1
Größe: 51,4 KB
ID: 3198


Nach dem erfolgreichen Import haben Sie mehrere neue Sachen in Ihrem Projekt. Zunächst einmal in Visu den neuen Ordner xxAPI mit der Seite xxAPI-INIT:

Klicke auf die Grafik für eine vergrößerte Ansicht

Name: xxapi init.JPG
Ansichten: 2
Größe: 64,7 KB
ID: 3199

Auf dieser Seite sind genau drei Dinge: ein 14-Byte/Text Button, dessen Variable den Code der XXAPI enthält. Zum anderen steht in der "Visu-Seite" dieses Buttons die Adresse Ihrer Startseite: MeinStart. Dort kann sie dann auch geändert werden.

Darunter ist ein weiterer Button, der die Webabfrage xxAPI auslöst. Und ein Begrenzungsknopf, der Teil des XXAPI Systems ist.


Zum anderen gibt es bei den Webabfragen ("Web-Seiten/IP-Geräte abfragen und auswerten") einen neuen Ordner xxAPI mit folgenden drei Dateien: xxAPI, xxAPI-checkVersion und xxAPI-Demo.

Klicke auf die Grafik für eine vergrößerte Ansicht

Name: xxapi webab.JPG
Ansichten: 1
Größe: 64,5 KB
ID: 3200

Die Webabfrage xxAPI lädt vom Server die neueste Version des XXAPI herunter. xxAPI-checkVersion checkt auf dem Server, welches die neueste Version von XXAPI ist. Und was xxAPI-Demo macht, weiss ich selber nicht. Ist wohl auch nicht relevant für den Betrieb.


2. Den Ordner hsav installieren

Im Ordner der Datei xxAPI.V1.00.zip befindet sich ein Ordner namens hsav. Dieser ganze Ordner muss jetzt von Hand in den Ordner C:\Program Files\Gira\HS+FS\exp240\DE\hsupload kopiert werden. Sollte auf Ihrem Rechner bereits ein Ordner namens hsav bestehen, dann kopieren Sie den Inhalt des neuen hsav Ordner in den das alten. Sie haben dann wahrscheinlich schonmal die AJAX Erweiterung von Dacom installiert.

Man beachte den Teil exp240. Wenn Sie mehrere Versionen des Experten auf dem Rechner haben (durch Updates auf neuere Versionen), dann müssen Sie hier immer den Neuesten angeben. Bei Experte 2.5 zum Beispiel exp250.

In demOrdner hsav befindet sich zum einen ein weiterer Ordner namens js. Dieser enthält die Dateien ajax.js, gpl-3.0.txt und xxAPI-ajax100.diff:

ajax.js ist die Dacom AJAX Schnittstelle. Da Dacom diese seit Jahren nicht mehr weiterentwickelt, wird sich daran wohl auch nix mehr ändern.
gpl-3.0.txt ist eine Lizenzvereinbarung zu OpenSource für XXAPI
xxAPI-ajax100.diff enthält den Code für die XXAPI Erweiterung Version 1.0


Zum anderen sind dort auch die beiden Dateien secure.htm und start.htm enthalten.

Die Datei start.htm startet einerseits das XXAPI. Andererseits macht es auch ein schönes Wartefenster, wenn die Verbindung des HS zum Netzwerk gestört ist.

Die Datei secure.htm enthält eine voreingestellte Benutzer/Passwort Kombination und startet Ihrerseits das Programm start.htm. Man braucht es nicht unbedingt. Aber es kann nützlich sein, wenn man eine Visu installiert, ohne das der Benutzer ein Passwort eingeben muss. Dann schreibt man diese Benutzer/Passwort Information in die Datei secure.htm und nennt die Datei dann um mit irgendeinem, möglichst unsäglichen Namen. Zum Beispiel sec213453hfgd.htm. Wenn dann diese .htm Datei aufgerufen wird, startet das System direkt durch bis zur Visualisierung. Ich kann ohne diesen Mechanismus leben, der von mir verwendete Firefox Browser speichert auf Wunsch die Zugangsdaten sowieso.

Die Datei können Sie einfach mit dem Systemprogramm EDITOR oder jedem anderenTexteditor bearbeiten:

Klicke auf die Grafik für eine vergrößerte Ansicht

Name: secure.JPG
Ansichten: 1
Größe: 57,2 KB
ID: 3201

Beachte: Der Name des Ordner hsav wurde von Dacom als Standardname für genau den Ordner gewählt, der standardmäßig die AJAX Visu enthält. Das bringt uns in Probleme, wenn wir einen Update des Experten machen. Zum Beispiel von Version 2.4 auf 2.5. Dann wird der Ordner hsav nämlich überschrieben, obwohl sich am Inhalt eigentlich nix geändert hat. Wenn man das vermeiden will, kann man den Ordner hsav auch einfach umbenennen. Zum Beispiel in hsav1. Man muss sich nur merken, wie der Name lautet, weil man ihn später als Parameter für den Webaufruf der Startseite braucht (siehe Punkt 4).


3. Die Passworte anpassen

Jetzt muss man natürlich im Experten dem Benutzer auch die neue Startseite xxAPI-Init zuordnen. Im Experten zist diese Einstellung zu finden unter "Benutzer/admin/Benutzerrechte". admin ist dabei der gewählte Benutername. So wird erreicht, dass wenn sich der Benutzer admin einloggt, er auf die Seite xxAPI-INIT weitergeleitet wird, die ihrerseits die erste Startseite der Visu aufruft. Von diesen xxAPI-INIT Seiten könnte übrigen für jeden Benutzer eine eigene Kopie erstellt werden, die dann jeweils auf eine andere Startseite verweist. Beispielsweise wenn man einen User hat, der immer nur mit einem Handy einloggt:

Klicke auf die Grafik für eine vergrößerte Ansicht

Name: passwd.JPG
Ansichten: 1
Größe: 70,4 KB
ID: 3202


4. Projekt übertragen und aufrufen

Jetzt sind wir an sich fertig. Das Projekt muss nur noch auf den HS übertragen werden. Um die Startseite aufzurufen empfehle ich den Browser Firefox (FF), da sich der Internet Explorer (IE) zickig anstellt. Jedenfalls bei mir. Unter firefox-im-vollbild-modus-kiosk-modus ist eine Methode beschrieben, wie man auch im FF einen kompletten Vollbildmodus für die Visualisierung hinbekommt.

Aufgerufen wird die Visu mit der Zeile http://192.168.254.230/opt/hsav1/start.htm.

Dabei ist 192.168.254.230 die IP adresse des HS. hsav1 ist der Name des Ordners, den wir in Punkt 2 einkopiert haben. Wenn Sie den Namen nicht geändert haben, dann muss hier natürlich nur hsav stehen.

Jetzt sollte XXAPI installiert sein. Viel Spass.


Bekannte Probleme:

1. XXAPI hat zumindest in der Vergangenheit nicht einwandfrei mit dem Internet Explorer 8 zusammengearbeitet. Deshalb empfehle ich die Verwendung des Firefox Browsers, um die Visu darzustellen:
Webbrowser Firefox | Schneller, sicherer & anpassbar | Mozilla Europe

Nach Angaben von Benutzer Michel (der die XXAPI Demo geschrieben hat) soll es demnächst eine sauber unter IE8 laufende Lösung geben.

2. Wenn man die Webabfrage xxAPI mehr als einmal pro Minute aufruft, dann meldet der knx-user-group Server einen Fehler. Eine erfolgreiche Abfrage darf erst 60 Sekunden nach der Letzten erfolgen. Ganz unten in der Rückmeldung steht dann "60Sekunden warten".
Erklärung von user NilsS: "Gab da am Anfang ein paar Probleme manche waren "zu aktuell"."