Zum Hauptinhalt springen

Lokale LOQED-Brücken-API-Integration

Vor über 2 Jahren aktualisiert

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:

  1. Melde dich auf https://app.loqed.com/API-Config an.

  2. Scrolle zur Überschrift "Ausgehende Webhooks über LOQED Bridge".

  3. 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:

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:

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.

Bild

  • Klicke auf "Neuen API-Schlüssel hinzufügen".

Bild

  • 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".

Bild


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.

Verwandte Artikel
LOQED verfügbare APIs
LOQED Web API Integration
Loxone & LOQED Integration
Doorbird & LOQED Integration
Integration von Domoticz und LOQED
Hat dies deine Frage beantwortet?