Metainformationen zur Seite
Dies ist eine alte Version des Dokuments!
Plugin-Daten | |
---|---|
Autor | Michael Schlenstedt Christian Fenzl |
Logo | |
Status | STABLE |
Version | 0.3.4 |
Min. LB Version | 1.4.2 |
Release | https://github.com/mschlenstedt/LoxBerry-Plugin-Nuki/archive/0.3.4.zip |
Pre-Release | https://codeload.github.com/mschlenstedt/LoxBerry-Plugin-Nuki/zip/0.4.0 |
Beschreibung | Bindet NUKI-Devices (Smartlock, Opener) über die NUKI-Bridge und MQTT an den Miniserver an. |
Sprachen | EN, DE |
Forum | https://www.loxforum.com/forum/projektforen/loxberry/plugins/210944-nuki-smartlock-plugin |
Nuki Smartlock
Version History…
Version 0.4.0 PRE-RELEASE
- Erweitert um die neuen Device Types Smart Door und Smart Lock 3.0 (Nuki Bridge API V1.13.1 vom 30.12.2021)
- Korrektur der Farbhinterlegung des RSSI-Wertes
Version 0.3.5 PRE-RELEASE
- Fix: Wenn mehrere Bridges in Reichweite des selben SmartLock/Openers sind, zeigte die Device-Liste sonderbare bzw. fehlerhafte Informationen
- Änderung: Die Device-List zeigt jetzt nur noch Geräte, die erfolgreich mit einer Bridge gepaired sind, d.h. ohne Pairing zu einer Bridge werden keine Geräte mehr angezeigt. Das Pairing der Geräte muss (wie bisher) mit der Nuki App erfolgen.
Version 0.3.4 RELEASE
- Korrigiert einen Fehler im Selbsttest/Healthcheck, dass es bei mehreren Nuki-Geräten vorkommen konnte, dass der Fehler "Nicht alle Geräte gefunden" gemeldet wurde
- Stündliche Überprüfung durch Cron: Wenn die Bridge ein Nuki-Gerät als Offline meldet, wird bei den drei Wiederholungsversuchen nun jeweils 10 Sekunden gewartet
Version 0.3.3 RELEASE
- Integriert sich in den LoxBerry Selbsttest / Healthcheck (ab LB 2.2)
- doorsensorState zum VI Template hinzugefügt
Version 0.3.2 PRE-RELEASE
- Behebt einen Fehler für Nuki Opener, dass die stündliche Ausführung per Cron immer einen Fehler lieferte
- Die stündlichen Abfragen probieren jetzt bis zu drei Mal, sollte ein Fehler zurückkommen (alle Geräte)
Version 0.3.1 RELEASE
- Callback erzeugt ein Log (als "Callback" bei den Logfiles)
Version 0.3.0 RELEASE
- Das NUKI Plugin registriert die MQTT Subscription automatisch beim MQTT Gateway
- Schnellere Anzeige des Token- und Online-Status (insbesondere bei mehreren Bridges)
- Besseres Logging für asynchrone Ajax-Requests
Version 0.2.2
- Korrigiert den Statusabruf per Cron für Nuki Opener (nicht betroffen ist das normale Smartlock)
- Korrigiert kleine Fehler im Template Builder
- Visuelle Optimierung der Popups
Version 0.2.1
- Behebt eine Deadlock-Situation des Webinterfaces
Version 0.2
- Sicherheit: Token wird nicht mehr ins Logfile geschrieben
- Sicherheit: Durchgehend alle Aktionen sind mit dem SecurePIN geschützt
- Geräte: Anzeige der Geräte-Signalstärke (RSSI) in Farbe
- Analog-Action zum VO-Template hinzugefügt
- Anpassungen für die Unterstützung von Multilingual
- Deutsche Übersetzung
Version 0.1.1
- Virtual Outs gefixt
- Sonderzeichen/Encodingfehler in VI/VO-Namen gefixt
Version 0.1.0
- erste öffentliche Version
Download
Direkter Download-Link: Siehe Tabelle oben
Letzter Entwicklungsstand im Repo: https://github.com/mschlenstedt/LoxBerry-Plugin-Nuki
Funktion des Plugins
Das Plugin verbindet sich mit der NUKI Bridge (Hardware-Bridge oder Software-Bridge), die zur Nutzung zwingend notwendig ist. Von der Bridge werden alle Zustandsänderungen an den NUKI-Devices an das Plugin und weiter and den MQTT-Broker gemeldet. Nutzt man als Broker das MQTT Gateway Plugin, werden diese Änderungen direkt an den Miniserver übertragen. Über die NUKI Bridge können die Devices gesteuert werden (z. B. Abschließen oder Aufschließen). Das Plugin erzeugt die dazu notwendigen Virtuellen Ausgänge. Diese lassen sich direkt in Loxone Config einbinden.
SecurePIN
Aus Sicherheitsgründen ist das Webinterface des NUKI Smartlock Plugins mit dem SecurePIN geschützt.
Kompatibilität mit Nuki-Geräten
Gerät | Kompatibel |
Nuki Smartlock 1.0 mit Bridge | YES |
Nuki Smartlock 2.0 mit Bridge | YES |
Nuki Smartlock 3.0 mit Bridge | YES |
Nuki Smartlock 3.0 PRO (ohne Bridge) | NO |
Nuki Smartlock 3.0 PRO (mit Bridge) | YES |
Nuki Opener | YES |
Nuki Box | UNKNOWN |
Nuki Smart Door | UNKNOWN |
Konfiguration: Schritt für Schritt (mit MQTT Gateway Plugin)
Nimm dein NUKI Smartlock und deine NUKI Bridge lt. NUKI-Anleitung in Betrieb
Wenn dein Smartlock und die Bridge richtig konfiguriert ist, sollte es möglich sein, mit der NUKI App zumindest aus deinem WLAN das Smartlock zu bedienen.
Installieren des MQTT Gateway Plugins
Im MQTT Gateway Plugin:
- "Set virtual inputs via HTTP webservice" aktivieren
- "Expand JSON data" aktivieren
- Folgende Subscription erstellen:
nuki/#
(ab Plugin-Version 0.3.0 passiert das automatisch bei Verwendung des MQTT Gateways)
Installieren dieses NUKI Smartlock Plugins
NUKI Smartlock Plugin: Bridges suchen
Auf dem "Bridges" Tab drücke den Button "Search for Bridges" ("Suche nach Bridges"). Es werden der Plugin-Konfiguration automatisch alle Bridges hinzugefügt, die sich in deinem Netzwerk befinden:
Der Token ist - wie du siehst - noch unbekannt. Dieser wird für den Zugriff des Plugins auf die Bridge benötigt.
TOKEN abrufen
Dafür musst du ein Pairing durchführen. Dafür wird es gleich notwendig, auf den Knopf der Bridge zu drücken.
Klicke also auf das Pairing-Symbol . Es erscheint ein Fenster mit folgendem Hinweis:
Unten steht nun Waiting, und du hast 30 Sekunden Zeit dafür, den Knopf in der Mitte der Bridge zu drücken.
War das erfolgreich, erscheint der Token in der Bridge-Übersicht.
Alternativ ist es möglich, den Token mit der NUKI App auszulesen (siehe NUKI Webseite) und mit dem Bearbeiten-Symbol manuell einzutragen.
Devices suchen
Wechsele auf den Tab „Devices“. Es wird automatisch eine Suche nach deinen NUKI Smart Locks und Openers durchgeführt. Nur Geräte, die hier gefunden werden, werden vom Plugin verarbeitet.
Solltest du keine Geräte finden, prüfe in der NUKI App das Pairing zwischen Bridge und dem Smart Lock. Du kannst danach die Suche nochmal ausführen.
MQTT im NUKI-Plugin einrichten
Wechsle auf den Tab "MQTT".
Setze ein Topic, unter dem alle NUKI SmartLocks ihre Daten senden. Standard ist nuki
.
Wenn auf diesem LoxBerry das MQTT-Gateway Plugin installiert ist, aktiviere die Checkbox "Use MQTT Gateway credentials". Alle weiteren Felder sind dann unerheblich, weil diese Informationen direkt aus der MQTT Gateway Plugin-Konfiguration gelesen werden. Solltest du diese Checkbox nicht sehen, hast du das MQTT Gateway Plugin noch nicht installiert.
Mit deaktivierter Checkbox kannst du die MQTT-Einstellungen selbst durchführen.
Testen der MQTT-Übertragung der Smartlock-Stati
Öffne im MQTT-Gateway die "Incoming Overview" und führe, z.B. mit der NUKI-App, oder direkt mit dem Knopf auf dem Smartlock, einen Sperrbefehl aus.
Die Übertragung der Statusänderung erfolgt, sobald der Sperrbefehl vom Smartlock fertig durchgeführt ist.
Hinweis: Aus eigenen Tests sowie Feedback aus dem Loxforum und NUKI Developer Forum wissen wir, dass es bei der Rückmeldung zu einer Verzögerung von bis zu ca. 20 Sekunden kommen kann. Ursache dafür ist die späte Rückmeldung der NUKI Bridge (Stand: 17.09.2019, Bridge-Firmware 2.2.13).
Einrichten von virtuellen Eingängen und Ausgängen mit Templates
Öffne dafür die Devices-Ansicht und klicke das Virtual In / Virtual Out Symbol des Gerätes.
Oben findest du Downloads für Virtuelle Ausgänge und Virtuelle Eingänge. Verwende die Vorlagen-Import-Funktion der Loxone Config, um diese zu importieren (Templates in Loxone Config einbinden).
Die Vorlagen sind genau für dieses Gerät erstellt.
- Die Vorlage für Virtuelle Ausgänge gehen direkt zur NUKI Bridge - d.h. auch wenn der LoxBerry ausfallen sollte, funktionieren die Sperrbefehle.
- Die Vorlage für Virtuelle Eingänge sind die Bezeichnungen, die vom MQTT-Gateway übermittelt werden. Hinweis: Da es keine Vorlagenfunktion direkt für Virtuelle Eingänge gibt, haben wir eine Vorlage für Virtuelle HTTP Eingänge erzeugt. Die URL und Polling Time in der Vorlage muss leer bleiben!
Darunter findest du eine Tabelle, welche Daten von NUKI bzw. dem Plugin übermittelt werden und die Erklärung der Werte.
Loxone Config
Hast Du die virtuellen Ein- und Ausgänge in LoxoneConfig importiert, kannst Du diese entsprechend in Deiner Programmierung verwenden. Ein Beispiel für eine Status-Anzeige und eines RadioButton-Bausteins zum Schalten des NUKI findest Du im folgenden (Idee übernommen aus dem Original-Wiki-Artikel NUKI einbinden).
Beispieldatei zum Download: nuki_example.Loxone
Darstellung in LoxoneConfig
Darstellung in der Loxone App
Technische Informationen
Zurückgelieferte Informationen in den Virtuellen Eingängen
Feld | Im Input Template | Mögliche Werte |
batteryCritical | x | 0 → Batterie ok 1 → Batterie kritisch |
deviceType | 0 → NUKI Smart Lock 2 → NUKI Opener |
|
doorsensorState | Türsensor (ab Nuki SmartLock 2.0) 0 → unavailable 1 → deactivated 2 → door closed 3 → door opened 4 → door state unknown 5 → calibrating |
|
doorsensorStateName | Türsensor (Text von doorsensorState) | |
mode | x | Beim Smart Lock immer → 2 Beim Opener: 2 → Door Mode 3 → Ring to Open permanently active |
nukiId | x | The ID of the device |
state | x | -1 bis 255 (siehe Tabelle unten) |
stateName | Textbezeichnung des state | |
sentBy | x | Wordurch wurde diese Statusmeldung ausgelöst 1 → Callback 2 → Cronjob 3 → Manuell 254 → Test |
sentByName | Textuelle Bezeichnung von sentBy | |
sentAtTimeISO | Zeitstempel im Human Readable Format, wann die Übertragung stattgefunden hat | |
sentAtTimeLox | x | Loxone Zeitstempel, wann die Übertragung stattgefunden hat (kann in den Loxone Eigenschaften mit <v.u> als Zeit angezeigt werden) |
State-Tabelle
ID | smartlock (deviceType 0) | opener (deviceType 2) |
-1 | Plugin-Fehler oder Smart Lock nicht erreichbar | |
0 | uncalibrated | untrained |
1 | locked | online |
2 | unlocking | - |
3 | unlocked | rto active |
4 | locking | - |
5 | unlatched | open |
6 | unlocked (lock ‘n’ go) | - |
7 | unlatching | opening |
253 | - | boot run |
254 | motor blocked | - |
255 | undefined | undefined |
Der Status -1 wird vom Plugin bei jeglichen Fehlern gesetzt, die den Zugriff auf die Bridge oder das Smart Lock verhindern. Zum Beispiel
- Bridge nicht erreichbar
- Token falsch
- Smart Lock ID existiert nicht (mehr)
- Keine Verbindung von Bridge zu SmartLock
Callback
Das Plugin verwendet für das Pushen die NUKI Bridge-Funktion "Callback", d.h. das Plugin richtet automatisch bei der Bridge die URL ein, mit der die Bridge bei einer Statusänderung die Daten an das Plugin übermittelt.
Das Plugin verwendet zum Einrichten des Callbacks die IP-Adresse von LoxBerry. Es wird automatisch stündlich überprüft
- ob der Callback auf allen Bridges noch existiert, oder
- ob sich die IP-Adresse von LoxBerry geändert hat,
und der Callback auf den Bridges aktualisiert. Dies passiert nur bei Bridges, die in im NUKI Plugin eingerichtet und online sind und der Token stimmt. Ändert sich die IP-Adresse von LoxBerry, kann es daher bis zu einer Stunde dauern, bis der Callback aktualisiert wird. Bearbeite im Plugin die Bridge (ohne Änderungen) und speichere, dann wird der Callback sofort aktualisiert.
Weitere Information zu Callbacks:
- Die Daten des Callbacks werden erst übermittelt, wenn die Statusänderung erfolgreich abgeschlossen ist.
- Andere Callbacks als die eigenen des Plugins werden vom Plugin nicht gelöscht oder angepasst.
- Wird das NUKI Plugin auf mehreren LoxBerrys installiert und die Bridges konfiguriert, legt jedes NUKI Plugin seine eigenen Callbacks an, die parallel existieren
- Es sind maximal 3 Callbacks auf der Bridge möglich. Die Liste der aktuellen Callbacks findest du in den Bridge-Details.
Stündliche Abfrage direkt vom Smart Lock
Zusätzlich zur Überprüfung der Callbacks wird stündlich direkt von allen konfigurierten Smartlocks der aktuelle Status abgerufen. Die benötigt etwas Strom, jedoch haben wir bei den Tests die Erfahrung gemacht, dass es passieren kann, dass die Bluetooth-Verbindung zwischen SmartLock und Bridge abbricht, womit die Callbacks nicht mehr funktionieren. Mit diesem Direktabruf wird der Status aktualisiert, und wir können prüfen, ob alles funktioniert.
Die Daten werden dabei in die gleichen Eigenschaften übertragen.
Die stündliche Aktualisierung ist erkennbar an sentBy=2
bzw. sentByName=cron
, während die Echtzeit-Rückmeldung mit sentBy=1
bzw. sentByName=callback
übermittelt wird.
Wenn sich der Wert sentAtTimeLox für mehr als eine Stunde (3600 Sekunden) nicht ändert, stimmt etwas nicht (epochtime (Unix-Zeit) zum Prüfen auf Datenaktualität nutzen).
Sollte bei unserer Prüfung ein Fehler auftreten, wird von uns der state = -1
gesetzt, und der stateName
auf den Fehler, den wir erhalten haben. Auch der state
sollte deswegen von euch in der Loxone Config überprüft werden. Was genau bei einem Fehler passiert ist, findet man dann in im Log "Cronjob".
Alte/falsche/fremde Callbacks entfernen
Das NUKI-Plugin verwaltet seine Callbacks auf den Bridges vollautomatisch, es ändert jedoch nichts an fremden Callbacks.
Um sämtliche Callbacks zu löschen, und nur den Plugin-Callback zu setzen:
- Öffne in der Bridge-Ansicht die Details (Info-Symbol)
- Klicke den Button "Reset Callbacks"
- Es werden dadurch alle Callbacks gelöscht, und jener vom Plugin angelegt.
- Nach der Aktualisierung muss der Plugin-Callback erscheinen.
Deinstallation des Plugins
Wenn du das Plugin deinstallieren möchtest, lösche zuerst alle Bridges aus der Plugin-Konfiguration. Durch das Löschen wird unser Callbacks von den Bridges entfernt. Deinstallierst du das Plugin, ohne die Bridges zu entfernen, bleiben unsere Callbacks auf den Bridges registriert.
LoxBerry Selbsttest / Healthcheck
Das Plugin integriert sich in den LoxBerry Selbsttest (ab LoxBerry 2.2). Geprüft wird dabei der Status und die letzte Übermittlungszeit am Broker, sowie der Gerätestatus der Nuki-Geräte. Wird der Status länger als drei Stunden nicht aktualisiert, oder ein Nuki-Gerät wurde als nicht erreichbar gemeldet, wird dies als Error ausgegeben.
Roadmap
- Tests mit Software Bridge (bitte im Forum um ein kurzes OK/NOK bzw. Feedback, wenn du das Plugin mit der Software Bridge verwendest!)
- Tests mit NUKI Opener integrieren (bitte im Forum um ein OK/NOK bzw. Feedback - evt. Remote Support Session, wenn es Probleme gibt)
Links
Versionen der Bridge Firmware (Release-Versionen): https://developer.nuki.io/t/nuki-bridge-firmware-release-notes-public-releases/2797
Versionen der NUKI Smartlock 2.0 Firmware (Release-Versionen): https://developer.nuki.io/t/nuki-smart-lock-2-0-release-notes-public-releases/2685
Versionen der NUKI Smartlock 1.0 Firmware (Release-Versionen): https://developer.nuki.io/t/nuki-smart-lock-1-0-release-notes-public-releases/2801
Versionen der NUKI Opener Firmware (Release-Versionen): https://developer.nuki.io/t/nuki-opener-release-notes-public-releases/2858
Fragen stellen und Fehler melden
Im Loxforum in diesem Thread: https://www.loxforum.com/forum/projektforen/loxberry/plugins/210944-nuki-smartlock-plugin