---
title: "Nuki Smart Lock 4 Pro (MQTT)"
description: "Nuki Smart Lock 4 Pro via native MQTT: lock, unlock, unlatch, Lock 'n' Go, door sensor, battery. Needs a LAN broker on port 1883, e.g. TapHome Core."
url: "https://taphome.com/en/compatibility/nuki-smart-lock-4-pro-mqtt/"
language: en
lastmod: 2026-11-13
generator: hugo
ai:
  topics: ["mqtt","smart-lock","door-lock","access-control","wifi","thread","battery-powered"]
  questions: ["How to integrate the Nuki Smart Lock 4 Pro with TapHome?","What does the Nuki Smart Lock 4 Pro TapHome template control and read?","How to connect a Nuki Smart Lock to TapHome via MQTT without a Nuki Bridge?","How to enable MQTT in the Nuki app and which broker address to enter?","Where to find the hexadecimal Nuki ID of the lock?","Why does the Nuki lock show its state in TapHome but not react to commands?","Why does the Nuki Smart Lock not connect to the MQTT broker?","Which Nuki Smart Lock models support the MQTT API?"]
---

# Nuki Smart Lock 4 Pro (MQTT)

Communication: Packet Parser → MQTT

> Network address
> 
> With the MQTT broker built into TapHome, enter `127.0.0.1` as the broker address in TapHome. In the device, enter the IP address of the TapHome Core and give the Core an IP reservation in the router.
> 
> [Network Preparation](https://taphome.com/en/docs/setup/network-preparation/)

## Integration guide

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.

> [!WARNING]
> 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

1. In the Nuki app, tap the lock and open its settings.
2. Go to **Features & Configuration → Smart Home → MQTT** and follow the activation wizard.
3. 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.
4. 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.
5. **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.
6. 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.

> [!NOTE]
> 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.

## Available devices 7

These devices appear in TapHome after import.

Nuki Smart Lock 4 Pro Module

Zámok Multi-value Switch

Values / States: Zamknuté · Odomknuté

Service Actions

|             |
|-------------|
| Lock 'n' Go |

Variable: `batteryCritical`, Variable: `batteryCharging`, Variable: `keypadBatteryCritical`, Variable: `nukiConnected`, Variable: `serverConnected`, Variable: `commandResponse`, Variable: `nukiTimestamp`, Variable: `nukiFirmware`, Variable: `ready`, Variable: `lastState`, Variable: `lastAction`

Read switch state

```taphome
RETURN(Mu);
```

Write switch state

```taphome
IF(ready = 0 OR Mu = lastState)
    RETURN(0);
END
IF(Mu = 1)
    MQTTPUBLISH("nuki/$[NukiId]/lockAction", "2");
ELSEIF(Mu = 3)
    MQTTPUBLISH("nuki/$[NukiId]/lockAction", "1");
END
```

Listener

```taphome
IF(INDEXOF(RECEIVEDMSG.TOPIC, "nuki/$[NukiId]/") != 0)
    RETURN(0);
END
IF(RECEIVEDMSG.TOPIC = "nuki/$[NukiId]/state")
    VAR st := TODOUBLE(TOSTRING(RECEIVEDMSG.PAYLOAD));
    ready := 1;
    lastState := st;
    IF(st = 1)
        Mu := 1;
    ELSEIF(st = 2 OR st = 3 OR st = 5 OR st = 6 OR st = 7)
        Mu := 3;
    END
ELSEIF(RECEIVEDMSG.TOPIC = "nuki/$[NukiId]/batteryCritical")
    batteryCritical := TOSTRING(RECEIVEDMSG.PAYLOAD);
ELSEIF(RECEIVEDMSG.TOPIC = "nuki/$[NukiId]/batteryCharging")
    batteryCharging := TOSTRING(RECEIVEDMSG.PAYLOAD);
ELSEIF(RECEIVEDMSG.TOPIC = "nuki/$[NukiId]/keypadBatteryCritical")
    keypadBatteryCritical := TOSTRING(RECEIVEDMSG.PAYLOAD);
ELSEIF(RECEIVEDMSG.TOPIC = "nuki/$[NukiId]/connected")
    nukiConnected := TOSTRING(RECEIVEDMSG.PAYLOAD);
ELSEIF(RECEIVEDMSG.TOPIC = "nuki/$[NukiId]/serverConnected")
    serverConnected := TOSTRING(RECEIVEDMSG.PAYLOAD);
ELSEIF(RECEIVEDMSG.TOPIC = "nuki/$[NukiId]/commandResponse")
    commandResponse := TOSTRING(RECEIVEDMSG.PAYLOAD);
ELSEIF(RECEIVEDMSG.TOPIC = "nuki/$[NukiId]/timestamp")
    VAR tsUtc := DATETIME(TOSTRING(RECEIVEDMSG.PAYLOAD));
    VAR tsLocal := tsUtc.LOCALDATETIME;
    nukiTimestamp := TOSTRING(tsLocal, "d.M.yyyy HH:mm:ss");
ELSEIF(RECEIVEDMSG.TOPIC = "nuki/$[NukiId]/lockActionEvent")
    lastAction := TODOUBLE(GETAT(SPLIT(TOSTRING(RECEIVEDMSG.PAYLOAD), ","), 0));
ELSEIF(RECEIVEDMSG.TOPIC = "nuki/$[NukiId]/firmware")
    nukiFirmware := TOSTRING(RECEIVEDMSG.PAYLOAD);
END
```

Service Attributes

Stav zámku Nuki

```taphome
IF(lastState = 1, "Zamknuté", IF(lastState = 2, "Odomykanie", IF(lastState = 3, "Odomknuté", IF(lastState = 4, "Zamykanie", IF(lastState = 5, "Odblokované", IF(lastState = 6, "Odomknuté (Lock 'n' Go)", IF(lastState = 7, "Odblokovanie", IF(lastState = 0, "Nekalibrovaný", IF(lastState = 254, "Motor zablokovaný", "Neznámy (" + TOSTRING(lastState) + ")")))))))))
```

Krit. batéria zámku

```taphome
IF(batteryCritical = "true", "Áno — vymeniť batérie", "Nie")
```

Nabíjanie batérie

```taphome
IF(batteryCharging = "true", "Prebieha", "Neprebieha")
```

Krit. batéria klávesnice

```taphome
IF(keypadBatteryCritical = "true", "Áno — vymeniť batérie", "Nie")
```

Pripojenie k brokeru

```taphome
IF(nukiConnected = "true", "Pripojený", "Odpojený")
```

Pripojenie k serveru Nuki

```taphome
IF(serverConnected = "true", "Pripojený", "Odpojený")
```

Odozva na príkaz

```taphome
IF(commandResponse = "0", "Úspech", IF(LENGTH(commandResponse) = 0, "—", "Chyba zámku: " + commandResponse))
```

Posledná akcia

```taphome
IF(lastAction = 1, "Odomknutie", IF(lastAction = 2, "Zamknutie", IF(lastAction = 3, "Odblokovanie", IF(lastAction = 4, "Lock 'n' Go", IF(lastAction = 5, "Lock 'n' Go s odblokovaním", IF(lastAction = 6, "Úplné zamknutie", IF(lastAction = 80, "Kľúčenka (bez akcie)", IF(lastAction = 90, "Tlačidlo (bez akcie)", IF(lastAction = -1, "—", "Neznáma (" + TOSTRING(lastAction) + ")")))))))))
```

Posledná aktualizácia

```taphome
IF(LENGTH(nukiTimestamp) = 0, "—", nukiTimestamp)
```

Verzia firmvéru

```taphome
IF(LENGTH(nukiFirmware) = 0, "—", nukiFirmware)
```

Service Actions

Lock 'n' Go

```taphome
MQTTPUBLISH("nuki/$[NukiId]/lockAction", "4");
```

Dverový senzor Reed Contact

Read

```taphome
RETURN(Rc);
```

Listener

```taphome
IF(RECEIVEDMSG.TOPIC = "nuki/$[NukiId]/doorsensorState")
    VAR dsVal := TODOUBLE(TOSTRING(RECEIVEDMSG.PAYLOAD));
    IF(dsVal = 3)
        Rc := 1;
    ELSEIF(dsVal = 2)
        Rc := 0;
    ELSEIF(dsVal = 240)
        Rc := 1;
        ADDWARNING(0, "Dverový senzor: detekovaná manipulácia (tamper)");
    ELSEIF(dsVal = 1)
        ADDINFO(0, "Dverový senzor deaktivovaný");
    END
END
```

Odblokovanie (Unlatch) Push Button

Read button state

```taphome
Bp := 0;
```

Write button state

```taphome
MQTTPUBLISH("nuki/$[NukiId]/lockAction", "3");
```

Lock 'n' Go Push Button

Read button state

```taphome
Bp := 0;
```

Write button state

```taphome
MQTTPUBLISH("nuki/$[NukiId]/lockAction", "4");
```

Úroveň batérie Analog Input

Read input level

```taphome
RETURN(An);
```

Listener

```taphome
IF(RECEIVEDMSG.TOPIC = "nuki/$[NukiId]/batteryChargeState")
    An := TODOUBLE(TOSTRING(RECEIVEDMSG.PAYLOAD)) / 100;
END
```

Posledná akcia zámku Variable

Read

```taphome
RETURN(Va);
```

Listener

```taphome
IF(RECEIVEDMSG.TOPIC = "nuki/$[NukiId]/lockActionEvent")
    Va := TODOUBLE(GETAT(SPLIT(TOSTRING(RECEIVEDMSG.PAYLOAD), ","), 0));
END
```

Zamknúť Push Button

Read button state

```taphome
Bp := 0;
```

Write button state

```taphome
MQTTPUBLISH("nuki/$[NukiId]/lockAction", "2");
```

**Connection:** Packet Parser → MQTT

## Import parameters

Enter these values when you import the XML.

| Asked in the app              | Default       |
|-------------------------------|---------------|
| Nuki ID (hex, napr. 2BB28570) | `2BB28570`    |
| IP adresa MQTT brokera        | `192.168.1.1` |

## Related Documentation

- [MQTT Integration](https://taphome.com/en/compatibility/mqtt-guide/)
- [Packet Parser (HTTP, TCP, UDP, FTP, MQTT)](https://taphome.com/en/docs/integration/packet-parser/)
- [Packet parser functions](https://taphome.com/en/docs/script/packet-parser/)
- [Parsing functions](https://taphome.com/en/docs/script/parsing-functions/)
- [MQTT Broker](https://taphome.com/en/docs/integration/packet-parser/mqtt-broker/)
- [Listener scripts](https://taphome.com/en/docs/script/listener-scripts/)