mit dem Update für das "HTTP-/REST-API Server Subsystem" ist es nun möglich, dass eKey Fingerabdrucksensoren der x/s/d-Line ("aka "New Generation") mit dem Timberwolf Server kommunizieren.
Wir danken ekey für die Bereitstellung der Logos, Bilder und Testgeräten.
ekey x/s/d-Line mit Timberwolf Server nutzen
Voraussetzungen
Sie benötigen für die Durchführung dieser Anleitung:
1. eKey Fingerprint-Reader der neuen Generation
Genutzt werden kann diese Anleitung mit den ekey-Lösungen mit den Bezeichnungen
- xLine
- sLine
- dLine
2. bionyx APP:
Sie benötigen eine eingerichtete bionyx APP, die - über die bionyx Cloud - mit Ihrem ekey Controller verknüpft ist und zu der Sie administrativen Zugang haben
3. Timberwolf Server mit Firmware IP8 zur V 4.5:
Es kann jeder Timberwolf Server genutzt werden, der das Subsystem "HTTP-/Rest-API als Server" unterstützt. Hierzu benötigen Sie die Firmware IP 8 zur V 4.5 sowie die Lizenz dafür.
4. Kommunikation der Komponenten
- Der ekey Fingerprint-Leser ist per RS-485 mit dem ekey Controller verbunden
- Dieser ist mit dem Netzwerk über LAN oder WLAN verbunden
- Es besteht über das Internet eine Verbindung zur bionyx-Cloud (nicht in der Zeichnung dargestellt)
- Der Timberwolf Server ist per IP aus dem LAN / WLAN erreichbar, in dem sich der ekey Controller befindet
- Beim Erkennen eines Fingerabdrucks sendet der Leser eine Anfrage an den Controller, die an den Timberwolf Server gesendet wird.
Einschränkungen
Nach Angaben von ekey ist diese Lösung auf 5 HTTPS-Aufrufe pro bionyx Konto beschränkt.
Einrichtung
Hinweis: Es müssen nun sowohl der Timberwolf Server als auch ekey eingerichtet werden. Die Reihenfolge ist eigentlich egal, für den ersten Test aus der binoxy App ist es jedoch sinnhaft, die Einrichtung zuerst im Timberwolf Server vorzunehmen und anschließend die des des ekey-Systems über die bionyx-App.
1. HTTP-/REST-API Server Subsystem am Timberwolf Server aktivieren
Zunächst muss ein HTTP-/REST-API Server Subsystem aktiviert werden, sofern dieses noch nicht existiert.
A. Prüfen Sie in der Web-APP des Timberwolf Servers unter HTTP-API -> Subsysteme ob ein HTTP-/REST-API Server Subsystem eingerichtet worden ist.
Hinweis: Es kann nur eine Instanz eines solchen Subsystems eingerichtet werden. Sofern bereits eine Instanz angelegt ist, können Sie den nächsten Schritt "B" überspringen
B. Sofern kein HTTP-/REST-API Server Subsystem eingerichtet ist, dann legen Sie dies bitte an. Hierfür können Sie eine Bezeichnung und eine Beschreibung angeben. Anschließend [Speichern und starten] betätigen
2. Endpunkt für ekey im HTTP-/REST-API Server Subsystem anlegen
Für dem Zugriff durch ekey muss nun ein Endpunkt angelegt werden.
Hinweis: Falls Sie mehrere ekey Fingerprint-Sensoren und mehrere ekey Steuereinheiten ("Controller") in Ihrem Gebäude verbaut haben, dann ist hierfür durchaus ein Endpunkt ausreichend. Die Differenzierung der HTTPS-Anfragen ("Requests") erfolgt dann über die Ressourcen, die unterhalb des Endpunktes angelegt werden. Es ist jedoch auch möglich, für mehrere ekey-Controller jeweils einen eigenen Endpunkt anzulegen. Letzteres wäre dann nützlich, falls unterschiedliche Authentifizierungen verwendet werden sollen / müssen, da die Authentifizierung auf Ebene des Endpunktes zu konfigurieren ist.
A. Prüfen Sie, dass das richtige Subsystem ausgewählt ist.
Hinweis: Es kann zwar nur ein HTTP-/REST-API Server Subsystem angelegt werden, jedoch parallel dazu auch ein oder mehrere HTTP-/REST-API Client Subsysteme.
B. Klicken Sie auf [Neuer Endpunkt hinzufügen]
Hinweis: Alternativ können Sie eine Profildatei importieren
C. Assistenten ausfüllen
Hinweis: Die Angabe zum Pfad "ekey" können Sie auch ändern, müssen das aber dann bei der Konfiguration in der ekey APP berücksichtigen. Eine Autorisierung haben wir hier weggelassen, weil diese mit einem zeitlichen Limit in der ekey APP zu konfigurieren wäre und selbst, wenn man diese auf 5 Jahre anlegen würde ("= 157680000 Sekunden") dann erinnert sich in fünf Jahren sicher niemand mehr daran, dass die Autorisierung abgelaufen ist und das gewünschte Ereignis wird über die HTTP-/REST-API nicht mehr ausgelöst.
3. Ressource zum Endpunkt für ekey HTTPS-Anfrage anlegen
Für jede in der ekey APP ("ekey bionyx") angelegte HTTPS-Abfrage muss eine Ressource unterhalb eines Endpunktes angelegt werden. Obwohl man für diese Anfrage einen Endpunkt mit einer Ressource anlegen könnte, ist es für eine hierarchisch übersichtliche Darstellung empfehlenswert, nur einen Endpunkt für alle ekey Ressourcen zu verwenden. Ausnahme wären unterschiedliche Autorisierungen, da dieser auf der Ebene der Endpunkt zu konfigurieren sind.
A. Erweitern Sie den Endpunkt, so dass dieser aufklappt und betätigen Sie dann [+ Ressource hinzufügen]
B. Füllen Sie den Assistenten aus wie im Bild (Sie können auch einen anderen Pfad anlegen, müssen dies dann in der ekey APP berücksichtigen)
C. Sie erhalten nun diese Anzeige. Diese ist zum Testen bereits ausreichend. Sofern Sie über andere Objekte etwas ansteuern wollen, dann verknüpfen Sie das oberste - automatisch angelegte - Steuerobjekt "Trigger" mit Ihren Objekten
Hinweis: Dieses Steuerobjekt sendet ausschließlich ein TRUE, wenn eine ekey HTTPS-Anfrage erfolgreich ausgeführt wurde. Bei Warnung oder Fehler wird über dieses Steuerobjekt KEIN FALSE gesendet. Für Informationen zu Fehlern bitte die anderen Objekte verknüpfen und in der Logik auswerten, in Zeitserien aufzeichnen usw.
#######################################
4. HTTPS in der bionyx App aktivieren
Um HTTPS-Anfragen verwenden zu können, muss zunächst die Funktion "HTTPS" in der ekey bionyx App aktiviert werden.
A. Öffnen Sie zunächst die App und loggen Sie sich ein.
B. Sie sollten das Dashboard mit den Standardfunktionen von ekey bionyx sehen.
C. Wechseln Sie in die Einstellungen, indem Sie auf das Benutzersymbol klicken.
D. Wählen Sie dann "Smart Home Verbindungen" und aktivieren Sie die Schnittstelle.
Hinweis: Beachten Sie, dass nur ein Systemadministrator (der Besitzer des Systems) dazu berechtigt ist.
Andere Benutzer sehen diese Option in der ekey bionyx App nicht.
5. HTTPS Request in der ekey App einrichten
Wählen Sie "HTTP(S)-Anfrage" und drücken Sie die Schaltfläche mit dem Plus-Symbol.
Nun können Sie die Details Ihrer Anfrage hinzufügen.
A. Wählen Sie ein passendes Symbol für Ihre Funktion.
B. Geben Sie den Namen der Funktion ein (Licht an, Tür verriegeln, etc.).
C. Geben Sie den Namen des Ortes ein, an dem die Funktion ausgeführt werden soll (Wohnzimmer, Garage, usw.).
D. Wählen Sie die gewünschte METHODE für die HTTPS-Anfrage. Für die Kommunikation mit dem Timberwolf Server ist GET ausreichend
E. Geben Sie die URL der HTTP-/REST-API als Server des Timberwolf Server an. Also https://timberwolfxxxx.local/api/.... (wie von Ihnen für Endpunkt und Ressource im TWS vergeben). Je nach Namensauflösung in Ihrem LAN funktioniert auch https://timberwolfxxxx.fritz.box/api/.... oder auch https://192.168.x.xxx./api/..... Am Besten mit Browser testen.
(Weiter mit der gleichen Seite, nur gescrolled)
F. Bei Bedarf können Sie Request-Header und Request-Body senden, um weitere Informationen zu übertragen.
Dafür wären dann entsprechende Ressourcen-Einstellungen im Timberwolf Server zu übergeben. Wir haben dies auch getestet, aber es gibt nichts wirklich sinnhaftes, was man für die Verbindung mit dem Timberwolf Server mitgeben würde. Bei anderen Empfängern als dem Timberwolf Server kann die Übergabe eines Wertes in Header oder Body (in Verbindung mit POST oder PUT) erforderlich sein, hierfür bitte die Anleitungen bei ekey lesen.
G. Für Sicherheitsstufe TlsAllowedSelfSigned auswählen. Damit wird das selbst signierte Zertifikat des Timberwolf Servers akzeptiert.
H. Anschließend angeben, ob eine Authentifizierung gewünscht wird. Wir haben dies im Beispiel ohne Authentifizierung dokumentiert.
Bei unseren Tests hat es (nur) mit der Einstellung "Access Token" funktioniert, dies ist im Timberwolf Server dann als "Bearer Token" beim Endpunkt anzulegen. Allerdings muss hier ein Ablaufzeitraum in Sekunden angelegt werden. Selbst wenn man dies für fünf Jahre angibt ("157680000") besteht die Gefahr, dass man sich dem in fünf Jahren nicht mehr bewusst ist. Alternativ kann man auch über die Header-Konfiguration einen "Key=SupergeheimesPasswort" anlegen und diese in der Endpunkt-Konfiguration auch prüfen.
I. Wählen Sie dasjenige ekey-Gerät, das die HTTPS-Anfrage ausführen soll (ekey xLine-Steuereinheit, ekey dLine-Steuereinheit, etc. ).
J. Testen Sie nun die HTTPS-Anfrage, indem Sie wieder nach oben scrollen und dort den Testbutton klicken).
Die App gibt im Erfolgsfall leider keine Rückmeldungen, darum am besten auf dem Timberwolf Server prüfen, ob das funktioniert hat (Statuscode neben den Pfeilen, siehe Abbildung).
Anmerkung: Sofern Sie Objekte mit dem Statusobjekt "Request" im Timberwolf Server verknüpft haben, z.B. eine Beleuchtung oder ein Motorschloss, dann bitte beachten, dass dieses durch diesen Test aktiviert wird.
Rückmeldung im Falle von Fehlern:
Wenn die Anfrage über die bionyx APP gestartet wurde, dann zeigt diese die Fehlermeldung an, welche auch in den Status Objekten sichtbar wird. Bei der Nutzung eines Fingerprint-Readers wird, je nach Konfiguration, nach grünem Ring eine Ecke rot eingefärbt und den Fehlschlag der Requests anzuzeigen.
K. Speichern Sie in der ekey APP nun die HTTPS-Anfrage
Abschließend mit dem Finger testen um die gesamte Funktionskette zu prüfen.
Fertig
=================================================================================================
Weitere Doku
Doku im Wiki (wird noch erweitert): https://elabnet.atlassian.net/wiki/x/AQAXbg
Verfügbarkeit
Die hier benötigten neuen Funktionen stehen auf dem Timberwolf Server mit Firmware IP 8 zur V 4.5 seit 31. Juli 2025 zur Verfügung.
Über die Verfügbarkeit dieser neuen Funktionen in einer Hauptversion können wir im Moment keine belastbaren Angaben treffen.
lg
Das Team von ElabNET