Aqara LED Bulb T2: Zigbee2MQTT Setup for Home Assistant

The Aqara LED Bulb T2 (绿米 LED 球泡灯 T2; listed as LED 灯泡 T2 in Aqara’s mainland support material) can use Zigbee or Matter over Thread, one protocol at a time. For Home Assistant, Zigbee2MQTT gives direct access to the supported Zigbee controls, while Matter uses a Matter controller and a Thread border router.

Check the exact bulb and regional instructions before pairing. Aqara’s mainland-China documentation specifies Zigbee as the default; other regional versions may start in Thread. A bulb that is not discovered by Zigbee2MQTT is not necessarily missing Zigbee firmware—it may simply be in another mode, outside joining mode, or unsupported by an older device definition.

Zigbee and Matter over Thread

Changing the protocol changes the network and integration used by the bulb. It can also clear settings and require pairing again. Choose the route before building scenes and automations around its entity IDs.

Zigbee mode with direct Zigbee2MQTT control

In Zigbee mode, a supported T2 can join your own coordinator and appear in Home Assistant through MQTT. No Aqara hub is part of that route. Use the device page for the exact base and colour variant, rather than assuming every T2 has the same capabilities.

The hub-free Zigbee guide covers the coordinator and discovery setup.

Matter over Thread mode

In Thread mode, the bulb uses Matter for application control. Home Assistant needs its Matter integration and server, and the Thread network needs a working border router. A Thread border router is a network path, not a replacement for the Matter controller.

Prepare the bulb for Zigbee pairing

Use the regional T2 support page and manual for your bulb. The mainland-China FAQ documents protocol choice, reset behaviour, and the Zigbee default for that version. Do not apply one market’s default to every E26, E27, and GU10 unit.

Step 1: Check the current mode and model

Read the model on the bulb or packaging and check its matching Zigbee2MQTT support page. If it is already in Zigbee mode, try the documented joining procedure before assuming that an app or firmware installation is required.

If you previously commissioned it through Matter, it may still be in Thread mode. Use the relevant app/manual workflow to change protocols. Bluetooth may be used during that workflow; that does not make Bluetooth the bulb’s normal lighting-control network.

Step 2: Change protocol if needed

In Aqara Home, add the bulb using the nearby-device workflow and choose the protocol when offered. For the mainland version, Aqara says a bulb already on a network must first be reset with five power cycles before choosing the other protocol during addition. Wait for the transition to finish; it clears the old protocol’s settings. The app’s menus and default protocol can differ for an imported bulb.

Where a mode change is required, follow the Aqara Home pairing instructions for the exact regional version and choose Zigbee. Let the operation finish. Do not interrupt the bulb’s power during an indicated firmware or mode transition.

Aqara documents that protocol switching clears the previous protocol’s configuration. Plan to recreate its pairing and any affected automation references rather than expecting both networks to keep controlling it simultaneously.

Step 3: Reset the previous network association

Use the reset sequence from the bulb’s own instructions, distinguishing a network reset from a full factory reset. The mainland FAQ describes five power cycles for reset and ten for a full factory reset; verify the procedure for your version before using those numbers.

If the bulb was joined to an Aqara Zigbee hub, remove that association as required before pairing it to your own coordinator. Deleting an unrelated app account or other devices is not part of this task.

Step 4: Join your coordinator

1. Enable joining in the Zigbee2MQTT frontend.
2. Put the bulb into joining mode using the correct procedure.
3. Wait for the interview and configuration to finish.
4. Give it a friendly name and test on/off, brightness, and any colour controls that appear.

Use a current Zigbee2MQTT release with the matching device definition. An arbitrary minimum version quoted for the whole T2 family is less useful than checking the exact model. If pairing fails, inspect mode, reset status, power, coordinator coverage, and the log.

Controls available in Zigbee2MQTT

Check Exposes on the paired device. The standard light entity covers routine lighting control; extra settings may appear as separate controls or require MQTT commands. The app’s complete feature set is not automatically the Home Assistant feature set.

