A secondhand Hue bulb may still remember its previous Zigbee network. If you no longer have the old bridge, Touchlink can factory-reset a compatible bulb over the air so you can pair it with Zigbee2MQTT. It also helps when a supported light has become difficult to reset by its usual controls. Check the device and coordinator support first: this is a lighting commissioning feature, not a reset command that works on every Zigbee product.
When you actually need a Touchlink reset
A Zigbee device normally belongs to one network at a time. Moving it from a Hue Bridge, deCONZ, ZHA or another Zigbee2MQTT installation generally means making it leave its old network or following its factory-reset and pairing instructions. If the original controller still works, removing the device through that controller may be the simplest route. For an orphaned light, the manufacturer’s button or power-cycle sequence is the usual fallback.
Touchlink comes from Zigbee Light Link (ZLL) commissioning. Its inter-PAN exchanges let compatible devices communicate without already sharing a network. Zigbee2MQTT uses this to scan, identify and reset nearby hardware through the coordinator. A successful reset clears the target’s existing setup; it does not copy its old automations, groups or bindings into the new network.
The target must implement and enable Touchlink, and the coordinator driver must support the operation. Ordinary Zigbee pairing support does not establish Touchlink support.
Which devices actually support it
The official Touchlink guide lists most Philips and IKEA devices, some Tuya bulbs and Namron relays as examples. Treat those as families to investigate, rather than a guarantee for every model or firmware. For an Aqara door sensor or an unidentified Tuya relay, start with that exact model’s reset instructions instead of assuming a shared brand makes Touchlink available.
| Device family | What is documented | What to check |
|---|---|---|
| Philips Hue lighting | Many models support Touchlink; some also support reset by serial number | The exact bulb’s device page and firmware |
| IKEA Trådfri lighting | Many devices are among the documented examples | Model-specific reset and commissioning instructions |
| Tuya bulbs | Some models support it | Exact model and enabled Touchlink support |
| Namron relays | Included among the official examples | The particular relay’s documentation |
| Aqara/Xiaomi sensors, switches and relays | No blanket family support established by the Touchlink guide | Use the exact model’s physical reset procedure unless Touchlink is documented |
| Other Tuya sensors, switches and relays | A Tuya label alone does not establish support | Use the manufacturer’s reset procedure unless the exact device supports Touchlink |
Coordinator support matters just as much. At this review on 25 October 2026, Zigbee2MQTT documents full Touchlink support for Texas Instruments zStack adapters and partial support for Silicon Labs EmberZNet adapters. Its guide records an Ember scan-response problem with some firmware versions, while noting that Philips Hue reset is unaffected by that particular problem. Other adapter drivers are not currently listed as supported for Touchlink. A failed scan on one of these combinations is not proof that the bulb lacks the feature.
Keep the target very close to the coordinator antenna. The guide gives roughly 10 cm as typical, with stronger adapters sometimes reaching about a metre. That is an operating range, not a dependable boundary protecting other lights in the room. Some devices disable Touchlink a few minutes after power-on; a power cycle may reopen that commissioning window.
Running the reset over MQTT
The Zigbee2MQTT frontend has a Touchlink tab, so raw MQTT is optional. The examples below use the default zigbee2mqtt base topic; substitute your configured base topic if different. Start with a scan, confirm which physical light responds to identify, and only then reset it.
Topic: zigbee2mqtt/bridge/request/touchlink/scan
Payload: {}
Read the result on zigbee2mqtt/bridge/response/touchlink/scan. Each found entry supplies an ieee_address and channel. The scan can interrupt ordinary Zigbee communication for up to a minute, so choose a time when a temporary pause will be acceptable. Do not treat the result as an exhaustive inventory: the released herdsman scan implementation handles one response per scanned channel.
Use the returned address and channel to identify the target. The address below is an example, not a value to copy for your bulb.
Topic: zigbee2mqtt/bridge/request/touchlink/identify
Payload: {"ieee_address": "0x00124b00aabbccdd", "channel": 11}
Once the expected bulb identifies itself, use the same two values for the targeted reset.
Topic: zigbee2mqtt/bridge/request/touchlink/factory_reset
Payload: {"ieee_address": "0x00124b00aabbccdd", "channel": 11}
For this targeting method, channel is required along with ieee_address. In Zigbee2MQTT 2.14.2, a reset request missing either field takes the untargeted first-found-device path. An address on its own does not safely target the reset.
An untargeted request is available when you have isolated the device and cannot identify it first:
Topic: zigbee2mqtt/bridge/request/touchlink/factory_reset
Payload: {}
This starts a scan and resets the first suitable device found. It does not know which bulb you intended to reset. The corresponding response topic is zigbee2mqtt/bridge/response/touchlink/factory_reset; also watch the frontend and the light itself before assuming the reset achieved the expected result.
Isolate the target before you reset anything
Before an untargeted reset, power off other Touchlink-capable devices or make sure they are out of range. Close proximity to the intended bulb alone is not enough to choose it.
For targeted resets, copy both values from a scan and identify the physical light before proceeding. This reduces the risk of selecting a working bulb by mistake, but the values still have to belong to the device you intend to erase. If you cannot distinguish the target reliably, isolate it or use its documented physical reset method. Avoid repeatedly firing reset requests at a room full of installed lights.
Some Hue models offer another route when scanning is unavailable: the frontend’s Philips Hue reset action can use the serial number printed on the light. The Hue white A60 device page documents that action and its separate MQTT API. It is a Philips-specific option, not a replacement payload for arbitrary Touchlink devices.
When the first attempt doesn’t work
If a reset appears successful but the light does not enter pairing mode, the Touchlink guide says it may need one additional power cycle. Also check whether Touchlink was enabled during the attempt and whether your adapter and firmware support the operation. An empty scan result and a successful reset request are different observations; neither alone proves the device is ready to join.
Use the exact model’s physical reset sequence if the supported Touchlink route still fails. That is more useful than an indefinite reset loop, especially with an adapter combination that has a documented scan limitation. If you report a problem upstream, include the light model, adapter driver, firmware and Zigbee2MQTT version so that the report can be reproduced.
Re-pairing into Zigbee2MQTT
After the reset, enable permit-join for a short pairing window and follow the light’s pairing instructions. Check that it appears and completes its interview in the frontend or bridge log, then close joining. Our ghost-device troubleshooting guide covers entries that appear to join but fail to interview or remove cleanly.
A mains-powered bulb that operates as a router will normally resume that role on the new network. Confirm the device type rather than assuming every powered light is a useful router for every sensor. The guide to Zigbee router and end-device roles explains what that means for coverage.
Where this fits in a mixed-brand mesh
Touchlink can help reuse supported Hue or IKEA lighting alongside Aqara, Xiaomi and other Zigbee devices on one Zigbee2MQTT network. Resetting gets the light ready to join; it does not guarantee reliable routing for every other brand or equal feature support across firmware variants. Keep the normal mesh checks in mind: power, placement, interference and device-specific compatibility.
For routine use, the targeted scan-identify-reset sequence is easier to check than a first-found reset. Keep the untargeted option for a controlled setup with the other compatible devices switched off.
FAQ
Does Touchlink reset work on Aqara or Xiaomi devices? Do not assume so from the brand or Zigbee logo. Use the model’s normal physical reset instructions unless its Touchlink support is specifically documented.
Why did Touchlink reset the wrong bulb? An untargeted request resets the first suitable device found. In the reviewed release, an incomplete address/channel payload also takes that path. Isolate the target or supply both scan values and identify it first.
What if a Touchlink factory reset does not work? Check the target’s commissioning window and coordinator support. If it reset but will not pair, try the documented additional power cycle. Then use that model’s physical reset procedure rather than repeating commands indefinitely.
Can it reset a light joined to a different network? Yes, when the target and adapter support the operation. Touchlink commissioning does not require the two devices to be members of the same network.
Do I need raw MQTT? No. The Zigbee2MQTT frontend provides the normal Touchlink actions. MQTT is useful for a deliberate, precisely checked request; it is not required just because Home Assistant is involved.
What this is based on
The commands and support limits follow Zigbee2MQTT’s Touchlink documentation, the 2.14.2 bridge request handling and its bundled herdsman 10.10.0 Touchlink implementation. These are documented and source-checked procedures, not results from a physical reset test. For coordinator and platform choices, see the Sonoff ZBDongle-E and ZBDongle-P comparison and ZHA and Zigbee2MQTT comparison for Aqara devices.