Aqara LED Bulb T2: Zigbee2MQTT Setup for Home Assistant
The Aqara LED Bulb T2 (绿米 LED 球泡灯 T2) is a dual-protocol bulb. It can run as a Zigbee device or as a Thread/Matter device, but not both at once. That’s a useful design, though it also means the setup path is less obvious than it first looks.
If you’ve tried to add the T2 directly to a Zigbee coordinator and got nothing, you’ve hit the most common issue. The bulb ships with Bluetooth/Thread firmware active by default, and Zigbee has to be switched on explicitly through the Aqara Home app before the bulb will join a Zigbee mesh. Nothing about that is in Aqara’s English documentation. I found the correct sequence through a combination of community forum threads and GitHub issue tracking.
There is good news. As of Zigbee2MQTT 2.7.2 (January 2026), the T2 has native support under model ID lumi.light.agl003. If you’ve read older guides that tell you to use an external converter file, that step is gone. This article covers the current setup, both the Zigbee path and the Thread/Matter path, and explains which one makes sense for different setups.
The T2 is available in E26 (US/Japan/Canada), E27 (EU/UK/AU), and GU10 (EU) variants. All three run the same Zigbee firmware and the same Zigbee2MQTT device definition, so the steps below apply regardless of which socket you’re working with. If you want the broader picture of running Aqara Zigbee devices without an Aqara hub, my hub-free Zigbee setup guide covers coordinator picks and the Z2M baseline.
Two ways to run the Aqara T2 locally, Zigbee vs Thread
Before touching any coordinator or controller, you need to decide which mode you’re putting the bulb into. The choice sticks. Switching modes later requires going back through the Aqara app and repeating the firmware install step.
Zigbee mode, full feature access, direct Z2M control
In Zigbee mode the bulb joins your Zigbee2MQTT coordinator the same way any other Zigbee device does. You get the complete feature set, including on/off, brightness (0-254), color temperature from warm to cool white (111-500 mired), XY color space, five dynamic effects (breathing, candlelight, fading, flash, and a custom color array of up to 8 colors), effect speed control, transition curves, and configurable power-on behavior.
This is the path for anyone who already has a Zigbee coordinator running and wants maximum integration depth. Automations and scripts in Home Assistant control everything locally, with no cloud traffic involved once the bulb is paired.
Thread/Matter mode, hub-free, Matter-native
In Thread/Matter mode the T2 pairs directly with any Matter-compatible controller, including Apple Home, Google Home, Amazon Alexa, or Home Assistant’s Matter integration. No Aqara hub required, and local control is fully local. Matter runs on your LAN rather than through a cloud relay.
The trade-off is feature loss. Aqara-specific dynamic effects and hub-based scene integration are not available in Thread/Matter mode. You get standard Matter light controls (on/off, brightness, color temperature), which is enough for most everyday use cases but less than what Zigbee2MQTT exposes.
If your setup already has a Thread border router (Apple HomePod mini, Apple TV 4K, or a Home Assistant Yellow/Green with an optional Thread radio), Thread mode is worth considering, especially if you have non-Zigbee infrastructure. For pure Home Assistant setups with an existing Zigbee coordinator, Zigbee mode gives you more.
Zigbee mode, the required steps before Z2M will see the bulb
This is where people get stuck. The pairing requires four steps in sequence. Skipping any one of them means the bulb won’t appear in Z2M.
Step 1, pair via Bluetooth and install Zigbee firmware
Install the Aqara Home app (绿米 Aqara Home app) on your phone. Open it and add the T2 bulb as a new device. This initial pairing happens over Bluetooth and is used to push the Zigbee firmware image to the bulb.
The app discovers the bulb when it’s powered on and in Bluetooth pairing mode. Follow the in-app steps through to completion. The bulb needs to complete firmware installation before the mode switch works.
Step 2, switch mode to Zigbee in the Aqara Home app
Once the bulb is added, go to its settings in the Aqara Home app and find the mode or protocol option. Switch it from Thread to Zigbee. The app will apply the mode change and the bulb will restart.
Without this step, the bulb’s radio presents as a Thread device and a Zigbee coordinator will not see it regardless of how many times you try to pair.
Step 3, remove the bulb from the Aqara app
After switching to Zigbee mode, delete the bulb from your Aqara Home account. This is not optional. While the bulb remains claimed by the Aqara app, it won’t join a third-party Zigbee network. The removal de-authenticates it and puts it in a state where it can pair to any coordinator.
Step 4, pair to your Zigbee coordinator with Z2M 2.7.2 or later
Put your Zigbee2MQTT coordinator into pairing mode via the Z2M frontend (Settings > Permit join). Then trigger the bulb’s pairing mode by toggling power off and on five times rapidly. The bulb will blink twice slowly to indicate it’s waiting for a network.
Z2M should discover the bulb and identify it as lumi.light.agl003. If you’re on Z2M 2.7.2 or later, no external converter is needed because the device definition is built in. If you’re on an older version, update before pairing. The autogenerated definition that older versions fall back to has known issues including power readings that show as zero.
After pairing, the bulb appears in the Z2M device list and in Home Assistant as a standard light entity.
What Zigbee2MQTT exposes (and what it doesn’t)
Core light controls
The standard light entity covers on/off, brightness, color temperature, and XY color. These map cleanly to Home Assistant’s light platform. Transition support works, so you can set fade duration in automations and scripts.
Power-on behavior is also configurable. You can set whether the bulb returns to its previous state, turns on at full brightness, or stays off after a power cut. This setting is persistent on the bulb and doesn’t depend on Z2M being reachable.
Dynamic effects and custom color arrays
The five effects (breathing, candlelight, fading, flash, and a custom multi-color sequence) are exposed as additional entities in Z2M. Effect speed is adjustable from 1 to 100 percent. For the custom color array effect, you can define up to 8 colors that the bulb cycles through.
These controls appear as select and number entities in Home Assistant alongside the main light entity. Driving them from automations requires calling Z2M MQTT actions or using the entities directly. The standard Home Assistant light.turn_on service handles basic effects, but the custom color array needs MQTT payload calls.
The HACS integration, when to use it
In early 2026, Aqara announced a dedicated Home Assistant HACS integration for the T2 lighting line, covering the T2 bulb, T1M ceiling light, and T1 LED strip. Its purpose is to expose Aqara-specific dynamic effects through a cleaner Home Assistant interface than raw MQTT calls.
If you’re setting up the T2 for the first time with Z2M 2.7.2, you don’t need this integration to get the bulb working. The standard Z2M entities cover everything for normal use. The HACS integration is worth adding if you want to build automations around the custom effects without writing MQTT payloads by hand. Check the Aqara forum thread for current installation status, as it was announced but still gaining community testing coverage as of this writing.
Thread/Matter setup for Home Assistant
If you’ve decided on the Thread/Matter path, you can skip the Aqara app firmware step and the Z2M coordinator entirely.
Requirements, a Thread border router
Thread is a mesh protocol that needs a border router to bridge it to your IP network and to Home Assistant. If you’re using the Matter integration in Home Assistant, you need at least one Thread border router device reachable on your LAN. Options include an Apple HomePod mini, Apple TV 4K (3rd gen or later), a Google Nest Hub (2nd gen), or a compatible Silicon Labs border router.
Home Assistant Yellow and Green boards support Thread natively when paired with an appropriate radio chip. For a deeper look at Aqara’s own Matter-bridging hub option, see my Aqara Hub M100 Matter setup writeup.
Pairing stability tips
The T2 in Thread/Matter mode has a known pairing stability issue with Home Assistant. Some users report needing 5 to 10 attempts before the bulb is discovered during commissioning. The most reliable workaround is to pair the bulb to Apple Home first (if you have an Apple border router), then import it into Home Assistant via the Matter integration’s “add device” flow. Apple’s Thread implementation tends to commission the bulb more reliably on first attempt.
If you’re pairing directly to Home Assistant’s Matter integration, keep the phone running the pairing app close to the bulb and the border router during commissioning. The Thread join process is sensitive to signal quality in the first few seconds.
Once paired, Matter operation is stable. The instability is a commissioning-time issue, not a day-to-day reliability concern.
Practical decision, which mode should you pick?
Here’s how I’d frame the choice.
Go with Zigbee mode if:
– You already have a Zigbee coordinator running (HUSBZB-1, Sonoff Zigbee 3.0 USB Dongle Plus, ConBee III, etc.)
– You want access to effects and color array features via automations
– You want the bulb to integrate into your existing Z2M device ecosystem
– You don’t have a Thread border router
Go with Thread/Matter mode if:
– You have an Apple border router and want reliable Apple Home integration
– You don’t run a Zigbee coordinator and don’t want to add one
– Standard light controls (on/off, brightness, color temp) cover your use case
– You’re building a Matter-first setup and want interoperability across controllers
Both modes give you fully local operation. The difference is feature depth and infrastructure requirements.
Keeping it fully local, cloud traffic check
In Zigbee mode with Z2M, the T2 has no reason to contact Aqara’s servers after initial setup. There’s no cloud API involved. The bulb talks Zigbee to your coordinator, Z2M translates to MQTT, and Home Assistant reads the MQTT topics. No outbound connections from the bulb itself.
The one cloud dependency is the initial firmware installation step via the Aqara Home app. That’s unavoidable for getting Zigbee firmware onto the device, but it’s a one-time step. Once the bulb is removed from the Aqara account and paired to Z2M, the Aqara cloud is out of the picture.
In Thread/Matter mode, local control is also fully local once commissioned. Matter controllers communicate directly over your LAN with no cloud relay. The initial commissioning process for Matter involves a QR code scan and may briefly touch Matter infrastructure servers for device attestation, but ongoing light control is local.
If you want to verify the cloud-quiet behavior, run a DNS query log on your firewall for a few hours after pairing the bulb in Zigbee mode while controlling the light. You won’t see any outbound requests to Aqara or Lumi domains. For a related local-only walk-through that uses the same kind of post-pairing verification, see my FP300 Zigbee2MQTT setup guide.
Frequently asked questions
Does the Aqara T2 bulb work with Zigbee2MQTT without an Aqara hub?
Yes, but you still need the Aqara Home app once during setup to install Zigbee firmware and switch the mode. After that step and removing the bulb from your Aqara account, it pairs to any Zigbee coordinator with no hub involved.
How do I switch my Aqara T2 bulb from Thread mode to Zigbee mode?
Re-add the bulb to the Aqara Home app via Bluetooth, navigate to its settings, and change the protocol mode to Zigbee. The app pushes the mode change to the bulb. Then remove it from the Aqara account before pairing to your coordinator.
Do I still need an external converter for the T2 bulb in Zigbee2MQTT 2.7?
No. Native support for lumi.light.agl003 was added in Z2M 2.7.2 (January 2026). The external converter approach from earlier guides is obsolete. Update Z2M if you haven’t already.
What features does the T2 bulb lose in Zigbee mode compared to using the Aqara app?
You lose Aqara hub-based scene triggers and any effects that are exclusive to the Aqara app interface. Z2M exposes the core effects (breathing, candlelight, fading, flash, custom color array), so the loss is narrower than it sounds. The HACS integration for the T2 line is intended to close this gap further.
Which is better for local control, Zigbee mode with Zigbee2MQTT or Thread mode with Matter?
Both are fully local. The practical difference is that Zigbee mode gives more feature access and integrates with your existing Zigbee infrastructure, while Thread/Matter mode is simpler if you don’t run a Zigbee coordinator and have a Thread border router already. For broader context on choosing between Aqara presence and lighting devices across protocols, my FP2 vs FP300 comparison covers a similar Zigbee-versus-Matter decision in the sensor line.