A secondhand Hue bulb, an IKEA Trådfri light pulled off an old deCONZ setup, or a device stuck half-joined from a failed pairing attempt has one thing in common: it won’t join Zigbee2MQTT until something wipes its old network credentials. Touchlink is the over-the-air way to do that. This covers what it actually does, which devices support it, and how to run it without accidentally resetting the wrong thing.
When you actually need a Touchlink reset
Any Zigbee device that has already joined a network, whether that’s a Hue Bridge, a previous Zigbee2MQTT install, ZHA, or deCONZ, keeps that network’s credentials in its own memory. It won’t join a second network until those credentials are cleared. Normally that means a manual factory-reset sequence, a specific number of power cycles or a button held for a set number of seconds, per the manufacturer’s instructions.
Touchlink (built on the ZLL, Zigbee Light Link, standard) skips that. It lets Zigbee2MQTT interrogate or factory-reset a compatible device over the air, at close physical range, without needing the device’s original hub or a memorized reset ritual. That matters most for readers buying secondhand Zigbee bulbs, migrating off Hue or deCONZ, or troubleshooting a device that got stuck mid-pairing and now refuses to join anything.
Touchlink only works on devices that implement the Touchlink/ZLL cluster. It is not a general-purpose Zigbee reset tool.
Which devices actually support it
This is the part most guides skip, and it matters more for this site’s readers than the average Zigbee2MQTT user. The official Touchlink documentation lists Philips Hue and IKEA Trådfri devices, some Tuya bulbs, and Namron relays as the working examples. All of them are mains-powered lighting or relay hardware with a Touchlink/ZLL radio stack built in.
Most of the Aqara, Xiaomi, and Tuya sensors, switches, and relay modules covered elsewhere on this site do not implement Touchlink at all. If you’ve got a used Aqara door sensor or a Tuya relay stuck on someone else’s old network, Touchlink will not help. Those devices need their standard physical reset procedure instead, whatever the manufacturer documents for that model.
| Device family | Touchlink support | What to do instead |
|---|---|---|
| Philips Hue bulbs | Yes (most) | N/A |
| IKEA Trådfri bulbs | Yes (most) | N/A |
| Some Tuya bulbs | Yes, check the specific model | N/A |
| Namron relays | Yes | N/A |
| Aqara/Xiaomi sensors, switches, relays | No | Manufacturer’s physical reset sequence |
| Most Tuya sensors, switches, relays (non-bulb) | No | Manufacturer’s physical reset sequence |
Worth knowing: Touchlink operates at very close range, close enough that you’re typically holding the device near the coordinator or its antenna, so proximity is already doing a lot of the targeting work even before you specify anything in the MQTT payload.
Running the reset over MQTT
The Zigbee2MQTT frontend includes a dedicated Touchlink tab with three actions: scan, identify, and factory reset. You don’t strictly need to touch MQTT by hand. Those buttons publish to the same bridge request topics you can call directly, which is what the examples here use. The core command publishes to the factory-reset request topic shown below.
Topic: zigbee2mqtt/bridge/request/touchlink/factory_reset
Payload: {}
Publishing an empty payload tells Zigbee2MQTT to reset the first Touchlink-capable device it finds in range. That’s fine if you’re holding exactly one bulb near the coordinator. It’s a problem if there’s anything else Touchlink-capable powered on nearby, since Zigbee2MQTT has no way to know which one you meant.
The safer approach, and the one worth defaulting to, is targeting a specific device by its IEEE address instead of letting Zigbee2MQTT grab whatever answers first, as shown below.
Topic: zigbee2mqtt/bridge/request/touchlink/factory_reset
Payload: {"ieee_address": "0x00124b00aabbccdd", "channel": 11}
The channel field is optional. Before committing to a reset, run the scan command first. It lists the Touchlink-capable devices currently in range, along with the IEEE address and channel you’d use to target one of them.
Topic: zigbee2mqtt/bridge/request/touchlink/scan
Payload: {}
The scan can take up to a minute, and Zigbee2MQTT can’t talk to your other Zigbee devices while it runs, so don’t start it in the middle of an automation-heavy moment. The frontend’s Touchlink tab runs the same scan and shows the results in a list you can act on directly.
Isolate the target before you reset anything
An untargeted factory-reset request resets the first responding device, not necessarily the one in your hand. If anything else Touchlink-capable is powered on nearby, either power it off or physically move it out of range before running an untargeted reset.
This is the single most common way this feature goes wrong in practice: someone runs the untargeted command in a room with more than one Hue or Trådfri bulb still installed, and Zigbee2MQTT resets whichever one happened to answer first, not the secondhand unit they were trying to fix. Targeting by IEEE address avoids the problem entirely, but only if you already know the address, which you often won’t for a device that hasn’t joined your network yet. When you don’t have the address, isolating the device physically is the only reliable safeguard.
When the first attempt doesn’t work
If a Touchlink reset succeeds but the device doesn’t drop into pairing mode right away, the documented next step is a single additional power cycle before trying to join it again.
That said, reports across several long-running GitHub issue threads on the Zigbee2MQTT repository (spanning multiple years, not one isolated complaint) describe reset failures that depend on the specific coordinator or radio in use, resets that don’t reliably stick on the first attempt, and the wrong-device-grabbed problem in rooms with multiple bulbs. The pattern across those threads is consistent. Touchlink is a real and useful first attempt, but it is not a guaranteed fix. If a reset appears to succeed and the device still won’t join, the physical multi-press reset sequence for that specific model is the fallback, not a Touchlink retry loop.
Re-pairing into Zigbee2MQTT
Once a device has been successfully reset, whether by Touchlink or the manual method, it should enter pairing mode on its own or after that one extra power cycle. From there it joins Zigbee2MQTT the same way any new device does. Put the network into permit-join mode and wait for the device to appear in the frontend or the MQTT bridge log. Our ghost-device troubleshooting guide covers what to do if a device appears to join but then behaves like a ghost entry that won’t fully interview or won’t remove cleanly.
If the device previously acted as a Zigbee router (most mains-powered Hue and Trådfri bulbs do), expect it to take on that role again once it rejoins, which is relevant to how you plan mesh coverage around it. Our guide on Zigbee router vs end-device roles goes into how those roles actually work across brands.
Where this fits in a mixed-brand mesh
Readers running an Aqara- or Xiaomi-heavy Zigbee2MQTT setup sometimes end up with a handful of secondhand Hue or IKEA bulbs, either bought cheap specifically to shore up router coverage, or inherited from an earlier hub-based setup being retired. Touchlink is exactly the tool that makes reusing that hardware practical instead of requiring a full teardown of whatever network it was last part of. Once reset and rejoined, those bulbs sit on the same mesh as Aqara/Xiaomi end devices without any brand-specific handling required on the Zigbee2MQTT side.
I think Zigbee2MQTT would be better served by making the untargeted, first-responder reset behavior opt-in rather than the default. It’s a reasonable shortcut when there’s only one Touchlink-capable device powered on, but it’s a quiet landmine in any room that already has working bulbs from the same families.
FAQ
Does Touchlink reset work on Aqara or Xiaomi devices?
No, in almost all cases. Aqara and Xiaomi Zigbee sensors, switches, and relay modules don’t implement the Touchlink/ZLL cluster. Use each device’s standard physical reset sequence instead.
Why did Touchlink reset the wrong bulb in the room?
An untargeted factory_reset request (empty payload) resets whichever Touchlink-capable device responds first, not necessarily the one you meant. Target the specific device by IEEE address, or isolate it physically, to avoid this.
What do I do if a Touchlink factory reset doesn’t work?
Try one additional power cycle before retrying. If it still fails, community reports suggest this can be coordinator- or radio-dependent. Fall back to the device’s manual physical reset procedure rather than repeating Touchlink attempts indefinitely.
Can I use Touchlink on a device still joined to another Zigbee2MQTT or ZHA network?
Yes. Clearing a device’s existing network credentials without needing the original controller in hand is exactly the main use case for this feature.
Is there a frontend button for this, or does it require raw MQTT?
The Zigbee2MQTT frontend has a dedicated Touchlink tab with scan, identify, and factory-reset actions, so you don’t need to publish raw MQTT for the common cases. The MQTT bridge request topics still exist and are useful for scripting or when you want to target a specific IEEE address precisely. Note this is the Zigbee2MQTT frontend, not a control inside the Home Assistant dashboard itself.
What this is based on
This is written from Zigbee2MQTT’s own Touchlink documentation and cross-referenced against several GitHub issue and discussion threads reporting real-world reset outcomes across different coordinators. No specific bulb or relay was reset on a test bench for this article, and none of the worked examples above should be read as a bench-verified result. If you’re choosing a coordinator for a network that will need to absorb secondhand hardware like this, our Sonoff ZBDongle-E vs ZBDongle-P comparison and ZHA vs Zigbee2MQTT for Aqara devices are worth reading alongside this one before you commit to a setup.