Plugin-Daten
AutorMichael Schlenstedt Christian Fenzl
Logo
StatusSTABLE
Version0.5.0
Min. LB Version2.0.0
Release Downloadhttps://github.com/mschlenstedt/LoxBerry-Plugin-Nuki/archive/refs/tags/0.5.0.zip
BeschreibungBindet NUKI-Devices (Smartlock, Opener) über die NUKI-Bridge und MQTT an den Miniserver an.
SprachenEN, DE
Diskussionhttps://www.loxforum.com/forum/projektforen/loxberry/plugins/210944-nuki-smartlock-plugin

Nuki Smartlock

Version History...


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 → Native Nuki MQTT Support from ~Q2/2023
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

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)

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

  

Nuki Smartlock 3.0 PRO ohne Bridge

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.

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)

Fragen stellen und Fehler melden