Aqara Door Sensor in Home Assistant via Zigbee2MQTT (No Hub)

Aqara door and window sensors are some of the best bang-for-buck contact sensors in the Zigbee ecosystem — small, reliable, and cheap enough to put on every door and window without breaking anything. But Aqara pushes you toward their hub or the Mi Home cloud. You don’t need either.

This guide covers adding Aqara contact sensors directly to Home Assistant using Zigbee2MQTT — no Aqara Hub M2/M3, no Mi Home, no cloud account. Everything stays local.

Two models are covered: the MCCGQ11LM (Zigbee 1.2, the older and more common one) and the MCCGQ14LM (Zigbee 3.0, the one you should buy for new installs). They pair slightly differently and have different quirks — both are documented here.

What you need upfront: a running Home Assistant instance with the Zigbee2MQTT add-on already installed and a Zigbee coordinator connected. If you’re starting from zero with HA + Z2M, read Xiaomi/Aqara Zigbee Setup in Home Assistant with Zigbee2MQTT first, then come back.

What You Need Before You Start

Before touching the sensor, make sure you have:

• Home Assistant (any recent version) with the Zigbee2MQTT add-on running. This guide assumes Z2M is already paired to at least one device — if the add-on is freshly installed, make sure it’s communicating with your coordinator first.
• A compatible Zigbee coordinator. The Sonoff ZBDongle-P and ZBDongle-E both work well. So does the Home Assistant Connect ZBT-1 or ZBT-2 (the SkyConnect was renamed to Connect ZBT-1 in June 2024; ZBT-2 launched November 2025 with a newer chip).
• A fresh battery. Both the MCCGQ11LM and MCCGQ14LM use a CR1632. Battery state is the single most common reason for pairing failures. If yours came pre-installed, replace it before you start — factory batteries are often already partially drained.

On the model difference: The MCCGQ11LM runs Zigbee 1.2. The MCCGQ14LM runs Zigbee 3.0. This matters more than you’d expect — Zigbee 1.2 has documented mesh routing incompatibilities with certain popular plugs and bulbs. If you’re buying new sensors, get the MCCGQ14LM. If you already have MCCGQ11LM units, they’ll work — you just need to be more careful about mesh layout (covered in the troubleshooting section).

Pairing the Aqara Door Sensor to Zigbee2MQTT

Enable Permit Join

In the Zigbee2MQTT web UI (accessible from HA’s sidebar if you installed the add-on), click Permit join at the top. You have roughly 3 minutes once join is open. Alternatively, enable join for a specific device group if your Z2M version supports it — either works.

Trigger Pairing on the Sensor

1. Open the sensor. On the MCCGQ11LM, the reset button is a tiny pinhole on the side. On the MCCGQ14LM, it’s a small button on the back of the main unit.
2. Hold the reset button for approximately 5 seconds until the LED blinks blue three times in quick succession. Release.
3. The sensor will attempt to join. In Z2M’s device list, watch for a new entry to appear — it may show up immediately or after a few seconds.

If the device appears and completes the interview (Z2M shows the device with its model and a full set of exposed features), you’re done. Skip to Entities Exposed in Home Assistant.

If Auto-Join Doesn’t Complete

The MCCGQ11LM in particular can stall during the Zigbee interview — it shows up in Z2M but never fully joins. This is a known Zigbee 1.2 behavior. The fix:

1. After the initial 5-second long press, short-press the reset button every ~1 second repeatedly while Z2M shows the device as “interviewing.”
2. Keep short-pressing until Z2M shows the interview as complete and the device model name appears.

This prompts the sensor to respond to the interview requests instead of going silent. It’s annoying but it works.

Pairing Troubleshooting

Sensor appears briefly in Z2M then disappears:
– Most likely cause (MCCGQ11LM): Zigbee 1.2 routing conflict. The sensor is trying to join through a mesh router that doesn’t handle Zigbee 1.2 end-device traffic correctly.
– Fix: move the sensor physically close to your Zigbee coordinator — within 1–2 meters. With short range, it joins directly through the coordinator instead of routing. Once joined, you can move it to its installed location.
– Known incompatible router types for MCCGQ11LM: OSRAM/Ledvance smart plugs, older Centralite/GE/Iris plugs. Avoid these in the mesh path between the sensor and coordinator.

