Attached is the first version of the MQTT API specification.
It is currently limited to Smart Lock 3.0 Pro and uses - for an initial Beta phase - a specific provisioning method which does not require any integration into the Nuki Apps or other parts of the Nuki ecosystem.
Please read it carefully and give us feedback in this thread.
20220719 MQTT API.pdf (112.0 KB)
Thanks for the update JĂźrgen! I have put everything in place and sent a request to become a beta tester.
Just to be sure, I have to SHA256 hash the password of the SSID the lock is connected to and use that as the password for the user named ânukiâ in my MQTT broker, right?
Yes, thatâs the idea.
Just to go for sure: The MQTT firmware does not exist yet. It will be implemented once we collected feedback to the spec. If everything goes well it will be a subsequent beta update later this quarter.
I like the way of implementing MQTT via your API specification and as well the setup of the MQTT server via App.
The only thing that concerns me a bit is the unsecure authentication with the MQTT server. As a starting point thatâs absolut fine. However in these days perimeter security (trust of my network) is not the source of truth. Everybody talks about Zero Trust and with that a long term road to a secured communication also via MQTT should be on your bucket list.
Iâm using IP-Symcon (symcon.de) as my Smarthome broker with a built in MQTT server (comparable to HomeAssist) and connect via MQTT, Gateways (HMIP, âŚ), IP/LAN all different kind of devices (>300). With your Smart Lock 3.0 Pro MQTT API I would just specify a new âMQTT deviceâ and subscribe the topic ânuki/nuki id_in_hex/*â and get all the topics as status variable. The same way I would be able to create a new device to perform the lockAction ânuki/nuki id_in_hex/lockActionâ. Now I have the freedom to integration the Smart Lock MQTT devices in my events or action.
So looks very promising! Looking forward for the first beta to give it a try.
Thanks,
Seb.
So we (old SL customers) wonât be able to contribute to test thisâŚsorry to hear that.
My comments:
Seems that you want to publish many simple separate topics. It may be useful when I want to listen to only some of them. But today, also a more complex JSON structures are used for MQTT publishing. For example in Tasmota, there are complex JSON structures published along with the simple topics. For example there is a simple topic POWER with on/off values and RESULT topic with json structure like â{âPOWERâ:âONâ}â.
All the almost static âstateâ values could be published in one json structure (deviceType, name, firmware, mode).
I also do not find reason for âreset after 30 secondsâ for ringactionState topic. This topic simply should not be retained as it is only one moment action. If I want to see whether any ring occurred I can get it from ringactionTimestamp.
I also do not understand where the MQTT feature will be implemented as you have stated âOnly Smart Lock 3.0 Proâ for serverConnected. When older Smart Lock is connected through Bridge, it is also connected to server, so why this topic is not supported?
Maybe the unlock topic could accept two values âopenâ and âunlatchâ or âtrueâ and âunlatchâ.
Agreed. Weâll have a look at TLS / MQTTS once the basic setup works.
Yes. From implementation point of view it does not make much difference, but we wonât implement both. So it is either JSON or separate topics. And which version to choose depends pretty much on your feedback here in the group (i.e. which ones are easier to integrate into the platform with which everyone over here works).
Weâll remove it completely. The ringactionTimestamp should be sufficient.
First beta will be Smart Lock 3.0 Pro only. It might make it later on into the bridge, so it would be wise if the specification takes that into consideration and also theoratically would work with the bridge.
Only the SL3P has an IP stack and holds a direct connection to a server. All other Nuki devices are indirectly connected via the bridge. So a server connected state for any other device would just mirror the connection state of the bridge. But yes, it might make sense to add this too for the other products.
If you want to execute a specific lock Action you need to use the lockAction topic. unlock / lock are specifically designed to be used with the simple lock action which will automatically decide if unlock or unlatch is called based on the door handle setting.
As written above, you can contribute to the API specification. Unfortunately the SL3P and Bridge use completely different technologies, therefore none of the code can be reused and we need to start somewhere.
I thought the MQTT would be implemented on the bridge, nice to see that it can be implemented on the SL3P tooâŚbut if you started from the bridge, I think more people couldâve tested the beta firmware.
Iâll read the specs meanwhileâŚ
If itâs one or the other, as discussed some time ago in the first MQTT discussion, separate topics can be integrated more easily in automation platforms with no code (no json parsing). But @mclei is correct, like in tasmota, a simple or complex topic depends on what youâre trying to achieve/represent, so itâs not a matter of deciding one vs the other, it depends on the specifics. Hope you can think about this too.
Thanks for the feedbacks Juergen, highly appreciated.
Iâve readed and like the simple approach that mainly follows the Bridge API.
For the beta test using mqtt.local as host name, might be an issue in some installations. Not two weeks ago, for a weather project, I tried to assign an additional (second) host name (technically spoken a DNS A or CNAME record) on my brothers FRITZ!box and completely failed with that. Just to mention, but no better idea for now.
Summarised, I feel lucky with that spec.
Regards, Christian
The spec is practically the bridge API doc, looks complete from a first read.
A question: in this post you explained to me that transition states could not be captured because the bridge was notified only after the action had actually happened. Will we still have this limitation with MQTT?
Correct, the audience would be bigger. But SL3P does not have a local API at all which makes it the primary target for MQTT. Furthermore it has already an IP Stack and can directly communicate with the outside world.
For the bridge yes, but SL3P will not have this limitation. It can push (state) updates through MQTT as soon as they happen.
Yes, thatâs unfortunately a restriction of Fritz!OS. Workarounds for the beta are to route DNS requests through a dedicated local DNS server/forwarder (e.g. Pi-Hole) and or to use an old wifi router/repeater which supports that and open up a separate WLAN for the SL3P only.
Thanks for the feedback on the API spec.
Iâm not sure if we still need to have a discussion about JSON vs. separate topics: Does anyone over here have a strong argument/opinion in favor or against one of the options?
This could be a good reason to upgrade from an old SL to SL3P for people that want to integrate it through MQTT: with SL3P you wouldnât need the bridge and you would also have a better integration with intermediate states, etc. because itâs the source device sending and not a gw like the bridge.
Are you oriented to separate topics or JSON? Or a mix? 
The current spec uses separate topics, so this would be the way to go.
If itâs separate vs JSON, so a binary decision, I agree with the current approach: separate topics.
But it is not an option when I have Opener that does not have network connection without a Bridge.
Didnât mean to cover all cases. Maybe an Opener 2 is in the works, who knows. But for people with no Opener, the SL3P with MQTT is really a good upgrade choice vs the SL with the bridge: one device, easy integration, itâs what the SL shouldâve been since the beginning, when zigbee was expected.
Attached is version 1.1 of the specification with the suggestions that came last week:
No change in using separate topics vs. JSON.
Iâll wait until the end of the week. If there is no more feedback, weâll use this version as basis for the initial implementation.
20220726 MQTT API v1.1.pdf (112.5 KB)
Initial implementation only for the SL3P, based on what you said previously. There will be a beta also for the bridge after the SL3P phase ends or it will go official directly?
Technically SL3P is independent of the bridge.
There are no release schedules fixed yet.