Touchlink

Touchlink (or ZLL) is a feature that allows Zigbee devices to communicate, without necessarily being in the same network.

Devices must be physically close to each other, and have Touchlink enabled in their firmware.
Range depends on devices: normally 10cm, but up to 1m on strong adapters.

Example uses:

Identify or reset devices near the coordinator via Zigbee2MQTT
Reset devices via a Touchlink-capable device, e.g. Hue dimmer switch gen 1
Setup device-to-device binding (e.g. remote to light) without involving the coordinator and Zigbee2MQTT

Support

Coordinator

Texas Instruments adapters (zStack, CCxxxx) are fully supported.

Silicon Labs adapters (EmberZNet, EFR32xxxx) are partially supported.
2026-03-18: The Scan operation does not produce responses with some firmware versions. Philips Hue reset is not affected. Under investigation

Other adapters/drivers are currently not supported.

Devices

Compatible devices expose the Touchlink cluster, which includes most Philips and IKEA devices, some Tuya light bulbs, Namron relays and more.

Warning

Some devices may disable Touchlink after a few minutes! (security measure)
Power-cycle the device to make sure it's active.

Tips

All commands below can also be executed via the frontend Touchlink tab.

Scan

Scan for Touchlink-enabled devices near the coordinator.
The outcome of this scan can be used later, to choose which device to reset or identify.

This can take up to 1 minute. This is a disruptive operation, during the scan, communication with devices is unavailable (be sure to account for that, prefer times of lesser usage if necessary).

To scan, send an MQTT message to zigbee2mqtt/bridge/request/touchlink/scan with an empty payload.

The response will be sent to zigbee2mqtt/bridge/response/touchlink/scan, example payload: {"data":{"found":[{"ieee_address": "0x12345678", "channel": 12}, {"ieee_address": "0x12654321", "channel": 24}]},"status":"ok"}.

Identify

Identify a nearby device via Touchlink (e.g. bulb blinking).

Send an MQTT message to zigbee2mqtt/bridge/request/touchlink/identify with payload e.g. {"ieee_address": "0x12345678", "channel": 12}
(Use scan from above to determine ieee_address and channel).

Factory reset device

Factory reset nearby devices through Touchlink. Demonstration: video

If the device does not enter pairing mode after one of the following methods, it may additionally need one power-cycle.

To pair the device again, permit joining after the reset is done.

Any device

Without targeting a specific device, it is advised to power-off devices that should not be reset or ensure they are out of range (the first device found becomes the target). Send an MQTT message to zigbee2mqtt/bridge/request/touchlink/factory_reset with an empty payload.

Zigbee2MQTT will start scanning. After some time the device will identify itself and reset.