Aqara Door and Window Sensor T1 (MCCGQ12LM): Zigbee2MQTT + Home Assistant Setup Guide

If you landed here after searching “Aqara door sensor not working” or after wading through a long, unresolved Home Assistant community forum thread — I’ve been there. The MCCGQ12LM pairs quickly in theory and produces a frustrating non-result in practice for a specific, fixable reason. This guide covers the fix upfront, not buried at the end.

The T1 runs entirely over Zigbee2MQTT. No Aqara Hub, no Mi Home cloud, no Aqara Home app required. Once paired, Home Assistant picks it up via MQTT autodiscovery and you get a clean binary sensor you can build automations on.

What is the MCCGQ12LM?

The MCCGQ12LM is Aqara’s Zigbee 3.0 door and window sensor, sold as the “Door and Window Sensor T1.” It’s a two-piece contact sensor: a body with the electronics and a magnet that attaches to the moving part of the door or window. When the two halves come within 15 mm of each other, the sensor reports closed.

The hardware improvement over the original MCCGQ11LM is real. It ships with Zigbee 3.0 rather than the older 2.4 GHz Zigbee implementation, and uses a CR2032 coin cell rather than the harder-to-find CR1632. The form factor is also slimmer, which matters if you’re fitting it to double-glazed windows or narrow door frames where the original wouldn’t sit flush.

The trade-off is a stripped-down entity set. The original exposed six data points. The T1 exposes three. If you relied on device temperature or trigger count for diagnostics, that data isn’t available here. I’ll come back to whether that matters in practice.

It’s worth knowing: the T1 does not act as a Zigbee router. It’s an end-device, so it won’t extend your mesh. Plan your coordinator placement around that.

T1 vs original vs P1: which should you buy?

The original MCCGQ11LM is the right pick if you want richer diagnostic data — specifically device temperature and trigger count. Those can be useful for long-term reliability checks. The P1 (MCCGQ13LM) adds an adjustable detection gap, which helps if your door or window has an irregular frame.

Honestly, for most installs the T1 is the one to buy. Zigbee 3.0 means better network compatibility, the CR2032 is available at any convenience store, and the slimmer body fits more surfaces. The missing entities are a meaningful loss only if you were actually using them.

See our MCCGQ11LM setup guide for a full breakdown of the original, and the P1 (MCCGQ13LM) guide for the P1.

What you need

• A Zigbee USB coordinator paired with Zigbee2MQTT. A Sonoff Zigbee 3.0 USB Dongle Plus is a solid, widely used choice, but any Z2M-compatible coordinator works.
• Zigbee2MQTT running and connected to Home Assistant via MQTT
• Home Assistant with the MQTT integration configured
• The MCCGQ12LM sensor and magnet

No Aqara Hub. No Aqara Home app. No cloud account.

Pairing the T1 — and the fix for the most common failure

This is the section most people need.

The problem

The MCCGQ12LM can join your Zigbee network without completing the Z2M interview. When that happens, the device appears briefly in the Z2M log, then shows up in Home Assistant with no entities or as “Unknown.” The lumi.sensor_magnet.agl02 or lumi.magnet.agl02 device identifier is there, but nothing works.

The root cause is that the T1 drops into deep sleep mid-interview. The device joins the network, starts advertising its capabilities, then powers down before Z2M finishes reading them. Z2M stores an incomplete record. That record doesn’t produce working entities.

This is what the recurring “sensor not working” threads are about. The fix is a single technique.

How to pair correctly

1. Open Zigbee2MQTT and enable pairing mode (the permit join toggle in the Z2M dashboard or Devices panel in HA).

2. Find the reset button on the sensor body. It’s on the back, accessible with a pin or paperclip.

3. Press and hold the reset button for approximately 5 seconds until the blue LED blinks. This initiates the pairing sequence.

4. Immediately after the long press: keep pressing the button briefly, roughly once per second. You don’t need to hold it — a quick press to trigger a flash from the LED is enough.

5. Keep pressing once per second for 15 to 30 seconds. This keeps the sensor awake while Z2M completes the interview.

6. Watch the Z2M log. You should see the interview complete and the device description populate.

When I first tried this I skipped steps 4 and 5, assuming the long press was the whole procedure. The sensor showed up in Z2M as undefined and the contact entity never appeared. Going back through the process with the keep-alive presses resolved it on the second attempt.

If the interview still doesn’t complete, remove the device from Z2M entirely, wait 30 seconds, and run through the full sequence again. Don’t try to re-interview a partial entry — remove and restart.

What you’ll see after a successful pair

In the Z2M Devices panel, the MCCGQ12LM should show up with the friendly name you assigned and three exposed features. In Home Assistant, three entities will appear via MQTT autodiscovery:

• binary_sensor.<device>_contact
• sensor.<device>_battery
• sensor.<device>_voltage

The binary sensor state in HA maps as follows: when the door or window is closed (magnet and sensor body near each other), the contact value in Z2M is true and the HA binary sensor state is off. When the door opens, contact becomes false and the HA binary sensor goes on. That’s the standard open-circuit convention — on means the contact is broken, i.e., the door is open.

Entities in Home Assistant

Three entities, no more:

binary_sensor.<device>_contact — the main working sensor. on = door/window open, off = closed. This is what your automations will use.

sensor.<device>_battery — 0 to 100 percent remaining. Don’t expect this to show up immediately after pairing. The T1 sends battery reports on its own schedule, and the first reading can take up to 24 hours. This is normal. A fresh CR2032 will report 100% when it eventually syncs.

sensor.<device>_voltage — battery voltage in millivolts. Z2M will surface a low battery flag when voltage drops below approximately 2500 mV.

