Xiaomi / Aqara ZigBee device drivers (possibly may no longer be maintained)

Thanks for the ref to the Button implementation! I’ll start digging…

Thanks for your work on porting all of these! And thanks to Hubitat for modifying their ZigBee stack to, apparently, now work with these devices (haven’t had any fall off since that update).

With regard to the buttons, has anyone figured out how to use them? Neither the unofficial Hubitat port of webCoRE nor Rule Machine seem to work with them: if there’s a “button” capability in RM, I can’t find it, and these don’t show up as buttons at all in webCoRE. (I’m using one as a doorbell and want LANnouncer to chime and speak, so there are probably other ways to do this, which I would also be interested in, but I don’t want to hijack this thread for my specific use and am just curious in general if/how people are able to actually use these.)

I only have an "original" (round) Xiaomi Button, and it's working just fine in both Rule Machine and also Button Controller. Here's where I see it available in Rule Machine, when I'm in the Select Tigger Events menu:

As for WebCoRE - keeping in mind that it is not "officially" working on Hubitat yet - I don't use it personally, but @ajayjohnm confirmed that the latest beta of the "original" Xiaomi Button device driver is working for him in WebCoRE, and so I've pushed that new beta version through on GitHub so it can be copied from the link for the "original" Xiaomi Button device driver code (found up in the very first post of this thread.)

The Xiaomi Aqara Button device driver was just finished by @brianspranger, and although I don't have one of them, it should also work just great with Rule Machine, WebCoRE, etc.

Does that help?

This isn’t pretty but it works for a button trigger in WebCoRE; pushed and buttonPressed will show up for the Xiaomi button; here is an example for triggering off of button ‘2’ (a double click):

Xiaomi Button 1’s pushed is equal to 2
Xiaomi Button 1’s buttonPressed changes

It does make sense, and that's what I'd expect, but I don't have "Button" as a capability in Rule Machine at all:


I do in webCoRE, but neither my square nor round buttons show up (but a different button does). This isn't as surprising to me since I know Hubitat's button model is different from ST's and I'm not sure what this unofficial webCoRE fork supports. Maybe I should ask support about my Rule Machine problem, however, unless I'm missing something obvious. (I should add that I'm using the latest drivers I can find on Github.)

Hubitat implements buttons differently from ST…

Since @brianspranger discovered that a pushed - button 0 event is valid, I realize I could yet again rework the “original” Xiaomi Button driver to use button 0 as a “released” state that always happens when the button is released or immediately after a multi-click. Would that be a “prettier” way of doing it for WebCoRE use?

Maybe @ajayjohnm could chime in here, because my latest code revision is working for him. I really need to get WebCoRE installed to fully understand the interaction because it’s clearly not the same as what Rule Machine, Button Controller, and other apps are using for button events.

Yes, it seems you are missing something. :smile: You cannot use a button as a Condition in Rule Machine. You need to use it as a Trigger Event (as seen in my above screenshot.) Let us know if that works for you.

Oh, sweet baby clam juice, I just don’t know how to use Rule Machine. :rofl: Thanks for catching my mistake! (I never used RM on ST because CoRE and very soon webCoRE was “the thing” by the time I got tired of writing custom SmartApps every time, so you’ll have to excuse my new-ness to RM here.) Thanks!

Sorry if I wasn’t clear, it is working for me in WebCoRE. The Xiaomi button does show up (it does need to be added to the ‘enabled devices’ list in the WebCoRE app on Hubitat, but that is expected). I’m fine with the driver as is; now that I’ve worked out which states change and which are static between button presses it’s easy to use with WebCoRE as it is currently implemented.

I have to say this driver works really well with the Xiaomi button on Hubitat. I still have yet to experience a single missed click, unlike every other button device I’ve used with ST (including the minimote and the Xiaomis I’ve used on ST). It never seems to require a redundant wakeup click no matter how long its been since I’ve last used it. If I can manage to change the battery without destroying the device when it eventually wears out , it will have been the best $6 I smart thing I ever purchased.


Since @brianspranger discovered that a pushed - button 0 event is valid, I realize I could yet again rework the “original” Xiaomi Button driver to use button 0 as a “released” state that always happens when the button is released or immediately after a multi-click. Would that be a “prettier” way of doing it for WebCoRE use?

@veeceeoh I think that would be a more cleaner way of reporting clicks, but I also have doubts on whether it would continue to be possible to use all the events that you opened up for us, once the pushed value starts getting reset to 0. I think some testing would be needed there and I’d be glad to help.

