Nuki Smartlock

Version History...

Direkter Download-Link: Siehe Tabelle oben

Letzter Entwicklungsstand im Repo: https://github.com/mschlenstedt/LoxBerry-Plugin-Nuki

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.

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.

Nicht erforderlich ab LoxBerry 3.0.

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)

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.

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.

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.

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.

Ö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).

Ö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. 

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

Stand 09.01.2023

Das Nuki Smartlock 3.0 PRO kann aktuell ohne Bridge nicht eingebunden werden (das Pro besitzt keine lokalen Schnittstellen), jedoch läuft derzeit von Nuki eine Closed-Beta Phase für native MQTT-Unterstützung des 3.0 Pro. Es gibt noch keinen Release-Termin, jedoch ist für 2023 der Release geplant.

Mit der nativen MQTT-Schnittstelle wird das Nuki Smartlock Plugin nicht mehr benötigt, jedoch weiterhin das MQTT Gateway am LoxBerry. Voraussichtlich wird man dann in der Nuki-App die MQTT Server Einstellungen vornehmen. Im MQTT Gateway ist dann nur noch die Subscription einzurichten.

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

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.

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

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.

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.

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. 

• 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)

• 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

Im Loxforum in diesem Thread: https://www.loxforum.com/forum/projektforen/loxberry/plugins/210944-nuki-smartlock-plugin