[Edge] Driver for Aqara Cube

I am starting this separate thread following the request from the Edge driver author @veonua
You can use the channel invitation link

The driver is valid/tested for Xiaomi Cube, a.k.a. Mi Cube or Magic Cube, model nr. MFKZQ01LM

This topic is for all of us, current and future users of this powerful little thing!

We had a good run with basic and advanced DTH, but it’s time to move on to the new platform.

Here you can post your questions, report issues, make suggestions or provide feedback.

I will start with some questions and/or suggestions in my next post in this thread


Let me start by describing how this driver works and some capabilites and attributes

Officially, cube has totally 6 gestures:

  1. Slide
  2. Flip90
  3. Flip180 (Turn)
  4. Shake
  5. Knock (Double Tap)
  6. Rotate

This gestures, except Rotate are represented as Action attribute in this driver.
Rotate is represented with Rotation attribute, providing actual cube rotation (CW+/CCW-)

There are 2 additional Actions in this driver:

a) Ready: Not 100% sure, seems like indication that Cube is ready for action again (after previous one)
b) Fall: Don’t know how to activate this gesture/action yet. Same as drop? Any ideas? :slight_smile:

Furthermore, there are several more capabilities/attributes

Face: Showing which side the cube is on: up/down/front/back/left/right
SwitchLevel (Dimmer): Controlled by rotation left/right when Switch is ON
Switch: Enables/Disables controll of Dimmer. If OFF, dimmer value doesn’t change
MotionSensor (Motion): Activated on movement, 1min after deactivation for re-activation (wakeup?)
Battery: Well … battery level

I will start by making a suggestion on how to furter expand the Flip90 action in 4 distinct actions.

I am not a developer so not fully sure if something like this is even possible, but here is the idea :slight_smile:

No matter on which side you flip, the result will be Flip90 Action. Instead we could have 4 different flips, FlipLeft, FlipRight, FlipBack, FlipForward.

Not sure what would be the best way to implement this, could we use acceleration sensors?

If not, there is another possibility, based on previous and new face.

FlipLeft active if new face is Left and previous face was Up, or new face is Down and previous face was Left, or new face is Right and previous face was Down, or new face is Up and previous face was Right

Similar goes for other 3 potential new flips/actions. I could make a matrix/tables of all possible transitions.

@veonua what do you think of this? :slight_smile:

a) Ready : Not 100% sure, seems like indication that Cube is ready for action again (after previous one)

there is a limitation of the platform so it ignores repetitive events. So I just copied the behavior of the button in ST.

b) Fall : Don’t know how to activate this gesture/action yet. Same as drop? Any ideas?

just toss it, or drop it from the table. As soon as the cube experiences free fall, it reports this event.

1 Like

these capabilities were added just to use the cube as a dimmer in the Smart Light application. There is no way to have a rotary dimmer in ST except the Mirroring in the app.

“Off” disables dimming to prevent accidental light flashes. I have the cube on the nightstand, and goddamnit there is no way in the ST app to prevent the switch level turn-on the light.


The cube sends an event when it wakes up, so we got the vibration detector for free

it’s sensitive, so even placing a cup on the same table triggers this event.

personally, I use it only for “no motion at night for an hour” for activation of the night scene.


“Fall” is a tamper indicator. It is based on displacement along the Y axis of the internal accelerometer, like a fall detector. I’m not sure how far the drop has to be to trigger it. It is also called “Drop” in some translations.

“Slide” is also called Push” or “Nudge” and reports displacement along the X axis.

The accelerometer can also report which side is up after rotation which is Face. Note that “Face” doesn’t tell you which side is up: it tells you which side is up after movement. See the Home Assistant integration, for example.

For an edge driver, it’s important to note that this device has 4 models, with 4 different fingerprints (although I don’t know what they are):

  1. the original, which is Zigbee ZHA
  2. the T1, which is Zigbee 3.0
  3. the T1 Pro, which adds the option of a HomeKit mode, also called “Scene setting”
  4. a xioami clone. I’m not sure if it’s a clone of 1 or 2. There might even be multiple models under the xiaomi brand. :thinking:

Have fun: it’s a cool little device. :sunglasses:

Review article differentiating the models:

Aqara Cube T1 Pro (review) – Homekit News and Reviews



Appriciate your feedback @veonua

I managed to get the Fall/Drop or Toss in this case by droping it from hand to hand from ca. 20cm above.
I don’t dare throwing it to hard table :slight_smile:

Regarding the switch/dimmer, I was planning to use it in Sharptools “piston” in conjunction with an actual light. So, whatever is on the cube gets copied to the light level in % … hopefully this will work fine. Virtual device/dimmer could be of help here if needed

I can’t use Smart Light app since ST doesn’t offer it in EU, for some moronic reason only they know. And with Trend Setter app getting burried along with Groovy, I need to start thinking of alternatives … ok heavy OT here, back to the subject …

On the flip left and right. Maybe I don’t understand something but the side is relative to the user position.
So the rotation of the cube or side of the table changes the expected action.

It can be useful in a very limited set of cases and mindful users.
We need to have a well-researched use case for this advanced feature.

1 Like

Got it! Ca 20cm drop is enough, maybe even less :slight_smile:

I have to look into this! I noticed this a long time ago … if you take the cube, do some rotation in your hand, and place it back on board, it doesn’t report which side is one, but once you flip it, it works flawlesly.

Does this mean you could use the values from accelerometers to determine if the flip was to the left/right/forward/backwards?

In any case, I did some additional testing now, and after flipping being done, cube detect perfectly which side it is on, whatever the transition is! So based on previous value/side only (considering that it is correct, cube is not taken in the air so it forgets the side) it should be possible to distinct the flip!

1 Like

I get your point now! It’s not that simple as I thought/hoped :slight_smile:

It really depends on the rotation of the cube … you could allways return it to Up side, with Aqara text in front and use this as a starting/base position, but sounds like too much hastle.

I will give this some thought and get back if I come up with some clever way of doing this :slight_smile:

Btw, face detection works perfectly, I tested all posible face-to face transitions and flipping always produces the correct face.

1 Like

Hello I was having trouble pairing my cube to my hub, am I doing something wrong? I installed the edge driver it shows up on the smartthings app under the hubs installed drivers but when I try to scan for a device it never shows up. I cant find an answer online and am not sure if I’m missing a step. Online it said to try either channel 20 or 25 both failed to find the device. Any help would be greatly appreciated.

Did you put Cube in pairing mode?

These are the steps I took, worked every time

  • add a device in ST
  • put Cube in pairing mode by 3s reset press, it would provide 3 rapid blinks, mening paring was successful, 3 slower blinks means it was not
  • after 3 rapid blinks I would keep clicking the reset every few secs, so it doesn’t time out, until Cube was detected in ST

Worked every single time, with 2 devices

check the model numbers first

After pairing my cube it does not pick up this edge driver. (It’s installed on my hub)
It shows up as a generic Zigbee Switch. No 3 dots to switch edge driver.
I have no custom DTH for a Zigbee Switch in my IDE.

What can I do to force this to pick up the edge driver ?


Can you add this fingerprint to the driver?

1 Like

This worked after a couple of tries thank you so much.

Hi Cesar, which Cube did you have? I had one of the original ones and have also just bought a T1 Pro when I have connected them to the Smartthings Hub they have never shown a Zigbee ID only that the Execution Location is cloud.

How did you manage to add the info into the driver?

Thanks in advance

Hi I’m new to edge drivers. I’m wondering how you guys hook this device up with any lighting? Are smart apps going away with groovy?

My use case is simple, dim my light with the value this device computes. My current approach is to have like 20 routines that each gets triggered by dimmer range between x% ~ x+5%. Any suggestion is appreciated, thanks!

or use Mariano’s driver with increase/decrease step capabilities. it works as well but not as smooth as mirroring.

1 Like