---
title: "Zigbee2Tasmota Gateway"
description: "Bridge Zigbee devices to TapHome via MQTT with a Tasmota-flashed gateway. Manages pairing, device discovery and coordinates all Z2T device templates."
url: "https://taphome.com/en/compatibility/zigbee2tasmota-gateway/"
language: en
lastmod: 2026-03-29
generator: hugo
ai:
  topics: ["mqtt","zigbee","gateway","tasmota","wifi","ethernet"]
  questions: ["How to integrate Zigbee devices with TapHome using Tasmota?","What hardware do I need for a Zigbee2Tasmota gateway?","How to pair Zigbee devices with TapHome via Tasmota?","How to find the Zigbee Device ID after pairing?","What is the difference between eWeLink ZB-GW03 and Sonoff ZBBridge?","How to set up MQTT for Zigbee2Tasmota gateway in TapHome?"]
---

# Zigbee2Tasmota Gateway

Communication: Packet Parser → MQTT

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

> 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

Zigbee2Tasmota (Z2T) is a lightweight Zigbee-to-MQTT bridge running on ESP8266/ESP32 microcontrollers with an integrated Zigbee radio module. It enables TapHome to communicate with Zigbee devices over your local MQTT broker — no cloud connection required.

This gateway template is the **prerequisite for all Zigbee2Tasmota device templates**. It must be imported first, before adding any Zigbee device templates. The gateway handles device pairing and provides a Permit Join switch and a Devices Found counter in TapHome.

## Supported gateway hardware

The following Zigbee coordinators are compatible with Zigbee2Tasmota:

| Gateway | Processor | Zigbee Radio | Connectivity | Notes |
|---------|-----------|-------------|--------------|-------|
| **eWeLink ZB-GW03** (recommended) | ESP32 | EFR32 (EZSP) | Ethernet + Zigbee | Available with Tasmota pre-installed |
| **Sonoff ZBBridge** | ESP8266 | EFR32 (EZSP) | WiFi + Zigbee | Requires manual Tasmota flashing |
| **Sonoff ZBBridge Pro** | ESP32 | CC2652P (ZNP) | WiFi + Zigbee | Up to 128 devices, requires flashing |

Other compatible hardware includes Tube's Ethernet Zigbee Gateway (EFR32-based) and custom DIY builds using ESP32 with CC2530/CC2652 modules.

> [!TIP]
> The eWeLink ZB-GW03 is recommended for its Ethernet connectivity (more reliable than WiFi) and availability with Tasmota pre-installed — no flashing needed.

## Configuration

### Setting up the Tasmota gateway

