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

veeceeoh · October 30, 2018, 11:18pm

ANNOUNCEMENT: Multiple Device Driver Betas

It's been quite a while since I've made any updates to the Xiaomi device drivers for Hubitat. In the meantime, the Hubitat Button Implementation has been updated, Hubitat added their Dashboard allowing for custom device driver attributes to be displayed (such as a human-readable time/date stamp that would be nice to have as @mike has pointed out), more is known about the battery typical voltage range seen in Xiaomi devices, and Xiaomi has released new revisions of a few of their button devices.

So I'm currently in the process of updating all of the Xiaomi device drivers to address all of these things, starting with two beta releases today: A brand new device driver that replaces the 2-button Aqara Smart Light Switch driver, and an update to the Aqara Button device driver.

[BETA] v0.55b of Xiaomi Aqara Button Device Driver

With many thanks to @guyeeba for reporting on the new revision of the model WXKG11LM Aqara Button and the code changes to make it work, I am releasing this beta of the Aqara Button driver. At the same time, I am updating the way this driver produces button events with the model WXKG12LM Aqara Button.

The beta device driver code can be copied directly from here.

Here are charts showing what events are generated for actions on each of the three models of Aqara buttons:

Aqara Button - Model WXKG11LM (original revision)

Action	Event	Button #	Notes
Single-click	`pushed`	1
Double-click	`pushed`	2
Triple-click	`pushed`	3
Quad-click	`pushed`	4
Release	`pushed`	0	Generated by device driver with 2 second (user-adjustable) timer

Notes: The functionality for this model remains the same as before, even though it doesn't make use of the Hubitat-specific doubleTapped and released events. The reason for this is because of the additional triple- and quad-click functions supported by the hardware. If anyone thinks there are very good reasons to change it so that a double click results in a button 1 doubleTapped event, I'm all ears.

Aqara Button - Model WXKG11LM (new revision)

Action	Event	Button #
Single-click	`pushed`	1
Hold	`held`	1
Double-click	`doubleTapped`	1
Release	`released`	1

Note: I don't own this model, but I assume the hardware button held message is sent after 400ms like with Model WXKG12LM.

Aqara Button - Model WXKG12LM

Action	Event	Button #
Single-click	`pushed`	1
Hold	`held`	1
Double-click	`doubleTapped`	1
Release	`released`	1
Shake	`pushed`	2

Note: The hardware button held message is sent after the button has been held for 400ms.

Changes:

added compatibility for the new revision of Model WXKG11LM (ZigBee reported model: lumi.remote.b1acn01) with help from Hubitat user @guyeeba (Thanks again!!)
changed event type functionality for Model WXKG12LM to include DoubleTapableButton and ReleasableButton capabilities, so that pushed, held , doubleTapped , and released events are all assigned to button 1 , and shaking the button results in a button 2 pushed event.
added a routine to determine model at time pairing and set appropriate number of buttons available to Hubitat apps
added buttonPressedTime, buttonHeldTime, and buttonReleasedTime attributes used for generating human-readable date/time stamp events which can be utilized for Habitat dashboard display
renamed updateCoREEvent() to updateDateTimeStamp
changed default battery voltage range used for calculating percentage to 2.9 V minimum / 3.05 V maximum
minor formatting / comments fixes

[BETA] v0.55b of NEW Aqara Wireless Smart Light Switch Device Driver

Based on the 2-button Aqara Smart Light Switch device driver, his new driver adds support for the 1-button model (WXKG03LM). Note that this driver only supports the wireless battery-powered light switches, not the mains-powered versions. Many thanks to @Peter for his help in contributing to and testing the new code for the 1-button model.

The beta device driver code can be copied directly from here.

Here are charts showing what events are generated for actions on each of the two models of Aqara Wireless Smart Light Switches:

1-button model WXKG03LM

Action	Event	Button #
Single-click	`pushed`	1
Hold	`held`	1
Double-click	`doubleTapped`	1

Note: Holding the button for more than 15-20 seconds puts the device into pairing mode.

2-button model WXKG02LM

Action	Event	Button #
Press left button	`pushed`	1
Press right button	`pushed`	2
Press both buttons	`pushed`	3

Changes (to the code of the existing 2-button Aqara Smart Light Switch device driver)

