Aqara Light Sensor T1 (GZCGQ11LM): Local Zigbee2MQTT Setup

The GZCGQ11LM is a dedicated lux sensor. That’s it — one number, reported over Zigbee, no cloud required once it’s paired. I’ve been using lux sensors in my automations for a while and this is one of the cleanest devices to integrate via Zigbee2MQTT.

There’s a catch, though. A small percentage of units shipped in mid-2024 and late-2024 silently fail after pairing: the device interviews fine, Home Assistant sees it, and then illuminance stays null forever. There are also open bugs around configuring the reporting interval and adding a second or third unit to the same coordinator. None of these are showstoppers if you know what to look for, but they’ve tripped up a lot of people who assumed the sensor was faulty hardware.

I’ll cover the setup path first, then the known issues with clear identification steps so you’re not debugging blind.

What the GZCGQ11LM actually is

The GZCGQ11LM measures ambient illuminance from 0 to 83,000 lux on a single CR2450 coin cell. No mains power, no motion sensing, no temperature channel. If you’re looking for a combined motion-and-lux device, the Aqara P1 and FP2 both include lux as a secondary reading — the T1 light sensor is the right choice when you want a dedicated lux reading without a motion trigger.

Its Zigbee model identifier is lumi.sen_ill.agl01. It’s a Zigbee 3.0 end device with a magnetic mount on the back, which makes placement flexible: stick it to a window frame, attach it above a desk, or face it toward a light source you want to track.

The sensor reports on illuminance change, not on a fixed schedule. detection_period controls the minimum interval between successive reports — it’s a minimum gap, not a polling rate. If lux doesn’t change meaningfully, the sensor stays quiet.

Prerequisites and choosing between Z2M and ZHA

You’ll need a running Zigbee coordinator (USB dongle or network-connected adapter) already paired to a Zigbee2MQTT instance, with the Z2M integration active in Home Assistant. If you’re not there yet, our guide on running Aqara Zigbee devices in Home Assistant without a hub covers the stack setup.

Zigbee2MQTT gives you more control:
– Full detection_period configuration via the UI (1–59 seconds) — though see the bug note below
– illuminance_raw entity to expose the unprocessed sensor value alongside the calibrated reading
– illuminance_calibration for percentage offset correction
– OTA firmware updates (with caveats)

ZHA is simpler but less configurable:
– Illuminance and battery entities work correctly
– detection_period is not configurable from the ZHA UI — it uses a Lumi-proprietary cluster that ZHA doesn’t expose
– OTA was closed as “not planned” in the ZHA device handler issue tracker

If detection_period matters for your use case — for example, you want fast lux response for a lighting automation — use Z2M. If you just want a lux reading with minimal configuration, ZHA gets the sensor working fine.

Note on the entity name: Zigbee2MQTT 2.0.0 (January 2025) removed the old illuminance_lux property and renamed it to illuminance. On any current Z2M install the lux reading lives in the illuminance property, and the Home Assistant entity is sensor.<device>_illuminance. If you’re on a pre-2.0 Z2M version you’ll still see illuminance_lux — but you should upgrade. This guide uses the current name throughout.

Pairing the GZCGQ11LM to Zigbee2MQTT

Open the Z2M frontend and start a pairing session (Permit join, or target your coordinator directly).

Press and hold the button on the back of the sensor for about 5 seconds until the LED flashes. The device will enter pairing mode.

Keepalive trick for busy networks: After the initial hold, keep pressing the button once per second throughout the pairing window. The GZCGQ11LM is a sleepy end device and can stop advertising mid-interview if it goes idle before the coordinator finishes querying it. Pressing the button keeps it awake and significantly improves interview reliability, especially on networks with 20+ devices already paired.

When pairing succeeds, Z2M will identify the device as lumi.sen_ill.agl01 and create entities for illuminance, battery, and battery voltage.

One expected behavior that looks like a bug: battery percentage may take up to 24 hours to appear after first pairing. This is normal Zigbee lazy reporting. The battery voltage entity usually populates sooner and gives you an immediate sanity check on the cell.

Known issues to check before assuming hardware fault

