TapHome

Aqara Door and Window Sensor

Packet Parser → MQTT
Submitted by
Last updated: 03. 2026

Requires external gateway

tasmota zigbee2tasmota-gateway — product page

Aqara Door and Window Sensor

This device communicates via Zigbee through a Tasmota gateway. Make sure you have the 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
ParameterDescriptionExample
MQTT Broker IP AddressIP of your MQTT broker192.168.1.10
MQTT Broker PortBroker port (default 1883)1883
Gateway nameTasmota MQTT topic (Configuration → MQTT → Topic)tasmota_XXXXX
Device IDZigbee short address from pairing0x1234

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:

AttributeDescription
IEEEAddrUnique 64-bit hardware identifier
ModelIdZigbee model ID (lumi.sensor_magnet.aq2)
ManufacturerManufacturer string reported by the device
EndpointsActive Zigbee endpoints
ConfigDevice Zigbee configuration
Link QualitySignal 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).

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

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 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.

Step 2 — Import the Gateway Template in TapHome

  1. Download the gateway template from the 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
IEEEAddrZigbee IEEE address — unique 64-bit hardware identifier of the sensor
ModelId
Manufacturer
Endpoints
Config
Link QualityZigbee signal strength — 0% (no signal) to 100% (best)
Battery VoltageCR1632 coin cell voltage in volts
Battery PercentageEstimated 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

Aqara - Door and Window Sensor

Read (module)
MQTTPUBLISH("cmnd/" + GWname+ "/ZbInfo", ID)
Listener
if INDEXOF(RECEIVEDMSG.Topic, "SENSOR") > 0
	var ZbReceived := PARSEJSON(RECEIVEDMSG.Payload, "ZbReceived." + ID, true);
    var bat := PARSEJSON(ZbReceived, "BatteryPercentage", true);
    if(!ISNULL(bat), BatteryPercentage := bat);
    var volt := PARSEJSON(ZbReceived, "BatteryVoltage", true);
    if(!ISNULL(volt), BatteryVoltage := volt);
    
    var deviceInfo := PARSEJSON(RECEIVEDMSG.Payload, "ZbInfo." + ID, true);
    if !ISNULL(deviceInfo)
    	LastSeenEpoch := PARSEJSON(deviceInfo, "LastSeenEpoch");
        COMPLETESERVICEATTRIBUTE("IEEEAddr", PARSEJSON(deviceInfo, "IEEEAddr"));
        COMPLETESERVICEATTRIBUTE("ModelId", PARSEJSON(deviceInfo, "ModelId"));
        COMPLETESERVICEATTRIBUTE("Manufacturer", PARSEJSON(deviceInfo, "Manufacturer"));
        COMPLETESERVICEATTRIBUTE("Endpoints", PARSEJSON(deviceInfo, "Endpoints"));
        COMPLETESERVICEATTRIBUTE("Config", PARSEJSON(deviceInfo, "Config"));
        COMPLETESERVICEATTRIBUTE("Link Quality", ROUND(LINEAR(PARSEJSON(deviceInfo, "LinkQuality"), 0,0, 254, 100)) + "%");
    end
end

if BatteryPercentage < 30
	ADDWARNING("Low battery (<30%)");
end

if !ISNAN(LastSeenEpoch)
	DATETIME now := NOW();
	var secondsSeen := now.UNIXTIME - LastSeenEpoch;
	if secondsSeen > 12 * 60 * 60
		if secondsSeen > 24 * 60 * 60
			ADDERROR("Device is offline > 24H");
		else
			ADDWARNING("Device is offline > 12H");        
		end
	end
end
Service Attributes
IEEEAddr
MQTTPUBLISH("cmnd/" + GWname+ "/ZbInfo", ID)
ModelId
Manufacturer
Endpoints
Config
Link Quality
Battery Voltage
BatteryVoltage + " V"
Battery Percentage
BatteryPercentage + "%"
Door Sensor Reed Contact Read-only

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

boolean

Door Sensor

Listener
if INDEXOF(RECEIVEDMSG.Topic, "SENSOR") > 0
    var val := PARSEJSON(RECEIVEDMSG.Payload, "ZbReceived." + ID + ".Contact", true);
    if(!ISNULL(val), Rc := val);
end
Window Sensor Reed Contact Read-only

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

boolean

Window Sensor

Listener
if INDEXOF(RECEIVEDMSG.Topic, "SENSOR") > 0
    var val := PARSEJSON(RECEIVEDMSG.Payload, "ZbReceived." + ID + ".Contact", true);
    if(!ISNULL(val), Rc := val);
end
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