TapHome
English
Slovenčina Čeština Magyar Italiano Polski Deutsch Română Hrvatski

English

Official · TapHome

Xiaomi Mi Temperature and Humidity Sensor (WSDCGQ01LM) via Zigbee2MQTT

Xiaomi WSDCGQ01LM round Zigbee temperature and humidity sensor (CR2032) in TapHome over MQTT through a Zigbee2MQTT bridge. Reports temperature, relative humidity, battery level, battery voltage and Zigbee link quality. Paired in Zigbee2MQTT with Permit join and the reset button.

Zigbee2MQTTPacket Parser → MQTT1 deviceRevision 1.0 Last updated: November 10, 2026

Import into the TapHome appHardware › Packet Parser › Add from template

Download Template
On this page

Integration guide

The Xiaomi Mi Temperature and Humidity Sensor (model WSDCGQ01LM) is a small round, battery-powered Zigbee sensor for indoor use. It measures ambient temperature and relative humidity and runs on a CR2032 coin cell. Zigbee2MQTT also lists it under the white-label names Xiaomi YTC4042GL, YTC4007CN and YTC4018CN. It is not the square Aqara WSDCGQ11LM, which also measures air pressure.

TapHome communicates with the sensor indirectly. The WSDCGQ01LM pairs with a Zigbee coordinator managed by a Zigbee2MQTT bridge, which publishes the readings as JSON on MQTT topics. TapHome subscribes to these topics through a Packet Parser MQTT module and maps them to one temperature sensor device with humidity, battery and link quality values. Other Zigbee2MQTT sensors, for example the Tuya TS0201 or the Aqara RTCGQ11LM motion sensor, are set up the same way.

Requirements

  • Zigbee coordinator — a Zigbee adapter supported by Zigbee2MQTT
  • Zigbee2MQTT bridge — running on a host next to the coordinator
  • MQTT broker — reachable from both the Zigbee2MQTT host and the TapHome control unit
  • TapHome control unit with Packet Parser MQTT support

The sensor itself has no Wi-Fi or Ethernet connection. All IP networking happens between the MQTT broker, Zigbee2MQTT and the TapHome control unit. The template expects the default Zigbee2MQTT base topic zigbee2mqtt.

Pairing with Zigbee2MQTT

The WSDCGQ01LM must be paired with the Zigbee2MQTT coordinator before the template is imported:

  1. Place the sensor close to the Zigbee coordinator.
  2. Open the Zigbee2MQTT web UI and enable pairing mode (Permit join).
  3. Press and hold the reset button for about 5 seconds, until the blue light starts blinking. The reset button is the small button on the top of the device.
  4. The sensor joins automatically and appears in the Zigbee2MQTT device list with its IEEE address. Optionally assign a friendly name (for example bedroom_climate) in the device settings.

The battery percentage can take up to 24 hours to appear after pairing — the sensor reports it only periodically.

Placement

The sensor is for indoor use only. It can stand freely at the desired location, or it can be fixed with the adhesive sticker after removing the protective film (an extra sticker is included in the box). The surface must be clean and dry. Do not mount the sensor on a metal surface.

Zigbee2MQTT device options

Zigbee2MQTT offers device-specific options for this sensor. They take effect with the next report from the device:

OptionDescription
temperature_calibrationAbsolute offset added to the temperature value
temperature_precisionNumber of decimal places for temperature (0–3, can only decrease precision)
humidity_calibrationAbsolute offset added to the humidity value
humidity_precisionNumber of decimal places for humidity (0–3, can only decrease precision)

Configuration

Import parameters

When importing the template, enter the address of the MQTT broker:

ParameterDescriptionDefault
Mqtt Broker ipAddressIP address of the MQTT broker192.168.0.1
Mqtt Broker portTCP port of the MQTT broker1883

The module subscribes to the root topic zigbee2mqtt/#.

Module variable

After the import, set the module variable Xiaomi_WSDCGQ01LM_1 to the identity of the sensor in Zigbee2MQTT:

VariableDescriptionHow to obtainDefault in the template
Xiaomi_WSDCGQ01LM_1Zigbee2MQTT friendly name or IEEE address of the sensorZigbee2MQTT web UI → Devices → WSDCGQ01LM → copy the friendly name or IEEE address0x00158d0001823a01

The default value 0x00158d0001823a01 is only an example. Replace it with the friendly name or IEEE address of your sensor, otherwise the template receives no data.

The listener script reacts only to messages on the topic zigbee2mqtt/ followed by the value of this variable, so the value must match the Zigbee2MQTT name exactly. In the TapHome app, the template is added to the MQTT interface with these import parameters, and the variable is then edited in the module settings.

A friendly name (for example bedroom_climate) is easier to read than the IEEE address. If the friendly name is changed later in Zigbee2MQTT, the variable in TapHome must be updated as well.

Device capabilities