This is the section I wish I’d had when I first set these up. Three separate open bugs affect this device, and they look similar on the surface — all present as “sensor paired but not working” — but they have different causes.

Bug 1: detection_period write timeout

Changing detection_period via the Z2M web UI slider sends a manuSpecificLumi.write command to the device. On a significant number of units, this times out: Z2M logs a write timeout after 10 seconds and the slider reverts. The device page shows the setting but the device never confirms receipt.

This is an open bug (Z2M issue #22193) with no confirmed workaround as of the time of writing. The issue has been reproduced across multiple coordinator hardware types. If you need a specific reporting interval and the UI slider doesn’t stick, there’s currently no reliable alternative path — the bug is at the protocol level, not a misconfiguration on your end.

Practical implication: if your use case doesn’t require a specific detection_period, don’t change it. The default behavior is reasonable for most lux-triggered automations.

Bug 2: 2024-batch silent no-data bug

Hardware batches manufactured around May 2024 and October 2024 exhibit a particularly frustrating behavior: the device pairs correctly, Z2M identifies it as lumi.sen_ill.agl01, entities appear in Home Assistant, and then illuminance stays null indefinitely. No errors logged, no interview failures — the sensor just never reports.

This has been confirmed on Z2M 1.41.0 with an SLZB-06 coordinator and on Z2M 2.7.1-1 with an SLZB-06M. The affected GitHub issues (#24845 and #30281) were still open with no confirmed fix at the time the brief for this article was compiled.

How to check if you’re affected:

1. Let the sensor sit paired for at least 30 minutes without touching it
2. In Z2M, look at the “Last seen” timestamp for the device
3. If “Last seen” updates but illuminance stays null, you’re likely hitting this bug
4. If “Last seen” never updates at all, try re-pairing with the keepalive button presses described above

If you’re on an affected batch, there’s currently no software workaround documented. The issue thread is active; check it for any updates before concluding the hardware is defective.

Bug 3: Multi-unit pairing failure

If you’re deploying two or three GZCGQ11LM sensors on the same coordinator, you may find the second or third unit fails to pair. This isn’t a range or interference issue — it affects users even when pairing the second sensor right next to the coordinator. Open bug (Z2M issue #23714), confirmed on Sonoff Dongle Plus with Z2M 1.39.1, no documented workaround.

If you hit this: try pairing the second unit immediately after a Z2M restart, before any other devices have checked in. Some users in the issue thread report this helps, though it’s not consistent.

Configuring illuminance_calibration and illuminance_raw

Once the sensor is reporting, Z2M exposes two optional settings worth knowing about.

illuminance_calibration is a percentage offset applied to the raw sensor reading before it appears in Home Assistant. If you have a reference light meter (or another calibrated sensor in the same location), you can use this to correct systematic offsets. A value of 5 adds 5% to the raw reading; -10 subtracts 10%.

illuminance_raw enables a second entity that exposes the unprocessed sensor value alongside the calibrated illuminance entity. Most users won’t need this, but it’s useful if you want to compare pre- and post-calibration readings or if you’re diagnosing whether an unexpected lux value is coming from sensor drift or the calibration offset.

Both settings are configured from the Z2M device page under the Exposes tab.

Building lux-triggered automations in Home Assistant

The GZCGQ11LM doesn’t support on-device conditional logic — you can’t set a threshold on the sensor itself that triggers an output. All threshold logic belongs in Home Assistant automations, using the illuminance entity as the trigger or condition entity.

Here’s a working automation that turns on a light group when the room drops below 50 lux and turns it off when it rises above 200 lux:

automation:
  - alias: "Lights on when dim"
    trigger:
      - platform: numeric_state
        entity_id: sensor.light_sensor_t1_illuminance
        below: 50
    action:
      - service: light.turn_on
        target:
          entity_id: light.living_room

  - alias: "Lights off when bright"
    trigger:
      - platform: numeric_state
        entity_id: sensor.light_sensor_t1_illuminance
        above: 200
    action:
      - service: light.turn_off
        target:
          entity_id: light.living_room

The threshold values (50 and 200 lux) are starting points. Natural daylight through a window can run 1,000–10,000 lux; a well-lit room at night is typically 100–300 lux; a dim lamp might be 20–50 lux. Log your sensor’s readings across a typical day before committing to thresholds.

Combining with a motion sensor: A lux-only automation will turn on lights in the middle of the day if a cloud passes over. The more useful pattern is to add a motion sensor as a second condition, so the light only comes on when lux is low and someone is present. Pair this sensor with the RTCGQ12LM T1 motion sensor for a two-condition setup:

automation:
  - alias: "Motion + dim: turn on light"
    trigger:
      - platform: state
        entity_id: binary_sensor.motion_sensor_t1_occupancy
        to: "on"
    condition:
      - condition: numeric_state
        entity_id: sensor.light_sensor_t1_illuminance
        below: 80
    action:
      - service: light.turn_on
        target:
          entity_id: light.living_room

This reads as: “when motion is detected, check whether it’s currently dim; if yes, turn on the light.” The lux sensor acts as a gate, not a trigger.

If you’d rather pair the lux gate with a motion sensor that also reports lux on the same device, the Aqara P1 motion sensor covers that combined setup in its own guide.

ZHA path

If you’re running ZHA rather than Z2M, the GZCGQ11LM is recognized via the IlluminationT1 quirk class and exposes two entities: illuminance and battery.

What works: lux reporting, battery percentage.

What’s missing compared to Z2M: detection_period isn’t configurable from the ZHA UI (the Lumi-proprietary cluster isn’t exposed). illuminance_calibration and illuminance_raw aren’t available either. OTA was closed as not planned in the ZHA device handler tracker.

For a simple lux-reading use case, ZHA is perfectly usable. If you need to adjust reporting speed or calibrate the sensor, Z2M is the better path.

Privacy posture

Once paired, the GZCGQ11LM has no cloud dependency. It communicates exclusively over Zigbee to your local coordinator. Lux readings go to Z2M, then to your local MQTT broker, then to Home Assistant — entirely on your LAN. There’s no Aqara app requirement, no Mi Home account, no outbound traffic from the sensor itself.

If you’re running this alongside hub-connected devices, the Z2M path for this sensor is fully independent of any Aqara hub. This sensor works without internet by design, which is the broader case we cover in does Aqara work without internet.

Frequently asked questions

Does the Aqara Light Sensor T1 work without the Aqara hub?

Yes. The GZCGQ11LM is a plain Zigbee 3.0 device and pairs directly to any Zigbee coordinator running Z2M or ZHA. No Aqara hub, no Aqara Home app, no cloud account needed.

How do I set the detection period on the GZCGQ11LM in Zigbee2MQTT?

Open the Z2M device page, go to the Exposes tab, and use the detection_period slider (range: 1–59 seconds). Be aware that a confirmed bug causes write timeouts on many units — the slider may revert without the change taking effect. There’s no workaround documented as of Z2M issue #22193.

Why is my Aqara light sensor not reporting lux after pairing?

Two likely causes. First, try re-pairing with the keepalive button technique described above — sleepy end devices sometimes fail the interview without it. Second, if the device paired correctly and still shows null illuminance after 30+ minutes, check whether your unit is from a May 2024 or October 2024 hardware batch. A confirmed bug affects those batches and no fix is documented yet (Z2M issues #24845 and #30281).

Can I use the Aqara Light Sensor T1 with ZHA instead of Zigbee2MQTT?

Yes, ZHA recognizes the device and exposes illuminance and battery entities. The trade-off is that detection_period isn’t configurable from ZHA’s UI, and calibration options aren’t available. For basic lux readings and automations, ZHA works fine.

How do I trigger lights automatically based on lux level in Home Assistant?

Use the sensor.<device>_illuminance entity in an automation with a numeric_state trigger. Set a below threshold to trigger lights on and an above threshold to trigger lights off. The YAML examples in the automation section above are a working starting point. For presence-aware lighting, add a motion sensor as a condition rather than a separate trigger.

If the sensor is working correctly, the setup from here is mostly about tuning your lux thresholds to match your actual lighting conditions. Give it a few days of logging before you settle on values — lux varies significantly by season, time of day, and window orientation, and a threshold that feels right on a cloudy afternoon may switch your lights on at noon in summer.