Core light controls

For the documented colour T2 E27, brightness uses 0–254 and colour temperature uses 111–500 mired; larger mired values are warmer. MQTT accepts a transition in seconds, so {"brightness":156,"transition":3} requests a three-second brightness change. Home Assistant’s light controls use their own display scales, so do not enter a raw Zigbee brightness value into a percentage field.

Supported colour models expose on/off, brightness, colour temperature, and XY colour. The T2 E26 and T2 E27 pages describe those variants; use the GU10 page for that base.

Test power-on behaviour after a deliberate, safe power cycle so you know how the room will behave after an outage. Use the lamp and circuit types permitted by the manufacturer; a conventional dimmer is not automatically suitable for a smart bulb.

Effects and colour settings

The E27 device definition lists breathing, candlelight, fading and flash, plus off to disable an effect. effect_speed accepts 0–100, and effect_colors accepts one to eight RGB colour objects. For example, publish {"effect":"breathing","effect_speed":25} to zigbee2mqtt/YOUR_BULB/set after checking that the same controls appear on your model. Start with one effect before adding a colour sequence.

The supported colour variants expose dynamic effects and effect settings in Zigbee2MQTT. Choose only values listed for your device, and confirm the visible result. Some advanced controls may not be presented in Home Assistant’s ordinary light card.

Do not substitute a settings format from another Aqara light or a community converter. Check the exact device page’s accepted values before sending an effect or colour-array command.

Optional custom integrations

Basic Zigbee2MQTT control does not require HACS. If a community integration offers a useful interface for an advanced setting, check its supported models, maintenance, and dependencies first.

A community project should not be described as an official Aqara integration without evidence. Keep a working basic control path while evaluating an optional tool, and remove duplicate automations if both tools manage the same bulb.

Set up Matter over Thread

Choose this route if you want the bulb on a Matter/Thread network. Home Assistant’s Matter documentation covers commissioning and sharing a device already added to another ecosystem. Switching from Zigbee requires changing the bulb’s protocol and pairing again.

Use a working Thread border router

Confirm that the border router is connected to the local network and that the phone used for commissioning has the required Thread credentials. A product name alone is not enough: some Apple TV variants have Thread and others do not. A generic USB Zigbee coordinator is not a Thread border router unless explicitly configured for that role.

Home Assistant Green needs appropriate external Thread infrastructure; do not assume it has a built-in Thread radio. An Aqara border router is one option, but an Aqara hub is not a universal requirement for Matter control. The M100 guide covers that option.

If commissioning fails

• Check that the bulb is in Thread/Matter joining mode and that the pairing code is for that state.
• Confirm the phone’s Thread credentials and the intended border router.
• Keep Home Assistant and the border router on the same LAN for the initial test, with local IPv6 and multicast working.
• If already commissioned elsewhere, use that ecosystem’s Matter sharing flow to generate a new code.
• Read the failure in the Companion app or Matter Server log before resetting again.

Repeated resets do not fix missing Thread credentials or blocked IPv6. Test one bulb before commissioning the rest of a room.

Choose by the controls you need

Use Zigbee when you already have a suitable coordinator and want the device-specific controls exposed by Zigbee2MQTT. Use Matter over Thread when you want that network and its sharing workflow, and its available lighting controls meet your needs.

Other dual-protocol devices have their own differences. The FP300 setup guide and FP2/FP300 comparison illustrate why a protocol choice should be made for the exact product rather than the whole brand.

Check local operation

Direct Zigbee control goes through your coordinator and MQTT broker. Matter commands use the local IP network through the Thread border router. Neither route requires a vendor cloud relay for every light command.

Initial setup, app services, firmware downloads, and remote phone access have separate requirements. After setup, test the lighting controls and automations during a controlled WAN outage. A quiet DNS log alone does not prove that all traffic is blocked or that every function works offline.