NUKI Hub firmware for the ESP32


Posting here to let the home assistant community know about a little project of mine, the NUKI Hub firmware. It can control NUKI locks via an ESP32. Just flash it (webflash available), pair it with your NUKI and configure WiFi/MQTT and you’re ready to go. Reports the current lock state (and much more) via MQTT, and allows to execute commands like locking and unlocking.

You’ll find everything on the github page:



Wow great. i made a test installation works fine. can you add more information? I have the problem with the normal bridge that i don’t know witch person open the door or close the door. This information is just avalable over the webapi. But this is slow. Just a id would be great for personal automation.




I think this should be possible, if slightly more complicated.

This information isn’t provided in the lock state (which changes after a lock action), but is in the logs. So after a lock state change, the firmware has query the lock for an updated log entry. This could impact battery life, so it should be configurable wether to do this or not. That’s probably the reason why it’s slow over web api, the log isn’t updated less often than the lock state.

I’ll look into it.

The new release 2.1 supports publishing authorization data. You have to enable it in the web interface first, because this could impact battery life. I wouldn’t expect a big impact, unless the query interval is set really low.


Thanks for the update. wow
It this normal that i just receive a 0 in nuki/lock/authorizationId.
and the nuki/lock/authorizationName: don’t exist.
In the serial log i found this error message:

lld_pdu_get_tx_flush_nb HCI packet count mismatch (1, 2)




that message appears from time to time, it doesn’t really matter. 0 and empty name are defaults, so no log entry was retrieved. Did you enable “Publish auth data” in the web interface. It’s disabled by default. If yes, what does the NUKI app show as last log entry?


I reflash the esp32 now i receive sometimes a id and also a name. But the name goes away. I add the data to home assistant. Mybe i can see a pattern. The information in the app is available.

Can you add a topic if is the system offline or online? Would be helpful for the mqtt integration in HA.
and a small point would be nice if i can add the mqtt Server by DNS Name and not by IP.

I saw you made diffrent posts in diffrent Smarthome Systems about this Project. I hope a lot of people will use that :-). Did you prefer the fiture requests here or github?

Mybe is everting runs good then i can share the MQTT Configuration for Home Assistant, but in the moment i sill lern.



Hi, you see a name if an authorization was actually required, for example if you used the smartphone app or a fob to open or close the door. If you use the button on the lock, or the lock does a smart action (for example auto-lock), the id and name will be empty because no authorization was required.

I’ve just tried entering my mqtt broker by name and not ip, it worked just fine. Maybe recheck the name you used?

What do mean by “the system is offline or online”?

Yes, I’m spreading the word over a few forums :). Myself I use iobroker for a long time, but since the firmware uses mqtt, it should be quite universal.

A new Release is out. Version 3.0 supports the NUKI Opener in addition to the Lock.

And the latest Release 4.0 finally supports the much requested OTA.

An important update for all Home Assistant users: NUKI Hub 4.4 now supports Home Assistant MQTT Auto Discovery.

1 Like

Hi @technyon I’d like to thank you for your project, I’ve only been experimenting for a short while, but it seems to work very well. One thing I struggled with a bit was the limitations on password lengths (both for the auth credentials and the MQTT server).

The 30 character limit was only documented in the code and apparently there’s some kind of validation issue with certain characters. I had trouble getting the credentials working until I limited my passwords to well under 30 chars and to alnum-only. (Problem with the HTTP credentials is that you have to erase the ESP32 if it disagrees with what your password manager thinks the password is.

It seems you like long passwords :smiley: Yes it might be a good idea to put the limit into the interface. How long are your passwords usually?

I have already thought about changing the password input to the usual type and retype to make sure you don’t get it wrong. But yes if you forget or mistype the password, you can only erase and reflash the ESP.

1 Like

Well, my PW manager likes them. I prefer the “random pronouncable words” style, so they tend to be more towards fifty characters. But also there seems to be some issue with shorter passwords when they use non-alnum characters? I haven’t seen anything obvious in the code, but since the PW generated (and saved) a PW short than 30 characters and the ESP32 didn’t recognize it after setting it, something must be going on.

I don’t think retyping the PW would help with that, maybe some debugging option? Not fit for production use of course, but at least we could have a closer look.

Do you have any example for a password with alphanumeric characters that doesn’t work?

Here you go, very special debug version that prints the password to the serial console:

Have not tried the debug version yet, but I’ve noticed that it might not have been the passwords after all: After some time (or some actions, like trying to do a OTA update), the ESP32 refuses to accept the auth credentials. It is still pingable and relays the MQTT commands, but the web interface can only be accessed again (because while it’s still asking for the credentials, it does not accept them) after a hard reboot.

You’re the first to report this. Is the web server still responding (port 80 open ?), or is it just not accepting the credentials?

Maybe just go with simpler passwords? I mean 30 characters are very strong if you use random characters, upper and lower case and numbers, even without special characters.

This is with simplified (shorter) credentials with only alphanumeric characters, though I’ve not tried it with trivial ones (yet). I guess the web server is still responding because the browser pops up the credentials? Anyway, OTA did not work for me at all (despite several tries in several locations with very good wifi reception), I finally updated using the web installer/USB.

Yes if the popup appears the web server is answering. Sounds all very strange, there’s no real explanation I can think of. Once the credentials are saved they are saved and should always work, no matter how complex the password is. Must be something in the communication. You could try the developer console in the browser to see what’s going over the line.

Weirdly, I had the problem again (without trying to update the firmware) today - credentials error in the web UI. Using HA, I could not unlock the door. However, I then used the Nuki app to do it it instead and the state of the lock was correctly registered in HA.

Then I tried the web UI again - this time it worked fine. The ESP did not reboot during that time (no new connection in the MQTT broker log). I’ve got two theories now:

  1. It could be network trouble - ESP32 wifi, at least with the PCB antenna, is always somewhat flaky (pings in the tens or hundreds of milliseconds, instead of single digits like “proper” devices).
  2. Or sometimes the ESP32 gets busy with something and has trouble servicing the network (either on the link level or the HTTP server) at the same time.

Since trying to do an OTA update seems to reliably trigger the issue, I’m inclined to believe it’s #2. Maybe I’m using the wrong kind of ESP32? I bought some ESP32 D1 Mini clones (so its a WROOM). Unfortunately, I can’t get a reliable bluetooth connection to the lock from where I could easily lay ethernet cables.