Maybe @ajayjohnm could chime in here, because my latest code revision is working for him. I really need to get WebCoRE installed to fully understand the interaction because it’s clearly not the same as what Rule Machine, Button Controller, and other apps are using for button events.

@bertabcd1234 In webCoRE, buttons only show up in the ‘Holdable Buttons’, ‘Sensors’ and ‘Battery Powered Devices’ sections. If you are currently looking into the ‘Buttons’ section of the Available Devices menu, then you won’t see your button there.

As for using button clicks as triggers, you always need to use a combination of conditions to pin-point what action took place. For e.g. to use a single button click trigger, use…
If buttonReleased changes
If buttonHeld did not change
If pushed = 1

Lastly, @veeceeoh, if you want to get started with webCoRE, @ogiewon has done all of us a big favor and posted all the fixes and modifications needed to the webCoRE code, to make it run on Hubitat,

1 Like

In that case, I think I’ll wait until I get webCoRE set up on my Hubitat, and then do some testing myself. I’ve been keeping tabs on the thread with all the fixes needed to get it working, so I’ll start with that, thanks!

1 Like

[RELEASE] v0.5 of Xiaomi Aqara Smart Dual Button Light Switch Device Driver
(Only for the wireless 2 button model WXKG02LM)
This device driver was crafted by @gn0st1c (on Github - not sure of his username on here!)

For convenience please copy the driver code from this direct link.

The Aqara Smart Dual Button Light Switch model WXKG02LM is a battery-powered, wall-surface two-button ZigBee device. The hardware supports unique messages for pressing the left button, right button, and both buttons at the same time, but does not have momentary ("hold") or multi-click support.

Here's what it looks like: aqara2button

And here's what happens with each kind button press:

Type of press Button Event(s)
Left button press button 1
Right button press button 2
Both pressed button 3
Multi-click Not supported*
Hold Not supported (same behavior as single press)

*Note: a 6-press multi-click appears to generate a status message resulting in the battery voltage being updated

Other Features:

  • The date/time of the most recent button is sent as a lastPressed (human readable) and lastPressedDate (java format) which should help with WebCoRE use
  • Battery replacement date tracking, stored in batteryLastReplaced state
  • Commands / Preferences include:
    • A Reset Battery Replaced Date command to track battery life
    • Date / 24-hour clock settings for display of lastCheckin
    • Min/Max voltage values used to calculate the battery percentage
    • Display log message toggle setting

Notes / Limitations:

  • I have had great difficulty pairing this device, and the pairing initialization process has only completed twice out of dozens of attempts. However, there are a couple of ways I have found it can be added "manually". Please see the special pairing instructions below.
  • This device driver is not final, and some features or preferences may be added / removed
  • When viewing the device details page in the Hubitat web interface, there is a push command which is not used in this driver, so clicking it has no effect. Here's what it looks like:

Special Pairing Instructions:

  1. In your web browser, open up two tabs, one displaying your Hubitat's Device list, and the other with the ZigBee Logging page (in Settings --> Zigbee Information --> Zigbee Logging)
  2. Start "Discover Devices" in the tab with your Hubitat's Device list.
  3. Hold down either button of the Xiaomi Smart Light Switch, until the LED flashes.
  4. The LED will flash, then a pause, and either flash consecutively 3 times, or flash once. Unlike all other Xiaomi devices, a single flash seems to indicate a successful connection. Either way, the best way to know is by then short-pressing either button. If the LED flashes just once as you press a button, then it's connected, but if it flashes twice, then go back to step 3 (hold a button until LED flashes).
  5. In the Device page, when the Hubitat recognizes the switch, it will display its Zigbee ID. Make sure to copy or write down this ID.
  6. In the ZigBee Logging page, look for log entries that start with a 4-digit hexadecimal number. It will also list that hexadecimal number above the log entries as well. The way to be sure you've got the right number is that log entries should be added if you press a button. Copy or write down this number also.
  7. Back in the Device page, if the switch hasn't finished initializing, there are two things to try:
  8. Click the Add Virtual Device button, but don't enter in any information. Just click the << Device List link near the top. If you're lucky, the hub secretly added the switch to your device list. In my case it was recognized as a Xiaomi Temperature Humidity Sensor. If you do see a new device, then view its Device Details by clicking on its name in the left column. Then you can change the device Type to "Xiaomi Aqara Dual Button Light Switch" using the pop-up list in the lower right corner of the page. Click the save button on the lower right, and then the switch can be used.
  9. If the hub didn't secretly add the switch to your device list, you can add it manually. Go back to the Device List page, and click the Add Virtual Device button. Enter a name for the switch, the Zigbee ID you wrote down, and type the hexadecimal number into the Device Network Id field. Finally select the device Type: "Xiaomi Aqara Dual Button Light Switch", and click the save button to add the switch to your devices list.
  10. Whew! You did it! I can post screenshots if people hae trouble with this.