added support for and parsing of button press, double-click, and hold messages sent by model WXKG03LM (1 button) which result in Hubitat button 1 pushed , doubleTapped , and held events, respectively
added a routine to determine model at time pairing and set appropriate number of buttons available to Hubitat apps
added attributes buttonDoubleTapped and buttonHeld to contain the most recent Epoch Time date/time stamps of corresponding button events that can be used in addition to buttonPressed in WebCoRE pistons
added buttonPressedTime, buttonDoubleTappedTime, and buttonReleasedTime attributes used for generating human-readable date/time stamp events which can be utilized for Habitat dashboard display
renamed updateCoREEvent() to updateDateTimeStamp
changed default battery voltage range used for calculating percentage to 2.9 V minimum / 3.05 V maximum
minor formatting / comments fixes

NOTE: When this new device driver goes out of beta, I plan to "retire" the old 2-button Wireless Smart Light Switch device driver.

Any feedback and/or suggestions on these beta device drivers is both welcome and much appreciated!

mike · October 30, 2018, 11:29pm

@veeceeoh

Looking forward to them. I just quickly had a look with my non Aqara buttons, and the new drivers seem to work well for them. Double click, triple click etc do update the Button last pressed (and button number) in a human readable format, but single click does not.

The model number is WXKG01LM.

Rxich · October 31, 2018, 6:42pm

Keith- You're doing fantastic work here and I really appreciate your incorporating the model numbers, as it seems you never know what will show up at your door after ordering. Just now on gearbest I see 2 aqara door/window sensors, one is Aqara and another is AQara. I'm not sure what the heck they're trying to differentiate.
Some sensors are referred to as international, anyone know what that indicates? possibly meaning NOT locked to china, I don't know. Plus the model numbers shown in website pics will not necessarily match what gets delivered to you "smart home", but your house probably already knew that

Anyone-how can we donate to these developers who give so much of their time?

saxnix · November 1, 2018, 2:01am

Thanks @veeceeoh. I have the

Device pages now successfully showing human-readable data

Also

+1 to this. I would like to shout a drink for @veeceeoh and @Cobra.

gavincampbell · November 1, 2018, 12:58pm

Do you happen to see multiple events firing at once on your door sensor. I've been trying to figure out why my chime would fire multiple times when a door opens and closes and see in the contact sensor that it will fire an open/close/open sometimes when a door is opened (or reverse when its closed). Its more evident on a sliding door where the magnet would slide across as it opens and closes but I also see it if the magnet is just pulled away.

Here is an example of a log from a simple open event. You can see it fires multiple times ms appart. Any ideas?

