[RELEASE] Xiaomi Aqara and Mijia Drivers with Device Presence

Here's my take on 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.

There's a little backstory below, but due to the faff I've had with Xiaomi products I will only post drivers here that work together and will only comment on things I have actually tested and experienced myself, however limited that may be.


Search on Hubitat Package Manager v1.8.7 or later for "xiaomi", "aqara" or "mijia" and you should see Xiaomi Aqara and Mijia Drivers from BirdsLikeWires.

Or straight from the BirdsLikeWires GitHub if you like to do things manually.


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.

Device Configuration

If you are switching between drivers you will need to reconfigure the device. This clears out old variables and may also update the settings on the device itself.

After switching drivers from the Device page under the Type dropdown menu, tap the reset button on the device and click the Configure button on the driver page within a couple of seconds. A temporary configuration status will appear with a value of "set". If there are configuration changes to the device itself this will change to "received" within a few seconds.

Mesh Advice

I didn't think I would ever write anything for these devices due to my inability to have them stay on my Hubitat mesh, but when I discovered the limitations of interfacing with them on their own hubs I had to give it another shot. I'm now extremely happy with them despite the four years (yeah, I know) it has taken to get here.

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 method I can recommend. My setup is very simple:

Then I add no other devices apart from those which I've written drivers for, or that have sat on the mesh for a week with the generic system "Device" driver in debug mode so I can scowl at them. If a driver appears above then I've had success keeping the devices happy together.

I found and reliably repeated that the 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".

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:

1 Like

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

Download the Hubitat app