---
title: "Aqara Door and Window Sensor"
description: "Aqara MCCGQ11LM Zigbee contact sensor in TapHome via MQTT through a Zigbee2Tasmota gateway: open/closed state, battery level and offline warnings."
url: "https://taphome.com/en/compatibility/zigbee2tasmota-aqara-door-and-window-sensor/"
language: en
lastmod: 2026-03-29
generator: hugo
ai:
  topics: ["mqtt","sensor","zigbee","zigbee2tasmota","battery-powered","security"]
  questions: ["How to integrate the Aqara door and window sensor with TapHome?","What does the Aqara MCCGQ11LM TapHome template detect?","How to pair the Aqara door sensor with a Zigbee2Tasmota gateway?","Why is my Aqara door sensor not reporting contact state?","Does the Aqara door sensor template monitor battery level in TapHome?","How does one template create both a door sensor and a window sensor?"]
---

# Aqara Door and Window Sensor

Communication: Packet Parser → MQTT

- [Aqara Door and Window Sensor](https://www.aqara.com/en/product/door-and-window-sensor)

> [!IMPORTANT]
> This device communicates via **Zigbee** through a Tasmota gateway. Make sure you have
> the [Zigbee2Tasmota Gateway](https://taphome.com/en/compatibility/zigbee2tasmota-gateway/)
> template imported and your device paired before proceeding.

The Aqara Door and Window Sensor (MCCGQ11LM) is a compact, battery-powered Zigbee contact sensor. It detects whether a door or window is open or closed using magnetic reed switch proximity sensing. TapHome communicates with the sensor over MQTT through a Zigbee2Tasmota gateway — the sensor publishes its contact state in the `ZbReceived` JSON payload whenever the state changes.

This template creates **two devices** from a single physical sensor: a **Door Sensor** and a **Window Sensor**. Both parse the same `Contact` field from the Zigbee message. This allows users to assign one device as a door contact and the other as a window contact in TapHome, or use only the one that matches the actual installation. Unused devices can be hidden in TapHome settings.

## Configuration

### Pairing the sensor

1. In TapHome, turn on the **Permit Join** switch in the Zigbee2Tasmota Gateway module
2. On the sensor, press and hold the small button until the blue LED starts blinking, then release
3. Wait for the **Devices Found** counter to increment — the sensor's Device ID (e.g., `0x1234`) appears in the gateway service attributes
4. Import this device template using the Device ID from pairing

### Import parameters

| Parameter | Description | Example |
|-----------|-------------|---------|
| **MQTT Broker IP Address** | IP of your MQTT broker | `192.168.1.10` |
| **MQTT Broker Port** | Broker port (default 1883) | `1883` |
| **Gateway name** | Tasmota MQTT topic (Configuration → MQTT → Topic) | `tasmota_XXXXX` |
| **Device ID** | Zigbee short address from pairing | `0x1234` |

## Device capabilities

### Door and window contact detection

The template provides two reed contact devices — **Door Sensor** and **Window Sensor** — both mapped as `PacketParserReedContact` with the `security` capability. Each device parses the `Contact` field from `ZbReceived.{DeviceID}` in the MQTT SENSOR message:

- **Contact = true** → closed (door/window shut)
- **Contact = false** → open (door/window opened)

The sensor reports its contact state instantly on each state change, enabling real-time automation triggers (e.g., turn on lights when door opens, send alert on unexpected window opening).

### Battery monitoring

The module tracks battery health through two service attributes:

- **Battery Percentage** — estimated charge level; a **low battery warning** triggers when the level drops below 30%
- **Battery Voltage** — raw CR1632 cell voltage in volts

Battery data is parsed from `BatteryPercentage` and `BatteryVoltage` fields in the `ZbReceived` payload.

### Offline detection

The template monitors device availability using the `LastSeenEpoch` timestamp from `ZbInfo` polling (every 1 hour):

- **Warning** — device has not been seen for more than **12 hours**
- **Error** — device has not been seen for more than **24 hours**

This helps detect situations where the sensor has lost Zigbee connectivity or the battery is fully depleted.

### Diagnostic service attributes

The module exposes additional Zigbee metadata retrieved via `ZbInfo` polling:

| Attribute | Description |
|-----------|-------------|
| **IEEEAddr** | Unique 64-bit hardware identifier |
| **ModelId** | Zigbee model ID (`lumi.sensor_magnet.aq2`) |
| **Manufacturer** | Manufacturer string reported by the device |
| **Endpoints** | Active Zigbee endpoints |
| **Config** | Device Zigbee configuration |
| **Link Quality** | Signal strength scaled from 0–100% |

### Additional capabilities

The Aqara MCCGQ11LM also reports internal device temperature via Zigbee. Per-message link quality (LQI) is available in each SENSOR payload but is currently only exposed at module level via hourly `ZbInfo` polling. These capabilities can be added in a future template update.

## Troubleshooting

### Sensor not reporting contact state

1. Verify the sensor is paired with the Zigbee2Tasmota gateway — check `ZbStatus` in the Tasmota console
2. Confirm the **Device ID** in the template matches the short address from pairing (e.g., `0x1234`)
3. Open and close the door/window to trigger a state change — the sensor only publishes on change, not continuously
4. Use an MQTT client (e.g., MQTT Explorer) to subscribe to `tele/{GWname}/SENSOR` and verify the sensor publishes `ZbReceived` messages with a `Contact` field

### Offline warning despite working sensor

1. The offline detection relies on `ZbInfo` polling (hourly). If the sensor has not sent any message within 12 hours, a warning appears
2. Battery-powered Zigbee devices sleep between events — this is normal behavior. The warning typically clears after the next contact state change or `ZbInfo` poll
3. If the warning persists beyond 24 hours, check the battery (CR1632) and re-pair the device if necessary

### Both Door Sensor and Window Sensor showing the same state

This is expected — both devices parse the same physical sensor's `Contact` field. Hide the unused device in TapHome (**Settings** → **Devices** → select the device → **Hide**).

> [!WARNING]
> The Aqara MCCGQ11LM uses a CR1632 coin cell battery. Battery life is typically 2+ years under normal use. Frequent state changes (e.g., high-traffic doors) or weak Zigbee signal (requiring message retransmissions) can reduce battery life.

## How to install in TapHome

### Prerequisites

- Zigbee gateway with Tasmota firmware (e.g., Sonoff ZBBridge, eWeLink ZB-GW03)
- MQTT broker running on your local network (TapHome built-in broker or external)
- TapHome CCU on the same network

> [!TIP]
> TapHome has a built-in MQTT broker — enable it in **Settings** → **Hardware** → **MQTT Broker**. No additional software is needed.

### Step 1 — Set Up the Tasmota Zigbee Gateway

1. Flash [Tasmota firmware](https://tasmota.github.io/docs/Getting-Started/) on a supported Zigbee coordinator (e.g., Sonoff ZBBridge, eWeLink ZB-GW03)
2. Connect the gateway to your Wi-Fi network via the Tasmota web UI
3. Navigate to **Configuration** → **Configure MQTT** and set:
   - **Host:** your MQTT broker IP (e.g., `192.168.1.10`)
   - **Port:** `1883`
   - **Topic:** note down the topic name (e.g., `tasmota_XXXXX`) — you will need it during template import

For detailed instructions, see the [Tasmota Zigbee documentation](https://tasmota.github.io/docs/Zigbee/).

### Step 2 — Import the Gateway Template in TapHome

1. Download the gateway template from the [Zigbee2Tasmota Gateway](https://taphome.com/en/compatibility/zigbee2tasmota-gateway/) compatibility page
2. In TapHome, go to **Settings** → **Hardware** → **Packet Parser** → **Import**
3. Import the template with these parameters:
   - **MQTT Broker IP Address:** your broker IP (e.g., `192.168.1.10`)
   - **MQTT Broker Port:** `1883`
   - **Gateway name:** the Tasmota MQTT topic from Step 1 (e.g., `tasmota_XXXXX`)

After import, you will see two devices: **Permit Join** (switch) and **Devices Found** (counter).

### Step 3 — Pair a Zigbee Device

1. In TapHome, turn on the **Permit Join** switch — this opens a 60-second pairing window
2. On the Zigbee device, start the pairing procedure (typically hold the reset button for 5 seconds until the LED blinks)
3. Watch the **Devices Found** counter — it increments when a new device joins
4. Check the **Service Attributes** of the gateway to see the new device's ID (e.g., `0x1234`), manufacturer, and model
5. The pairing mode deactivates automatically after the timeout

### Step 4 — Import the Device Template

1. Download the device-specific template from the corresponding compatibility page
2. Import the template with these parameters:
   - **MQTT Broker IP Address:** same as the gateway
   - **MQTT Broker Port:** `1883`
   - **Gateway name:** same Tasmota MQTT topic as above
   - **Device ID:** the short address from pairing (e.g., `0x1234`)

## Available devices

Aqara Door and Window Sensor Module

Service Attributes

|                    |                                                                       |
|--------------------|-----------------------------------------------------------------------|
| IEEEAddr           | Zigbee IEEE address — unique 64-bit hardware identifier of the sensor |
| ModelId            |                                                                       |
| Manufacturer       |                                                                       |
| Endpoints          |                                                                       |
| Config             |                                                                       |
| Link Quality       | Zigbee signal strength — 0% (no signal) to 100% (best)                |
| Battery Voltage    | CR1632 coin cell voltage in volts                                     |
| Battery Percentage | Estimated battery level — warning triggered below 30%                 |

Custom Variables

`GWname` (string) Tasmota MQTT topic name of the Zigbee gateway (found in Configuration → MQTT → Topic) 

`ID` (string) Zigbee short address of the sensor (assigned during pairing)

After pairing the sensor via Permit Join, find the device short address in the gateway's Devices Found service attribute or via Tasmota console command ZbStatus

Door Sensor Reed Contact Read-only

Reed contact for door open/close detection — reads the Contact field from the Zigbee sensor message

boolean

Window Sensor Reed Contact Read-only

Reed contact for window open/close detection — reads the Contact field from the Zigbee sensor message

boolean

**Connection:** Packet Parser → MQTT

Possible improvements (3)

- Device Temperature — Blakadder lists device temperature measurement as an exposed feature. The Aqara MCCGQ11LM reports internal temperature via Zigbee, but the TapHome template does not parse it.
- Link Quality (device-level) — LinkQuality is available per SENSOR message but only exposed as a module-level service attribute via ZbInfo polling.
- Sensor Calibration — Some Zigbee platforms support per-sensor calibration offsets. Not configurable in TapHome template.

## Sources

- Tasmota Zigbee Documentation
  
  [tasmota.github.io](https://tasmota.github.io/docs/Zigbee/)
- Zigbee Compatible Devices Database
- Blakadder Device Entry — Aqara MCCGQ11LM
  
  [zigbee.blakadder.com](https://zigbee.blakadder.com/Aqara_MCCGQ11LM.html) 2026-03-29
- Aqara Product Page — Door and Window Sensor
  
  [www.aqara.com](https://www.aqara.com/en/product/door-and-window-sensor) 2026-03-29
- Aqara MCCGQ11LM — Product Specifications Datasheet
  
  [cdn-reichelt.de](https://cdn-reichelt.de/documents/datenblatt/R800/AQARA_MCCGQ11LM_DB-EN.pdf) 2026-03-29

## Related Documentation

- [MQTT Integration](https://taphome.com/en/compatibility/mqtt-guide/)
- [Packet Parser (HTTP, TCP, UDP, FTP, MQTT)](https://taphome.com/en/docs/integration/packet-parser/)
- [Packet parser functions](https://taphome.com/en/docs/script/packet-parser/)
- [Parsing functions](https://taphome.com/en/docs/script/parsing-functions/)
- [MQTT Broker](https://taphome.com/en/docs/integration/packet-parser/mqtt-broker/)
- [Listener scripts](https://taphome.com/en/docs/script/listener-scripts/)