# [Release] Xiaomi / Aqara device drivers

#243

Well the voltage readings are the only thing that are "accurate".

Without complete understanding of the power usage characteristic of each different type of Xiaomi device, the battery percentage can only be very roughly estimated using the simple equation of:

`% = (current voltage reported - min voltage) / (max voltage - min voltage)`

So with your suggestion of 3.5V for a max and 2.7 for the min, your brand new battery would result in battery percentage report of 44%. Is that what you're seeing when you manually change those max/min values in the device details page? Honestly I'm not sure that most users would like to see new batteries reported at 44%.

That said, I'm all in favor of changing the defaults to something more appropriate, but I'd prefer to have more empirical data. Like what starting voltage people see when they have put in new batteries. There is likely to be a good range there, and I've received new Xiaomi sensors with batteries reporting over 3.055V to start. Then on the other end of the range, at what voltage do the sensors stop working, or start working improperly. This is a difficult one to nail down. What voltage were you seeing reported before you installed new batteries?

I took a look at the event reports for a number of my Xiaomi devices, checking for the earliest battery voltage reading I could find (anywhere between 2 to 5 months ago), and the most recent reading). Here's what I found:

Aqara Button 3.045 3.035
Aqara Button 3.055 3.045
Dual Button Switch 3.045 3.025
Dual Button Switch 3.025 3.025
Dual Button Switch 3.045 3.045
Xiaomi Door/Window 3.015 3.005
Xiaomi Door/Window 3.075 3.065
Xiaomi Door/Window 3.005 2.955
Aqara Leak Sensor 3.055 3.045
Aqara Leak Sensor 3.055 3.045
Aqara Temp/Humidity 3.005 2.985
Xiaomi Temp/Humidity 2.995 2.985
Xiaomi Mi Cube 3.025 3.015

Based on this, I think it's possible the voltage declines very slowly and by a small amount and is not a good indicator of mAh (milliAmp hours). And therein lies the real problem with calculating battery percentage off of the Voltage. Battery capacity is only correctly measured in Wh (Watt hours), but mAh can be used if derived using circuitry that checks impedance, from what I've read. But we only have voltage to work with.

Just based on that list of my devices above, I'd be more inclined to set a narrower and more specific range, like a max of 3.04 and a min of 2.95. But that's for my particular set of batteries and environmental conditions, and I have zero confidence on the min value as I have not had to replace any batteries yet.

#244

Hi @veeceeoh. The bit I put in above is oncorrect. The max default value is 3.0 not 3.5 as I stated. Typo I'm afraid.
That's why I suggested 3.055 as this is the maximum I have seen.
Using 3.0 means most of my devices continually report 100% for some time before they start to drop.
I have changed the default values in your code for my use but thought I would make a suggestion and the 2.7 I suggested is probably to low. I think I will try 2.9 and see what happens.
Great device handler though and without it I'd be screwed moving from ST to HE.

#245

veeceeoh,

I know you didn't make the Driver Code for the Power Outlet, but can you help with this error on line 107 of this code: Xiaomi Zogbeee Outleet · GitHub

The device works well as a power outlet, but is just not reporting the temperature, and the refresh command to get the temperature causes this error.

This is the error.

groovy.lang.MissingMethodException: No signature of method: com.hubitat.zigbee.Zigbee.parseHATemperatureValue() is applicable for argument types: (java.lang.String, java.lang.String, java.lang.String) values: [temperature: 14, temperature: , C] on line 107 (parse)

#246

Well, I just received a few WXKG11LMs, and WXKG03LMs, and I checked the 11LMs... they're lumi.remote.b1acn01 devices.

With slight modifications your driver works, here are the changes I made:

The fingerprint is:

``````// Aqara Button - new revision - model WXKG11LM
fingerprint endpointId: "01", profileId: "0104", inClusters: "0000,0012,0003", outClusters: "0000", manufacturer: "LUMI", model: "lumi.remote.b1acn01"
``````

``````		capability "PushableButton"
capability "HoldableButton"
capability "ReleasableButton"
capability "DoubleTapableButton"
``````

It uses the same cluster as WXKG12LM (cluster 0012), so - as I had no better idea to distinguish them - I used model ID. I joined the very same button a few times to the hub, and noticed that sometimes there is garbage after model ID (e.g. "lumi.remote.b1acn01�B!� (!!�!,\$ !�"), so I used .startsWith() in parse():

``````	} else if (cluster == "0012") {
if (device.data.model.startsWith("lumi.remote.b1acn01")) {
// Model WXKG11LM new model only
map = parse11LMNewModelMessage(Integer.parseInt(valueHex[2..3],16))
} else {
// Model WXKG12LM only
map = parse12LMMessage(Integer.parseInt(valueHex[2..3],16))
}
} else if (cluster == "0000" & attrId == "0005") {
``````

and this is the parser for this device:

``````// Build event map based on type of WXKG11LM (new model) action
private parse11LMNewModelMessage(value) {
// Button message values (as integer): 0: held, 1 = push, 2 = double-click, 255 = release
def messageMap = [
0: "held",
1: "single-clicked",
2: "double-clicked",
255: "released"
]
def eventTypeMap = [
0: "held",
1: "pushed",
2: "doubleTapped",
255: "released"
]
def coreTypeMap = [
0: "Held",
1: "Pressed",
2: "Pressed",
255: "Released"
]

displayInfoLog("Button was \${messageMap[value]} (Button \${eventTypeMap[value]})")
updateCoREEvent(coreTypeMap[value])

return [
name: eventTypeMap[value],
value: 1,
isStateChange: true,
descriptionText: "Button was \${messageMap[value]}"
]
}
``````

Short-pressing the reset button sends battery level (3.055 on a brand new device), your code processes it perfectly, but no long-term tests are performed yet... so that's all folks...

Maybe tomorrow I can check the 03LMs, it's possible that those are new models as well...

#247

@veeceeoh

Is there a way to get the Last Opened (webcore) to show on the dashboard? Obviously a random number like this 1540161099151 means nothing to me on the dashboard. I'd love to show it on the dashboard in a date format.

#248

I'm going to be doing an update to all Xiaomi device drivers for Hubitat, so I am going to change the default range to 3.05 max / 2.9 min.

I will have a look and see what I can figure out.

That's excellent news, and thank you for sharing the modified code that works!

I will update the master code available on my GitHub collection to include your suggestions, and post here to announce its availability.

I originally removed the "human readable" date attribute when porting over the device drivers to Hubitat because there wasn't any kind of UI for people to see. Now we've got dashboard, so I will go through all the drivers and add the human readable `Last Opened` back in.

#249

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!

#250

@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.

#251

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?

#252

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.

#253

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``````

#254

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.

#255

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.

#256

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

#257

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.

#258

@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.

#259

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.

#260

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.

#261

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 devices - are they pairing / staying connected for you?

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.

#262

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.