Blue LED blinks but Z2M never shows the device at all:
– Low battery is the most likely cause. CR1632 cells can test at acceptable voltage on a multimeter but still drop below threshold under the load of a Zigbee interview.
– Replace battery, retry immediately.

Interview stays at 0% / never progresses:
– Update Z2M to the latest version. Older versions have device database gaps that cause interview stalls.
– Restart Z2M after updating, then retry the full pairing sequence from the beginning.
– If still stuck: open Z2M logs (in the add-on log tab) and look for INTERVIEW_FAILED or timeout errors. These often indicate coordinator firmware is outdated. Firmware updates for the ZBDongle-P/E are done via a dedicated flasher tool (not through Z2M itself).

Entities Exposed in Home Assistant

Once paired, Zigbee2MQTT automatically creates entities in Home Assistant. For the Aqara contact sensors, you’ll get:

• binary_sensor.your_device_name_contact — the main entity. State is on when the door/window is open, off when closed. Note: in Z2M’s own UI, contact: true means closed — HA inverts this to the more intuitive “on = open” convention.
• sensor.your_device_name_battery — battery percentage (0–100%). Z2M also exposes a separate sensor.your_device_name_voltage entity (millivolts) on the MCCGQ11LM. Both are available without any template.
• sensor.your_device_name_device_temperature — present on the MCCGQ11LM. This is a rough ambient temperature reading from the sensor’s internal thermistor. It’s usable as a sanity check but drifts based on sun exposure and draft position. Don’t use it as your primary temperature source.
• sensor.your_device_name_linkquality — Zigbee signal quality (LQI, 0–255). Watch this after installation: below 20 means the mesh path is weak.

Renaming and Assigning to an Area

In Home Assistant, go to Settings → Devices & Services → Zigbee2MQTT → your device. From the device page:
– Click the pencil icon next to the device name to rename it (e.g., “Front Door Sensor”).
– Use the Area dropdown to assign it to a room. This makes the entity show up in the room view and in voice assistant configurations.

Renaming in HA doesn’t affect the Z2M device name. If you want Z2M and HA names to stay in sync, rename in Z2M’s device settings — HA picks up the change automatically.

Building Automations

Notify When a Door Opens

The most common use case: get a phone notification when a door or window opens.

alias: Front Door Open – Notify
description: ""
trigger:
  - platform: state
    entity_id: binary_sensor.front_door_sensor_contact
    to: "on"
condition: []
action:
  - service: notify.mobile_app_your_phone
    data:
      title: "Front Door"
      message: "Front door opened"
mode: single

Replace binary_sensor.front_door_sensor_contact with your actual entity ID and notify.mobile_app_your_phone with your companion app notify service.

Debounce for sliding doors or gates: If you’re mounting on a surface that vibrates or bounces (sliding gate, screen door), Z2M can send rapid open/close state changes. In Z2M’s device settings, you can set a debounce value (in milliseconds) to suppress state changes shorter than that window. 500ms is a reasonable starting point for most sliding surfaces.

Turn on Lights When the Door Opens at Night

alias: Front Door – Night Light Trigger
description: ""
trigger:
  - platform: state
    entity_id: binary_sensor.front_door_sensor_contact
    to: "on"
condition:
  - condition: time
    after: "21:00:00"
    before: "06:00:00"
action:
  - service: light.turn_on
    target:
      entity_id: light.hallway
    data:
      brightness_pct: 40
mode: single

Adjust the time window and the light entity to match your setup. You can add a turn_off with a delay if you want the light to auto-extinguish after a set period.

Simple DIY Alarm Zone

If you want to monitor multiple doors and windows and trigger an alert when any open while you’ve “armed” the system, use an input_boolean as the arm/disarm switch.

First, create the input_boolean in HA (Settings → Helpers → Create Helper → Toggle). Name it something like alarm_armed.

Then create the automation:

alias: Alarm Zone – Any Door or Window
description: ""
trigger:
  - platform: state
    entity_id:
      - binary_sensor.front_door_sensor_contact
      - binary_sensor.back_door_sensor_contact
      - binary_sensor.bedroom_window_sensor_contact
    to: "on"
