====== Nuki Smartlock ====== ++++ Version History...| **Version 0.5.0 PRE-RELEASE** * LoxBerry 3.0 Kompatibilität * Diese Version erfordert zumindest LoxBerry 2.0 **Version 0.4.1 RELEASE** * Limitiert die Installation auf LoxBerry 1.4.x bis LoxBerry 2.x (kann nicht unter LoxBerry 3.0 installiert werden) * Dies ist die letzte Version, die mit LoxBerry 1.4.x funktioniert (die nächste Version benötigt zumindest LoxBerry 2.0) **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 [[plugins:mqtt_gateway:start|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 [[haufig_gestellte_fragen_faq:was_ist_der_securepin|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_30_pro_ohne_bridge|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 === {{plugins:nuki_smartlock:1236862248.png?200}} 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: {{plugins:nuki_smartlock:1236862249.png?600}} 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 {{plugins:nuki_smartlock:1236862438.png?16}}. Es erscheint ein Fenster mit folgendem Hinweis: {{plugins:nuki_smartlock:1236862250.png?250}} 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 [[https://developer.nuki.io/t/how-to-get-api-key-and-ip-address-calling-url-for-brdige-service/1031/2|Webseite]]) und mit dem Bearbeiten-Symbol {{plugins:nuki_smartlock:1236862439.png?16}} 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%%''. {{plugins:nuki_smartlock:1236862251.png?500}} 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. {{plugins:nuki_smartlock:1236862252.png?500}} 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 {{plugins:nuki_smartlock:1236862440.png?16}} des Gerätes.  {{plugins:nuki_smartlock:1236862426.png?350}} 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 ([[https://loxwiki.atlassian.net/wiki/spaces/LOX/pages/1522696312/Templates+in+Loxone+Config+einbinden|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 [[https://loxwiki.atlassian.net/wiki/spaces/LOX/pages/1526628350/NUKI+einbinden|NUKI einbinden]]). Beispieldatei zum Download: {{plugins:nuki_smartlock:1236862551.loxone|nuki_example.Loxone}} ==== Darstellung in LoxoneConfig ==== {{plugins:nuki_smartlock:1236862550.png?600}} ==== Darstellung in der Loxone App ==== {{plugins:nuki_smartlock:1236862558.png?250}}  {{plugins:nuki_smartlock:1236862559.png?250}} ===== 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 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. {{plugins:nuki_smartlock:1236862427.png?500}} 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 ([[https://loxwiki.atlassian.net/wiki/spaces/LOX/pages/1522696392|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]]