MQTT API Specification v1.4

Attached is the the newest API specification v1.4 with the following changes:

  • Added HomeKit and MQTT to triggers. Lock actions originated via HomeKit and MQTT now also trigger a lockActionEvent
  • Added provisioning & security remarks
  • Added “Allow locking” flag
  • Added Home Assistant Discovery

The Home Assistant Discovery follows the implementation/script in this repo GitHub - Nardol/Nuki-MQTT-auto.-Discovery: Python Script creating HA auto-discovery topics for you Nuki Lock 3 Pro with MQTT enabled (Beta Firmware) by @Nardol.

If you have any comments or remarks, please make them here in this topic. We plan to freeze the spec next week. It will most likely be the basis for the initial public release (and everyone familiar with such processes knows, that once something is publicly released it is very hard to make any material changes because of all sorts of compatibility problems).

It is part of the 3.5.11 release firmware. Therefore no beta firmware is needed to activate the MQTT API anymore. Currently only the fixed credential mode can be used. Provisioning through the Nuki Apps will be made available through subsequent App releases. Please follow the Apps Beta channels for further information.

20220223 MQTT API 1.4.pdf (164.4 KB)

7 Likes

Change log date is wrong year-
1.4 - (DRAFT) 10.1.2022

I have not read the doc yet but something comes to my attention.
I’m making a pull request on Home Assistant Core to allow the support of locking, unlocking and jammed states.
The mentionned script implement opening, which is not implemented at all in Home Assistant lock entities in fact.

Should I make a pull request to this script for these three states to be implemented?
Because even if I hop so, I cannot be sure it will be available for Home Assistant 2022.2

The mentioned pull request:

1 Like

Another question I already had before but did not ask.
What is the difference between lock and full lock?

Hello Juergen,

first of all, thanks for the hard work you are doing.
I’m running Firmware 3.5.6 on the Smart Lock Pro 3.0.
I joined the Beta IOS app and enabled Debug Mode by pressing 7 times on Features & Configuration title.

I was able to get the state and lock it via MQTT (by renaming the DNS entry for my MQTT Server)
I have to say it is pretty solid. I’m even getting the Unlatching-> Unlatched statuswhich before I was not getting.
The door I have this particular Smartlock mounted to has also an electric opening mechanism, and as of right now I’m not dependant on time based conditions like before. I use the status updates from MQTT in few miliseconds and it’s awesome.
THANK YOU.
This is pretty solid stuff now. All the criticism I’ve seen on the forum seem to be coming to an end, as you can’t get more solid than this!

Yet I am still unable to find the MQTT section in the IOS in order to set it up without making changes in DNS

Is there something I am not doing right?

br,
Thomas

1 Like

No, you do it right. During the beta there is no way to configure via app if I understand correctly what I read on this forum.
And the doc states the smartlock will connect to the hardcoded MQTT server if running the beta firmware.

2 Likes

App Integration will come later this year.

BTW just as an extra info for everyone who are interested in the MQTT Beta:

1 Like

I think if the lock is turned one (360) or two times (720)

2 Likes

Hello,

thx for your answer.

I’ve read the document and it states the following which brought me to conclusion that I’m doing something wrong:

2.2 Provisioning
Provisioning of an MQTT server is done via the Nuki App in the Device Administration >
MQTT section.
It allows users to enable/disable the API, enter the credentials (username & password) and a
hostname or IPv4 address for the MQTT server.
In addition Home Assistant Discovery (Default: on) and “Allow Locking” (Default: on) can be
activated and deactivated.

Edit:
Nevermind, I just read this post again by Juergen again and it’s a “draft”, not yet implemented feature in the beta version.
Sorry for this confusion.

Correct. Full lock will always lock 2x (720), even if 1x (360) is selected in settings.

Ideally the platform (HA) can deal with those transition states. But in any case they should be optional and things should work without as well, because not all locks will have them and even the Nuki integrations via bridge API won’t have them. Not sure how HA deals with such compatibility requirements.

Yes, it will work without transitioning state. HA will report locked and unlocked, that’s all and durring transitional states the previous state will stay set as actual.

Because these transitional states are available with MQTT API, I think it could be good to have these information in Home Assistant even if Bridge integration does not provide these.

Finally this PR is only for locked and unlocked but I am also working on jammed state which is also not available with bridge integration but this state would be really useful if it could be implemented using MQTT.
If it is not, no issue with HA, same as I told about locking and unlocking, if motor is blocked when previous state for HA was locked the state will still be locked.

Maybe my suggestion arrives late but I did not know this script would be the base used by Nuki for HA auto-discovery, else I would have made it sooner and more for other point I disagree with this configuration, for example using lock name for unique ID which does not look reasonable in my opinion, IDs should not be set using an information which can change.

The choice for the script was because there seemed to be the consensus “that there is only one way to represent a Smart Lock in HA” in the Home Assistant MQTT auto-discovery implementation requirements topic. This maybe got lost because the topic went a bit off-topic …

Anyway it’s late, but not too late yet. Please contribute directly to the script on git (or at least write down all changes in the HA discovery topic) and we’ll add it to the requirements. Thank you.

1 Like

Hi there, is there a recommendation for a broker? Mosquitto seems to only accept SHA512, unless I am mistaken.

Thanks for your reply. I’ve made two PR on @MattDog_06 script, one for the IDs and other for typo which does not concern directly MQTT auto-discovery.

Now locking and unlocking have been merged, I’m going to make a PR also for that and will do so as soon as jammed will be supported.

What do you mean exactly?
A document with all MQTT topics and payloads for HA auto discovery?

Hi,

Mosquitto works well.
The sha256 is the encoding to use to generate the MQTT user’s password, create a user with login nuki and the password is your wi-fi key encoded using SHA256 so will be the same for any MQTT broker.

Or your question was about something else?

Hi Patrick, I appreciate the response.

Mosquitto uses SHA512 by default and I haven’t found an option to use SHA256. So do you simply add a SHA512 hash of the SHA256 of your WiFi password? Or a SHA512 hash of the WiFi pw?

I might overcomplicate things, so I’d appreciate any guidance you may have.

Yes. Just read the API spec in the top post. There is an example how to derive a string with the sha256 hash of your wifi password. Then you simply set this string as password for the nuki user on the mqtt broker.

1 Like

To make your changes either on git or write them down here in the forum.
You made them already on git, so everything is fine. Thank you.

@mattdog_06 do you think you could find some time to review my pull requests?

@Juergen another question comes to my mind even if I have an idea of the answer.
When the smartlock is jammed, we have the payload state 254 published.
But I don’t find any specific state when it is no longer jammed. So should we consider all is OK on next locking/locked/unlocking/unlocked state?
Because for jammed state, Home Assistant will expect two payloads: one for jammed and one when motor is OK. If my suposition is right it could be implemented this way but I prefer asking to be sure all is right.

EDIT: in fact if it could be possible to have a state when the lock is no longer jammed it would be helpful because the implementation will be as follow: there will be one topic for lock state:

  • locking
  • locked
  • Unlocking
  • unlocked
  • jammed
  • ok

But lock states will be treated independently from jammed state so even if the state change for example to unlocking, if no OK state as been received the lock will stay jammed.
EDIT2: pull request on Home Assistant has been adjusted by author: if no unjammed payload state is defined, any state other than jammed will change jammed state to unjammed. I hop it is OK.