Aqara T2 bulb Zigbee2MQTT & Home Assistant integration - A How To

absent · August 8, 2025, 6:28pm

After getting my T2 bulbs and trying to get them working in Home Assistant I was a little disappointed to find they weren’t supported by Zigbee2MQTT yet, however it is possible to get them working fully with a little modification.

If you haven’t yet installed the Zigbee firmware on the bulb, pair them via Bluetooth to the Aqara app on your phone, and install the firmware.
In your ZigbeeMQTT installation, create the directory zigbee2mqtt/data/external_converters if it doesn’t exist already.
In that folder, create the file aqara_t2_cct.js containing the linked code: prototype z2m aqara t2 converter · GitHub
Restart ZigbeeMQTT
Put ZigbeeMQTT into Permit Join mode.
Turn the bulb on/off 5 times to put it into pairing mode, the light will slowly pulse.
It should then be discovered by ZigbeeMQTT and appear in the dashboard.
The bulb should now appear as a device in Home Assistant.

More discussions on the bulb’s compatibility with ZigbeeMQTT can be found on its Github:

github.com/Koenkk/zigbee2mqtt

[New device support]: Aqara LED Bulb T2

opened 06:21PM - 04 Feb 25 UTC

ai

new device support

### Link https://eu.aqara.com/en-eu/products/aqara-led-bulb-t2-e27 ### Databas…e entry {"id":40,"type":"Router","ieeeAddr":"0x54ef4410010fcfc5","nwkAddr":34789,"manufId":4447,"manufName":"Aqara","powerSource":"DC Source","modelId":"lumi.light.agl003","epList":[1,21],"endpoints":{"1":{"profId":260,"epId":1,"devId":258,"inClusterList":[5,4,3,0,768,8,6,2820,1794,64704],"outClusterList":[25,10],"clusters":{"genBasic":{"attributes":{"modelId":"lumi.light.agl003","manufacturerName":"Aqara","powerSource":4,"zclVersion":3,"appVersion":27,"stackVersion":27,"hwVersion":1,"dateCode":"20250113"}}},"binds":[],"configuredReportings":[],"meta":{}},"21":{"profId":260,"epId":21,"devId":0,"inClusterList":[12],"outClusterList":[],"clusters":{},"binds":[],"configuredReportings":[],"meta":{}}},"appVersion":27,"stackVersion":27,"hwVersion":1,"dateCode":"20250113","zclVersion":3,"interviewCompleted":true,"meta":{},"lastSeen":1738692849080} ### Zigbee2MQTT version 2.1.0 ### Comments It supports both Zigbee and Thread. User will need Aqara Home app to switch lamp mode to Zigbee. ### External definition ```shell Autogenerated: const m = require('zigbee-herdsman-converters/lib/modernExtend'); const definition = { zigbeeModel: ['lumi.light.agl003'], model: 'lumi.light.agl003', vendor: 'Aqara', description: 'Automatically generated definition', extend: [m.deviceEndpoints({"endpoints":{"1":1,"21":21}}), m.light({"colorTemp":{"range":[111,500]},"color":true}), m.electricityMeter()], meta: {"multiEndpoint":true}, }; module.exports = definition; ``` ### What does/doesn't work with the external definition? Works: I can turn off/on, change color and brightness Don't work: can’t change `Power-on behavior` and Power/Voltage/etc shows `zero`.

Hopefully out of the box support will be added to ZigbeeMQTT in the future.

absent · August 8, 2025, 7:42pm

Adding a screenshot showing the device recognised in Home Assistant via Zigbee2MQTT.

Raman.V · August 8, 2025, 7:46pm

@absentcinema Thanks you
This will be useful for many.

frank5 · August 10, 2025, 3:27am

Thank you for this post. I have to try that right away.