---
title: "Nuki Smart Lock 4 Pro (MQTT)"
description: "Nuki Smart Lock 4 Pro via MQTT nativo: blocco, sblocco, apertura, Lock 'n' Go, sensore porta, batteria. Broker LAN sulla porta 1883, es. TapHome Core."
url: "https://taphome.com/it/compatibility/nuki-smart-lock-4-pro-mqtt/"
language: it
lastmod: 2026-11-13
generator: hugo
ai:
  topics: ["mqtt","smart-lock","door-lock","access-control","wifi","thread","battery-powered"]
  questions: ["Come integrare Nuki Smart Lock 4 Pro con TapHome?","Cosa controlla e cosa legge il template TapHome per Nuki Smart Lock 4 Pro?","Come collegare una Nuki Smart Lock a TapHome via MQTT senza Nuki Bridge?","Come attivare MQTT nell'app Nuki e quale indirizzo del broker inserire?","Dove trovo il Nuki ID esadecimale della serratura?","Perché la serratura Nuki mostra il suo stato in TapHome ma non reagisce ai comandi?","Perché la Nuki Smart Lock non si connette al broker MQTT?","Quali modelli di Nuki Smart Lock supportano l'API MQTT?"]
---

# Nuki Smart Lock 4 Pro (MQTT)

Comunicazione: Packet Parser → MQTT

