MQTT API Specification v1.3

Nuki APIs MQTT API
#1

We’re working on a new version of the API specification. It adds one quite cool feature, that has been requested often: a lockActionEvent topic

The Nuki device publishes to this topic a comma separated list whenever a lock action is about to be executed, consisting of:

  • LockAction
  • Trigger
  • Auth-ID
  • Code-ID (Keypad) or 0 (if unknown)
  • Auto-Unlock (0 or 1) or number of button presses (only button & fob actions) or keypad source (code, back key or fingerprint)

Only lock actions that are attempted to be executed are reported. E.g. unsuccessful keypad code entries or lock commands outside of a time window are not published.

Examples of what triggers that you can place on publishes from this topic:

  • React when a specific user did lock/unlock
  • React when a specific user comes home (i.e. auto-unlock was triggered)
  • React when the house is left (i.e. Lock’n’go with the button was executed)
  • Trigger something when the button on the Smart Lock was pressed (with or without lock action)
  • Trigger something when a fob was pressed twice (with or without lock action)
  • Trigger something when a specific keypad code was used

Here is the document as PDF:

20221027 MQTT API.pdf (102.7 KB)

Please have a look and let us know if you have any comments.

3 Likes
Who/What locked/unlocked the smart lock
#2

This would be truly awesome. The MQTT feature would both replace my Nuki Bridge and some Web API logic I now have in place to get the data above. Makes it really worth the upgrade to SL3 Pro.

1 Like
#3

No connection to the mqtt server. After a quick check, i realized the ip range in the documentation.

…resolve to a local IP or a local IP is given as hostname (10.0.0.0 - 10.255.255.255, 172.16.0.0 - 172.31.255.255, 192.168.0.0 - 192.168.255.255).

Are you really checking the local ip-ranges in the code? Would this be also in the final released version or?

No username and passwords sent to MQTT broker
#4

The initial posting has been updated with the final version 1.3 of the MQTT-API specification.

The full 1.3 scope including the new lockActionEvent is available with todays 3.5.2 beta.

1 Like
#5

Yes & Yes.

#6

This feature should not be just for Pro locks, it should be part of the bridge. I purchased the 3.0, not the 3.0 Pro, because I don’t want the Wi-Fi to be integrated. I believe it would deplete the battery at a faster rate due to the added processing overhead.
I like sustainability, but I’m not yet convinced to have rechargeable batteries for this kind of product.
Besides, the bridge is still required to connect to smart home systems.
The “non-Pro” products are not for free either, so they should also get these kinds of features.

2 Likes
#7

the bridge devices can use bridge api which is also local.

#8

With the Bridge API we cannot trigger something when a specific keypad code was used. We cannot know either if the back key on the keypad was pressed, for the example.

#9

Great addition to the product! Thank you!
Finally I can add automations to disable the alarm on successful keypad entry.

One question though: Is there any way to resolve the AuthID to keypad-users other than trial and error?

#10

Only trial and error for the time beeing.

#11

Hi,
in my opinion, it would be very useful to be able to decide to publish on Mqtt only the locking features and not the unlocking features, for obvious safety reasons.
What do you think?
Thanks

#12

Hi,
this feature is really great! I integrated it with ease into my Homeassistant instance.

I have a few suggestions:

It would be handy to also publish the codes which are not correct. Why? I wanted to use the keypad to lock / unlock the door (obviously) but also to control the blinds and other locks.
I wanted to setup a code which is not managed by nuki because I don’t want to use it to unlock the doors. I want to use it to trigger a rule in HomeAssistant to close all locks and blinds.

Best solution would be to have different triggers with the back button. One press currently triggers the lock action of the connected nuki smart lock. Plausible use cases would be press and hold the back button for 3 seconds to do xyz or press the back button 3 times short to do xyz.

The MQTT integration is absolutely great! Thanks for the good work! If we now could get more detailed events so many new options are possible.

1 Like
#13

Hi, @LexanRed.

I had previously suggested something with a similar purpose:
https://developer.nuki.io/t/option-to-allow-disallow-users-to-unlock-the-smart-lock/
https://developer.nuki.io/t/who-what-locked-unlocked-the-smart-lock/

Does it sound like what you want to achieve?
Of course, it implies that every code either only locks, only unlocks, or performs both actions.

#14

Hi Nelson,

yes, that’s the right direction. That would a great addition as well.
Things like double / triple tap on the back button or holding the back button for 2 seconds would be great as well.

I think both additions come in handy. The MQTT integration was the major reason for me go with Nuki. I installed three Smart Lock Pro 3.0 and three Keypad 2.0 in our house. Most likely more to come.

Having codes which do not lock / unlock but just send a MQTT command would be ok. Having the option to assign different actions to the back button would be better.

If that does not work out, I can imagine adding a battery powered switch next to the keypad. Depending on the open / closed state of the lock the switch does open the blinds or close them. But I would very much prefer to use the keypad for that.

1 Like
#15

If you want your ideas to be implemented please create a proper feature request and start collecting votes for it. Try to be specific and not combine different features into one ticket.

The Nuki Fob (and the button on the Nuki itself) already allow to assign “no action” to button presses, which will be reported via MQTT. i.e. you could use those too.