The template creates one device, Xiaomi WSDCGQ01LM, of the temperature sensor type. It is updated from the JSON state message on zigbee2mqtt/{Xiaomi_WSDCGQ01LM_1}.

Temperature and humidity

Temperature in °C is read from the temperature property. Relative humidity is read from the humidity property, which Zigbee2MQTT publishes in percent. The template divides it by 100 because TapHome keeps humidity on a 0–1 scale and displays it as a percentage, so a payload of 54.2 appears as 54.2 % in TapHome.

According to the manufacturer’s manual, the sensor measures:

QuantityRangeAccuracy
Temperature-20 °C to 50 °C±0.3 °C
Relative humidity10–90 % RH, non-condensing±3 %

Battery and signal monitoring

The device has three service attributes, read from the same JSON message:

  • Battery — remaining battery in percent (0–100 %) from the battery property, shown as for example 95%
  • Battery voltage — battery voltage in millivolts from the voltage property, shown as for example 3000mV
  • Atribút — Zigbee link quality (LQI) from the linkquality property, shown with the unit lqi; the template displays this attribute under the name Atribút

Battery and Battery voltage show - until the first message with these values arrives. The link quality attribute starts at 0lqi.

Technical specifications

ParameterValue
ModelWSDCGQ01LM
Wireless connectivityZigbee, 2405–2480 MHz
BatteryCR2032
Dimensions36 × 36 × 11.5 mm

Troubleshooting

No data in TapHome

  1. Check that the sensor appears in the Zigbee2MQTT device list with a recent “Last seen” time.
  2. Check that the Xiaomi_WSDCGQ01LM_1 variable matches the friendly name or IEEE address exactly, and that the example value 0x00158d0001823a01 was replaced.
  3. Subscribe to zigbee2mqtt/# with an MQTT client (for example MQTT Explorer) and confirm that JSON messages arrive on zigbee2mqtt/{friendly_name}.
  4. Check that the broker IP address and port in the import parameters are reachable from the TapHome control unit.

Sensor stops sending messages or leaves the network

Xiaomi devices do not fully comply with the Zigbee standard and sometimes disconnect from the network. The most common causes are:

  1. Weak signal — link quality below 20 is considered weak. Move the sensor closer to the coordinator or to a mains-powered Zigbee router.
  2. Low battery voltage — this can happen even when the battery still appears full. Try a different CR2032 battery.
  3. Incompatible router — routers from Centralite, General Electric, Iris, Ledvance, Legrand, OSRAM, Sylvania, Securifi and some other vendors are known to cause problems with Xiaomi devices. Connect the sensor directly to the coordinator by pressing the reset button while it is physically close to the coordinator.

Humidity value in smart rules is between 0 and 1

This is expected. TapHome keeps humidity on a 0–1 scale (0.542 = 54.2 %) and the app displays it in percent. Use the 0–1 value in smart rules and formulas.

Available devices 1

These devices appear in TapHome after import.

Xiaomi WSDCGQ01LM Module
Custom Variables
Xiaomi_WSDCGQ01LM_1 (string) = 0x00158d0001823a01
Xiaomi WSDCGQ01LM Temperature Sensor
Service Attributes
Battery
Battery voltage
Atribút
Variable: battery, Variable: voltage, Variable: link

Xiaomi WSDCGQ01LM

Listener
if RECEIVEDMSG.TOPIC = "zigbee2mqtt/"+ Xiaomi_WSDCGQ01LM_1 
   VAR payloadTemp := PARSEJSON(RECEIVEDMSG.PAYLOAD, "temperature");
   Te := payloadTemp;
   VAR payloadHum := PARSEJSON(RECEIVEDMSG.PAYLOAD, "humidity");
   Hu := payloadHum/100;
   battery := PARSEJSON(RECEIVEDMSG.PAYLOAD,"battery", true);
   voltage := PARSEJSON(RECEIVEDMSG.PAYLOAD,"voltage", true);
   link := PARSEJSON(RECEIVEDMSG.PAYLOAD,"linkquality", true);
end
Service Attributes
Battery
IF (ISNAN(battery), "-", battery + "%");
Battery voltage
IF (ISNAN(voltage), "-", voltage + "mV");
Atribút
IF (ISNAN(link), "-", link + "lqi");
Connection: Packet Parser → MQTT

Import parameters

Enter these values when you import the XML.

Asked in the appDefault
Mqtt Broker IP address192.168.0.1
Mqtt Broker port1883

Related Documentation

Found a problem with this device template?

Tell us what's wrong, what's missing, or how the template should behave. We rely on your feedback to keep the catalog accurate.

Template · TapHome portal Xiaomi Mi Temperature and Humidity Sensor (WSDCGQ01LM) via Zigbee2MQTT Open this template in the Customer Portal to apply it to one of your homes, or to draft a refinement and submit it back to the catalog. Packet Parser → MQTT View in TapHome portal