[RELEASE] Xiaomi Drivers with Health Status and Zigbee2MQTT

Here's my take on some drivers for a select few battery powered Xiaomi Aqara devices. There are a number of other excellent drivers out there with more complete support of the range, but these are for the devices I own and now use every day.

These are combination drivers and can be used with directly paired Xiaomi devices or those connected via my Zigbee2MQTT Routing Driver.

There's a little backstory below, but due to the faff I've had with Xiaomi products I can only recommend using Xiaomi devices on Hubitat via Zigbee2MQTT. I had partial success for a long time with them directly connected, but they were still troublesome. They are flawless using Zigbee2MQTT.


Search for the keyword "Xiaomi" on Hubitat Package Manager and you should see "Xiaomi Drivers from BirdsLikeWires". Requires HPM v1.8.7 or later. Or install manually from the links below.

If you have more than one driver installed for a particular device and pair it for the first time, there will be a "race condition" and whichever driver "wins" will perform the initial configuration.

This isn't a problem if you're switching between drivers on a device that has already been paired. Just follow the instructions in Device Configuration below.

Mesh Advice

Use Zigbee2MQTT and my Routing Driver. No, honestly, I promise it's the best way. It took me four years and a lot of code writing to come to this conclusion and you don't have to do that! :sweat_smile:

If you're completely insistent you're going to pair them directly to your Hubitat hub... you're going to need an additional hub to dedicate to them.

I've encountered so many issues getting them to work reliably that keeping them on their own separate network and making them available using Hub Mesh is the only directly-connected method I can recommend. My setup was very simple:

I found that even some of Xiaomi's own wired Smart Wall Switches (namely models QBKG22LM and QBKG25LM) will cause mesh instability. Battery devices will become unreliable and then drop completely within a few hours, so you will never find drivers for those here. Instead I use very reliable Samotech modules fitted behind the Wireless Remote Switches.

In theory the Zigbee channel shouldn't matter, but channel 23 was the best I had available, away from my wifi and with a little space between other Zigbee frequencies in use.

The drivers do nothing special to try and keep devices alive and connected. The mesh is either good or it's not and devices should check in every 50-60 minutes with battery readings. These reporting intervals are a firmware default and cannot be changed.

Devices and Features

Some of the devices send a unique transmission (sometimes with battery data) on a short press of the reset button. Where this could be useful it is mapped to a button press and referred to here as the "reset button" feature, to give an extra means of control for "free".

Note: Battery reports only come through every hour, so don't be surprised if you don't see that value appear when you've first paired a device. Give it a few hours and if it's paired correctly, it'll be there.

Xiaomi Aqara Temperature and Humidity Sensor WSDCGQ11LM

Provides temperature, relative humidity, calculated absolute humidity, pressure, pressure direction (rising or falling), reset button, device presence and battery reporting. Tapping reset is mapped as button one.

Xiaomi Aqara Wireless Mini Switch WXKG11LM

Supports push, double push, triple push, quadruple push, quintuple push, reset button, device presence and battery reporting. Tapping reset is the same transmission as the quintuple push, so is also reported as button five.

Xiaomi Aqara Wireless Mini Switch WXKG12LM

Supports push, double push, hold, release, reset button, acceleration (shake), level (calculated from duration held), device presence and battery reporting. Tapping reset is again reported as button five, while acceleration (shake) is reported as button six.

Xiaomi Aqara Wireless Remote Switch WXKG06LM / WXKG07LM

Supports push, double push, hold, long hold, device presence and battery reporting. Left key is button one, right key is button two, both keys together make button three, with each button supporting all four modes of press:

  • Press
  • Double Press
  • Hold (2 seconds)
  • Long Hold (5 seconds, reported as a "released" event)

If you hold a button for more than 10 seconds the device will reset, so don't do that.

The "long hold" feature makes use of a message received from the device if a button is still being held down three seconds after the "held" transmission has been sent. A "hold" is reported after two seconds, therefore this "long hold" message is triggered after five seconds.

Given that there is no genuine "released" message supported by the device it would seem the best way to capture this functionality is to consider it an "autorelease" of the button. Therefore a long hold is reported as the held button being released.

We're basically getting a fourth type of press for free! :tada:

Xiaomi Mijia Smart Light Sensor GZCGQ01LM

Supports illuminance, illuminance direction (brightening, darkening), device presence and battery reporting. Tapping reset is mapped as button one.


Reserved post just in case.

1 Like

I love your simple and clean approach! :+1:
Thanx a lot!

P.S.: "Just because you can doesn't mean you should." :rofl:

1 Like

Thank you @Jost, simple and reliable are my main two goals!

Well, that and squeezing every last feature possibility out of a device is also something I enjoy, which is why I was conflicted about including those temperature sensor readings! But I’ve not been able to make them reliable, the variability appears non-linear, so that’s in the bin for now. :joy:


I've been using "Xiaomi Aqara Mijia Sensors and Switches" which has done well - I only currently have one Aquara device (a temp/humidity sensor). I switched over to your driver and really like the results - a lot cleaner! Ty.

I recently installed a small he setup for a friend - installed was the Model WSDCGQ11LM manufactured by Aqara - I thought it was identical to the one I have here in my home. Her's in newer by about 3 months.
They came in what look like the same box - we paid the same price, I even forwarded the URL from Amazon - What could be different?

