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

Yeah i have kept pressing it. Haven't tried the reset whilst initialising will try again later...

It sounds like a minimum Voltage of 2.8V and either keeping the max at 3.05V or going up to 3.10V may yield more "realistic" battery level calculation, for Temp-Humidity Sensors, at least.

Related to this - After I saw my Xiaomi Cube report a voltage level of 2.735V, it went back up when I stopped doing tests with the newest driver.

Since then, it's been bouncing between 3.005V and 2.975V - which correspond to 70% and 50% using the current driver's 2.9V/3.05V min/max values. I'm going to look into calculating battery percentage level on a curve (something akin to a logarithmic curve) because from everything I understand about battery life with these button cells, there can still be quite a bit of capacity remaining as the voltage first starts to drop off from its maximum reading, but the relative capacity drops more as voltage goes down to the lowest levels.

I have a fair number of the original Door-Window sensors, but it's been ages since I've paired one, so I'll try it to see if anything is different than it was last year, but...

What @vjv explained is the best procedure for getting Xiaomi / Aqara devices paired. There's definitely a correct timing of the continuous short presses to get it to work, however. Basically, after the initial roughly 5 second long-press, on each short-press you should see the LED flash as you short-press and then wait for another LED flash before the next short-press.

Also, if the initialization hasn't finished within 90 seconds, I'd recommend starting over.

In other news, after a false start with a DOA device, I got a working ZigBee sniffer and with its help I have finally figured out how to correctly change the sensitivity level of the Aqara Vibration Sensor!

I need to re-work the code and do some testing when I have time, but a driver update is imminent!


Finally i might be able to use mine....
Hooray. Man


1 Like

Mine are all working now following vjv advice


Yippee! Seriously, thanks for staying with this.

[TUTORIAL] Use of the Xiaomi Mi Cube Controller device driver

Now that I've given the Xiaomi Mi Cube driver some love and it's more-or-less fully working, I am hoping for some input from users so I know what direction to take with future changes to it. In order to get that kind of feedback, I figure that people probably need to know how this driver works in the first place!

The first thing to keep in mind is that this driver is a port of SmartThings Community user @ClassicGOD's Xiaomi Magic Cube Controller (Advanced DTH), which in turn was based on user @DroidSector's Xiaomi Mi Cube / Magic Controller SmartThings device handler. So the explanations after the pairing instructions are adapted from @ClassicGOD's device handler notes.


Although an unpaired Xiaomi Cube has a neat trick of entering pairing mode when shaken in mid-air, this does NOT work when pairing to a Hubitat hub. Instead the reset "LINK" button, which is hidden under a removable cube face, must be used. To access this, use the metal lever tool included with the cube to gently pry open the face with the corresponding slot, as seen here:

Once the cube is opened, start the Hubitat hub's Zigbee and ZWave device discovery mode. Next, press and hold the cube's "LINK" reset button. The LED light will turn on, and when the LED blinks 2-3 times (after about 5 seconds) then release the reset button.

After a few moments, the LED will either blink rapidly 3 times - indicating successful pairing, or flash once - meaning pairing has not yet occured. In both cases, start repeatedly short-pressing the button. When short-pressing the button the LED will blink, but after a short delay, the LED will light up again, responding in the same way as above (3 blinks = paired, 1 longer flash = not yet paired.) Make sure the next short-press comes after the LED flash response, so about every 2 seconds.

Continue short-pressing the button about every 2 seconds until either the cube's device name appears in the web browser window, ready to be renamed, or 90 seconds has passed by. If not successfully paired after 90 seconds, start the whole pairing process again, beginning with the long-press of the "LINK" reset button.


