More details provided by the Nuki Bridge HTTP API

Add-ons Bindings
1

I recently purchased a Nuki Smart Lock because it’s the only option I could find that would support a European mortise lock with integration to OpenHAB. The Yale Linus looks like a better option but unfortunately, I couldn’t find a supporting binding.

However, I discovered that the Nuki HTTP API doesn’t provide information on what user locked/unlocked the lock and what actuator was used (keypad, manual, bridge, etc.), similar to what’s displayed on the Activity Logs in the app.

I think it would be very useful to have that information provided by the HTTP API so more advanced rules can be created, e.g., when a specific user locks the door via the keypad the vacuum cleaner could vacuum the home or the vacation mode could be activated.

What do you think?

2

It’s certainly possible to get the log using the web API, but there’s still the issue of having no callbacks from the web, which means you get notification of changed door status with delay.

I’m not sure how exactly would that work. Poll the door state API and when lock status changes, fetch latest log event and somehow send it from binding? Or poll the events endpoint as well and whenever new events appear send it? Due to the polling nature you would often get them in batches, sometimes maybe for multiple door opening if the polling interval is long enough.

Also how would that integration look like on a nuki thing? I captured a log when I came home today using auto-unlock and it looks like this:

  {
    "id": "aaaaaaaa",
    "smartlockId": 123456789,
    "deviceType": 0,
    "name": "",
    "action": 241,  // door close
    "trigger": 0,
    "state": 0,
    "autoUnlock": false,
    "date": "2022-12-20T00:00:42.000Z",
    "source": 0
  },
  {
    "id": "bbbbbbb",
    "smartlockId": 123456789,
    "deviceType": 0,
    "name": "",
    "action": 240,  // door open
    "trigger": 0,
    "state": 0,
    "autoUnlock": false,
    "date": "2022-12-20T00:00:21.000Z",
    "source": 0
  },
  {
    "id": "ccccccc",
    "smartlockId": 123456789,
    "deviceType": 0,
    "authId": "xxxxxxxxx",
    "name": "Firstname Lastname",
    "action": 3,  // unlatch
    "trigger": 0,
    "state": 0,
    "autoUnlock": true,
    "date": "2022-12-20T00:00:20.000Z",
    "source": 0
  },

What channels would be useful on a nuki thing with log history, separate channel for each attribute, or just send it in a for example trigger channel as a json string and let user deal with it using jsonpath transforms?

3

Thanks for your reply @m0rgoth.

I haven’t used the jsonpath transformation before, I’ll try to explore it.

I can see from your log that it’s possible to know the user, action, and partially, the actuator, although it can only be the locks. We still can’t know if it was initiated by the keypad/fob.

I wouldn’t think a delay would be a big problem as the door would be locked, so I don’t see a big security risk, although how long could the delay be when getting the log from the web API?

4

It should be possible to tell whether user used keypad and if it was code or fingerprint (see Swagger UI, you can try it yourself).

The problem is that long polling interval makes any automation useless (e.g. you want to do something when user comes home, but the rules runs several minutes after the person opened doors), setting it too short might negatively impact smartlock’s battery life.

5

I think, as long as the polling interval is configurable and there is a disclaimer in the documentation, users can find what works best for them.
In my case, I’m thinking about creating some automations when the lock is locked from outside, i.e., when leaving. I could find actions that could be done until I know who/what triggered the action.

About the channels, I think the JSON could be interesting, but I can’t imagine yet under what conditions the intermediate states would be of any use, other than debugging (maybe), so I think, separate channels for each attribute with the final state could do.
Maybe, the worst that could happen is that someone leaves but before the data is polled changes her/his mind and comes back.

6

By the way, what do you mean when you say

?

This is what’s mentioned in the documentation:

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.

Even the configuration mentions this:

Let the Nuki Binding manage the callback on the Nuki Bridge. Nuki bridge uses HTTP callback to notify openHAB about changes in device properties (e.g. when doors are opened, unlocked, doorbell rings, battery level changes etc.). If callback is not registered, binding will not work properly and channels will not be updated. If this is enabled, binding will automatically register and unregister callback as necessary. If this is disabled, user must register callback manually. It is recommended that this is turned on.

I’m confused.

I also realized that when an action takes place it is immediately logged in the Activity History. The binding also updates the status of the things quite quickly (just a few seconds), so I don’t understand why can’t the “activity history” be retrieved as fast as the other items.

7

I’m talking about the Nuki’s Web API. The bridge obiously supports callbacks and works fine, that’s what the current binding is built around. I think I got a bit confused since we’re discussing integration of Web API in other threads, and it’s the Web API that provides the access log, this information cannot be retrieved from Bridge API alone.

If you wanted to use only the Web API for automation (like if you bought the Nuki 3.0 Pro without bridge), then there are those issues with callbacks and polling latency and whatnot. But you’re right that at least theoretically you could use the combination of both (the Bridge API and the Web API) to put it together and find out who opened/locked the doors.

The binding could, after receiving callback from bridge, query the Web API for access log, but I still doubt that would work reliably enough - I don’t know how long does it take for access log to appear on the Web API. So it’s possible that the information won’t be there when the binding queries it.

Even if it was, I’m not sure how to expose it in the binding in a way that’s useful for rules. Let’s say that there are multiple channels that mirror the info we can get from log - someting like “name of last action user”, “trigger”, “source” etc. When the binding would call the Web API and received like 3 new log items, what would it do with them? Go through them one by one and update the corresponding channels? Then when you opened the door (and assuming the Web API returned updated log in time), you would get 3 updates to all channels at once and I’m not sure how would openHAB handle it.
If you made rule that triggers on update of one of the channels, you would probably want to also read values from other channels to piece together info about who and how opened the door. If the channels triggered 3 times in a row (like in the example I posted the “action” would change 3->240->241), you would have no guarantee that the data you read from other items in the rule are actually from the same log event.

8

Thanks a lot for your explanation, @m0rgoth.
I got it now. I was originally referring to the Bridge API, which is called Bridge HTTP API and I didn’t realize that the Web API is a different one. I mistakenly thought they were the same.

By the way, I have a Nuki 3.0 with an external bridge.

I tested it and the log on web.nuki.io was instantly updated when I updated the page. I don’t know if the Web API would provide the same data right away but I would expect it does.

What do you think if the binding gets the log from the Web API with a delay (great if it can be configurable) after the door status is updated by the Bridge HTTP API, and then from the batch find the latest record in the log and update the channels?
According to your example, only the data related to action 241 would be reported.

9

The problem with using only the latest record is that the info about user is usually in the first record, the rest is just logs from door sensor with no user info attached.

I think there would have to be a lot of work done in the binding to pair the user log with bridge events, and I’m not sure what exactly to expose in the binding to cover most people’s use cases.

1 Like
10

You’re right. That sucks!

I wonder if there is some sort of connection among the records because when you check the activity history on the app it shows the last status and the user.

If there is no logical way to link the records and extract the correct data to expose in the channels, then maybe just exposing the JSON and letting everyone proceed from there might be the only option left.

In the meantime, I posted on the Nuki forum asking for such a feature on the Bridge HTTP API.

11

Hi, @m0rgoth.
There is an interesting update on this topic in the Nuki forum.