[dev:1128](http://hubitat.localdomain/logs#dev1128)2018-11-01 08:51:49.589 am [debug](http://hubitat.localdomain/device/edit/1128)Front Door Sensor: Creating event [name:contact, value:open, isStateChange:true, descriptionText:Contact was opened]

[dev:1128](http://hubitat.localdomain/logs#dev1128)2018-11-01 08:51:49.587 am [info](http://hubitat.localdomain/device/edit/1128)Front Door Sensor: Contact was opened

[dev:1128](http://hubitat.localdomain/logs#dev1128)2018-11-01 08:51:49.584 am [debug](http://hubitat.localdomain/device/edit/1128)Front Door Sensor: Setting lastOpened to current date/time for webCoRE

[dev:1128](http://hubitat.localdomain/logs#dev1128)2018-11-01 08:51:49.582 am [debug](http://hubitat.localdomain/device/edit/1128)Front Door Sensor: Parsing message: read attr - raw: 2CE00100060800001001, dni: 2CE0, endpoint: 01, cluster: 0006, size: 08, attrId: 0000, encoding: 10, value: 01

[dev:1128](http://hubitat.localdomain/logs#dev1128)2018-11-01 08:51:49.500 am [debug](http://hubitat.localdomain/device/edit/1128)Front Door Sensor: Parsing message: read attr - raw: 2CE00100001801FF42090421A8130A212759, dni: 2CE0, endpoint: 01, cluster: 0000, size: 18, attrId: FF01, encoding: 42, value: 090421A8130A212759

[dev:1128](http://hubitat.localdomain/logs#dev1128)2018-11-01 08:51:49.488 am [debug](http://hubitat.localdomain/device/edit/1128)Front Door Sensor: Creating event [name:contact, value:closed, isStateChange:true, descriptionText:Contact was closed]

[dev:1128](http://hubitat.localdomain/logs#dev1128)2018-11-01 08:51:49.486 am [info](http://hubitat.localdomain/device/edit/1128)Front Door Sensor: Contact was closed

[dev:1128](http://hubitat.localdomain/logs#dev1128)2018-11-01 08:51:49.485 am [debug](http://hubitat.localdomain/device/edit/1128)Front Door Sensor: Setting lastClosed to current date/time for webCoRE

[dev:1128](http://hubitat.localdomain/logs#dev1128)2018-11-01 08:51:49.483 am [debug](http://hubitat.localdomain/device/edit/1128)Front Door Sensor: Parsing message: read attr - raw: 2CE00100060800001000, dni: 2CE0, endpoint: 01, cluster: 0006, size: 08, attrId: 0000, encoding: 10, value: 00

[dev:1128](http://hubitat.localdomain/logs#dev1128)2018-11-01 08:51:49.456 am [debug](http://hubitat.localdomain/device/edit/1128)Front Door Sensor: Creating event [name:contact, value:open, isStateChange:true, descriptionText:Contact was opened]

[dev:1128](http://hubitat.localdomain/logs#dev1128)2018-11-01 08:51:49.454 am [info](http://hubitat.localdomain/device/edit/1128)Front Door Sensor: Contact was opened

[dev:1128](http://hubitat.localdomain/logs#dev1128)2018-11-01 08:51:49.451 am [debug](http://hubitat.localdomain/device/edit/1128)Front Door Sensor: Setting lastOpened to current date/time for webCoRE

[dev:1128](http://hubitat.localdomain/logs#dev1128)2018-11-01 08:51:49.449 am [debug](http://hubitat.localdomain/device/edit/1128)Front Door Sensor: Parsing message: read attr - raw: 2CE00100060800001001, dni: 2CE0, endpoint: 01, cluster: 0006, size: 08, attrId: 0000, encoding: 10, value: 01

veeceeoh · November 1, 2018, 6:53pm

Two things:

First, I've seen randomly doubled up messages from most of my Xiaomi devices. I have no idea why that happens, but it isn't terribly often.

Second, for the door/window sensors, position and orientation are critical in terms of getting correct open & close messages. Remember that they use a magnetically activated physical contact, called a reed switch.

Reed switches react differently depending on the orientation and direction of travel of the activating magnet, as seen in this diagram (adapted from this PDF from HSI Sensing Company):

What the above diagram doesn't show is that for cheaper reed switch components, in the area between the Pull-In and Drop-Out lines, the switch contacts can oscillate between the open and close positions, which will result in a burst of open/close messages, or "false positives".

I have a couple Samsung SmartThings multi sensors and while testing magnet positions have seen this behavior with them as well, but it has been noted by Frédéric Dubois, creator of the ZiGate USB ZigBee hub stick, in his testing of various Xiaomi devices. (Linked sites in French, use Google Translate)

From my testing and experience with both the Xiaomi "original" and Aqara contact sensors, I would have to guess that they were not designed for applications where the magnet will slide by.

The only thing I can do to help with the false positives is to filter out repeat open or close messages until the "opposite" message is received. But this wouldn't help with cases when the reed switch is oscillating slowly, and may not work in cases where repeat messages arrive at extremely rapid speeds.

If you'd like to test a specially modified device driver to see how well this filter works, please let me know and I'll PM the modified code for you to give it a try.

gavincampbell · November 1, 2018, 7:02pm

I'll give a modified driver a shot and see if that helps. My work around's haven't been reliable at all.

What I did in my app was put in a marker since the last state change and filter out everything that happened in the last second or so. But I find it still is triggering multiple times. In my case I have chime and I have heard it triggered as many as 4 times on one door open. Not sure what more I can do. Some of the doors swing open and some are slide. I've change the slide orientation so they pull away and still get multiple triggers from the sensors.

I never use to have this issue though. I can't recall when it started but lately its been even worse and more consistent.

veeceeoh · November 1, 2018, 8:29pm

Just a wild guess, but battery voltage (decreasing over time) may change the behavior of the reed switch.

njanda · November 2, 2018, 7:40pm

I’ve similar behavior on my front door sensor, an Iris contact sensor and have had to tweak the location of the magnet in relation to the reed to limit the false triggering.
If a driver could sense the first state change and then stop reporting for 100ms, that might fix things.

bangali · November 6, 2018, 2:26am

@veeceeoh any chance of a driver for the aqara vibration sensor please?

sharing the logged data here if that helps in anyway with your decision.

here is the debug messages from the device. the 1st and 3rd messages are on triggering vibration. the 2nd and 4th seem to be auto generated about 4 mins after each vibration:

2018-11-05 18:12:28.436:debug Vibration Sensor: Parsing description: read attr - raw: 75E70101010E05052300001100, dni: 75E7, endpoint: 01, cluster: 0101, size: 0E, attrId: 0505, encoding: 23, value: 00110000

2018-11-05 18:08:28.210:debug Vibration Sensor: Parsing description: read attr - raw: 75E70101010A5500210100, dni: 75E7, endpoint: 01, cluster: 0101, size: 0A, attrId: 0055, encoding: 21, value: 0001

2018-11-05 18:07:14.641:debug Vibration Sensor: Parsing description: read attr - raw: 75E70101010E05052300001800, dni: 75E7, endpoint: 01, cluster: 0101, size: 0E, attrId: 0505, encoding: 23, value: 00180000

2018-11-05 18:03:13.786:debug Vibration Sensor: Parsing description: read attr - raw: 75E70101010A5500210100, dni: 75E7, endpoint: 01, cluster: 0101, size: 0A, attrId: 0055, encoding: 21, value: 0001

here is the data from the device:

endpointId: 01
application:
model: lumi.vibration.aq1
manufacturer:

thank you.

veeceeoh · November 6, 2018, 6:18pm

Thanks for the request and the debug log output.

Actually, I own two of the new Aqara Vibration Sensors and have been working on a SmartThings device handler for over a month now, and will be porting it to Hubitat quite soon.

These sensors are somewhat more complex that any other Xiaomi devices, and it's taken reverse-engineering by different people to pull together all the information necessary to create device drivers on different HA platforms. For a really "fun" and technical read on this new Xiaomi device, check out this GitHub comment thread:

Because Hubitat doesn't have a mobile app UI with tile "buttons" that can be assigned functions, I am looking at possibly making a companion App for the Xiaomi Vibration sensors, for the functions of setting open/close angle positions, and tracking of what I'm calling "activity report" values. For the time being, though, I will probably just make use of function call buttons in the device driver page for users to set open/close positions (if they choose to use that functionality of the sensor.)

EDIT: I have released a beta device driver, a few posts down, here.

eibyer · November 9, 2018, 10:14pm

I was so thrilled that my leak sensors were connected for approx 14 days then they all dropped off at the same time. I re-paired them but it only lasted one day the next time around.

bertabcd1234 · November 9, 2018, 11:11pm

There are some posts here on the subject if you do more searching, but the first post in this thread is probably the best resource: Xiaomi & Aqara Devices - Pairing & Keeping them connected

In short, you'll want to have repeaters because they are sensitive to "falling off" the network, but you also want to make sure your repeaters are known to play well with Xiaomi devices (they are not standard and many repeaters don't handle them reliably--the Hubitat hub didn't either until an early firmware update). Unfortunately, there are few. An Xbee is quite reliable but requires some assembly; most/all of the others are select smart bulbs (despite these reports, I'd still be careful since many are known to behave poorly on ZHA networks) and a discontinued Sylvania plug whose newer, incompatible revision is likely the only one you'll find.

eibyer · November 10, 2018, 12:12am

Thanks! I took a quick look and the one repeater I have is not compatible lol. It's a peanut plug.

Edit: oh man, even the Iris plug I just got from Lowe's clearance is not compatible.

SmartHomePrimer · November 10, 2018, 3:13am

Sylvania Smart + (not type A) is compatible. Ikea Trådfi light bulbs are said to be compatible, so perhaps their outlet shipping soon will be too. I asked some of the europeans on the ST forum that have already received the plugs, if they have Xiaomi devices and could map their network to see if their working for that, but I've had no response.

eibyer · November 10, 2018, 3:27am

I'm trying to digest the xbee info in other threads, it looks interesting except for the wait on the parts.

SmartHomePrimer · November 10, 2018, 5:24am

Yep. Still waiting myself. Months now. If you're in the US you have a better chance getting parts than me though. Also if you go for a Zigbee 2 version instead of the Zigbee 3 version I'm waiting on, then it will be faster.

The Zigbee 2 versions will work just fine and do what you need. I'm just buying a future is all my wait is about.

eibyer · November 11, 2018, 8:25pm

I'm excited to give it a try. I ordered an xbee s2 and a waveshare usb adapter from ebay so we'll see if this helps my xiaomi sensors.

bill · November 13, 2018, 9:54pm

what is the status of the xiaomi 2018 aqara vibration sensor on hubitat? I have an application for 6 of them, but I don't want to buy them until I'm sure they're supported. Thx

veeceeoh · November 14, 2018, 6:46am

[BETA] v0.5b of NEW Aqara Vibration Sensor Device Driver

The beta device driver code can be found here.

This sensor has quite a variety of features, which can be used in a number of ways / applications. Here is a chart to show how its functions are mapped to Hubitat events that can then be used with Apps for various automations:

Sensor Function	Hubitat event	Notes
Vibration/Shock Detected	`motion = active`	`motion inactive` is timer-based
Tilt Detected	`acceleration = active`	`acceleration inactive` is timer-based
Tilt Angle	`tiltAngle =` value	Custom attribute (see notes below)
Drop Detected	`button 1 = pushed`
XYZ accelerometer values	`contact = open/closed`	see notes below
Activity Report values	Custom attribute	see notes below
Change sensitivity level	n/a	not yet working

Notes:

Sensor Status: Purely for use in a Hubitat Dashboard, the custom attribute sensorStatus can be used for displaying the following states: Stationary, Vibration, Tilt, and Drop. The Open / Close states are not displayed because they can occur simultaneously during a vibration detected (motion = active) state.
Vibration/Shock detection: The sensor does not seem to work well for clothes washer / dryer cycle detection, and also no message is sent when the sensor is stationary. If "heavy" enough vibration continues, the sensor only sends subsequent vibration/shock detected messages every 60 seconds, so the device driver will is set up to reset motion to inactive after 65 seconds as a default, with a user-adjustable reset time in the preference section of the device details page (see screenshot below).
Tilt detection: The sensor sends a tilt detected message when it has been rotated in any direction, and both a Tilt Angle value message and XYZ accelerometer values message are sent when the sensor stops moving and has come to a resting position. Because Tilt detected is assigned to the acceleration capability, it also resets to acceleration inactive using a timer - in this case, 2 seconds, not user-adjustable. The reason for 2-seconds is purely to give a visual indicator in a Hubitat Dashboard if the custom attribute sensorStatus is used. However, since acceleration is state-based, it needs to be reset to inactive when no more tilts are detected after some length of time.
Tilt Angle: This value is sent after the sensor has been rotated and come to a resting position. It is a relative value, so in other words, the difference in angle from the sensor's previous resting position. There doesn't seem to be any built-in Hubitat capability that is well suited to assign to this data, so it is assigned to the custom attribute tiltAngle for events that can be used in WebCoRE, by a custom App, or displayed in a Hubitat Dashboard. It is not useful for determining an absolute open or closed position, however, which is why the XYZ Accelerometer value message data is used for that purpose.
Drop detection: The sensor sends this message whenever a free-fall drop is detected. It seemed best assigned to a trigger action, so button 1 pushed is used.
XYZ Accelerometer values: These values are sent after the sensor has been rotated and come to a resting position. Unlike the Tilt Angle report, they are absolute values, and in the device driver are converted to a 3-axis angle position. Although this calculated position is not extremely accurate, it is consistent enough to use for setting and storing absolute open and close positions. This is accomplished by putting the sensor in each position and then pressing the "Set Open" or "Set Closed" buttons in the device view page while logged into the Hubitat Hub (see screenshot below). The conversion to 3-axis positions includes a "margin of error" to allow for positions that don't exactly match the stored user-set position. I may make this margin value available for users to change in the device preferences.
Change Sensitivity Level: The sensor has 3 hardware sensitivity levels: low, medium, and high. Changing the level requires pushing the "Change Sensitivity Level" button in the device view page (see screenshot below). However, because no "level changed successfully" message from the sensor is passed on by the Hubitat hub (or in SmartThings, for that matter) and the current level cannot be queried by the Hubitat driver, I have not yet been able to confirm that the level change command works correctly. So I can't currently guarantee it will work on the Hubitat platform. I plan on opening a new forum thread to ask about the best method for sending the ZigBee write attribute command in this case. EDIT: This has been changed in the v0.7b beta driver, but is still not yet working.

An example screenshot from the device details page of my Aqara Vibration Sensor using the beta device driver: