MQTT API Specification v1.4

Motor blocked is a transition state. It occurs when the motor of the Smart Lock is stuck before reaching the target position. The Smart Lock will transition to either locked or unlocked a few seconds later, depending to where the bolt really is. If you map jammed to motor blocked (254) it will obviously behave exactly the same. If you map jammed to also boot run (253) and undefined (255) its slightly different and won’t have such a strong transitional behavior any more.

If the lock command was initiated by the MQTT API there will also be an error code sent via the commandResponse topic.

Yep, makes sense.

About Home Assistant auto discovery, will it be republished when smartlock is renamed in the Nuki app?
In fact are there some case topics will be published again?
For the smartlock name it will be useful because if the name is not changed from Home Assistant interface, it would allow to also make the change in Home Assistant entities and device.
So the name should also be changed in the device information,.

Also are some people interested in having version information (firmware and why not smartlock version so only 4p for now)?
Because the script and even my fork does not set these information.

Yes. The Smart Lock will also republish them with every connect to the MQTT server.

Some services (e.g. door sensor, keypad battery) will only be published when the respective accessories are installed.

1 Like

My last questions about Home Assistant auto-discovery, are you also interested in publishing hw/sw version?
And what about a Full lock button?
If so I can add it to the script.

It would be nice to have more feedback from HA users because for example, some entities can be also disabled by default but published to be enabled by user in HA UI.

@Juergen if all addition should be stopped now it is OK on my side, ideas I suggest in this post are only some thoughts I have with all possibilities Home Assistant MQTT auto-discovery offers and I am aware I asked at the end of the original timeline. Essential is here IMHO and for example the full lock buton could also be added using YAML, about version info it is not a must of course :slight_smile:

For me it depends,

If there is an option as well through MQTT like a message to start updating to latest version, than yes.
Like to Home Assistant Update Card that i can see which version is running on the SLP3 and which is the latest one, and if there is a newer one, send a command with MQTT to go and update itself.

But if only showing your version, without knowing if there is an update or we cant do anything with it, it is not that useful for me.

Another point (more technical) came to my attention. Should we prefix IDs with nuki to avoid duplicate if another MQTT device is published and which would have the same ID?
Probability looks very low but I would like to have some advice to avoid future issue.

EDIT: I done it for each topic so I am going to publish the last version and won’t touch anything else to also prefix unique IDs with nuki_.
I hop memory constraints will be OK with payloads a little long like these.
For people using the forked script, I also added a remove_lock to the python_script service if you want to make the update because it will fail without a remove before.

Hi there,

Is there a roadmap when this mqtt function (setup in nuki app and home assistant autodiscover) will be available in the beta?
Iam thinking about implementing it now, but when you will release it in a few days i need to start from scratch again.

EDIT:
Nevermind i gave it a try. So my Mqtt server sees the nuki lock and also the states are updated accordingly but i cannot send something to it. Can you maybe explain the structure?

mosquitto_pub -u MqttU -P "PW" -m "2" -t nuki/NUKIID/lockAction

Kind regards
Dox

With this weeks release of Firmware 3.5.11 the MQTT API is now also available in the release firmware. The initial post in this topic has been updated with the final 1.4 MQTT API specification.

Provisioning through the Nuki Apps will be made available through subsequent App releases. Please follow the Apps Beta channels for further information.

If you do not want to use beta firmware for your Smart Lock anylonger, please opt-out of the beta by sending an E-Mail stating this to contact@nuki.io with your Smart Locks Nuki ID this week, as the 3.6.x beta is about to start next week.

1 Like

As the mqtt API is now available in the release version, the mqtt topic in the forum has also been made publicly available.

Thank you all for your contribution to the MQTT API specification and the feedback you provided during the beta phase! :clap:

2 Likes

I am a beta tester for the Android App as well, but as I understand, a new release will be done for the MQTT config? Do you have any idea when this will appear in the Play Store?

Also, what are the consequences for staying a beta tester for the firmware? Will that just be prerelease firmware updates?

1 Like

We do not comment about our roadmap here in the forum. The Android beta channel will mention it in the release notes once it’s available.

If you participate in Smart Lock Betas you‘ll get access to the latest releases earlier, but they are not as well tested as release versions are. Smart Locks with beta firmware can also send debug logs to Nuki, which allows to refine and improve the firmware.

Hey.

I already have a door sensor on my door to control automation within HA, would it be possible to add support for exposing door status via MQTT to Smart Lock, something like doorOpen (true/false). It doesn’t make sense to me to have multiple sensors on the door :frowning:

1 Like

Why not simply using HA to do it?
It is its role to make automation based on different platforms like your scenario isn’t it?

I’d also welcome this. While it is certainly possible to orchestrate the behavior externally through HA, it would be neat if the lock could be directly supplied with the door sensor information. Whether this is something Nuki wants to facilitate from a business perspective is probably a different story, though.

My point is that the Nuki should have the same behavior/function conditions as when an official sensor is connected to it. The only difference is that I won’t need to have multiple sensors on the door.

2 Likes

Hallo Jürgen,

I have just bout Nuki 3 Pro with door sensor and the keypad - and what I am missing:
in App:

  • I can’t find the MQTT setup section (Nuki FW: 3.5.11, Android App: 2023.2.1)

in MQTT spec:

  • heartbeat - some status message send out approx. every 15 minutes to verify the connection
  • no clear user assignment who has initiated door unlock via keypad
  • maybe some much more easier to decode output of lockActionEvent:
      {"topic":"nuki/nuki-ID/lockActionEvent",
         "payload":{
              "LockAction":"3",
              "Trigger":"0",
              "Auth-ID":"<is this ID of the keypad?>",
              "Code-ID":"<access code name as set in app>",
              "Auto-Unlock ":"1"}}

/MfG
ZoloN

Is mentioned 3 posts above: MQTT API Specification v1.4 - #29 by Juergen

This is what the /connected topic does.

You get IDs for the Keypad User (Auth-ID) and the used Keypad Code (Code-ID). It’s not clear to me what you mean with “unclear user assignment”. If you mean that there are no user names or similar stuff present, maybe the answer to your next question gives you the proper answer.

The Smart Lock is battery driven. The more data it transmits the more energy it needs. Therefore the MQTT API has - like all other Nuki APIs - been built with the aim to produce as little data as necessary. Therefore comma seperated strings are sent rather than JSON objects which contain the same amount of information, but need much more characters.

hallo Jürgen,

all your answers seems be quite reasonable.

just - I still can’t find the MQTT setup page for my Nuki 3 Pro in the Android App, even I have successfully opted for beta an upgraded to 2023.3.1 version - assuming, this is the current beta release.

and still having problems to connect to my MQTT broker - mDNS seems be unstable in my environment (as I don’t use it elsewhere) and the DNS lookup is apparently failing, even all three forms of DNS entries are registered and resolvable: “mqtt.mydomain.local.”, “mqtt.local.” and “mqtt.”

/MfG
ZoloN

The Apps Beta channels do not contain any informations about MQTT provisioning yet, because it is not available yet. For the time beeing you can only use the debug mode provisioning method, which has also been available during the beta phase.