TapHome

Zigbee2Tasmota Gateway

Packet Parser → MQTT
Inviato da
Ultimo aggiornamento: 03. 2026
Zigbee2Tasmota Gateway

Zigbee2Tasmota (Z2T) è un bridge Zigbee-to-MQTT leggero che gira su microcontrollori ESP8266/ESP32 con modulo radio Zigbee integrato. Consente a TapHome di comunicare con dispositivi Zigbee tramite il broker MQTT locale — senza connessione al cloud.

Questo template gateway è il prerequisito per tutti i template dispositivi Zigbee2Tasmota. Deve essere importato per primo, prima di aggiungere qualsiasi template di dispositivo Zigbee. Il gateway gestisce il pairing dei dispositivi e fornisce in TapHome un interruttore Permit Join e un contatore Devices Found.

Hardware gateway supportato

I seguenti coordinatori Zigbee sono compatibili con Zigbee2Tasmota:

GatewayProcessoreRadio ZigbeeConnettivitàNote
eWeLink ZB-GW03 (consigliato)ESP32EFR32 (EZSP)Ethernet + ZigbeeDisponibile con firmware Tasmota preinstallato
Sonoff ZBBridgeESP8266EFR32 (EZSP)WiFi + ZigbeeRichiede flash manuale del firmware Tasmota
Sonoff ZBBridge ProESP32CC2652P (ZNP)WiFi + ZigbeeFino a 128 dispositivi, richiede flash

Altro hardware compatibile include il Tube’s Ethernet Zigbee Gateway (basato su EFR32) e build DIY personalizzate con ESP32 e moduli CC2530/CC2652.

L’eWeLink ZB-GW03 è consigliato per la connettività Ethernet (più affidabile del WiFi) e la disponibilità con firmware Tasmota preinstallato — nessun flash necessario.

Configurazione

Configurazione del gateway Tasmota
  1. Installa il firmware Tasmota sul coordinatore Zigbee (salta se preinstallato)
  2. Collega il gateway alla rete tramite l’interfaccia web di Tasmota
  3. Vai su Configuration → Configure MQTT e imposta:
    • Host: IP del broker MQTT (es. 192.168.1.10)
    • Port: 1883
  4. Annota il nome del Topic (es. tasmota_XXXXX) — questo è il parametro Gateway name necessario durante l’importazione del template

TapHome ha un broker MQTT integrato — attivalo in Settings → Hardware → MQTT Broker. Non è necessario nessun software broker aggiuntivo.

Parametri di importazione del template

Il template gateway richiede 3 parametri:

ParametroDescrizioneEsempio
MQTT Broker IP AddressIP del broker MQTT192.168.1.10
MQTT Broker PortPorta del broker (predefinita 1883)1883
Gateway nameTopic MQTT Tasmota da Configuration → MQTT → Topictasmota_XXXXX

Dopo l’importazione, il modulo si iscrive a tele/{GWname}/# e appaiono due dispositivi: Permit Join e Devices Found.

Funzionalità del dispositivo

Pairing dei dispositivi Zigbee

L’interruttore Permit Join controlla la modalità di pairing del gateway:

  1. Attiva Permit Join in TapHome — questo pubblica un comando ZbPermitJoin che apre una finestra di pairing di 60 secondi
  2. Avvia la procedura di pairing sul dispositivo Zigbee (in genere tieni premuto il pulsante di reset per 5 secondi finché il LED non lampeggia)
  3. Osserva il contatore Devices Found — si incrementa quando un nuovo dispositivo si unisce alla rete con successo
  4. Controlla l’attributo di servizio New devices sul gateway per vedere l’ID del dispositivo accoppiato (es. 0x1234), produttore e modello
  5. La modalità di pairing si disattiva automaticamente dopo il timeout

Il Device ID (indirizzo breve come 0x1234) visualizzato negli attributi di servizio è necessario durante l’importazione dei template specifici per dispositivo.

Monitoraggio dispositivi

Il modulo gateway interroga ZbInfo ogni ora per aggiornare le informazioni su tutti i dispositivi Zigbee accoppiati. L’attributo di servizio New devices mostra i dettagli dei dispositivi scoperti di recente, inclusi indirizzo breve Zigbee, produttore e identificatore del modello.

Funzionalità aggiuntive

Il gateway Tasmota Zigbee supporta anche l’elenco di tutti i dispositivi accoppiati (ZbStatus), la visualizzazione della configurazione di rete (ZbConfig — PanID, canale, chiavi di crittografia), la denominazione dei dispositivi, la gestione dei gruppi e il binding diretto dispositivo-a-dispositivo. Queste funzionalità diagnostiche e di gestione potranno essere aggiunte in un futuro aggiornamento del template.

Template dispositivi Zigbee supportati

Dopo aver accoppiato un dispositivo, importa il template specifico corrispondente. Ogni template dispositivo richiede 4 parametri: MQTT Broker IP, Port, Gateway name (uguale al gateway) e il Device ID dal pairing.