Users upgrading from the MCCGQ11LM will notice device_temperature, power_outage_count, and trigger_count are gone. The T1 does not expose them. If you were using trigger_count to log open/close frequency, you’d need to handle that in an HA counter helper instead.

Configuration and quirks

Debounce for sliding doors

If you’re installing the T1 on a horizontal sliding door or window, you may see multiple conflicting state messages in quick succession as the door moves. The sensor registers the magnet passing through detection range at different distances during travel.

Add a debounce setting in the Z2M device configuration to coalesce these events:

'0x<ieee_address>':
  friendly_name: 'front_sliding_door'
  debounce: 1

The debounce: 1 setting (value in seconds) means Z2M waits 1 second after the first state change before reporting, collapsing any rapid toggling into a single event. For standard hinged doors this isn’t needed.

Battery reporting delay

The 24-hour battery reporting delay is a common concern. It’s expected behavior. The sensor is not broken. Battery percentage and voltage data appear on the device’s own reporting interval, not on initial join. Leave it overnight and both sensors will populate.

No OTA updates

The T1 has no OTA firmware update support via Zigbee2MQTT, as of Z2M’s current device definition at the time of writing. Firmware updates require the Aqara Hub path. If you’re running purely via Z2M, you’re locked to the factory firmware — which is fine for this sensor class but worth knowing if you’re evaluating whether to keep the Aqara hub around for maintenance.

Building automations

Four practical examples using the contact binary sensor.

Entry alert

Trigger a mobile notification or TTS announcement when a door opens.

alias: "Front door opened - alert"
trigger:
  - platform: state
    entity_id: binary_sensor.front_door_contact
    to: "on"
action:
  - service: notify.mobile_app_your_phone
    data:
      message: "Front door opened"

Door left open reminder

Notify if a door stays open for more than 5 minutes, then repeat every 5 minutes until it closes.

alias: "Front door left open"
trigger:
  - platform: state
    entity_id: binary_sensor.front_door_contact
    to: "on"
    for:
      minutes: 5
action:
  - repeat:
      while:
        - condition: state
          entity_id: binary_sensor.front_door_contact
          state: "on"
      sequence:
        - service: notify.mobile_app_your_phone
          data:
            message: "Front door has been open for {{ (now() - states.binary_sensor.front_door_contact.last_changed).seconds // 60 }} minutes"
        - delay:
            minutes: 5

Night security alert

High-priority push if any contact sensor opens between 22:00 and 07:00.

alias: "Night security - door/window open"
trigger:
  - platform: state
    entity_id: binary_sensor.front_door_contact
    to: "on"
condition:
  - condition: time
    after: "22:00:00"
    before: "07:00:00"
action:
  - service: notify.mobile_app_your_phone
    data:
      title: "Security alert"
      message: "Front door opened during night hours"
      data:
        push:
          interruption-level: critical

Window open, pause climate

Stop your thermostat or AC from running when a window is open. Saves energy and avoids the system fighting itself.

alias: "Pause climate on open window"
trigger:
  - platform: state
    entity_id: binary_sensor.bedroom_window_contact
    to: "on"
action:
  - service: climate.set_hvac_mode
    target:
      entity_id: climate.bedroom_ac
    data:
      hvac_mode: "off"

Pair this with a reverse automation that resumes climate when the window closes, or leave it manual if you prefer control.

Troubleshooting

Sensor shows up in Z2M but has no entities in HA.
The interview didn’t complete. Remove the device from Z2M, run the full pairing sequence again, and use the keep-alive button presses during the interview window. See the Pairing section above.

Battery entity shows “unavailable” after pairing.
Normal. The T1 sends battery reports on its own schedule. Wait up to 24 hours for the first reading.

Contact state seems reversed — HA shows “on” when door is closed.
Double-check your installation. binary_sensor state = on means the door is open (contact broken). If the physical state is wrong, verify the magnet is within 15 mm of the sensor body when the door is closed, and that neither piece is mounted backwards relative to each other.

Device keeps dropping from Z2M.
End-devices need a reasonably close router or coordinator. The T1 does not route, so if it’s far from the nearest powered Zigbee device, it may drop. Add a router-capable device (a plug, a relay module, or a router-mode adapter) nearer to the sensor.

I’m upgrading from MCCGQ11LM and I can’t find device_temperature.
It’s not available on the T1. The stripped entity set is a deliberate difference between the models, not a Z2M bug. If you need device temperature for diagnostics, the original MCCGQ11LM remains available.

Installation notes

Sensor body mounts to the fixed frame; the smaller magnet piece mounts to the moving door or window leaf. Or the reverse — either orientation works as long as the two pieces align within 15 mm when closed.

Maximum detection gap is approximately 15 mm. If your door has more play than that when “closed,” the sensor will report open even when the door is latched. The T1 has a fixed gap threshold. If your frame needs a wider gap, the P1 (MCCGQ13LM) supports selectable gaps of 10, 20, or 30 mm.

The T1’s slimmer profile fits surfaces where the original MCCGQ11LM’s wider body would be visible or wouldn’t sit flat. Worth measuring your frame before ordering if aesthetics matter.

CR2032 batteries are easy to source — any electronics shop, pharmacy, or convenience store carries them. Battery life is typically 2+ years at normal open/close frequency. Z2M will surface the low battery flag when voltage drops below around 2500 mV.

For those coming from a hub-based setup or considering one as an alternative: the Aqara Hub E1 guide covers the E1 hub path if you’d rather keep Aqara’s native integration in the loop. And for the integration method question in general, our ZHA vs Zigbee2MQTT comparison compares ZHA against Z2M for Aqara devices.

Whether Aqara eventually adds OTA support to the T1 via Z2M is worth watching — the device definition is maintained by the community, and it’s the kind of gap that gets filled when enough units are in the field.