TapHome

Sonoff SNZB-01

Packet Parser → MQTT
Inviato da
Ultimo aggiornamento: 04. 2026
Sonoff SNZB-01

Il Sonoff SNZB-01 è un pulsante wireless Zigbee 3.0 compatto alimentato da una batteria a bottone CR2450. Comunica con TapHome indirettamente — il pulsante si accoppia con un coordinatore Zigbee2MQTT (es. Sonoff ZBDongle-P/E o stick basato su CC2652), che inoltra i messaggi Zigbee ai topic MQTT. TapHome si sottoscrive a questi topic MQTT tramite un modulo PacketParser MQTT.

Il template rileva tre azioni del pulsante (pressione singola, pressione doppia, pressione lunga) e monitora la percentuale della batteria, la tensione della batteria e la qualità del segnale Zigbee.

Configurazione

Configurazione Zigbee2MQTT

Prima di importare il template TapHome, l’SNZB-01 deve essere accoppiato con un coordinatore Zigbee2MQTT:

  1. Aprire l’interfaccia web Zigbee2MQTT e abilitare la modalità di accoppiamento (Permit join)
  2. Sull’SNZB-01, rimuovere il coperchio posteriore e tenere premuto il pulsante di reset per 5 secondi finché il LED lampeggia tre volte
  3. Il dispositivo appare nell’elenco dispositivi Zigbee2MQTT con un indirizzo IEEE (es. 0x00124b001eab21e5) o un friendly name
Variabile del modulo

Dopo l’importazione del template in TapHome, impostare la variabile personalizzata SonoffSNZB01 per identificare il dispositivo sul broker MQTT:

VariabileDescrizioneCome ottenereEsempio
SonoffSNZB01Friendly name Zigbee2MQTT o indirizzo IEEE dell’SNZB-01Zigbee2MQTT web UI → Devices → trovare SNZB-01 → copiare friendly name o indirizzo IEEE0x00124b001eab21e5

La variabile viene utilizzata come prefisso del topic MQTT — lo script listener si sottoscrive a zigbee2mqtt/{SonoffSNZB01} e zigbee2mqtt/{SonoffSNZB01}/action.

L’utilizzo del friendly name (es. living_room_button) invece dell’indirizzo IEEE rende la configurazione più leggibile. Il friendly name può essere modificato nell’interfaccia web Zigbee2MQTT nelle impostazioni del dispositivo.

Funzionalità del dispositivo

Rilevamento pressione pulsante

Il template mappa l’SNZB-01 come dispositivo Push Button in TapHome. Gli eventi di pressione arrivano sul topic zigbee2mqtt/{id}/action e vengono mappati su valori numerici:

Azione fisicaMQTT payloadValore TapHome
Pressione singola (rilascio + 0,6 s attesa)single1
Pressione doppiadouble3
Pressione lunga (tenere premuto 2 secondi)long2

Dopo la lettura dello stato del pulsante, il valore viene resettato a 0 — le azioni del pulsante sono basate su eventi e non possono essere rilette.

Monitoraggio batteria e segnale

Ogni istanza del pulsante espone tre attributi di servizio:

  • Battery — percentuale batteria residua (0–100 %) dal topic JSON di stato. L’SNZB-01 utilizza una batteria a bottone CR2450 con durata tipica di 1–2 anni.
  • BatteryVoltage — tensione della batteria in millivolt dal topic JSON di stato.
  • LinkQuality — indicatore di qualità del segnale Zigbee (0–255 lqi) dal topic JSON di stato. Valori più alti indicano un segnale migliore.

Tutti gli attributi mostrano "-" fino alla ricezione del primo messaggio dal dispositivo.

Funzionalità aggiuntive

Il bridge Zigbee2MQTT fornisce anche un topic per la richiesta proattiva dello stato (zigbee2mqtt/{id}/get) che consente di richiedere i valori di batteria e tensione su richiesta, e un topic di disponibilità per il rilevamento online/offline. Queste funzionalità potranno essere aggiunte in un futuro aggiornamento del template.

Risoluzione dei problemi

Le pressioni del pulsante non vengono rilevate
  1. Verificare che l’SNZB-01 sia accoppiato con il coordinatore Zigbee2MQTT — dovrebbe apparire nell’elenco dispositivi con stato verde
  2. Controllare che la variabile personalizzata SonoffSNZB01 corrisponda esattamente al friendly name o all’indirizzo IEEE del dispositivo (distinzione maiuscole/minuscole)
  3. Utilizzare un client MQTT (es. MQTT Explorer) per sottoscriversi a zigbee2mqtt/# e premere il pulsante — un messaggio dovrebbe apparire sul topic /action
  4. Se non appaiono messaggi MQTT, il dispositivo potrebbe aver perso la connessione Zigbee — riaccoppiare tenendo premuto il pulsante di reset per 5 secondi
