Mit einigen Smart Home-Plattformen oder -Geräten hat LOQED keine direkte Integration. Wenn du ein fortgeschrittener Benutzer bist, kannst du deine Integration mit Hilfe der LOQED-API entwickeln. Lies unbedingt unseren Artikel "Fortgeschrittene Benutzer: Verfügbare APIs" zuerst.
Wenn die Tür geöffnet/verschlossen wird, rufe eine URL auf (ausgehender Webhook)
Wenn sich der Status des Schlosses ändert (offen, entsperrt, verriegelt) und für andere Informationen (Batteriestatus, Online-Status), kann die LOQED Bridge eine URL aufrufen (Daten an POST senden). Unten siehst du, welche Daten als JSON an diese URL gepostet werden. Du kannst auch GET-Parameter für die URL hinzufügen, indem du den JSON-Schlüssel zwischen "[" und "]" setzt. Zum Beispiel: https://your.server.nl/script?yourstate=[requested_state ]. Du kannst auch festlegen, bei welchen Änderungen ein Webhook-Aufruf ausgelöst werden soll (z. B. kannst du festlegen, dass eine URL nur aufgerufen wird, wenn die Tür verschlossen ist).
Die folgenden JSON-Schlüssel werden immer gesendet:
mac_wifi: enthält die Wi-Fi MAC-Adresse der Brücke. Dies hilft, die Brücke zu identifizieren. Der Multicast-DNS-Name der Brücke enthält ebenfalls diese Adresse.
mac_ble: enthält die Bluetooth-MAC-Adresse der Bridge.
Erreichter Zustand
Nachdem der Motor nicht mehr läuft, werden die folgenden JSON-Schlüssel für die Trigger trigger_state_changed_open, trigger_state_changed_latch, trigger_state_changed_night_lock, trigger_state_changed_unknown: gesendet
angeforderter_Zustand
ÖFFNEN
DAY_LOCK
NIGHT_LOCK
UNBEKANNT
event_type
STATE_CHANGED_OPEN (requested_state = OPEN)
STATE_CHANGED_LATCH (requested_state = DAY_LOCK)
STATE_CHANGED_NIGHT_LOCK (requested_state = NIGHT_LOCK)
STATE_CHANGED_UNKNOWN (requested_state = UNKNOWN)
MOTOR_STALL (requested_state = UNKNOWN)
STATE_CHANGED_OPEN_REMOTE (requested_state = OPEN)
STATE_CHANGED_LATCH_REMOTE (requested_state = DAY_LOCK)
STATE_CHANGED_NIGHT_LOCK_REMOTE (requested_state = NIGHT_LOCK)
GO_TO_STATE_TO_LOCK (requested_state = NIGHT_LOCK)
key_local_id (null, wenn z.B. Manuelles Öffnen mit dem Knopf oder durch Drücken der Taste). Sie enthält die KeyID, die den Zustand der Sperre geändert hat.
Zu einem Staat gehen
Wenn das Schloss in eine neue Position geht (es kann die Position zum Beispiel nicht erreichen, wenn die Batterien fast leer sind), werden die folgenden JSON-Schlüssel für die Trigger trigger_state_goto_open, trigger_state_goto_latch, trigger_state_goto_night_lock: gesendet
go_to_state
ÖFFNEN
DAY_LOCK
NIGHT_LOCK
event_type
GO_TO_STATE_INSTANTOPEN_OPEN ( Touch to Open ) (go_to_state = OPEN)
GO_TO_STATE_INSTANTOPEN_LATCH ( Auto Unlock ) (go_to_state = DAY_LOCK)
GO_TO_STATE_MANUAL_UNLOCK_BLE_OPEN (go_to_state = OPEN)
GO_TO_STATE_MANUAL_LOCK_BLE_LATCH (go_to_state = DAY_LOCK)
GO_TO_STATE_MANUAL_LOCK_BLE_NIGHT_LOCK (go_to__state = NIGHT_LOCK)
GO_TO_STATE_TWIST_ASSIST_OPEN (go_to_state = OPEN)
GO_TO_STATE_TWIST_ASSIST_LATCH (go_to_state = DAY_LOCK)
GO_TO_STATE_TWIST_ASSIST_LOCK (go_to_state = NIGHT_LOCK)
GO_TO_STATE_MANUAL_UNLOCK_VIA_OUTSIDE_MODULE_PIN (go_to_state = OPEN)
GO_TO_STATE_MANUAL_UNLOCK_VIA_OUTSIDE_MODULE_BUTTON (go_to_state = OPEN)
GO_TO_STATE_TOUCH_TO_LOCK (go_to_state = NIGHT_LOCK)
key_local_id (255 bedeutet unbekannt, z.B. Manuelles Öffnen durch Knopf oder Drücken des Knopfes)
Prozentsatz der Batterie
Wenn das Schloss den aktuellen Batteriestand sendet (alle paar Stunden), werden die folgenden JSON-Schlüssel für den Trigger trigger_battery: gesendet
battery_type (0 = Alkaline, 1 = NiMH, 2 = Lithium (nicht wiederaufladbar), 3 = unbekannt)
Batterie_Prozentsatz
Online Status
Wenn das Schloss die Verbindung zur Bridge verliert, werden die folgenden JSON-Schlüssel für den Trigger trigger_online_status: gesendet
wifi_strength (derzeit in dB, bald wird dies in eine Prozentzahl geändert)
ble_strength (derzeit in dB, bald wird dies in eine Prozentzahl geändert. -1 bedeutet, dass das Schloss nicht angeschlossen ist)
Überprüfe, ob die Webhook-Anfrage von der LOQED-Brücke kam
Du könntest empfindliche Handlungen vornehmen, wenn sich die Tür öffnet (z. B. das Licht einschalten, den Alarm ausschalten, die Heizung einschalten). Deshalb musst du sicherstellen, dass auf der von dir angegebenen URL keine anderen Geräte solche Aktionen auslösen können. You can:
Stelle sicher, dass keine anderen Geräte die URL aufrufen können, indem du die IP nur auf die IP-Adresse der LOQED Bridge beschränkst. Stelle außerdem sicher, dass sich die IP-Adresse der Brücke nicht ändert, indem du sie im DHCP-Dienst deines Routers festlegst.
Überprüfe die Hash-Signatur, die in den Kopfzeilen des Webhook-Aufrufs gesendet wird. Im Header findest du TIMESTAMP (8 Bytes) und HASH (hex). Du kannst den Hash selbst berechnen, indem du sha256(BODY + TIMESTAMP + base64_decode(bridge_authentication_key) ausführst. Der Bridge-Authentifizierungsschlüssel kann auf https://app.loqed.com/API-Config gefunden werden. Der BODY ist der unveränderte Body, der mit der Anfrage empfangen wurde (mit dem gesamten JSON-Code). Vergiss auch nicht zu überprüfen, ob der Zeitstempel nur wenige Sekunden von der tatsächlichen Zeit abweicht, um Replay-Angriffe zu verhindern.
Mit unserem Tool einen Webhook auf der Brücke auflisten, hinzufügen und löschen
Der einfachste Weg, Webhooks aufzulisten, hinzuzufügen oder zu löschen, ist die Verwendung unseres Javascript-Tools:
Melde dich auf https://app.loqed.com/API-Config an.
Scrolle zur Überschrift "Ausgehende Webhooks über LOQED Bridge".
Klicke auf die Schaltfläche "Webhaken hinzufügen/löschen" neben der richtigen Brücke. Das Tool wird geöffnet und deine Bridge-IP-Adresse und dein Authentifizierungsschlüssel sind bereits ausgefüllt.
Einen Webhook auf der Bridge mit deinem Code auflisten, hinzufügen und löschen
Wenn du es den Nutzern deines Produkts leichter machen willst, es mit LOQED zu verbinden, kannst du auch die Bridge-API verwenden, um die Webhooks einzurichten. Im Folgenden werden die API-Endpunkte beschrieben. Du kannst dir den Code des oben erwähnten Javascript-Tools ansehen, wenn du ein Beispiel suchst. Die LOQED Bridge kann mit mDNS in deiner Anwendung gefunden werden (probiere zum Beispiel "DNS-sd -B _http._tcp" unter Windows)
Für alle /webhooks Webserver-Methoden sind zwei Header obligatorisch:
TIMESTAMP: enthält den aktuellen Zeitstempel
HASH - sha256 Hash-String
Die Hash-Berechnung ist für jede Art von Anfrage spezifisch und wird im entsprechenden Abschnitt beschrieben. Du brauchst den Authentifizierungsschlüssel der Brücke, um den Hash berechnen zu können. Diesen Schlüssel findest du nach dem Einloggen unter https://app.loqed.com/API-Config . Es gibt keine andere Möglichkeit, diesen Schlüssel abzurufen.
GET:
Gibt ein JSON-Array mit Schlüsseln zurück:
id" : 1 (int)
trigger_state_changed_open' : 0/1
trigger_state_changed_latch' : 0/1
trigger_state_changed_night_lock' : 0/1
trigger_state_changed_unknown' : 0/1
trigger_state_goto_open' : 0/1
trigger_state_goto_latch' : 0/1
trigger_state_goto_night_lock' : 0/1
trigger_battery' : 0/1
trigger_online_status' : 0/1
Gibt HTTP-Codes zurück:
Rückgabe eines HTTP 400 BAD REQUEST Codes und eines Strings mit einer Beschreibung, falls die Header ungültig sind oder nicht gefunden wurden
HTTP 401 UNAUTHORIZED zurückgeben, wenn die Authentifizierung fehlgeschlagen ist
POST:
trigger_state_changed_open' : 0/1
trigger_state_changed_latch' : 0/1
trigger_state_changed_night_lock' : 0/1
trigger_state_changed_unknown' : 0/1
trigger_state_goto_open' : 0/1
trigger_state_goto_latch' : 0/1
trigger_state_goto_night_lock' : 0/1
trigger_battery' : 0/1
trigger_online_status' : 0/1
Die HASH im Header muss wie folgt formatiert werden: SHA256(URL + trigger_bitmap + TIMESTAMP + LOCK_TOKEN), wobei URL ein String, trigger_bitmap 4 Bytes, TIMESTAMP eine 8 Bytes lange Zahl und LOCK_TOKEN der base64-dekodierte (!) Sicherheitsschlüssel der Bridge ist (der Schlüssel auf der Seite webhooks.loqed.com ist in base64). Das HASH sollte in Hexadezimal angegeben werden. Die trigger_bitmap enthält die Auslöser. Zum Beispiel ist 0x000F (15 dezimal) 0000 0000 0000 1010 im Binärformat, was bedeutet, dass die folgenden Auslöser aktiviert sind:
"trigger_state_changed_open":0
"trigger_state_changed_latch":1
"trigger_state_changed_night_lock":0
"trigger_state_changed_unknown":1
"trigger_state_goto_open":0
"trigger_state_goto_latch":0
"trigger_state_goto_night_lock":0
"trigger_battery":0
"trigger_online_status":0
Wir haben auch ein kleines PHP-Snippet, das zeigt, wie ein Webhook erstellt wird. Du kannst es hier herunterladen .
Retouren:
HTTP 200 OK Code und String mit Beschreibung im Falle einer erfolgreichen Webhook-Erstellung
HTTP 400 BAD REQUEST Code und String mit Beschreibung für den Fall, dass JSON für die Webhook-Erstellung nicht gültig ist
HTTP 400 BAD REQUEST Code und String mit Beschreibung, falls Header ungültig sind oder nicht gefunden werden
HTTP 401 UNAUTHORIZED, wenn die Authentifizierung fehlgeschlagen ist
HTTP 500 INTERNAL SERVER ERROR Code und String mit Beschreibung für den Fall, dass der Webhook mit dieser URL bereits existiert
HTTP 500 INTERNAL SERVER ERROR Code und String mit Beschreibung für den Fall, dass die maximale Anzahl von Webhooks erreicht wird
LÖSCHEN:
Retouren:
HTTP 200 OK Code und String mit Beschreibung bei erfolgreicher Löschung des Webhooks
HTTP 400 BAD REQUEST Code und String mit Beschreibung, falls Header ungültig sind oder nicht gefunden werden
HTTP 401 UNAUTHORIZED, wenn die Authentifizierung fehlgeschlagen ist
HTTP 404 NOT FOUND Code und String mit Beschreibung für den Fall, dass der Webhook mit {webhookId} nicht gefunden wurde
HTTP 500 INTERNAL SERVER ERROR Code und String mit Beschreibung, falls ein Fehler beim Löschen aufgetreten ist
Testen
Wir empfehlen die Verwendung von Webhook.site , wenn du überprüfen willst, ob dein Smart Lock/Bridge die Webhook URL aufruft. Dort kannst du auch die JSON-Daten sehen.
Öffne/schließe die Tür, wenn etwas passiert (eingehender Webhook)
Wenn du dein Schloss von einem Dienst oder Gerät eines Drittanbieters aus steuern möchtest, kannst du dies über einen HTTPS GET-Aufruf an deine LOQED Bridge URL tun.
Einen API-Schlüssel erstellen
Zuerst musst du einen neuen Schlüssel für dein LOQED Touch Smart Lock erstellen.
Öffne die Seite https://app.loqed.com/API-Config .
Melde dich mit deiner E-Mail-Adresse und deinem Passwort an, die du für die Anmeldung in der LOQED-App verwendest.
Klicke auf "Neuen API-Schlüssel hinzufügen".
Gib einen Namen zur einfachen Identifizierung ein. Das kann alles sein, was du willst.
Wenn du mehrere Schlösser hast, kannst du das richtige Schloss im Dropdown-Menü rechts neben "Schloss auswählen" auswählen.
Klicke auf "API-Schlüssel hinzufügen".
Du hast jetzt den API-Schlüssel erstellt.
Die API aufrufen
Derzeit unterstützt die API die folgenden Befehle:
Öffnen (das Schloss öffnet sich und kehrt dann in die Verriegelung zurück. Wird nur bei Türen ohne Griff an der Außenseite unterstützt). Es wird ein leeres JSON-Objekt zurückgegeben.
Verriegelung (entriegelt). Es wird ein leeres JSON-Objekt zurückgegeben.
Nachtsperre (abgeschlossen). Es wird ein leeres JSON-Objekt zurückgegeben.
Status. ACHTUNG: Wir empfehlen, den Status nur einmal am Tag abzufragen, um die Belastung der Brücke so gering wie möglich zu halten. Anstatt den Status abzufragen, solltest du einen Webhook implementieren, der deinen Server anruft, damit du eine sofortige Benachrichtigung erhältst, sobald sich der Status der Sperre ändert. Sie gibt die folgenden JSON-Schlüssel zurück:
mac_wifi (Identifikation sperren)
mac_bluetooth
lock_online (1, wenn die Sperre online ist, sonst 0)
battery_percentage (-1 wenn das Schloss offline ist, sonst 0 - 100)
battery_type (0 = Alkaline, 1 = NiMH, 2 = Lithium (nicht wiederaufladbar), 3 = unbekannt)
bolt_state_numeric (0 = unbekannt, 1 = offen, 2 = day_lock, 3 = night_lock)
bolt_state (unknown, open, day_lock, night_lock)
Lass die LOQED-Brücke die digitale Signatur erzeugen
Die Befehle an das Smart Lock müssen digital signiert werden. Am einfachsten ist es, diese Signatur von der LOQED-Brücke erstellen zu lassen. Verwende einfach die vier bereitgestellten URLs (open, latch, night lock, status), die auf webhooks.loqed.com angezeigt werden. Beachte, dass die HTTP-Verbindung zur Bridge nicht gesichert ist, sodass andere Personen in deinem lokalen Netzwerk den Verschlüsselungsschlüssel möglicherweise abrufen können. Wenn du Befehle sicher versenden willst, musst du die digitale Signatur selbst erstellen.
Erstelle die digitale Signatur selbst
Unter https://app.loqed.com/Bridge-API-example/ stellen wir Beispielcode (Javascript und PHP) bereit, der zeigt, wie die digitale Signatur erstellt wird. Du kannst diese Methode nur verwenden, wenn du ein Plugin für das Smart Home System erstellen kannst, mit dem du dich verbinden willst. Die benötigten Daten (IP, Geheimnis, KeyID) findest du unter https://app.loqed.com/API-Config , nachdem du auf die Schaltfläche "Anzeigen / Bearbeiten" neben dem API-Schlüssel geklickt hast.