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

coops8d · September 23, 2018, 7:08am

Oh sorry yeah I don't have that sensor.

emersonvier · September 23, 2018, 4:40pm

Hi I am trying pairing the Original Xiaomi Door/Windows Sensor, but always show "Initializing"

So I trying to add Virtual Device, but the Status still "UNKNOWN" .

saxnix · September 23, 2018, 8:36pm

You should be able to follow the instructions listed below (posted by @veeceeoh) to do a manual pairing. The post is was written for the Smart Light Switch, but it worked for me with the Door/Window sensor. Also, if you haven't done so yet, first go and add its driver linked in the 1st post, and then do this.

veeceeoh:

Special Pairing Instructions :

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)

Start “Discover Devices” in the tab with your Hubitat’s Device list.

Hold down either button of the Xiaomi Smart Light Switch, until the LED flashes.

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

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.

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.

Back in the Device page, if the switch hasn’t finished initializing, there are two things to try:

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.

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.

Whew! You did it! I can post screenshots if people hae trouble with this.

Smartsmartsmart · September 24, 2018, 6:16am

Would it be possible to pair Xiaomi hub with Hubitat? I would be nice to have it working with Hubitat as it can be used for announcements, sirens, night light etc.

veeceeoh · September 26, 2018, 5:11pm

Possible, yes. There is a user-contributed solution for SmartThings called Mi Connector:

However, it involves installing a server in Docker on a Raspberry Pi or Synology NAS, and then a SmartApp and DTHs in SmartThings. And it's currently in constant development.

With my plate already overflowing, I have no plans whatsoever to port that solution over to Hubitat, but maybe there's someone else interested...?

Did my "Special Pairing Instructions" that @saxnix quoted (thanks for that!) work for you?

veeceeoh · September 26, 2018, 9:06pm

IMPORTANT ANNOUNCEMENT - New versions of some Xiaomi devices incompatible with current device drivers

From an Athom Homey Community thread dedicated to Xiaomi devices, I have learned that there are at least three Xiaomi Aqara devices with a new revision which seem to have firmware changes that make them incompatible with the current SmartThings DTHs (device handlers).

Here's a list:

Device	Model	New Zigbee Model ID	Old Zigbee Model ID
Aqara Button	WXKG11LM	`lumi.remote.b1acn01`	`lumi.sensor_switch.aq2`
Aqara Smart Light Switch - 1 Button	WXKG03LM	`lumi.remote.b186acn01`	`lumi.sensor_86sw1lu` or `lumi.sensor_86sw1`
Aqara Smart Light Switch - 2 Button	WXKG02LM	`lumi.remote.b286acn01`	`lumi.sensor_86sw2Un` or `lumi.sensor_86sw2`

NOTE: The devices with the New Zigbee Model ID are the new versions that don't work with the current device handlers.

An easy way to know that you've probably received one of the new versions of the above devices is that it will only pair as a generic "Device", instead of choosing the correct device driver.

To check the Zigbee Model ID, you should be able to view it while logged into your Hubitat hub when you view details about the device by clicking on it's name in the Devices page. Search for the "Data" row, near the bottom of the page, where you'll hopefully see something like this:

I don't have any of these new versions myself, and don't plan on purchasing more any time soon, so...

If any receives one of the above three models and it pairs as a "device" please post in this thread, and I'll explain how to get some log output which should hopefully help me to update the device driver to work correctly.

If you have a device with an Old Zigbee Model ID listed above, there's no need report back that they're working fine.

saxnix · September 26, 2018, 9:55pm

@veeceeoh, is there a setting I need to change to be able to view the buttonPressed, buttonReleased info as a date/time for the Aquara Button?

and same question for the other Xiaomi devices?

guyeeba · September 27, 2018, 7:50am

I have a WXKG02LM with model ID lumi.sensor_86sw2Un, and it's working fine with your DTH...

I just noticed that I have 2 more WXKG02LM from the same shipment with lumi.sensor_86sw2 ID (without the trailing "Un"), and they're working as well.

EDIT: I bought them on Nov. 16 2017, so they're not really "new"...

veeceeoh · September 27, 2018, 4:55pm

Since there's no mobile app for Hubitat like there is for SmartThings, I removed the human readable event time/date stamps from all of the Hubitat drivers because the only place you can view them is via the device details page for a single device when logged into your hub locally - in the Events list.

However I kept the Unix-format "Epoch" time/date stamps for use in WebCoRE, because that can be very helpful in creating Pistons.

If you just want to be able to view when events occurred for any device (not just Xiaomi devices), then click on the "Events" link at the top of the device details page for that device.

Was there some other reason you need to see human readable dates of events besides just viewing them?

Thanks for reporting in! However...

I messed up on that chart with the Zigbee Model IDs, and it's fixed now. Sorry about that!

The "old" Zigbee Model ID for the WXKG02LM that works fine with the current device drivers may appear either as lumi.sensor_86sw2Un or lumi.sensor_86sw2. Similarly, the "old" version of the WXKG03LM can appear either as lumi.sensor_86sw1lu or lumi.sensor_86sw1.

I only really need to hear from anyone who's recently bought one of the three listed devices which is only coming up as a generic "Device" when paired, and also has a New Zigbee Model ID.

saxnix · September 27, 2018, 8:00pm

Yep, that's what I was after - thank you (forgot it was there .

Is there a way to set up automatic exporting of events to google sheets (or similar)?

veeceeoh · September 27, 2018, 8:19pm

There's a SmartThings SmartApp for that, but it hasn't been ported to Hubitat yet (that I know of):

saxnix · September 27, 2018, 9:27pm

Thanks for the info about Simple Event Logger. It looks like it would do the trick, but after searching, it doesn't look like anyone has ported it over yet. I will follow a thread where some have discussed it, but at this stage it doesn't look like anyone is taking on the challenge.

bobbles · October 2, 2018, 7:56am

I have quite a few Xiaomi /Aqara devices and whenever I change to a new battery I see that it reports a battery level of 3.055V.
Would it be possible to change the max default voltage to this instead of 3.5 and maybe the min to 2.7V.
Mine never drop below 100% and changing to the above values starts to give a better reading. Not sure how accurate the readings are though.

veeceeoh · October 2, 2018, 5:25pm

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:

Device	Earliest reading	Latest reading
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.

bobbles · October 2, 2018, 6:01pm

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.

mike · October 9, 2018, 10:45am

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)

guyeeba · October 16, 2018, 5:16pm

veeceeoh:

Here's a list:

Device Model New Zigbee Model ID Old Zigbee Model ID

Aqara Button WXKG11LM lumi.remote.b1acn01 lumi.sensor_switch.aq2

Aqara Smart Light Switch - 1 Button WXKG03LM lumi.remote.b186acn01 lumi.sensor_86sw1lu or lumi.sensor_86sw1

Aqara Smart Light Switch - 2 Button WXKG02LM lumi.remote.b286acn01 lumi.sensor_86sw2Un or lumi.sensor_86sw2

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"

The capabilites follow Hubitat's method:

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

mike · October 21, 2018, 11:26pm

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

veeceeoh · October 22, 2018, 4:04pm

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.

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!