---
title: "Zigbee2Tasmota Gateway"
description: "Collega dispositivi Zigbee a TapHome tramite MQTT con un gateway Tasmota. Pairing, scoperta dispositivi e coordinamento di tutti i template Z2T."
url: "https://taphome.com/it/compatibility/zigbee2tasmota-gateway/"
language: it
lastmod: 2026-03-29
generator: hugo
ai:
  topics: ["mqtt","zigbee","gateway","tasmota","wifi","ethernet"]
  questions: ["Come integrare dispositivi Zigbee con TapHome usando Tasmota?","Quale hardware serve per un gateway Zigbee2Tasmota?","Come accoppiare dispositivi Zigbee con TapHome tramite Tasmota?","Come trovare il Device ID Zigbee dopo il pairing?","Qual è la differenza tra eWeLink ZB-GW03 e Sonoff ZBBridge?","Come configurare MQTT per il gateway Zigbee2Tasmota in TapHome?"]
---

# Zigbee2Tasmota Gateway

Comunicazione: Packet Parser → MQTT

- [Documentazione Tasmota Zigbee](https://tasmota.github.io/docs/Zigbee/)

> 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

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:

| Gateway | Processore | Radio Zigbee | Connettività | Note |
|---------|-----------|-------------|-------------|------|
| **eWeLink ZB-GW03** (consigliato) | ESP32 | EFR32 (EZSP) | Ethernet + Zigbee | Disponibile con firmware Tasmota preinstallato |
| **Sonoff ZBBridge** | ESP8266 | EFR32 (EZSP) | WiFi + Zigbee | Richiede flash manuale del firmware Tasmota |
| **Sonoff ZBBridge Pro** | ESP32 | CC2652P (ZNP) | WiFi + Zigbee | Fino 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.

> [!TIP]
> 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](https://tasmota.github.io/docs/Getting-Started/) 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

> [!TIP]
> 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:

| Parametro | Descrizione | Esempio |
|-----------|-------------|---------|
| **MQTT Broker IP Address** | IP del broker MQTT | `192.168.1.10` |
| **MQTT Broker Port** | Porta del broker (predefinita 1883) | `1883` |
| **Gateway name** | Topic MQTT Tasmota da Configuration → MQTT → Topic | `tasmota_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:

- [Aqara Temperature, Humidity and Pressure Sensor](https://taphome.com/it/compatibility/zigbee2tasmota-aqara-temperature-humidity-and-pressure-sensor/)
- [Aqara Door and Window Sensor](https://taphome.com/it/compatibility/zigbee2tasmota-aqara-door-and-window-sensor/)
- [Aqara Vibration Sensor](https://taphome.com/it/compatibility/zigbee2tasmota-aqara-vibration-sensor/)
- [Aqara Water Leak Sensor](https://taphome.com/it/compatibility/zigbee2tasmota-aqara-water-leak-sensor/)
- [Aqara Single Switch Module T1 (With Neutral)](https://taphome.com/it/compatibility/zigbee2tasmota-aqara-single-switch-module-t1-with-neutral/)
- [IKEA TRADFRI E1810 Remote](https://taphome.com/it/compatibility/zigbee2tasmota-ikea-tradfri-e1810/)
- [Livarno SMART TS0505B](https://taphome.com/it/compatibility/zigbee2tasmota-livarno-smart-ts0505b/)
- [Moes Smart Switch](https://taphome.com/it/compatibility/zigbee2tasmota-moes-smart-switch/)

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

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

Questi dispositivi compaiono in TapHome dopo l'importazione.

Zigbee2Tasmota Gateway Modulo

Attributi di servizio

|                   |                                                                                                      |
|-------------------|------------------------------------------------------------------------------------------------------|
| Nuovi dispositivi | Dispositivi 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) |

Lettura (modulo)

```taphome
MQTTPUBLISH("cmnd/" + GWname+ "/ZbInfo", "");
```

Scrittura (modulo)

```taphome
if (St = 0, count := NaN, if (isnan(count), count := 0) )
```

Listener

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

```taphome
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 dispositivi | Dettagli del dispositivo accoppiato — ID, produttore e modello dei dispositivi Zigbee scoperti |

Lettura

```taphome
Va := count
```

Attributi di servizio

New devices

```taphome
new
```

Permit Join Interruttore Lettura e scrittura

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

boolean

Valori / Stati: ON · OFF

Scrittura stato interruttore

```taphome
if St = 1
	MQTTPUBLISH("cmnd/" + GWname+ "/ZbInfo", "");
	new := "";
	ID := "";
end

MQTTPUBLISH("cmnd/" + GWname+ "/ZbPermitJoin", tostring(St));
```

Listener

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

## Parametri di importazione

Inserisci questi valori quando importi l'XML.

| Richiesto nell'app                                          | Predefinito     |
|-------------------------------------------------------------|-----------------|
| Mqtt Broker Indirizzo IP                                    | `192.168.0.1`   |
| Mqtt Broker port                                            | `1883`          |
| Gateway name (Tasmota->Configuration->MQTT->Topic) | `tasmota_XXXXX` |

## Fonti

- Tasmota Zigbee Documentation
  
  [tasmota.github.io](https://tasmota.github.io/docs/Zigbee/) 2026-03-29
- Zigbee Compatible Devices Database
  
  2026-03-29
- Supported Zigbee Gateway Hardware
  
  [templates.blakadder.com](https://templates.blakadder.com/ewelink_ZB-GW03.html) 2026-03-29

## 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/)