Geldt voor: LOQED Touch en LOQED Pure.
Dit is een geavanceerd ontwikkelaarsartikel voor lokale netwerkintegraties en uitgaande webhooks.
De lokale bridge-API is voornamelijk Bridge-georiënteerd. Voor LOQED Pure of op gateways gebaseerde configuraties controleert u de huidige API-beschikbaarheid voordat u een nieuwe integratie bouwt.
Bij sommige smart home-platforms of apparaten heeft LOQED geen directe integratie. Als u een gevorderde gebruiker bent, kunt u uw integratie ontwikkelen met behulp van de LOQED API. Lees zeker eerst ons artikel "Geavanceerde gebruikers: Beschikbare API's".
Wanneer de deur wordt geopend/vergrendeld, roept u een URL op (uitgaande webhook)
Wanneer de status van het slot verandert (openen, ontgrendelen, vergrendelen) en voor andere informatie (batterijpercentage, online status), kan de LOQED Bridge een URL oproepen (POST-gegevens naar). Hieronder kunt u zien welke gegevens als JSON naar deze URL worden gePOST. U kunt ook de GET-parameters van de URL toevoegen door de JSON-sleutel tussen "[" en "]" in te stellen. Bijvoorbeeld: https://your.server.nl/script?yourstate=[requested_state]. U kunt ook kiezen voor welke wijzigingen een webhook-oproep moet worden geactiveerd (u kunt er bijvoorbeeld voor kiezen om alleen een URL te bellen als de deur op slot is).
De volgende JSON-sleutels worden altijd verzonden:
mac_wifi: bevat het Wi-Fi MAC-adres van de bridge. Dit helpt bij het identificeren van de brug. De multicast DNS-naam van de bridge bevat dit adres ook.
mac_ble: bevat het Bluetooth MAC-adres van de bridge.
Staat bereikt
Nadat de motor is gestopt met draaien, worden de onderstaande JSON-sleutels verzonden voor de triggers trigger_state_changed_open, trigger_state_changed_latch, trigger_state_changed_night_lock, trigger_state_changed_unknown:
gevraagde_staat
GEOPEND
DAG_LOCK
NIGHT_LOCK
ONBEKEND
gebeurtenistype
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 = ONBEKEND)
MOTOR_STALL (requested_state = ONBEKEND)
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_TOUCH_TO_LOCK (requested_state = NIGHT_LOCK)
key_local_id (null als bijvoorbeeld handmatig wordt geopend met een knop of door op een knop te drukken). Hierin staat de KeyID die de status van het slot heeft gewijzigd.
Naar een staat gaan
Wanneer het slot naar een nieuwe positie gaat (het kan de positie mogelijk niet bereiken als de batterijen bijvoorbeeld bijna leeg zijn) worden onderstaande JSON-sleutels verzonden voor de triggers trigger_state_goto_open, trigger_state_goto_latch, trigger_state_goto_night_lock:
ga_naar_staat
GEOPEND
DAG_LOCK
NIGHT_LOCK
gebeurtenistype
GO_TO_STATE_INSTANTOPEN_OPEN (Touch to Open) (go_to_state = OPEN)
GO_TO_STATE_INSTANTOPEN_LATCH (Automatisch ontgrendelen) (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 betekent onbekend, bijvoorbeeld handmatig openen met een knop of door op een knop te drukken)
Batterijpercentage
Wanneer het slot het huidige batterijpercentage verzendt (elke paar uur) worden onderstaande JSON-sleutels verzonden voor de trigger trigger_batterij:
batterijtype (0 = Alkaline, 1 = NiMH, 2 = Lithium (niet-oplaadbaar), 3 = onbekend)
batterij_percentage
Onlinestatus
Wanneer het slot de verbinding met de bridge verliest, worden onderstaande JSON-sleutels verzonden voor de trigger trigger_online_status:
wifi_strength (momenteel in dB, binnenkort verandert dit in een percentage)
ble_strength (momenteel in dB, binnenkort verandert dit in een percentage. -1 betekent dat het slot niet is aangesloten)
Controleer of het webhookverzoek afkomstig is van de LOQED Bridge
U kunt gevoelige acties ondernemen als de deur opengaat (bijvoorbeeld de verlichting aandoen, het alarm uitzetten, de verwarming aanzetten). Daarom moet u ervoor zorgen dat op de URL die u heeft opgegeven, geen ander apparaat dergelijke acties kan activeren. U kunt:
Zorg ervoor dat geen ander apparaat de URL kan aanroepen door het IP-adres alleen te beperken tot het IP-adres van de LOQED Bridge. Zorg er ook voor dat het bridge-IP-adres niet verandert door dit vast te leggen in de DHCP-service van uw router.
Controleer de hashhandtekening die in de headers van de webhook-aanroep is verzonden. In de header vindt u TIMESTAMP (8 bytes) en HASH (hex). Je kunt de hash zelf berekenen door sha256(BODY + TIMESTAMP + base64_decode(bridge_authentication_key) uit te voeren. De bridge-authenticatiesleutel kun je vinden op https://app.loqed.com/API-Config. De BODY is de ongewijzigde body die bij het verzoek is ontvangen (met alle JSON-code). Vergeet ook niet te valideren of de tijdstempel zich binnen een paar seconden van de werkelijke tijd bevindt, om replay-aanvallen te voorkomen.
Met onze tool kunt u een webhook op de bridge weergeven, toevoegen en verwijderen
De eenvoudigste manier om webhooks weer te geven, toe te voegen of te verwijderen is door gebruik te maken van onze Javascript-tool:
Inloggen op https://app.loqed.com/API-Config
Scroll naar het kopje "Uitgaande webhooks via LOQED Bridge"
Klik op de knop "Webhooks toevoegen/verwijderen" naast de juiste bridge. De tool wordt geopend en uw bridge-IP-adres en authenticatiesleutel zijn vooraf ingevuld.
Met uw code kunt u een webhook op de bridge weergeven, toevoegen en verwijderen
Als u het gebruikers van uw product gemakkelijker wilt maken om het te verbinden met LOQED, kunt u ook de bridge-API gebruiken om de webhooks in te stellen. Hieronder worden de API-eindpunten beschreven. Als u een voorbeeld zoekt, kunt u de code van de bovengenoemde Javascript-tool bekijken. De LOQED Bridge kan worden gevonden met behulp van mDNS in uw applicatie (probeer bijvoorbeeld "DNS-sd -B _http._tcp" op Windows)
Voor alle /webhooks-webservermethoden zijn twee headers verplicht:
TIMESTAMP: bevat de huidige tijdstempel
HASH – sha256 hash-tekenreeks
De hashberekening is specifiek voor elk type verzoek en wordt beschreven in de bijbehorende sectie. Om de hash te kunnen berekenen, heb je de authenticatiesleutel van de bridge nodig. Deze sleutel vindt u na het inloggen op https://app.loqed.com/API-Config. Er is geen andere manier om deze sleutel op te halen.
Maak een lijst van webhooks
KRIJG: https://bridge-ip-address/webhooks
De HASH in de header moet worden geformatteerd: SHA256(TIMESTAMP + LOCK_TOKEN), waarbij TIMESTAMP een getal van 8 bytes is en LOCK_TOKEN de beveiligingssleutel van de base64-gedecodeerde (!) bridge is (de sleutel op de webhooks.loqed.com-pagina bevindt zich in base64). De HASH moet in hexadecimale vorm zijn.
Retourneert JSON-array met sleutels:
'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
Retourneert HTTP-codes:
Retourneert HTTP 400 BAD REQUEST-code en tekenreeks met beschrijving voor het geval de headers ongeldig zijn of niet worden gevonden
Retourneer HTTP 401 UNAUTHORIZED als de authenticatie is mislukt
Maak een webhook
POST: http://bridge-ip-adres/webhooks
Hoofdtekst: JSON met sleutels:
'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
De HASH in de header moet worden opgemaakt: SHA256(URL + trigger_bitmap + TIMESTAMP + LOCK_TOKEN), URL is een string, trigger_bitmap 4 bytes, TIMESTAMP is een getal van 8 bytes en LOCK_TOKEN is de door base64 gedecodeerde (!) bridge-beveiligingssleutel (de sleutel op de webhooks.loqed.com-pagina bevindt zich in base64). De HASH moet in hexadecimale vorm zijn. De trigger_bitmap bevat de triggers. 0x000F (15 decimaal) is bijvoorbeeld 0000 0000 0000 1010 in binair getal, wat betekent dat de volgende triggers zijn ingeschakeld:
"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
We hebben ook een klein PHP-fragment dat laat zien hoe een webhook wordt gemaakt, je kunt het hier downloaden.
Retouren:
HTTP 200 OK-code en string met beschrijving in geval van succesvolle creatie van een webhook
HTTP 400 BAD REQUEST-code en tekenreeks met beschrijving voor het geval dat JSON niet geldig is voor het maken van een webhook
HTTP 400 BAD REQUEST-code en tekenreeks met beschrijving voor het geval headers ongeldig zijn of niet worden gevonden
HTTP 401 UNAUTORIZED als authenticatie mislukt
HTTP 500 INTERNAL SERVER ERROR-code en tekenreeks met beschrijving voor het geval de webhook met deze URL al bestaat
HTTP 500 INTERNAL SERVER ERROR-code en tekenreeks met beschrijving voor het geval dat het MAX-aantal webhooks bereikt
Webhook verwijderen
VERWIJDEREN: http://bridge-ip-adres/webhooks/{webhookId}
De HASH in de header moet worden geformatteerd: SHA256(id + TIMESTAMP + LOCK_TOKEN), ID is een getal van 8 bytes, TIMESTAMP is een getal van 8 bytes en LOCK_TOKEN is de beveiligingssleutel van de base64-gedecodeerde (!) bridge (de sleutel op de webhooks.loqed.com-pagina bevindt zich in base64). De HASH moet in hexadecimale vorm zijn.
Retouren:
HTTP 200 OK-code en string met beschrijving in geval van succesvolle verwijdering van de webhook
HTTP 400 BAD REQUEST-code en tekenreeks met beschrijving voor het geval headers ongeldig zijn of niet worden gevonden
HTTP 401 UNAUTORIZED als authenticatie mislukt
HTTP 404 NOT FOUND-code en tekenreeks met beschrijving voor het geval dat webhook met {webhookId} niet is gevonden
HTTP 500 INTERNAL SERVER ERROR-code en tekenreeks met beschrijving voor het geval er een fout is opgetreden tijdens het verwijderen
Testen
Wij raden aan om te gebruiken Webhook.site als u wilt verifiëren dat uw slimme slot/bridge de webhook-URL aanroept. U kunt daar ook de JSON-gegevens bekijken.
Open/vergrendel de deur als er iets gebeurt (inkomende webhook)
Als u uw slot wilt bedienen vanaf een service of apparaat van derden, kunt u dit doen door middel van een HTTPS GET-oproep naar uw LOQED Bridge-URL.
Een API-sleutel maken
Eerst moet u een nieuwe sleutel aanmaken op uw LOQED slimme slot.
Open de pagina https://app.loqed.com/API-Config.
Log in met uw e-mailadres en wachtwoord dat u gebruikt voor het inloggen op de LOQED app.
Klik op ‘Nieuwe API-sleutel toevoegen’.
Voer een naam in voor gemakkelijke identificatie. Dit kan alles zijn wat je maar wilt.
Als u meerdere sloten heeft, kunt u in het vervolgkeuzemenu direct naast ‘Selecteer slot’ het juiste slot selecteren.
Klik op ‘API-sleutel toevoegen’.
U heeft nu de API-sleutel aangemaakt.
Roep de API aan
Momenteel ondersteunt de API de volgende opdrachten:
Open (slot gaat open en keert terug naar grendel. Alleen ondersteund op deuren zonder handgreep aan de buitenkant). Er wordt een leeg JSON-object geretourneerd.
Vergrendeling (ontgrendeld). Er wordt een leeg JSON-object geretourneerd.
Nachtslot (op slot). Er wordt een leeg JSON-object geretourneerd.
Status. LET OP: wij raden aan om de status slechts één keer per dag op te vragen, om de belasting op de brug tot een minimum te beperken. In plaats van om de status te vragen, kunt u het beste een webhook implementeren die uw server aanroept, zodat u direct een melding krijgt zodra de vergrendelingsstatus verandert. Het retourneert de volgende JSON-sleutels:
mac_wifi (slotidentificatie)
mac_bluetooth
lock_online (1 als het slot online is, anders 0)
batterijpercentage (-1 als het slot offline is, anders 0 - 100)
batterijtype (0 = Alkaline, 1 = NiMH, 2 = Lithium (niet-oplaadbaar), 3 = onbekend)
bolt_state_numeric (0 = onbekend, 1 = open, 2 = dagslot, 3 = nachtslot)
bolt_state (onbekend, open, dagslot, nachtslot)
Laat de LOQED-bridge de digitale handtekening genereren
Commando's naar het slimme slot moeten digitaal worden ondertekend. Het eenvoudigste is om de LOQED-bridge deze handtekening te laten genereren. Gebruik eenvoudigweg de vier meegeleverde URL's (open, grendel, nachtslot, status) die worden weergegeven op webhooks.loqed.com. Houd er rekening mee dat de HTTP-verbinding met de bridge niet beveiligd is, waardoor andere mensen op uw lokale netwerk mogelijk de coderingssleutel kunnen ophalen. Als u veilig opdrachten wilt verzenden, moet u zelf de digitale handtekening genereren.
Genereer zelf de digitale handtekening
Bij https://app.loqed.com/Bridge-API-example/ wij bieden voorbeeldcode (Javascript en PHP) die laat zien hoe de digitale handtekening tot stand komt. Je kunt deze methode alleen gebruiken als je een plug-in kunt maken voor het smart home-systeem waarmee je verbinding wilt maken. De gegevens die u nodig heeft (IP, geheim, KeyID) vindt u op https://app.loqed.com/API-Config nadat u op de knop "Bekijken / Bewerken" naast de API-sleutel hebt geklikt.