condition:
  - condition: state
    entity_id: input_boolean.alarm_armed
    state: "on"
action:
  - service: notify.mobile_app_your_phone
    data:
      title: "⚠ Alarm"
      message: "{{ trigger.to_state.attributes.friendly_name }} opened while armed"
  - service: persistent_notification.create
    data:
      title: "Security Alert"
      message: "{{ trigger.to_state.attributes.friendly_name }} opened"
mode: parallel
max: 10

Add as many contact sensor entities as you have to the entity_id list under trigger. The mode: parallel ensures simultaneous opens (e.g., someone kicks in two doors at once) both fire alerts. Arm/disarm by toggling input_boolean.alarm_armed — from the UI, a dashboard button, or an NFC tag.

MCCGQ11LM vs MCCGQ14LM — Which to Buy?

Bottom line: If you’re buying sensors today, get the MCCGQ14LM. The Zigbee 3.0 standard is more robust and routing is less fragile. The MCCGQ11LM is fine if you already have them — just be methodical about pairing close to the coordinator and keeping problematic router devices out of the mesh path.

If you’re running a mixed Zigbee 1.2/3.0 network (most people are), the MCCGQ14LM sensors will coexist cleanly. Zigbee 3.0 end-devices can use Zigbee 3.0 routers while your older MCCGQ11LM units do their thing. Z2M handles both transparently.

Keeping Sensors Connected Long-Term

Battery Monitoring

The sensor.battery entity reports percentage (0–100%). Z2M also exposes a separate voltage entity (mV) for the MCCGQ11LM — both are available without any template.

If you want a low-battery alert, add an automation:

alias: Contact Sensor – Low Battery Alert
trigger:
  - platform: numeric_state
    entity_id:
      - sensor.front_door_sensor_battery      - sensor.back_door_sensor_battery
    below: 15
action:
  - service: notify.mobile_app_your_phone
    data:
      title: "Low Battery"
      message: "{{ trigger.to_state.attributes.friendly_name }}: {{ trigger.to_state.state }}%"
mode: parallel

CR1632 cells in light-use sensors (1–5 triggers per day) typically last 1–2 years. High-frequency doors (front door, kids’ rooms) may need replacement every 8–12 months.

Zigbee Mesh Health

Linkquality below 20 is a warning sign. Check the linkquality sensor for each contact sensor after final installation. If it’s weak:
– Add a mains-powered Zigbee router (a smart plug or bulb) near the problem sensor. Zigbee meshes self-heal, so a nearby router will automatically get picked up.
– If it stays weak even with a nearby router, check that the router itself has good linkquality to the coordinator.
– Walls with foil insulation, concrete, and metal door frames all attenuate Zigbee. Physical placement matters more than anything else.

For whole-network mesh visualization, Z2M has a built-in network map (the graph icon in the Z2M UI). Run it after adding a new sensor to confirm the routing looks sane.

If a sensor drops offline and won’t come back:
1. Bring it physically close to the coordinator.
2. Power-cycle it by removing and reinserting the battery.
3. If it doesn’t re-join automatically, you may need to remove the device from Z2M and pair it fresh. Z2M will recreate all entities in HA; rename and re-assign the area if needed.

Conclusion

Aqara contact sensors are a solid choice for local-first home automation — they’re cheap, small, well-supported in Zigbee2MQTT, and once paired, they just work. No Aqara Hub, no cloud dependency, no Mi Home account required.

The MCCGQ14LM is the better pick for new purchases. The MCCGQ11LM is worth keeping if you have existing stock — just pair it close to the coordinator and stay aware of mesh routing.

With the automations above, you can cover everything from basic door notifications to a multi-sensor alarm zone, all running entirely on your local network.

Next steps:
– Combine door sensors with motion sensing for full room awareness: Aqara P1 Motion Sensor in Home Assistant via Zigbee2MQTT
– New to Zigbee2MQTT entirely? Start here: Xiaomi/Aqara Zigbee Setup in Home Assistant with Zigbee2MQTT
– Prefer a hub-based approach? Aqara E1 Hub in Home Assistant — Local Setup
– Or go the Matter route: Aqara Hub M3 as a Matter Bridge in Home Assistant