The driver offers 3 different Cube Modes of operation, which is set in the Preferences section of the device details page of a paired Xiaomi Cube:

  1. Simple - 7 buttons
    This mode is set by default when the Xiaomi Cube is paired and matches the functionality when it's used with a Xiaomi Gateway and the Mi Home mobile app. The 7 buttons are assigned to the 7 basic gestures as follows:
    1. Shake (in mid-air)
    2. Flip 90 degrees
    3. Flip 180 degrees
    4. Slide
    5. Knock (pick up and firmly hit surface twice)
    6. Rotate Right (spin clockwise)
    7. Rotate Left (spin counter-clockwise)
  2. Advanced - 36 buttons
    Xiaomi Magic Cube Controller (Advanced DTH) author @ClassicGOD discovered that the messages sent by the cube for slides, knocks, and flips to any side also contained orientation data, meaning a number for which face of the cube is pointing up (and for the flip gestures, the number of which face was up before the cube was flipped.)
    Multiply 6 faces by those 3 gestures and there are 18 possible combinations, but if the last-known upward face number is known it can also be used with shake and left/right rotation gestures to increase the number of combinations to a total of 36.
    Here are the face number arrangements of the Mi and Aqara-branded cubes:

    The Advanced Mode button assignments are as follows:
    • button 1 to 6 - flip ending with face 0 to 5 pointing up
    • button 7 to 12 - slide with face 0 to 5 pointing up
    • button 13 to 18 - knock with face 0 to 5 pointing up
    • button 19 to 24 - right rotation with face 0 to 5 pointing up
    • button 25 to 30 - left rotation with faces 0 to 5 pointing up
    • button 31 to 36 - shake with face 0 to 5 pointing up
  3. Combined - 43 buttons
    In this mode, every gesture produces two button pushed events: The first for buttons 1 to 6 as defined in Simple Mode, and the second following Advanced Mode but with the button assignments all increased by 7 as follows:
    • button 8 to 13 - flip ending with face 0 to 5 pointing up
    • button 14 to 19 - slide with face 0 to 5 pointing up
    • button 20 to 25 - knock with face 0 to 5 pointing up
    • button 26 to 31 - right rotation with face 0 to 5 pointing up
    • button 32 to 37 - left rotation with faces 0 to 5 pointing up
    • button 38 to 43 - shake with face 0 to 5 pointing up

Combined mode example: A flip from face #0 to face #3 will result in button 3 pushed (Basic Mode flip 180 degrees) - and - button 11 pushed (flip ending with face #3 pointing up).


The driver also uses the “Three Axis” capability to indicate orientation and should work with apps like the Mood Cube app ported to Hubitat. This functionality is affected by limitations described below.


Because the hardware does not send face # pointing up data for all gestures, there are some limitations to how well the button events work in the Advanced and Combined Cube Modes:

  • The cube only sends face orientation data for these gestures:
    • 90/180 degree flip
    • slide
    • knock
  • Orientation data for rotation and shake gestures is based on the last known orientation.
  • The cube does not send any data if gesture is unrecognized - rotating the cube randomly in the air and placing it down will probably not result in any button pushed event(s).
  • The driver will correct last known orientation and send missing flip/face activation events if needed as soon as it receives the orientation data
  • For the above reasons, rotation and shake gestures may result in button pushed events for the wrong faces, if previous flip gestures are not performed correctly (e.g., rotating the cube randomly in the air)

Please by all means if anyone has any more ideas or suggestions to add to this tutorial, please let me know and I will add them to this post (and at some point start a new thread so it can be the OP.)


Just a note, the Aqara model has the brand name on face 0, not face 5 like the Mi brand.

1 Like

Thank you very much. The offset value for all works fine now.
Is it only me, not sure - the attribute ‘ lastcheckintime’ or ‘lastCheckinEpoch‘ does not show up even it is enabled or disabled. Not a breaker but just checking if I am doing something wrong.

Good to know. I will create a second button map image to add to the tutorial post. I'd be interested to know if there are any other differences between the Xiaomi Mi and Aqara variants of the cube. I guess those would manifest themselves as behavior inconsistent to what's explained in the tutorial.

I will take a look at that as soon as I can, but I am a bit tied up for a couple of days (see below)

Just a FYI for anyone hoping to see the Vibration Sensor driver update or any other updates:

SmartThings is releasing a firmware update tomorrow with changes to the way ZigBee messages are sent to the device handler which breaks a bunch of Xiaomi / Aqara DTHs for SmartThings. Sound familiar? :joy:

