TapHome

Zigbee2Tasmota Gateway

Packet Parser → MQTT
Submitted by
Last updated: 03. 2026
Zigbee2Tasmota Gateway

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:

GatewayProcessorZigbee RadioConnectivityNotes
eWeLink ZB-GW03 (recommended)ESP32EFR32 (EZSP)Ethernet + ZigbeeAvailable with Tasmota pre-installed
Sonoff ZBBridgeESP8266EFR32 (EZSP)WiFi + ZigbeeRequires manual Tasmota flashing
Sonoff ZBBridge ProESP32CC2652P (ZNP)WiFi + ZigbeeUp 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.

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

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:

ParameterDescriptionExample
MQTT Broker IP AddressIP of your MQTT broker192.168.1.10
MQTT Broker PortBroker port (default 1883)1883
Gateway nameTasmota MQTT topic from Configuration → MQTT → Topictasmota_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:

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

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

Zigbee2Tasmota Gateway Module
Service Attributes
New devicesRecently 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)

Tasmota - Zigbee GW

Read (module)
MQTTPUBLISH("cmnd/" + GWname+ "/ZbInfo", "");
Write (module)
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
Service Attributes
New devices
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 devicesPaired device details — ID, manufacturer, and model of discovered Zigbee devices

Devices Found

Read
Va := count
Service Attributes
New devices
new
Permit Join Switch

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

boolean
Values / States: ON · OFF

Permit Join

Write switch state
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) )
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.

Sources