> Indirizzo di rete
> 
> Con il broker MQTT integrato in TapHome, inserisci `127.0.0.1` come indirizzo del broker in TapHome. Nel dispositivo inserisci l’indirizzo IP del TapHome Core e assegna al Core una prenotazione IP nel router.
> 
> [Preparazione della rete](https://taphome.com/it/docs/setup/network-preparation/)

## Guida all'integrazione

Nuki Smart Lock 4 Pro è una serratura smart a batteria da installare sulla serratura esistente, con Wi-Fi integrato e Matter over Thread. Il template la collega a TapHome tramite l'interfaccia MQTT propria della serratura (Nuki MQTT API), quindi non servono né un Nuki Bridge né altri gateway. La serratura funziona come client MQTT: si connette a un broker MQTT nella rete locale, pubblica i propri stati nei topic `nuki/<Nuki ID>/…` e riceve i comandi di blocco negli stessi topic. Il broker può essere l'interfaccia **MQTT Broker** in esecuzione direttamente sul TapHome Core.

TapHome legge lo stato della serratura, lo stato del sensore porta, il livello della batteria e l'ultima azione della serratura, e invia i comandi blocco, sblocco, apertura (unlatch) e Lock 'n' Go.

Secondo Nuki, la stessa API MQTT è disponibile su tutti i modelli Smart Lock di 4ª generazione (con o senza Pro), sullo Smart Lock 3.0 Pro (firmware 3.5.12 o superiore) e sui modelli più recenti Smart Lock Ultra, Smart Lock Pro (5ª generazione) e Smart Lock Go. Il template prende il nome dallo Smart Lock 4 Pro.

> [!WARNING]
> La serratura si connette solo a un broker nella rete locale (indirizzi privati 10.x.x.x, 172.16.x.x – 172.31.x.x, 192.168.x.x), sempre sulla porta 1883 e senza crittografia: TLS non è supportato. La sicurezza dei comandi dipende interamente dalla sicurezza della rete Wi-Fi o LAN. Usa l'interfaccia MQTT solo in una rete affidabile.

## Connessione di rete

MQTT passa attraverso la connessione di rete della serratura, quindi la serratura deve prima trovarsi nella stessa rete del broker. Nuki supporta MQTT tramite Wi-Fi o tramite Thread (Matter).

- **Wi-Fi:** nell'app Nuki apri **Settings → Features & Configuration → Built-in Wi-Fi → Configure Wi-Fi** della serratura, seleziona la rete e inserisci la relativa password. La serratura supporta solo Wi-Fi a 2,4 GHz (802.11 b/g/n); le reti a 5 GHz non sono supportate.
- **Thread:** in alternativa, la serratura si collega alla rete tramite Matter over Thread, come descritto da Nuki.

Non ci sono collegamenti elettrici: la serratura funziona a batterie (4× AA o il Nuki Power Pack) e si monta meccanicamente sul lato interno della porta secondo la guida di installazione Nuki.

## Configurazione

### Broker MQTT

La serratura ha bisogno di un broker MQTT raggiungibile nella rete locale:

| Requisito | Valore |
|---|---|
| Indirizzo del broker | indirizzo IPv4 privato, oppure un hostname che si risolve in un indirizzo IP privato |
| Porta | 1883 (fissa, non modificabile) |
| Crittografia | nessuna (TLS non è supportato) |
| Nome utente e password | facoltativi lato broker; ciascuno al massimo 32 caratteri |
| Versione del protocollo MQTT | 3.1.1 o superiore |

I broker cloud su internet non funzionano. Con l'interfaccia **MQTT Broker** di TapHome, l'indirizzo del broker è l'indirizzo IP del TapHome Core. Se sul broker sono impostati nome utente e password, le stesse credenziali vanno inserite nell'app Nuki.

### Attivazione di MQTT nell'app Nuki

1. Nell'app Nuki tocca la serratura e apri le sue impostazioni.
2. Vai su **Features & Configuration → Smart Home → MQTT** e segui la procedura guidata di attivazione.
3. Inserisci l'**hostname o l'indirizzo IPv4 del broker** (con TapHome come broker, l'indirizzo IP del Core, non quello della serratura) e, se il broker li richiede, **nome utente** e **password**.
4. Lascia attivo **Allow locking** (predefinito). Senza questa opzione la serratura non si iscrive ai topic dei comandi: TapHome ne mostra solo gli stati e non può bloccarla né sbloccarla.
5. **Auto discovery** (discovery di Home Assistant, attivo per impostazione predefinita) non è usato da TapHome: il template legge solo i topic `nuki/<Nuki ID>/…`. Puoi lasciarlo attivo o disattivarlo.
6. Controlla lo stato della connessione, che l'app Nuki mostra nella stessa sezione MQTT.

### Nuki ID

I topic di ogni serratura contengono il suo **Nuki ID** in forma esadecimale, per esempio `2BB28570`. È stampato sull'etichetta della serratura ed è visibile anche nell'amministrazione del dispositivo nell'app Nuki. L'ID va inserito esattamente in questa forma esadecimale.

### Parametri del template

In TapHome il template si aggiunge tramite un'interfaccia **Packet Parser** con i seguenti parametri di importazione:

| Parametro | Cosa inserire | Esempio |
|---|---|---|
| Nuki ID (hex) | Nuki ID esadecimale della serratura, dall'app Nuki o dall'etichetta | `2BB28570` |
| Indirizzo IP del broker MQTT | indirizzo del broker per TapHome: con l'interfaccia TapHome MQTT Broker `127.0.0.1` (il Core si collega a se stesso); la serratura riceve l'indirizzo IP del Core, **non** quello della serratura | `127.0.0.1` |

## Funzionalità del dispositivo

### Serratura

L'interruttore **Serratura** mostra **Bloccata** o **Sbloccata**. Gli stati Nuki in sblocco, sbloccata, aperta, sbloccata (Lock 'n' Go) e in apertura valgono tutti come Sbloccata. Durante il blocco, e quando la serratura non è calibrata o il motore è bloccato, l'interruttore mantiene l'ultimo valore.

Selezionando **Bloccata** viene inviata l'azione Nuki *lock*, selezionando **Sbloccata** l'azione *unlock*: la serratura si sblocca senza ritrarre lo scrocco. Il template invia un comando solo dopo aver ricevuto uno stato dalla serratura e solo quando il valore richiesto è diverso dallo stato attuale.

Attributi di servizio del dispositivo Serratura:

- **Stato serratura Nuki** — lo stato esatto, compresi In blocco, In sblocco, Aperta, In apertura, Sbloccata (Lock 'n' Go), Non calibrata e Motore bloccato
- **Batteria serratura critica** e **Batteria tastierino critica** — se le batterie vanno sostituite
- **Batteria in carica**
- **Connessione al broker** — se la serratura è connessa al broker MQTT
- **Connessione al server Nuki**
- **Risposta al comando** — Successo, oppure il codice di errore dell'ultimo comando segnalato dalla serratura
- **Ultima azione** — nome dell'ultima azione della serratura, per esempio Sblocco, Blocco, Apertura (unlatch) o Lock 'n' Go (lo stesso valore del dispositivo Ultima azione serratura, vedi sotto)
- **Ultimo aggiornamento** — ora dell'ultimo aggiornamento ricevuto dalla serratura, espressa nell'ora locale del TapHome Core
- **Versione firmware**

Il dispositivo Serratura ha anche un'azione di servizio **Lock 'n' Go**.

### Blocco, Apertura (Unlatch) e Lock 'n' Go

- **Blocco** — pulsante: blocca la serratura (azione Nuki *lock*). Invia il comando a ogni pressione, indipendentemente dallo stato dell'interruttore Serratura.
- **Apertura (Unlatch)** — pulsante: sblocca la serratura e ritrae lo scrocco, così la porta si apre senza usare la maniglia.
- **Lock 'n' Go** — pulsante: sblocca la serratura e la blocca di nuovo dopo la chiusura della porta.

### Sensore porta

Il **Sensore porta** mostra **Aperta** o **Chiusa** quando un Nuki Door Sensor è associato alla serratura. Quando il sensore porta segnala una manomissione, il dispositivo mostra Aperta e genera un avviso. Un sensore porta disattivato viene segnalato con un messaggio informativo.

### Livello batteria

**Livello batteria** mostra la carica delle batterie della serratura in %.

### Ultima azione serratura

**Ultima azione serratura** mostra il numero dell'ultima azione che la serratura stava per eseguire, avviata da TapHome, dall'app Nuki, dal pulsante sulla serratura, da un tastierino o da un telecomando (fob):

| Valore | Azione della serratura |
|---|---|
| 1 | sblocco |
| 2 | blocco |
| 3 | apertura (unlatch) |
| 4 | Lock 'n' Go |
| 5 | Lock 'n' Go con apertura (unlatch) |
| 6 | blocco completo |
| 80 | telecomando (fob, senza azione) |
| 90 | pulsante (senza azione) |

Il valore resta numerico per poter essere usato come trigger per le smart rule; il dispositivo Serratura mostra la stessa azione per nome nell'attributo di servizio **Ultima azione**. I codici errati inseriti sul tastierino e i comandi fuori da una fascia oraria consentita non vengono segnalati dalla serratura.

> [!NOTE]
> Dopo un riavvio del TapHome Core il template **non invia alcun comando** alla serratura: l'interruttore Serratura assume lo stato segnalato dalla serratura. La serratura pubblica i propri stati come messaggi retained, quindi i valori vengono ripristinati da ciò che il broker conserva; un dispositivo che dopo il riavvio non riceve un tale valore mostra lo stato corretto alla successiva variazione sulla serratura.

## Risoluzione dei problemi

- **La serratura non si connette al broker:** nell'app Nuki verifica che l'indirizzo del broker sia un indirizzo IP privato nella stessa rete (con TapHome, l'indirizzo IP del Core), che il broker accetti connessioni sulla porta 1883 senza TLS e che nome utente e password corrispondano alle impostazioni del broker. L'attributo di servizio **Connessione al broker** deve mostrare Connesso.
- **L'attivazione di MQTT nell'app Nuki non riesce:** aggiorna il firmware della serratura, verifica che la serratura sia connessa alla rete (Wi-Fi a 2,4 GHz o Thread), che la versione del protocollo MQTT sia 3.1.1 o superiore e che nome utente e password siano autorizzati sul broker. Se l'app segnala un identificativo client non valido, Nuki chiede di contattare il proprio supporto.
- **Gli stati vengono mostrati, ma i comandi non hanno effetto:** attiva **Allow locking** nelle impostazioni MQTT dell'app Nuki. L'attributo di servizio **Risposta al comando** mostra Successo o il codice di errore della serratura. La serratura elabora un solo comando alla volta; se vengono inviati più comandi in parallelo, le risposte possono sovrapporsi.
- **In TapHome non viene mostrato nulla:** controlla il Nuki ID: deve essere in forma esadecimale, esattamente come appare nell'app Nuki o sull'etichetta.
- **Stato serratura Nuki mostra Non calibrata:** completa la calibrazione della serratura nell'app Nuki.
- **Il Sensore porta non cambia mai:** alla serratura deve essere associato un Nuki Door Sensor; senza di esso la serratura non segnala lo stato della porta.

## Dispositivi disponibili 7

Questi dispositivi compaiono in TapHome dopo l'importazione.

Nuki Smart Lock 4 Pro Modulo

Zámok Interruttore multivalore

Valori / Stati: Zamknuté · Odomknuté

Azioni di servizio

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

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

Lettura stato interruttore

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

Scrittura stato interruttore

```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
```

Attributi di servizio

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)
```

Azioni di servizio

Lock 'n' Go

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

Dverový senzor Contatto reed

Lettura

```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) Pulsante

Lettura stato pulsante

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

Scrittura stato pulsante

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

Lock 'n' Go Pulsante

Lettura stato pulsante

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

Scrittura stato pulsante

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

Úroveň batérie Ingresso analogico

Lettura livello ingresso

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

Listener

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

Posledná akcia zámku Variabile

Lettura

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

Listener

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

Zamknúť Pulsante

Lettura stato pulsante

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

Scrittura stato pulsante

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

**Connessione:** Packet Parser → MQTT

## Parametri di importazione

Inserisci questi valori quando importi l'XML.

| Richiesto nell'app            | Predefinito   |
|-------------------------------|---------------|
| Nuki ID (hex, napr. 2BB28570) | `2BB28570`    |
| IP adresa MQTT brokera        | `192.168.1.1` |

## Documentazione correlata

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