NUKI Hub: ESP32 firmware to control NUKI devices


Posting here to let the openhab community know about a project of mine, the NUKI Hub firmware. It can control NUKI locks (and openers) 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 it on the github page:


Thank you very much for sharing your hub implementation!

I just tried to get it to run and it seems to be working fine as I see the lock state in the web interface and I see log messages in the serial monitor when locking or unlocking the lock. However I do not receive any mqtt messages for my lock (and I dont see any being sent in the serial monitor). I do receive the homeassistant config messages so it is not a general mqtt connection issue. Do you have any hints on debugging this?


With serial monitor you’re referring to the debug output of the ESP via USB serial connection? MQTT communication isn’t logged except for connects and disconnects.

Do the nodes for the lock exist (e. g. lock/state, lock/action)? If so just to confirm, lock/state isn’t changing when the lock state changes? The “MQTT NUKI Smartlock Path” is set in the web interface (not empty, no spaces or other fancy characters)?

Also, which MQTT broker are you using?


first of all thank you for your support!

Yes I’m referring to the serial debug output. I was using the serial monitor of arduino IDE, sorry for the confusion.

This is what I receive initially when enabling the homeassistant discovery:

{"dev":{"ids":["nuki_3049ee64"],"mf":"Nuki","mdl":"SmartLock","name":"Haustür"},"~":"nuki","name":"Haustür battery low","unique_id":"3049ee64_battery_low","dev_cla":"battery","ent_cat":"diagnostic","pl_off":"0","pl_on":"1","stat_t":"~/battery/critical"}
{"dev":{"ids":["nuki_3049ee64"],"mf":"Nuki","mdl":"SmartLock","name":"Haustür"},"~":"nuki","name":"Haustür battery voltage","unique_id":"3049ee64_battery_voltage","dev_cla":"voltage","ent_cat":"diagnostic","stat_t":"~/battery/voltage","state_cla":"measurement","unit_of_meas":"V"}
{"dev":{"ids":["nuki_3049ee64"],"mf":"Nuki","mdl":"SmartLock","name":"Haustür"},"~":"nuki","name":"Haustür trigger","unique_id":"3049ee64_trigger","ent_cat":"diagnostic","stat_t":"~/lock/trigger","enabled_by_default":true}
{"dev":{"ids":["nuki_3049ee64"],"mf":"Nuki","mdl":"SmartLock","name":"Haustür"},"~":"nuki","name":"Haustür battery level","unique_id":"3049ee64_battery_level","dev_cla":"battery","ent_cat":"diagnostic","stat_t":"~/battery/level","state_cla":"measurement","unit_of_meas":"%"}
{"dev":{"ids":["nuki_3049ee64"],"mf":"Nuki","mdl":"SmartLock","name":"Haustür"},"~":"nuki","name":"Haustür door sensor","unique_id":"3049ee64_door_sensor","dev_cla":"door","stat_t":"~/lock/doorSensorState","pl_off":"doorClosed","pl_on":"doorOpened","pl_not_avail":"unavailable"}
{"dev":{"ids":["nuki_3049ee64"],"mf":"Nuki","mdl":"SmartLock","name":"Haustür"},"~":"nuki","name":"Haustür WiFi signal strength","unique_id":"3049ee64_wifi_signal_strength","dev_cla":"signal_strength","ent_cat":"diagnostic","stat_t":"~/maintenance/wifiRssi","state_cla":"measurement","unit_of_meas":"db"}
{"dev":{"ids":["nuki_3049ee64"],"mf":"Nuki","mdl":"SmartLock","name":"Haustür"},"~":"nuki","name":"Haustür bluetooth signal strength","unique_id":"3049ee64_bluetooth_signal_strength","dev_cla":"signal_strength","ent_cat":"diagnostic","stat_t":"~/lock/rssi","state_cla":"measurement","unit_of_meas":"db"}

I think I also saw the lock/state when I tried this on sunday but I might be wrong. It is definitely not here now (or is it binary_state?). Apart from this I don’t receive any further messages when the state of the lock or the state of the door sensor changes (the web ui shows the correct lock state however).

The MQTT NUKI Smartlock Path is set to “nuki”, and the MQTT user is granted read and write access to the “nuki/#” topic.

I’m using moquitto 2.0.15.

EDIT: Got it working now… Of course it was a mistake on my end… I granted the correct mqtt access rights for the lock but forgot to grant the rights to my openhab user :see_no_evil:

Thanks again for your help, so far everything seems to work as expected!

Great you got it working. “binaryState” is only for home assistant if used together with the home assistant auto discovery.

I have another question/feature request: would it be possible to also provide the battery level or battery state as shown in the nuki app for the door sensor?

Wow, that’s great for the ones having no Nuki Bridge
But doesn’t this mean, the ESP32 directly asks the Smart Lock for any status request? Which would seriously reduce battery lifetime I guess?
or do you plan to build some Caching into the ESP32 itself - as the Bridge does?

Could be… however since I use a 3.0 pro it could even save me battery if I would switch wifi off. So far however wifi is still on and I haven’t noticed a significant drop of the battery level. But I’ve been using it only for a couple of days now…

The state is cached on the ESP32. The lock actively notifies about changes using iBeacons, so this is no problem, there shouldn’t be any significant reduction of battery life.

1 Like