The Nuki Smart Lock 4 Pro is a battery-powered retrofit smart lock with built-in Wi-Fi and Matter over Thread. The template connects it to TapHome through the lock’s own MQTT interface (Nuki MQTT API), so neither a Nuki Bridge nor any other gateway is needed. The lock works as an MQTT client: it connects to an MQTT broker in the local network, publishes its states under the topics nuki/<Nuki ID>/… and accepts lock commands on the same topics. The broker can be the MQTT Broker interface running directly on the TapHome Core.
TapHome reads the lock state, door sensor state, battery level and the last lock action, and sends the commands lock, unlock, unlatch and Lock ’n’ Go.
According to Nuki, the same MQTT API is available on all Smart Lock 4th generation models (with or without Pro), the Smart Lock 3.0 Pro (firmware 3.5.12 or higher) and the newest models Smart Lock Ultra, Smart Lock Pro (5th generation) and Smart Lock Go. The template is named after the Smart Lock 4 Pro.
The lock connects only to a broker in the local network (private addresses 10.x.x.x, 172.16.x.x – 172.31.x.x, 192.168.x.x), always on port 1883 and without encryption — TLS is not supported. Security of the commands depends entirely on the security of the Wi-Fi or LAN. Use the MQTT interface only in a trusted network.
Network connection
MQTT runs over the lock’s network connection, so the lock must first be in the same network as the broker. Nuki supports MQTT over Wi-Fi or over Thread (Matter).
- Wi-Fi: in the Nuki app open the lock’s Settings → Features & Configuration → Built-in Wi-Fi → Configure Wi-Fi, select the network and enter its password. The lock supports only 2.4 GHz Wi-Fi (802.11 b/g/n); 5 GHz networks are not supported.
- Thread: alternatively, the lock is connected to the network via Matter over Thread, as described by Nuki.
There is no wiring — the lock runs on batteries (4× AA or the Nuki Power Pack) and is mounted mechanically on the inside of the door according to the Nuki installation guide.
Configuration
MQTT broker
The lock needs an MQTT broker that it can reach in the local network:
| Requirement | Value |
|---|---|
| Broker address | private IPv4 address, or a hostname that resolves to a private IP address |
| Port | 1883 (fixed, cannot be changed) |
| Encryption | none (TLS is not supported) |
| Username and password | optional on the broker side; each at most 32 characters |
| MQTT protocol version | 3.1.1 or newer |
Cloud brokers on the internet do not work. With the MQTT Broker interface of TapHome, the broker address is the IP address of the TapHome Core. If a username and password are set on the broker, the same credentials are entered in the Nuki app.
Enabling MQTT in the Nuki app
- In the Nuki app, tap the lock and open its settings.
- Go to Features & Configuration → Smart Home → MQTT and follow the activation wizard.
- Enter the hostname or IPv4 address of the broker (with TapHome as the broker, the IP address of the Core — not the IP address of the lock), and the username and password if the broker requires them.
- Leave Allow locking switched on (default). Without it the lock does not subscribe to the command topics: TapHome then only shows its states and cannot lock or unlock it.
- Auto discovery (Home Assistant discovery, default on) is not used by TapHome — the template reads only the
nuki/<Nuki ID>/…topics. It can stay on or be switched off. - Check the connection status, which the Nuki app shows in the same MQTT section.
Nuki ID
The topics of each lock contain its Nuki ID in hexadecimal form, for example 2BB28570. It is printed on the label of the lock and also shown in the device administration of the Nuki app. The ID must be entered exactly in this hexadecimal form.
Template parameters
In TapHome, the template is added through a Packet Parser interface with the following import parameters:
| Parameter | What to enter | Example |
|---|---|---|
| Nuki ID (hex) | hexadecimal Nuki ID of the lock, from the Nuki app or the label | 2BB28570 |
| MQTT broker IP address | address of the broker for TapHome — with the TapHome MQTT Broker interface 127.0.0.1 (the Core connects to itself); the lock gets the IP address of the Core, not the IP address of the lock | 127.0.0.1 |
Device capabilities
Lock
The Lock switch shows Locked or Unlocked. The Nuki states unlocking, unlocked, unlatched, unlocked (Lock ’n’ Go) and unlatching all count as Unlocked. During locking, and when the lock is uncalibrated or the motor is blocked, the switch keeps its last value.
Selecting Locked sends the Nuki lock action lock, selecting Unlocked sends unlock — the lock unlocks without pulling the latch. The template sends a command only after it has received a state from the lock and only when the requested value differs from the current state.
Service attributes of the Lock device:
- Nuki lock state — the exact state, including Locking, Unlocking, Unlatched, Unlatching, Unlocked (Lock ’n’ Go), Uncalibrated and Motor blocked
- Lock battery critical and Keypad battery critical — whether the batteries need replacing
- Battery charging
- Broker connection — whether the lock is connected to the MQTT broker
- Nuki server connection
- Command response — Success, or the error code of the last command reported by the lock
- Last action — name of the last lock action, for example Unlock, Lock, Unlatch or Lock ’n’ Go (the same value as the Last lock action device, see below)
- Last update — time of the last update from the lock, shown in the local time of the TapHome Core
- Firmware version
The Lock device also has a Lock ’n’ Go service action.
Lock, Unlatch and Lock ’n’ Go
- Lock — push button: locks the lock (Nuki lock action lock). It sends the command on every press, regardless of the state of the Lock switch.
- Unlatch — push button: unlocks the lock and pulls the latch, so the door can be opened without the handle.
- Lock ’n’ Go — push button: unlocks the lock and locks it again after the door is closed.
Door sensor
The Door sensor shows Open or Closed when a Nuki Door Sensor is paired with the lock. When the door sensor reports tampering, the device shows Open and raises a warning. A deactivated door sensor is reported as an information message.
Battery level
Battery level shows the charge of the lock’s batteries in %.
Last lock action
Last lock action shows the number of the last lock action that the lock was about to execute — from TapHome, the Nuki app, the button on the lock, a keypad or a fob:
| Value | Lock action |
|---|---|
| 1 | unlock |
| 2 | lock |
| 3 | unlatch |
| 4 | Lock ’n’ Go |
| 5 | Lock ’n’ Go with unlatch |
| 6 | full lock |
| 80 | fob (without action) |
| 90 | button (without action) |
The value stays numeric so that it can be used as a trigger for smart rules; the Lock device shows the same action by name in its service attribute Last action. Unsuccessful keypad code entries and commands outside an allowed time window are not reported by the lock.
After a restart of the TapHome Core the template sends no command to the lock — the Lock switch takes over the state reported by the lock. The lock publishes its states as retained messages, so values are restored from what the broker keeps; a device that does not receive such a value after the restart shows the correct state at the next change on the lock.
Troubleshooting
- The lock does not connect to the broker: check in the Nuki app that the broker address is a private IP address in the same network (with TapHome, the IP address of the Core), that the broker accepts connections on port 1883 without TLS, and that the username and password match the broker settings. The service attribute Broker connection must show Connected.
- MQTT activation fails in the Nuki app: update the firmware of the lock, check that the lock is connected to the network (2.4 GHz Wi-Fi or Thread), check that the MQTT protocol version is 3.1.1 or newer, and check that the username and password are authorized on the broker. If the app reports an incorrect client identifier, Nuki asks to contact its support.
- States are shown, but commands do nothing: switch on Allow locking in the MQTT settings of the Nuki app. The service attribute Command response shows Success or the error code of the lock. The lock processes only one command at a time; when several commands are sent in parallel, the responses can overlap.
- Nothing is shown in TapHome: check the Nuki ID — it must be in hexadecimal form exactly as shown in the Nuki app or on the label.
- Nuki lock state shows Uncalibrated: finish the calibration of the lock in the Nuki app.
- The Door sensor never changes: a Nuki Door Sensor must be paired with the lock; without it the lock does not report a door state.
