Using Nuki Lock 3.0 Fully Local without Bridge

Hi all,

I’m creating this post to show how I installed a Nuki Lock 3.0 without a Nuki Bridge and fully local

Update 2022-12

I discovered a new addon that works really well, has pre-built images so it doesn’t have to build it on the HA machine. I added the installation instructions to the Software section.

If you installed the bridge with the script I provided, make sure to delete the service unit:

sudo systemctl stop nukibridge
sudo rm /etc/systemd/system/nukibridge.service 


I spent a few months looking for a good smart lock. I had a few requirements:

  • Relatively cheap
  • Not changing my current lock mechanism since I have a pretty secure and expensive door.
  • No drilling my door
  • Full local control, no proprietary cloud or app mandatory
  • Ability to open the door, not just unlock it

After some time researching I concluded that Nuki was my match and went for it. Can’t complain at all.


That’s it :wink:

:warning: This kind of smart locks demand that you can insert the key in both ends of the door lock and turn the key :warning:

:money_with_wings: When buying the lock, make sure you find a coupon code which will reduce the price by 30€.
The end price should be then 139€ for the entire setup :money_with_wings:


The lock can be controlled via Bluetooth from the phone with the Nuki app, without connecting it to the cloud at all.

But I wanted to be able to open it not only when I’m close to it, and also have entities in HA for information about the lock state. For that I installed a fantastic project that will make the Raspberry (where my HA instance is) act as a Nuki Bridge for free.

Nuki Lock Instalation

  1. Pick one of the two systems to install the Lock on the door. Either the tape one or the screwed one. I wen with the tape one but for a less permanent solucion I would go with the screwed. Mention that it is not screw into the door, but that tight around the existing lock.
    This is the screwed version:

As you can see this 3 screws will tight around the metal lock. Nuki provides the allen key to tighten them.
2. Install it onto the door. This is the result:

  1. Insert the key into the lock, remove the plastic that protects the batteries and plug in the Lock.

Configuring the lock

Before going with pair process, you need to configure the Lock to fit your door through the Nuki App. This step is to tell the Lock how many times it needs to rotate to fully lock/unlock the door. It is fully local through Bluetooth and does not need to connect to the cloud or even the internet.

Bridge Installation

If you don’t want to use a bridge and control the lock only from your smartphone over Bluetooth, ignore this step. Although it won’t be able to integrate with HomeAssistant.

Alternatively to RaspiNukiBridge, there are is an addon (there are a few really but this one is the only one I got working) that you can install and simplify the process a lot, I strongly recommend using it:

  1. IMPORTANT Make sure you configured the Lock with Nuki app.
    If you skip this process the pairing with the bridge won’t work

Using Addon (Recommended)

  1. Visit this link: GitHub - regevbr/RaspiNukiBridge: Simple Nuki Bridge implementation using asyncio
  2. Add the repository and then install the add-on from HomeAssistant
  3. Read the addon installation documentation. But basically put the lock in pair mode and Start the addon.
  4. Restart the addon! For some people, not restarting the addon causes problems.

Using local python lib

  1. I created a script to ease the pairing process, mainly using the work of ftarolli. Run the following command to start it:

    sudo wget -O - | bash

    The script will clone the RaspiNukiBridge into ~/.local/bin
    Once the script finishes it will print some lines to create a service that will automatically the bridge start on boot.

  2. To test if it works you can run:

    python ~/.local/lib/RaspiNukiBridge/ --lock

Install the HA integration

Once the bridge is installed and working, go ahead and install the integration following these steps.

If you changed the port in the addon config, you should concatenate the port to the IP when configuring the integration like so:<port>

If you are running the Supervised or Docker installs, the IP of the bridge is not going to be You will need to find the container’s IP with the following command:

docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' $(docker ps --format '{{.Names}}' | grep nuki)

These are all the entities exposed for the Lock:

Bonus Track 1

Install the mushroom cards to get a nice lock entity like this:


Bonus Track 2

I installed a widget with fingerprint authentication in the Companion App that allows me to open the door with just one tap on my phone. I use the service for the lock.nuki_lock_name entity.

Hope this helps people to get around their mind, because it took me a few months to take the step and spent so many time reading about smart locks.



hi, what OS version are you using?

I’m running the last version of Raspbian, but it should work on any Debian system.

Thanks, but I running HA OS. Do u know if there is a way to run it in HA OS?

As I said in the post there are some addons you can try. You have the links there. They should work with HA OS. Give them a try and come back to post updates.

I had a few problems running them, some Dockefile commands where a bit off, but they may work for you.

Hi @victorigualada, thanks for sharing this great work.
When pairing is running, I can get successfully public and private keys, but just after that I get the following error:

Any advice? Thanks!


That looks to me like a python version matching problem.

Could you try running this without sudo?

I have python3.9 installed, and that’s the version I installed it with.

@juanrferia I found a new addon that works perfectly. You should try that since it doesn’t require anything else than installing and starting the addon. It’s super fast. I updateed the instructions on how to do it.

WOW! That works perfectly! Thanks a lot @victorigualada!

1 Like

Hello, I’m running HA on a odroid N2 and I was able to install the add-on. I also could get the token after pairing. Then I figured out what IP address I have to use. But now I’m stuck. I couldn’t install either the official integration nor nuki lock integration of HACS.

What do you mean you couldn’t install? Can you describe what you are doing, post any possible errors and/or pictures?

Well I want to set up the Integration in HA with the token and the IP of the add-on bridge.

Is your installation supervisor, OS or docker?

If it’s OS the IP for the bridge should be (localhost)

I’ve tried both ip’s. I’ve looked which IP it is with

in the terminal.

Which HA installation do you have?

It is an odroid N2 blue with HA OS
Home Assistant 2022.12.8
Supervisor 2022.11.2
Operating System 9.4
Frontend 20221213.1 - latest

If you are running OS, you don’t need to find the IP since the container can be accessed through localhost. You should then be using

You may also need to set the port after the ip or the port you set in the configuration.

Also make sure the addon is running, check the logs for any error message, try to make a request to the port where the addon is running:
curl localhost:8080

I’ve got the following Error.

Traceback (most recent call last):
  File "/opt/./", line 547, in _notification_handler
    command, data = await self._parse_command(uncrypted)
  File "/opt/./", line 424, in _parse_command
    "current_time": datetime.datetime(values[3], values[4], values[5],
ValueError: year 0 is out of range

This a Python that indicates a problem converting some times/dates. It looks like the date is incorrect. Is your OS date correct? Try to find a command to list it. Also try to reboot the system (not HA but the OS)

You will need to investigate by yourself that error. Try to look at the addon logs but also on the supervisor logs (Settings > System > Logs and select Supervisor on the top right dropdown)

The date looks fine. I started again from the beginning and now I have a different error.

2023-01-01 09:42:22.258|E||Error while sending data on attempt 1
2023-01-01 09:42:22.258|E||[org.bluez.Error.Failed] le-connection-abort-by-local
Traceback (most recent call last):
File "/opt/./", line 644, in task
await self.connect()
File "/opt/./", line 677, in connect
await self._client.connect()
File "/usr/lib/python3.9/site-packages/bleak/backends/bluezdbus/", line 278, in connect
File "/usr/lib/python3.9/site-packages/bleak/backends/bluezdbus/", line 23, in assert_reply
raise BleakDBusError(reply.error_name, reply.body)
bleak.exc.BleakDBusError: [org.bluez.Error.Failed] le-connection-abort-by-local
2023-01-01 09:42:22.459|I||Trying to send data. Attempt 2

Any idea how to fix this?