1. Flash [Tasmota firmware](https://tasmota.github.io/docs/Getting-Started/) on your Zigbee coordinator (skip if pre-installed)
2. Connect the gateway to your network via the Tasmota web UI
3. Navigate to **Configuration** → **Configure MQTT** and set:
   - **Host:** your MQTT broker IP (e.g., `192.168.1.10`)
   - **Port:** `1883`
4. Note down the **Topic** name (e.g., `tasmota_XXXXX`) — this is the **Gateway name** parameter needed during template import

> [!TIP]
> TapHome has a built-in MQTT broker — enable it in **Settings** → **Hardware** → **MQTT Broker**. No additional broker software is needed.

### Template import parameters

The gateway template requires 3 parameters:

| Parameter | Description | Example |
|-----------|-------------|---------|
| **MQTT Broker IP Address** | IP of your MQTT broker | `192.168.1.10` |
| **MQTT Broker Port** | Broker port (default 1883) | `1883` |
| **Gateway name** | Tasmota MQTT topic from Configuration → MQTT → Topic | `tasmota_XXXXX` |

After import, the module subscribes to `tele/{GWname}/#` and two devices appear: **Permit Join** and **Devices Found**.

## Device capabilities

### Pairing Zigbee devices

The **Permit Join** switch controls the gateway's pairing mode:

1. Turn on **Permit Join** in TapHome — this publishes a `ZbPermitJoin` command to open a 60-second pairing window
2. Start the pairing procedure on your Zigbee device (typically hold the reset button for 5 seconds until the LED blinks)
3. Watch the **Devices Found** counter — it increments when a new device successfully joins the network
4. Check the **New devices** service attribute on the gateway to see the paired device's ID (e.g., `0x1234`), manufacturer, and model
5. The pairing mode deactivates automatically after the timeout

The Device ID (short address like `0x1234`) displayed in the service attributes is needed when importing device-specific templates.

### Device monitoring

The gateway module polls `ZbInfo` every hour to refresh information about all paired Zigbee devices. The **New devices** service attribute shows details of recently discovered devices including their Zigbee short address, manufacturer, and model identifier.

### Additional capabilities

The Tasmota Zigbee gateway also supports listing all paired devices (`ZbStatus`), network configuration viewing (`ZbConfig` — PanID, channel, encryption keys), device naming, group management, and direct device-to-device binding. These diagnostic and management capabilities can be added in a future template update.

## Supported Zigbee device templates

After pairing a device, import the corresponding device-specific template. Each device template requires 4 parameters: MQTT Broker IP, Port, Gateway name (same as the gateway), and the Device ID from pairing.

Available Zigbee2Tasmota device templates:

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

## Troubleshooting

### Gateway not connecting to MQTT broker

1. Verify the Tasmota gateway is connected to the network (check the Tasmota web UI)
2. Confirm the MQTT broker IP and port match between the Tasmota MQTT configuration and the TapHome template import parameters
3. Check that the MQTT broker is running and accessible on the specified port

### Permit Join not finding devices

1. Ensure the Zigbee device is in pairing mode — most devices require holding a button for 5+ seconds
2. Check that the Permit Join switch is ON in TapHome before starting the device pairing procedure
3. Move the Zigbee device closer to the gateway during initial pairing (within 2-3 meters)
4. Some devices require a factory reset before they can pair with a new coordinator

### Device ID not appearing

1. After successful pairing, check the **New devices** service attribute on the gateway module for the device ID, manufacturer, and model
2. If the service attribute is empty, try toggling Permit Join OFF and ON again, then re-pair the device
3. The Device ID can also be found in the Tasmota console (`ZbStatus` command) via the gateway's web UI

> [!WARNING]
> The Zigbee radio channel should not overlap with your Wi-Fi channel. For best results, use Zigbee channels 15, 20, or 25 which have minimal Wi-Fi interference. Check the current channel with the `ZbConfig` command in the Tasmota console.

## Available devices 2

These devices appear in TapHome after import.

Zigbee2Tasmota Gateway Module

Service Attributes

|             |                                                                                             |
|-------------|---------------------------------------------------------------------------------------------|
| New devices | Recently discovered Zigbee devices — shows device ID, manufacturer, and model after pairing |

Custom Variables

|                   |                                                                                       |
|-------------------|---------------------------------------------------------------------------------------|
| `GWname` (string) | Tasmota MQTT topic name of the Zigbee gateway (found in Configuration → MQTT → Topic) |

Read (module)

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

Write (module)

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

Service Attributes

New devices

```taphome
new
```

Devices Found Variable Read-only

Counter of successfully paired Zigbee devices — increments during Permit Join when a new device joins

numeric

Service Attributes

|             |                                                                                  |
|-------------|----------------------------------------------------------------------------------|
| New devices | Paired device details — ID, manufacturer, and model of discovered Zigbee devices |

Read

```taphome
Va := count
```

Service Attributes

New devices

```taphome
new
```

Permit Join Switch Read and write

Zigbee pairing mode switch — enables a 60-second window for new devices to join the network

boolean

Values / States: ON · OFF

Write switch state

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

**Connection:** Packet Parser → MQTT

Possible improvements (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.

## Import parameters

Enter these values when you import the XML.

| Asked in the app                                            | Default         |
|-------------------------------------------------------------|-----------------|
| Mqtt Broker IP address                                      | `192.168.0.1`   |
| Mqtt Broker port                                            | `1883`          |
| Gateway name (Tasmota->Configuration->MQTT->Topic) | `tasmota_XXXXX` |

## Sources

- 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

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