I've been maintaining and updating the collection of SmartThings DTHs for a while now, so I will be busy making code changes for a bunch of updates over there. When finished I'll return to working on the Vibration Sensor driver update.

In the meanwhile...

[RELEASE] v0.8 of Aqara Wireless Smart Light Switch Device Driver

I have decided to move this driver out of beta, so it's now located in the repository among all the other drivers. This also means that the direct link to the code has changed.

The new permanent location to grab the code from is here. There are no other changes to the code than the version is listed as 0.8, not 0.7.5b.

I plan to soon retire the xiaomi-aqara-dual-button-hubitat driver, so if you've been using that, I'd recommend switching over to this newer Aqara Wireless Smart Light Switch Device Driver.

Thanks again for your patience and support everyone!

For now, everything else looks the same between the Mi and Aqara cubes, just brand face location.

Good luck doing the ST updates, I have ST beta program so probably I have those updates already.

1 Like

Suggestion: alternative button naming .. for those of us who have forgotten our 6 times table! instead of 1..6, 7..12, 13..18 - how about a numbering scheme in 10's 1..6, 11..16, 21..16?

This has got to go low on your todo list, if it even makes it onto the list.

1 Like

For Xiaomi smoke detector, does resetToClear() silent the alarm OR the alarm only cease when no smoke is detected?

I used resetToClear() but it doesn't stop the alarm and only when the device is removed from smoke source, the device revert to Clear status on its own.

From the screen capture, after smoke is detected, I used a switch to trigger resetToClear(). This doesn't stop the alarm. After removing the smoke source, the device sends a clear event which stops the alarm.

I've not seen these "cubes" in Aus. but they look interesting.

Can anyone chime in on channel changes and if they're Aquara door/window contact sensors find their way back? I'm finally moving my ST multifunction sensors over and found out they do not pair well on my existing channel. I went a few channels to find one that they both would pair on (was just using an Aquara on hand to test).
But none of my existing in place sensors are reporting back unless I go and repair/sync them. Am I stuck doing that or can this just be waited out? While it's only a few more sensors, more just curious as to how I should be doing this. All my outlet and motion sensor zigbee devices seemed to work fine.

Because its ZigBee, just a reboot of the hub should be sufficient according to this article (about half way down, just after the first picture of some circles):

you have to go and repair/sync each device xiaomi do not repair themselves unfortunately maybe when they make zigbee 3 versions they will fix this

Ok, at least I know I'm not crazy then. Sadly, one of my sensors now keeps dropping, lol. Not sure I'm liking that I went Xiaomi now. Hopefully it's just one unit.

[UPDATE] v0.3.3b of Xiaomi Mi Cube Controller device driver for Hubitat

Thanks to some sleuthing by @codahq, the driver should now produce correctly formatted threeAxis events for compatibility with his Hubitat port of SmartThings' Mood Cube app.

I also added the driver's Import URL both to the 2nd line of the code -and- to the driver's "definition" line. Adding the URL to the definition line should auto-populate the import URL when the [Import] button is pushed while viewing the driver. With the URL already filled in, to import the latest version of the driver, just click the [Import] button in the pop-up window and then [close], like this:

The updated beta device driver code can be grabbed from here.

Change List

  • Changed formatting of threeAxis event values to match Hubitat's requirements (thanks to Hubitat user @codahq for identifying this issue)
  • Added driver's Import URL to the top line of the header comments section
  • Added 'importUrl' data to the driver's metadata - definition line

resetToClear() only clears the smoke detected event state for the Hubitat hub.

I do not own a Xiaomi Mijia Honeywell Smoke Detector, but based on all of my reading nobody has discovered any way to send a command to the detector to either start or silence the alarm. Not even the native Mi Home app has this option, from what I understand.

If it's just one then that might be due to an incompatible ZigBee repeater device.


Welcome back from your sojourn into ST-land.

1 Like

Anybody using the Aqara relay module?

Noticed it on AliExpress

Seems pretty interesting, dual channel dry-contact outputs and switch inputs.

Download the Hubitat app