TapHome

Aqara Temperature, Humidity and Pressure Sensor

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

Requires external gateway

tasmota zigbee2tasmota-gateway — product page

Aqara Temperature, Humidity and Pressure 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 WSDCGQ11LM is a compact battery-powered Zigbee sensor that measures ambient temperature, relative humidity and atmospheric pressure. It communicates with TapHome over MQTT through a Zigbee2Tasmota gateway — the sensor sends periodic readings via the tele/{gateway}/SENSOR topic, and the template parses the ZbReceived JSON payload.

The sensor is powered by a CR2032 coin cell battery. The template monitors battery level and voltage via service attributes, warns when battery drops below 30%, and detects device offline states (warning after 12 hours, error after 24 hours).

Configuration

Pairing the sensor
  1. On the Zigbee2Tasmota gateway, enable Permit Join (via the gateway template switch in TapHome or Tasmota console command ZbPermitJoin 1)
  2. Press and hold the reset button on the Aqara sensor for approximately 5 seconds until the blue LED blinks
  3. Release the button — the sensor should pair within 60 seconds
  4. Note the assigned Device ID (e.g., 0x1234) from the gateway’s service attributes or Tasmota console
Import parameters

After pairing, import the device template with these parameters:

ParameterDescriptionExample
MQTT Broker IP AddressIP of the MQTT broker192.168.1.10
MQTT Broker PortBroker port (default 1883)1883
Gateway nameTasmota MQTT topic (Configuration → MQTT → Topic)tasmota_XXXXX
Device IDShort Zigbee address from pairing0x1234

Aqara/Xiaomi Zigbee devices do not fully comply with the Zigbee standard and may experience connectivity issues with certain Zigbee routers. Known incompatible routers include Centralite, General Electric, OSRAM, Sylvania, SmartThings and Securifi. Use routers confirmed compatible with Xiaomi devices (e.g., IKEA TRADFRI).

Device capabilities

Temperature and humidity

The Temperature and Humidity device reads the Temperature and Humidity fields from the ZbReceived JSON payload. Temperature is reported in °C as a direct value. Humidity is reported as a raw integer (e.g., 4520 for 45.20%) and divided by 100 in the listener script to produce the ratio that TapHome displays as a percentage.

Both values update whenever the sensor transmits a SENSOR message — typically every few minutes or on significant change.

Atmospheric pressure

The Pressure device reads the Pressure field from the ZbReceived JSON payload. The value is reported in hPa (hectopascals) and mapped via ValueLogTypeConversion from raw type 62 to pressure type 25 with a 1:1 linear scale.

Atmospheric pressure can be used for weather trend monitoring or altitude-based automation rules.

Battery and device health

The module exposes several service attributes populated by the ZbInfo polling mechanism (1-hour interval via the ReadScript):

  • Battery Percentage — estimated CR2032 battery level. A warning is raised when the level drops below 30%.
  • Battery Voltage — current battery voltage in volts.
  • Link Quality — Zigbee signal strength scaled from 0–254 to 0–100%.
  • IEEEAddr, ModelId, Manufacturer, Endpoints, Config — device identification and Zigbee configuration metadata.

The template also tracks LastSeenEpoch from ZbInfo responses. If the sensor has not been seen for more than 12 hours, a warning is raised. After 24 hours, an error is raised — indicating the sensor may be offline, out of range, or its battery is depleted.

CR2032 battery updates from Zigbee devices can take up to 24 hours to refresh. A sudden drop does not necessarily mean the battery is failing — wait for the next reporting cycle.

Additional capabilities

The WSDCGQ11LM also supports per-sensor calibration offsets for temperature, humidity and pressure readings (available in zigbee2mqtt). The battery voltage is additionally exposed as a device-level entity in some Zigbee stacks. These capabilities can be added in a future template update.

Troubleshooting

Sensor not reporting data
  1. Verify the Zigbee2Tasmota gateway is connected to the MQTT broker and receiving messages (check tele/{GWname}/SENSOR in an MQTT client)
  2. Confirm the Device ID in the template matches the short address assigned during pairing (e.g., 0x1234)
  3. Check the Link Quality service attribute — values below 20% indicate a weak Zigbee signal. Move the sensor closer to the gateway or add a compatible Zigbee router device
  4. Press the sensor button once to force a transmission and verify the gateway receives the message
Humidity reading appears incorrect

The template divides the raw Humidity value by 100 (e.g., 4520 becomes 0.4520, displayed as 45.20%). If the reading appears too low (e.g., 0.45% instead of 45%), verify the Zigbee2Tasmota firmware version — some firmware versions report humidity already in percentage format, making the division unnecessary.

Device shows offline warning
  1. Check the battery level — a depleted CR2032 will cause the sensor to stop transmitting
  2. The Aqara sensor is a Zigbee end device (not a router) and communicates through nearby Zigbee router devices. If a router goes offline, the sensor may become unreachable
  3. Try pressing the sensor button to wake it and force a re-association with the Zigbee network
  4. If the issue persists, re-pair the device by holding the reset button for 5 seconds until the blue LED blinks

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 Temperature, Humidity and Pressure 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% (excellent)
Battery Voltage
Battery PercentageEstimated CR2032 battery level — warning at less than 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 - Temperature, Humidity and Pressure 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 + "%"
Pressure Variable Read-only

Atmospheric pressure in hPa — useful for weather tracking and altitude-based automation

numeric Unit: hPa

Pressure

Listener
if INDEXOF(RECEIVEDMSG.Topic, "SENSOR") > 0
    var val := PARSEJSON(RECEIVEDMSG.Payload, "ZbReceived." + ID + ".Pressure", true);
    if(!ISNULL(val), Va := val);
end
Temperature and Humidity Temperature Sensor Read-only

Combined air temperature (°C) and relative humidity (%) from a single Zigbee sensor

temperature + humidity Unit: °C / %

Temperature and Humidity

Listener
if INDEXOF(RECEIVEDMSG.Topic, "SENSOR") > 0
    var temp := PARSEJSON(RECEIVEDMSG.Payload, "ZbReceived." + ID + ".Temperature", true);
    var hum := PARSEJSON(RECEIVEDMSG.Payload, "ZbReceived." + ID + ".Humidity", true);
    if (!ISNULL(temp), Te := temp);
    if (!ISNULL(hum), Hu := hum/ 100);
end
Connection: Packet Parser → MQTT
Possible improvements (3)
  • Battery Voltage (device-level) — Battery voltage in mV exposed as a separate entity in zigbee2mqtt. TapHome template reads it as a module-level service attribute instead.
  • Sensor Calibration Offsets — zigbee2mqtt supports per-sensor calibration offsets for temperature, humidity, and pressure. Not configurable in TapHome template.
  • Link Quality (device-level) — LinkQuality is available per SENSOR message but only exposed as a module-level service attribute via ZbInfo polling.

Sources