To get technical: they're "zigbee compliant," but zigbee allows manufacturers to use proprietary coding without requiring that they also provide all the standard basic functions.

This is very different from zwave, which requires that manufacturers first provide all the standard basic functions, and can then layer their own proprietary stuff on top.

Both hubitat and SmartThings use the Zigbee Home Automation ("ZHA") "profile.

The original Xiaomi Devices never said they used the ZHA profile, and never promised to work with anything except their own Gateway.

The Aqara devices are supposed to be using the ZHA profile, and they're certainly closer to it than the originals, but there are still some proprietary features in the optional areas, and that can interfere with the way they work on a fully standardized platform.

They aren't alone in that: the IKEA Tradfrii line has very similar design issues, although the symptoms are somewhat different.

More on profiles:


Huh. Interesting. So a standard with no standards. :smiley:

It definitely has standards, but they are at a different level than Z wave standards. It’s actually much more similar to Wi-Fi. There’s no guarantee at all that two different home automation devices using Wi-Fi will be able to understand each other. The message content is not part of the Wi-Fi protocol standard. Just the transmission format. The same is true for top level Zigbee. It’s a message transport protocol, not a message content definition.

Zigbee goes farther than Wi-Fi by providing the profiles, which do standardize the message content. But their use is optional.

I realize. I meant with regards to communication and function. :slight_smile:

Interesting read, but the last comment in that article confuses me. Zigbee 3.0 is supposed to be able to join legacy networks, and legacy devices are supposed to be able to join 3.0 networks. Here’s a Silicon Labs KB quote to that, I believe the Zigbee alliance website makes the same statement.

“Zigbee 3.0 has been designed to allow for interoperability between zigbee 3.0 devices and legacy HA and ZLL devices. With proper configuration, ZLL and HA devices can join zigbee 3.0 networks and similarly zigbee 3.0 devices have the functionality to join legacy legacy networks operating with either ZLL or HA networking. This KBA will help you understand the configurations necessary for allowing this.“

How does this differ from “backward compatible” in your post?

Lastly, @veeceeoh, if you want to get started with webCoRE, @ogiewon has done all of us a big favor and posted all the fixes and modifications needed to the webCoRE code, to make it run on Hubitat,

Forgot to post a link to what I was referring. Given below is the fork that can be directly pasted and used in Hubitat. (Credits go to Ogiewon and other who contributed to it.)

1 Like

Zigbee 3.0 is a big topic with a lot of tiny technical details. :sunglasses: Since neither the hubitat hub nor the Xiaomi devices are using zigbee 3.0, I don’t want to hijack this thread. Why don’t you start a new thread to discuss Zigbee 3.0 and I’ll be happy to continue there.

1 Like

As always @veeceeoh, thanks for the driver!

I’ve got two questions. hopefully they’re both quick!

  1. is there an air-pressure capability? Currently, the driver for the Aqara temp/humidity sensors only report the “Temperature Measurement” abd “Relative Humidity Measurement” but do expose a pressure value on events that get fired off. I’ve managed to update one of the apps i use (the MQTT bridge: [PORT] Hubitat MQTT Bridge) to also use the pressure value… but it got me thinking as to why the driver only reports 2 of the the devices three capabilities.

  2. is there a “released” event for the aquara buttons when they’re configured in momentary mode? I see the runIn() call calling ReleaseButton which should fire off a call to getContactResult which should log to the event log a Button was released message, right? I don’t see these “released” messages showing up in the event log for any given button, but i do see the Button was single/double/tripple clicked messages. Thoughts on what i might be doing wrong (is my ReleaseTime value set too low (currently 1 sec?)? Or is there something else that i can do / help with to figure out why release events are not showing?

Thanks for you time. Appreciate all the effort :slight_smile:

Download the Hubitat app