This page is part of archived documentation for openHAB 2.5. Go to the current stable version
# Nuki Binding
This is the binding for the Nuki Smart Lock (opens new window).
This binding allows you to integrate, view, control and configure the Nuki Bridge and Nuki Smart Locks.
# Prerequisites
- At least one Nuki Smart Lock which is paired via Bluetooth with a Nuki Bridge. For this go and get either:
- The Bridge HTTP-API has to be enabled during Initial Bridge setup (opens new window). Note down the IP, Port and API token.
It is absolutely recommended to configure static IP addresses for both, the openHAB server and the Nuki Bridge!
You can configure the Nuki Binding either by using Paper UI or manually through text files.
# Nuki Bridge Callback
The Nuki Binding will manage the required callback from the Nuki Bridge to the openHAB server if manageCallbacks is set to true.
If manageCallbacks is not set it will default to true.
If you want to manage the callbacks from the Nuki Bridge to the openHAB server by yourself, you need to set manageCallbacks to false.
Then add the callback on the Nuki Bridge via Bridge API Endpoint /callback/add in the format http://<openHAB_IP>:<openHAB_PORT>/nuki/bcb.
The Sheet NukiBridgeAPI (opens new window) is a helpfull tool for listing, adding and removing callbacks.
# Supported Bridges
This binding supports just one bridge type: The Nuki Bridge. Create one bridge per Nuki Bridge available in your home automation environment.
The following configuration options are available:
| Parameter | Description | Comment |
|---|---|---|
| ip | The IP address of the Nuki Bridge. Look it up on your router. It is recommended to set a static IP address lease for the Nuki Bridge (and for your openHAB server too) on your router. | Required |
| port | The Port which you configured during Initial Bridge setup (opens new window). | Default 8080 |
| apiToken | The API Token which you configured during Initial Bridge setup (opens new window). | Required |
| manageCallbacks | Let the Nuki Binding manage the callbacks on the Nuki Bridge. It will add the required callback on the Nuki Bridge. If there are already 3 callbacks, it will delete the callback with ID 0. | Default true |
# Supported Things
This binding support just one thing type: The Nuki Smart Lock. Create one smartlock per Nuki Smart Lock available in you home automation environment.
The following configuration options are available:
| Parameter | Description | Comment |
|---|---|---|
| nukiId | The Nuki-ID of the Nuki Smart Lock. It is a 8-digit hexadecimal string. Look it up on the sticker on the back of the Nuki Smart Lock (remove mounting plate). | Required |
| unlatch | If set to true the Nuki Smart Lock will unlock the door but then also automatically pull the latch of the door lock. Usually, if the door hinges are correctly adjusted, the door will then swing open. | Default false |
# Supported Channels
lock (Switch)
Use this channel with a Switch Item to lock and unlock the door.lockState (Number)
Use this channel if you want to execute other supported lock actions or to display the current lock state.
Supported Lock Actions are:2(Unlock),7(Unlatch),1002(Lock 'n' Go),1007(Lock 'n' Go with Unlatch) and4(Lock).
Supported Lock States are :1(Locked),2(Unlocking),3(Unlocked),4(Locking),7(Unlatching),1002(Unlocking initiated through Lock 'n' Go) and1007(Unlatching initiated through Lock 'n' Go with Unlatch).
Unfortunately the Nuki Bridge is not reporting any transition states (e.g. for Lock 'n' Go).lowBattery (Switch)
Use this channel to receive a low battery warning.doorsensorState (Number)
Use this channel if you want to display the current door state provided by the door sensor.
Supported Door Sensor States are :0(Unavailable),1(Deactivated),2(Closed),3(Open),4(Unknown) and5(Calibrating).
# Full Example
A manual setup through files could look like this:
# things/nuki.things
Bridge nuki:bridge:NB1 [ ip="192.168.0.50", port=8080, apiToken="myS3cr3t!", manageCallbacks=true ] {
Thing smartlock SL1 [ nukiId="12AB89EF", unlatch=false ]
}
# items/nuki.items
Switch Frontdoor_Lock "Frontdoor (Unlock / Lock)" <nukiwhite> { channel="nuki:smartlock:NB1:SL1:lock" }
Number Frontdoor_LockState "Frontdoor (Lock State)" <nukisl> { channel="nuki:smartlock:NB1:SL1:lockState" }
Switch Frontdoor_LowBattery "Frontdoor Low Battery" <nukibattery> { channel="nuki:smartlock:NB1:SL1:lowBattery" }
Number Frontdoor_DoorState "Frontdoor (Door State)" <door> { channel="nuki:smartlock:NB1:SL1:doorsensorState" }
# sitemaps/nuki.sitemap
sitemap nuki label="Nuki Smart Lock" {
Frame label="Channel Lock" {
Switch item=Frontdoor_Lock
}
Frame label="Channel State used for lock actions" {
Switch item=Frontdoor_State mappings=[2="Unlock", 7="Unlatch", 1002="LnGo", 1007="LnGoU", 4="Lock"]
}
Frame label="Channel State" {
Text item=Frontdoor_LockState label="Lock State [MAP(nukilockstates.map):%s]"
}
Frame label="Channel Low Battery" {
Text item=Frontdoor_LowBattery label="Low Battery [%s]"
}
Frame label="Channel Door State" {
Text item=Frontdoor_DoorState label="Door State [MAP(nukidoorsensorstates.map):%s]"
}
}