openhab-addons/bundles/org.openhab.binding.nuki/README.md

Nuki Binding

This is the binding for the Nuki Smart Lock.
This binding allows you to integrate, view, control and configure the Nuki Bridge and Nuki Smart Locks.

Prerequisites

1. At least one Nuki Smart Lock which is paired via Bluetooth with a Nuki Bridge. For this go and get either:
   • a Nuki Smart Lock and a Nuki Bridge or
   • the Nuki Combo or
   • a Nuki Smart Lock and the Nuki Nuki Software Bridge
2. The Bridge HTTP-API has to be enabled during Initial Bridge setup. 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!

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 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.	Default 8080
apiToken	The API Token which you configured during Initial Bridge setup.	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) and 4 (Lock).
  Supported Lock States are : 1 (Locked), 2 (Unlocking), 3 (Unlocked), 4 (Locking), 7 (Unlatching), 1002 (Unlocking initiated through Lock 'n' Go) and 1007 (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) and 5 (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]"
	}
}