NEW BINDING creation support Request - NUKI SMART LOCK


I have just received a REST API description for NUKI smartlocks (

It seems to be pretty straight forward as being REST with some JSON responses. But i am not really a java programmer as such - i would solve this with the use of the HTTP binding - but would be smart as well to have something in a seperate binding.

Sample from the API:

{“success”: true}

Anyone else been interested that we could join forces? Or who could guide me how to implement the same?

thx Karsten

I disagree. If the interface can be fully utilized using the HTTP binding that is where it should be implemented. There are already soooo many bindings and the number of bindings that have to be maintained and reviewed is one of the major reasons why updates to OH are so slow and why OH 2’s release is delayed.

So unless the API requires a bunch of complicated stuff the HTTP binding cannot handle (e.g. oauth or some other complicated authorization) or requires complicated parsing of the results (e.g. XSLT transforms to pull out needed data) or it integrates a bunch of APIs into one binding (e.g. the Weather binding) I would recommend against implementing a new binding.

What I would recommend is adding a new page to Application Integration section of the wiki. See the Roku page for an example of one way to document integration with a similar simple REST API product.

As an aside, I personally would not be comfortable using a door lock that did not have encryption (i.e. https) and some form of authentication. Otherwise anyone who can get on your network can open your door. I would recommend at least segregating this onto a separate internal network that cannot be reached from nor can get to the Internet and make sure your wifi is very locked down. Your OH server would then bridge between the two networks so you can get to your home automation.

I received my first NUKI lock yesterday, another one as well as a bridge will follow in a while when production ramps up. Right now I’m using an old android phone as bridge and plan to integrate it into openhab as well. Currently it seems i’m having an issue with bluetooth range of the Galaxy S4 mini i’m using as bridge or perhaps some race conditions when openhab and/or apps try to access the lock itself, however in most cases all works fine.

According to the “HTTP Bridge API” documentation ( there are basically three commands, one to retrieve the list of locks managed by the bridge, one to request the status per lock and another to change the status.

/lockstate returns the following values:

0 uncalibrated
1 locked
2 unlocked
3 unlocked (lock ‘n’ go)
4 unlatched
5 locking
6 unlocking
7 unlatching
254 motor blocked
255 undefined

I already had the states above showing up in openhab correctly using the following item:

String EGFrontdoorLock "Haustüre [%s]" { http="<[http://EGTec1NukiBridge:8080/lockstate?token=yyyyy&nukiid=xxxxx:30000:JSONPATH($.stateName)]" }

Now I want to change this item in a way that it is still showing the status as currently, but also offers a switch to lock/unlock the door. Basically for all states except “locked” it should show the switch as “open”, and when i turn the switch it should lock the door and update status accordingly. For the “locked” status (and only for this status) it should allow me to unlock the door.

I changed my item to the following:

Switch EGFrontdoorLock “Haustüre [%s]” { http="
>[OFF:POST:http://EGTec1NukiBridge:8080/lockaction?token=yyyyy&nukiid=xxxxx&action=1]" }

with this I can successfully lock and unlock the lock by using the switch, however the state is not shown correctly as returned by the lock (see above), instead it is always “ON” or “OFF”. How can I use a mapping file to correctly map the states returned from the lock to ON/OFF while at the same time keeping the description text that is provided by the lock, using just one item ?

Hi Max,

got mine yesterday as well. Started to include it as well. Had same issue.
I used a rule to solve this with by posting an update to the switch item based on the state coming from your EGFrontdoorLock

am currently traveling and only able to post the rule on friday.


Hi Max,

as promised - this is how i mad sure the update is loaded to my switch:

 rule "GarageLock Update"
 	Item NukiLockState2	received update
 	if (NukiLockState2.state == "1") {
 		if (NukiLock1.state==ON)
 	if (NukiLockState2.state == "2") {
 		if (NukiLock1.state==OFF)
 	if (NukiLockState2.state == "3") {
 		if (NukiLock1.state==OFF)

While NukiLockState2 is defined similar to your:

Number EGFrontdoorLock “Haustüre [%f.0]” { http="<[http://EGTec1NukiBridge:8080/lockstate?token=yyyyy&nukiid=xxxxx:30000:JSONPATH($.state)]" }

just looking for the Numbered state and not the naming.


I just received my Nuki lock. Do you guys have anything further to add to these configuration examples? I was thinking of writing a binding, but as Richard said there is very little point when everything can be handled by the HTTP binding quite easily.

In saying that…I do think a nicely rolled up binding makes life a lot easier for non-tech users wanting to deploy these types of devices. Especially with OHv2 whereby you could just give the Thing your bridge ip/port and it could discover your Nuki locks automatically via the REST API, and configure the channels/devices etc.

It also means it is easier to hide things like your API token since they live in the openhab.cfg files (which are easier to secure) rather than item files which often get shared around.

I am not running OHv2 yet but when I eventually migrate I might look at writing this.

In vacation Just now. Back only monday. Will Post what i have then.
Still a Bit struggling with the stability of the Android Bridge, as it
looses Connection to the nuki sometimes.



Sounds like the various apps/firmware are very much a work-in-progress. Have you signed up to the beta updates?

I look forward to hearing what you have setup upon your return.

Enjoy your holidays!

All very good arguments for a new binding for this in OH 2.

Hi, @Max1968, @karsten_kaiser_197, @ben_jones1, do you know if you can configure the Nuki to trigger an HTTP request or some other kind of action when it does an auto unlock. I have a door before my main door that has an electric latch that I can trigger with an HTTP request and would like that door to open when the Nuki senses that I am approaching home.


Hi Ferderico,

the API documentation is here:

I havent used auto-unlock for now. but as far as i understand the Lock itself is not triggering any http activities. this is only possible from the bridge. But a state change is not triggering a http POST. You only might be able to see this with the http binding and the request frequency towards the lock via the bridge.


I remember someone stating somewhere that once the bridge is available (the physical device, not the android app) there will be some webhook feature offering exactly this. I just checked the api documentation ( which is not yet describing this feature, guess i either saw it in the kickstarter comments or their slack channel.

I requested some response from Nuki Dev team. As soon as i got feedback i will share it here.

At least what i learned back in April - quoting the message: “it was that there was a kind of an issue with the e2e encryption. the bridge had been designed originally as been just a router between internet and Nuki…
They might plan something on push notifications - but with some hurdles on encryption and permissions - as not everyone should receive a notification,”

I have been talking to the Nuki dev team (they have a Slack channel you can join). The web hooks are coming, in both the Android bridge app and the yet-to-be-released Nuki Bridge. I am waiting for this feature to be added as this will make like a load easier.

NOTE: if you poll the Android bridge from openHAB this will cause the bridge to query the lock each time over bluetooth. I mistakenly thought the bridge would act as a proxy and retain the state of the lock, only being updated when the lock changed, meaning I could poll the bridge as often as I liked. However this is not the case and constant polling will destroy the lock batteries.

That explains My Battery draining :slight_smile:

Cheers Karsten


It looks like everybody is only talking about controling Nuki via the bridge and HTTP.
Why not using bluetooth directly ?
There is an api and that would/should avoid batrery drain and most importantly the need of a bridge (which connects Nuki to the cloud)…

Ofcourse the issue is that there is no bluetooth lte genic binding for OH2 yet…

But what about the idea of thinking about a specific one using bluetooth for nuki ?

You would still need a bridge of sorts - in your case a BT bridge.

The latest version of the Nuki Bridge firmware supports callback URLs so I have mine configured to callback to openHAB whenever the lock state changes, and openHAB can send lock/unlock commands via the REST API.

All working very nicely now. The bridge doesn’t need to connect to the Nuki servers other than to get the time during startup. Without this connection it does tend to behave a bit funny which is a shame. I requested they enhance the bridge so it could work in offline mode but they are too busy to worry about this edge case (their words) right now.

I tried it with no internet and once it was up and running I could send commands and receive updates. But as soon as the bridge restarts it can’t load the time and things go awry.

All in all, very happy with the bridge!

OK. Were you able to figure out how the bridge is getting the time ? is that via a standard protocol like NTP ?

What I do not like so much about the bridge is that it’s another piece of hardware needed to control the lock (of course using REST is an advantage…)…

If it works directly using the android app (without bridge) a standard Bluetooth card in a pc, should be enough to control it via OH, or am I missing something ?

I have been looking at Nuki since the beginning but was too late to get one on Kickstarter and then I decided to wait a bit before buying it (as it has been delayed and its price doubled :slight_smile:) so I do not have it yet…

Someone has created a Pi -> BT bridge for controlling the Nuki, which might be worth a look if you don’t want to use the bridge?