Skip to end of metadata
Go to start of metadata
Autor
Logo

Status

RELEASE

Version0.2.2
Min. LB Version

LB 1.4.2

Downloadhttps://github.com/mschlenstedt/LoxBerry-Plugin-Nuki/archive/0.2.2.zip
ZweckBindet NUKI-Devices (Smartlock, Opener) über die NUKI-Bridge und MQTT an den Miniserver an.
LanguagesEN, DE
Diskussionhttps://www.loxforum.com/forum/projektforen/loxberry/plugins/210944-nuki-smartlock-plugin
 Version History...

Version 0.1.0

  • erste öffentliche Version

Version 0.1.1

  • Virtual Outs gefixt
  • Sonderzeichen/Encodingfehler in VI/VO-Namen gefixt

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

  • Behebt eine Deadlock-Situation des Webinterfaces

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

Inhalt



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.

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/#

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

FeldIm Input TemplateMögliche Werte
batteryCriticalx

0 → Batterie ok
1 → Batterie kritisch

deviceType
0 → NUKI Smart Lock
2 → NUKI Opener
modexBeim Smart Lock immer → 2
Beim Opener: 2 → Door Mode 3 → Ring to Open permanently active
nukiIdxThe ID of the device
statex-1 bis 255 (siehe Tabelle unten)
stateName
Textbezeichnung des state
sentByx

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
sentAtTimeLoxxLoxone Zeitstempel, wann die Übertragung stattgefunden hat (kann in den Loxone Eigenschaften mit <v.u> als Zeit angezeigt werden)

State-Tabelle

IDsmartlock (deviceType 0)opener (deviceType 2)
-1Plugin-Fehler oder Smart Lock nicht erreichbar
0uncalibrateduntrained
1lockedonline
2unlocking-
3unlockedrto active
4locking-
5unlatchedopen
6unlocked (lock ‘n’ go)-
7unlatchingopening
253-boot run
254motor blocked-
255undefinedundefined

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.

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)
  • Deutsche Übersetzung des Plugins

Fragen stellen und Fehler melden

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