Different device drivers?

no! and that's the rub. I recently saw the post from @birdslikewires about his driver release and jumped on it. My HE and device took to it like a duck in water. The big thing was it reduced an error on 'battery' which was causing my personal battery management app angst.

I remoted my friends location, and applied the same driver to her's. and the result in the screen above describes the difference I see. The only difference I'm aware of is the age of purchase... a difference of 60-90 days. I think I previously mentioned, same price, same box... just ... not the same!

Doesn't look like hers is fully initialized...maybe hit Configure again.

I was going to say the same thing. I don't think Configure will fix it though. You may have to remove/add again so it initializes.

Seen this before even with older drivers, sometimes they just don't initilize properly.

I have a love/hate relationship with these devices and am now slowly phasing them out.

1 Like

Hey @jshimota, looks like we all have the same device, though you've got some extras in the Device Details section which would have been added by other drivers. They'll make no difference to the one here, though.

If you've swapped driver from the dropdown menu, just make sure you hit Configure afterwards, as suggested by @thebearmay and @gavincampbell. That sets up a few things and initialises the values.

It can take up to an hour before battery reports are received, but if you want to speed things up just short-press the reset button (that should generate a "pushed" message) and ask your friend to breathe into the sensor. The button press may send battery data and the increased temperature and humidity should generate the other messages.

None of that last paragraph is necessary though, if you're remote then just make sure that Configure button is pressed and the rest will take care of itself over the next hour or two.

hmm. I'm ultra cheap so this was a 'smart' buy. I've got to go onsite and rebuild her door lock and add a few things (she's so happy with the automation she wants an Alexa in the garage so she can listen to music while doing laundry), an add of a contact sensor to the garage door, etc.... She just found out her washer dryer are 'smart'. So we'll also be exploring that...

@birdslikewires Will do! excellent recommendations to cause a report from the device. She's at work, so I can't try anything for a few hours, which will in turn give the device time to report possibly.

Nice eyeball on the extra values! I was using Markus' ohlalalabs driver previously and didn't clear states/attributes - just switched driver and mashed config /refresh... The new driver is less cumbersome, and seems quicker - but thats just subjective opinion on my part. We have 2 more of these devices to install so it will be very interesting! (going to use them to control the bath fan for humidity). Thank you for returning my call!

1 Like

With quite a lot of Aqara devices, Samotech dimmer modules & Tradfri repeaters on my mesh I'll be installing forthwith! Thank you.


Added the Mijia Smart Light Sensor GZCGQ01LM and implemented pressure direction (rising and falling) to the Aqara Temperature and Humidity Sensor WSDCGQ11LM.

Just thrown some links onto your comment there! :wink:

There's a Tradfri Repeater "driver" and a dedicated Samotech driver for the SM308 series that I've put together recently.


Added support for the single-key Wireless Remote Switch WXKG06LM. The WXKG06LM (one key) and WXKG07LM (two keys) are largely identical in message format, so they've been integrated into the same driver.

Also added "autorelease" to the WXKG06LM / WXKG07LM driver. This is essentially "long hold" support, using a message which is always transmitted three seconds after a "hold" is detected. Seeing as these devices don't support real "released" messages, we use that "released" attribute to essentially report a long hold instead.

So for each key four press types are now supported:

  • Press
  • Double Press
  • Hold (2 seconds)
  • Long Hold (5 seconds, reported as a "released" event)

If you hold a button for more than 10 seconds the device will reset, so don't do that.

I usually use "hold" events to trigger a local group of devices to switch off. I'm now using this "long hold" to turn off related devices elsewhere in the house. Just remember that a "long hold / autorelease" always occurs in addition to the prior "hold" event.


Before I start down the path of pairing this device with a driver can someone confirm if I will be able to have an immediate changes in lux reported (specifically - over a certain threshold and even better if it could also require a certain number of milliseconds over that threshold).

OR.....is this device and ANY driver for it just limited to getting a reading every X time increment.

Use Case: Think flashlight or headlights shining through a window into a pitch black space (and yeah, the "duration of the luminescence being above the threshold" was how I was thinking :thinking: I'd thwart triggering during a lightening storm).

I realize the solution here might well be "part Driver & part Rule". I just was wondering if anyone can see an impasse getting there knowing what they know about the device and this driver.

Thanks in advance.

I have 4 of these and I find them quite responsive. They do seem to report immediately on a significant lux change.

I didn't use this driver before (*), but I just installed it and it doesn't seem to have any special setting for lux. None of them seem to.

(*) I was using Markus' driver on 2 and Chirpy's driver on the the other 2. I switched one to use this driver.

1 Like


Same experience as @jlv. I have at least 4 of these. They are very responsive. Please look at the log file below - it indicates increases in a Lutron Caseta dimmer and the corresponding lux increases detected by this sensor. The starting lux value for the sensor was 34 (when the dimmer was off).

As the log shows, dimmer level changes are detected within < 10 seconds.

Thanks guys. Appreciate the input. Got one on reading some of your earlier dialogues elsewhere. Just wanting to make sure before I get knee deep in making it work that there isn't something I'll be banging my head against w/o realizing.

1 Like