Valori di batteria o qualità del segnale obsoleti
  1. I dati di batteria e segnale si aggiornano solo quando il dispositivo si risveglia (alla pressione del pulsante o alla segnalazione periodica)
  2. Se i valori mostrano "-", non è stato ancora ricevuto alcun messaggio — premere il pulsante per attivare un aggiornamento
  3. Assicurare una buona ricezione del coordinatore Zigbee — la portata dell’SNZB-01 dipende dalla rete mesh Zigbee

Il Sonoff SNZB-01 è stato dismesso e sostituito dall’SNZB-01P. Il template TapHome rimane funzionante per i dispositivi SNZB-01 esistenti, ma per nuovi acquisti si consiglia l’SNZB-01P che offre portata migliorata e batteria ricaricabile USB-C.

Dispositivi disponibili

Sonoff SNZB-01 Modulo
Variabili personalizzate
SonoffSNZB01 (string) = 0x00124b001eab21e5Friendly name Zigbee2MQTT o indirizzo IEEE del dispositivo SNZB-01 — usato come prefisso del topic MQTT
Open Zigbee2MQTT web UI → Devices → find SNZB-01 → copy the Friendly name (or use the IEEE address, e.g. 0x00124b001eab21e5)
Pulsante wireless Pulsante

Rilevamento pressione pulsante — singola (1), doppia (3), lunga (2); si resetta a 0 dopo la lettura

enum
Attributi di servizio
BatteriaPercentuale batteria residua (batteria a bottone CR2450, 0–100 %)
LinkQualityIndicatore qualità segnale Zigbee — 0 (peggiore) a 255 (migliore)
BatteryVoltageTensione della batteria in millivolt

Pulsante wireless

Lettura stato pulsante
Bp := 0;
Scrittura stato pulsante
# Simple HTTP Request:
# VAR response := SENDHTTPREQUEST("/example/set/value=" + Bp);
# IF response.IsSuccess = false
#  ADDERROR(response.StatusCode);
# END
#
# Set Http request method, body and headers
# VAR response := SENDHTTPREQUEST("/example/setValue", "GET", "value=" + Bp, "header1:value1", "header2:value2", ...);\r
# Or VAR request := HTTPREQUEST("/example/setValue");
# request.Method := "PUT";
# VAR response := SENDHTTPREQUEST(request);
#r
#
# Send TCP, UDP data:
# VAR data1 := "{\"name\":\"John\", \"age\":" + Bp + "}";
# SENDDATA(data1);
# VAR data2 := TOBYTES("{\"name\":\"John\", \"age\":" + Bp + "}", "iso-8859-1");
# SENDDATA(data2);
# You can process received TCP or UDP data in the Listener script
#
#
# Upload data to FTP:
# FTPUPLOAD("filePath", "somedata=" + Bp, "write"); # use "append" mode to append data to existing file
Listener
Bp := 0;

IF (COMPARE(RECEIVEDMSG.TOPIC, "zigbee2mqtt/"+ SonoffSNZB01 +"/action", CompareOptions.IgnoreCase) = 0)
	var payloadString := TOSTRING(RECEIVEDMSG.PAYLOAD);
	
    IF (COMPARE(payloadString, "single", CompareOptions.IgnoreCase) = 0)
          Bp := 1;
        ELSEIF (COMPARE(payloadString, "long", CompareOptions.IgnoreCase) = 0)
          Bp := 2;
        ELSEIF (COMPARE(payloadString, "double", CompareOptions.IgnoreCase) = 0)
          Bp := 3;
        ELSE
          Bp := 0;
    END  
END;   

IF (COMPARE(RECEIVEDMSG.TOPIC, "zigbee2mqtt/"+ SonoffSNZB01, CompareOptions.IgnoreCase) = 0)
    battery := PARSEJSON(RECEIVEDMSG.PAYLOAD,"battery", true);
    voltage := PARSEJSON(RECEIVEDMSG.PAYLOAD,"voltage", true);
    link := PARSEJSON(RECEIVEDMSG.PAYLOAD,"linkquality", true);
    
END
Attributi di servizio
Battery
IF(ISNAN(battery),"-",battery+"%");
LinkQuality
IF(ISNAN(link),"-",link+"lqi");
BatteryVoltage
IF(ISNAN(voltage),"-",voltage+"mV");
Connessione: Packet Parser → MQTT
Possibili miglioramenti (2)
  • Proactive State Request — Publish {"battery":""} or {"voltage":""} to request values on demand. Could wake sleeping device.
  • Availability Status — Online/offline availability topic. Could detect unreachable devices.

Fonti