Template dispositivi Zigbee2Tasmota disponibili:

Risoluzione problemi

Il gateway non si connette al broker MQTT
  1. Verifica che il gateway Tasmota sia connesso alla rete (controlla l’interfaccia web di Tasmota)
  2. Conferma che IP e porta del broker MQTT corrispondano tra la configurazione MQTT di Tasmota e i parametri di importazione del template in TapHome
  3. Verifica che il broker MQTT sia in esecuzione e raggiungibile sulla porta specificata
Permit Join non trova dispositivi
  1. Assicurati che il dispositivo Zigbee sia in modalità pairing — la maggior parte dei dispositivi richiede di tenere premuto un pulsante per 5+ secondi
  2. Verifica che l’interruttore Permit Join sia attivo in TapHome prima di avviare la procedura di pairing del dispositivo
  3. Durante il pairing iniziale, posiziona il dispositivo Zigbee più vicino al gateway (entro 2–3 metri)
  4. Alcuni dispositivi richiedono un ripristino alle impostazioni di fabbrica prima di poter essere accoppiati con un nuovo coordinatore
Il Device ID non appare
  1. Dopo un pairing riuscito, controlla l’attributo di servizio New devices sul modulo gateway per Device ID, produttore e modello
  2. Se l’attributo di servizio è vuoto, prova a spegnere e riaccendere Permit Join (OFF → ON), poi accoppia nuovamente il dispositivo
  3. Il Device ID si trova anche nella console Tasmota (comando ZbStatus) tramite l’interfaccia web del gateway

Il canale radio Zigbee non dovrebbe sovrapporsi al canale Wi-Fi. Per i migliori risultati, usa i canali Zigbee 15, 20 o 25 che hanno interferenza Wi-Fi minima. Verifica il canale attuale con il comando ZbConfig nella console Tasmota.

Dispositivi disponibili

Zigbee2Tasmota Gateway Modulo
Attributi di servizio
Nuovi dispositiviDispositivi Zigbee scoperti di recente — mostra ID dispositivo, produttore e modello dopo il pairing
Variabili personalizzate
GWname (string)Nome del topic MQTT Tasmota del gateway Zigbee (si trova in Configuration → MQTT → Topic)

Tasmota - Zigbee GW

Lettura (modulo)
MQTTPUBLISH("cmnd/" + GWname+ "/ZbInfo", "");
Scrittura (modulo)
if (St = 0, count := NaN, if (isnan(count), count := 0) )
Listener
if INDEXOF(RECEIVEDMSG.Topic, "SENSOR") > 0
    var ModelId := PARSEJSON(RECEIVEDMSG.Payload, "ZbReceived." + ID + ".ModelId", true);
    var Manufacturer := PARSEJSON(RECEIVEDMSG.Payload, "ZbReceived." + ID + ".Manufacturer", true);
    if !ISNULL(Manufacturer) and !ISNULL(ModelId)
    	new := new + ID + " - " + Manufacturer + " (" + ModelId + ")";
    	ID := "";
    	count := count +1;
    end
end

if INDEXOF(RECEIVEDMSG.Topic, "RESULT") > 0
	if PARSEJSON(RECEIVEDMSG.Payload, "$.ZbState.JoinStatus", true) = 1
		ID := PARSEJSON(RECEIVEDMSG.Payload, "$.ZbState.ShortAddr");
	end
end
Attributi di servizio
New devices
new
Dispositivi trovati Variabile Solo lettura

Contatore dei dispositivi Zigbee accoppiati con successo — si incrementa durante Permit Join quando un nuovo dispositivo si unisce

numeric
Attributi di servizio
Nuovi dispositiviDettagli del dispositivo accoppiato — ID, produttore e modello dei dispositivi Zigbee scoperti

Dispositivi trovati

Lettura
Va := count
Attributi di servizio
New devices
new
Permit Join Interruttore

Interruttore modalità pairing Zigbee — abilita una finestra di 60 secondi per l'ingresso di nuovi dispositivi nella rete

boolean
Valori / Stati: ON · OFF

Permit Join

Scrittura stato interruttore
if St = 1
	MQTTPUBLISH("cmnd/" + GWname+ "/ZbInfo", "");
	new := "";
	ID := "";
end

MQTTPUBLISH("cmnd/" + GWname+ "/ZbPermitJoin", tostring(St));
Listener
if INDEXOF(RECEIVEDMSG.Topic, "RESULT") > 0
    var Status := PARSEJSON(RECEIVEDMSG.Payload, "ZbState.Status", true);
    if Status = 20
        St := 0;
    elseif Status = 21
        St := 1;
    end
end

if (St = 0, count := NaN, if (isnan(count), count := 0) )
Connessione: Packet Parser → MQTT
Possibili miglioramenti (2)
  • Zigbee Device List — Lists all paired devices with short/IEEE addresses. Could provide a device inventory view.
  • Zigbee Network Configuration — PanID, ExtPanID, channel, encryption keys. Could expose as service attributes.

Fonti