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

🚧 Developers
1

NOTE: Although many users have had great success using them, Xiaomi / Aqara ZigBee devices are NOT officially supported or guaranteed to work on the Hubitat Elevation platform.

I am maintaining a collection Xiaomi device drivers for Hubitat in a GitHub repository, at veeceeoh/xiaomi-hubitat.

These device drivers are based on the bspranger/Xioami repository of device handlers for SmartThings, but with significant modifications and improvements for use only on the Hubitat Elevation hub platform.

Rather than start a new thread for each separate Xiaomi device driver as I finish them, I will post announcements on this thread, and add them to the list below in this initial thread post.

Currently supported Xiaomi / Aqara devices:

  • "original" Xiaomi & Aqara Temperature/Humidity sensors (code here)
  • "original" Xiaomi Motion Sensor (code here)
  • Aqara Motion Sensor (code here)
  • "original" Xiaomi & Aqara Door/Window contact sensors (code here)
  • Aqara Leak sensor (code here)
  • "original" Xiaomi Button (code here)
  • Aqara Button - models WXKG11LM & WXKG12LM (code here)
  • Aqara Smart Wireless Wall Switches (2016/2018 versions) - 2 button WXKG02LM & 1 button WXKG03LM (code here)
  • Aqara Smart Wired Wall Switches (w/ Neutral) - drivers by @guyeeba here
  • Aqara Smart Wired Wall Switches (No Neutral) - drivers by @guyeeba here
  • Aqara Two-Way Wireless Control Relay - driver by @guyeeba here
  • Mi "Magic" Cube Controller (beta code here)
  • MiJia Honeywell Smoke Detector (code here)
  • MiJia Honeywell Gas Detector (beta code here)

For a complete and detailed list of Xiaomi / Aqara ZigBee devices with Model numbers and Hubitat driver links, see the chart at the bottom of this post.

Basic pairing instructions (except for Leak sensor, Smart Wall Switches, & Smoke Detector):

  1. Navigate to the Device Discovery page of your hub's web UI and click "Zigbee" to put the hub in ZigBee discovery mode.
  2. Hold the Xiaomi / Aqara device's reset button until the device's LED flashes 2-3 times, which indicates it has started pairing mode.
  3. After a brief pause, the LED will flash again:
    • 2-3 quick flashes indicates success
    • 1 long flash means pairing has not started yet.
  4. In either case, keep the device "awake" by short-pressing the reset button repeatedly (about every 2-3 seconds, following the same push and LED response sequence described in steps 2-3 above), until the device is recognized by Hubitat.
  5. If the device does not appear by the end of the ZigBee discovery time period, try again. If pairing continues to fail after 10 minutes of attempts, please see this thread focusing on pairing and keeping Xiaomi / Aqara devices connected.

Dropped Connection Issue:
Some Xiaomi / Aqara users report device(s) dropping their connection less than 60 minutes after pairing, and for other users within 24 hours. Just be forewarned: Since Xiaomi / Aqara devices were specifically designed to work with a Xiaomi Gateway hub, there's no guarantee that they will stay connected for 100% of Hubitat users. For more information, please see this thread focusing on pairing and keeping Xiaomi / Aqara devices connected.

To reconnect a "lost" sensor without deleting and re-pairing it:

  1. Put Hubitat in "Discover ZigBee Devices" mode.
  2. Try short-pressing the sensor's reset button once. If that doesn't result in the device being recognized, then:
    1. LONG-press the reset button and release when the LED flashes (same as for pairing).
    2. Wait for the LED to flash again.
    3. 3 quick flashes indicates reconnection.
    4. If only one long flash, short-press the button and go to step 3.
    5. Stop pressing the reset button when the device is recognized

Notes on all Xiaomi device drivers:

  • All references to a mobile app user interface that were in the original SmartThings device handlers have been removed, since Hubitat uses a different UI with its Hubitat Dashboard.
  • Xiaomi devices send reports based on changes, and a status report (including battery voltage data) every 50-60 minutes. These settings and the report time intervals are hardware-based and cannot be adjusted.
  • The battery level / voltage is not reported at pairing. The sensors are programmed to supply battery voltage data in their first status report, 50-60 minutes after pairing.
  • Pairing Xiaomi devices can be difficult as they were not designed to use with a Hubitat hub.

IMPORTANT NOTE: On Feb 6 2019 hub update 2.0.5 was released, which included a change to the way ZigBee messages are passed on to device drivers. I had to update all of my drivers to include a compatibility fix. If you are using any hub firmware older than 2.0.5, a preference setting needs to be turned on. See this post for more details about the compatibility fix update.

Please if you have feedback about any of my Xiaomi device drivers, post on this thread. Otherwise, if you have feedback or questions on pairing Xiaomi devices and/or keeping them connected to your Hubitat hub, please join the discussion on this other forum thread.

Detailed List of Xiaomi / Aqara Zigbee Devices:

Device Name Device Type Model / SKU Zigbee Model Hubitat Driver?
Mi Cube Controller Multi-function Controller MFKZQ01LM lumi.sensor_cube beta driver
Xiaomi Door and Window Sensor Magnetic Contact Sensor MCCGQ01LM lumi.sensor_magnet available
Aqara Door and Window Sensor Magnetic Contact Sensor MCCGQ11LM lumi.sensor_magnet.aq2 available
Aqara Door and Window Sensor T1 Magnetic Contact Sensor MCCGQ12LM not yet known not yet
Xiaomi Motion Sensor IR Motion Sensor RTCGQ01LM lumi.sensor_motion available
Aqara Motion Sensor IR Motion Sensor RTCGQ11LM lumi.sensor_motion.aq2 available
Aqara Smart Bulb Smart Bulb (E27) ZNLDP12LM lumi.light.aqcn02 not yet
Aqara Smart Curtain Motor Window Curtain Motor ZNCLDJ11LM lumi.curtain no
Xiaomi Smart Plug Plug-in Outlet Switch ZNCZ02LM lumi.plug no
Aqara Smart Plug Plug-in Outlet Switch ZNCZ12LM lumi.ctrl_86plug.aq1 no
Aqara Smart Rolling Shutter Motor Window Shutter Motor ZNGZDJ11LM not yet known no
Aqara Smart Wireless Curtain Motor (B1) Window Curtain Motor ZNCLDJ12LM not yet known no
Xiaomi Temperature and Humidity Sensor Temp & Humidity Sensor RTCGQ01LM lumi.sensor_ht available
Aqara Temperature and Humidity Sensor Temp & Humidity Sensor WSDCGQ11LM lumi.weather available
Aqara Two-Way Wireless Control Relay In-Wall Switch (no Neutral) LLKZMK11LM lumi.relay.c2acn01 from guyeeba
Aqara Wall Outlet In-wall Outlet Switch QBCZ11LM not yet known no
Aqara Wall Switch - Single (no Neutral) Wall Switch (no neutral) QBKG04LM lumi.ctrl_neutral1 from guyeeba
Aqara Wall Switch - Double (no Neutral) Wall Switch (no neutral) QBKG03LM lumi.ctrl_neutral2 from guyeeba
Aqara Wall Switch - Single (w/Neutral) Wall Switch w/Neutral QBKG11LM lumi.ctrl_ln1.aq1 from guyeeba
Aqara Wall Switch - Double (w/Neutral) Wall Switch w/Neutral QBKG12LM lumi.ctrl_ln2.aq1 from guyeeba
Aqara Wall Switch S2 - Double (w/Neutral) Wall Switch w/Neutral QBKG20LM not yet known not yet
Aqara Water Leak Sensor Water Contact Sensor SJCGQ11LM lumi.sensor_wleak.aq1 available
Aqara Water Leak Sensor T1 Water Contact Sensor SJCGQ12LM not yet known not yet
Xiaomi Smart Wireless Switch Multi-function Button WXKG01LM lumi.sensor_switch available
Aqara Wireless Mini Switch Multi-function Button WXKG11LM (2015) lumi.sensor_switch.aq2 available
Aqara Wireless Mini Switch Multi-function Button WXKG11LM (2018) lumi.remote.b1acn01 available
Aqara Wireless Mini Switch Multi-function Button WXKG12LM lumi.sensor_switch.aq3 available
Aqara Wireless Mini Switch T1 Multi-function Button WXKG13LM not yet known not yet
Aqara Wireless Remote Switch - Single Multi-function Button WXKG03LM (2016) lumi.sensor_86sw1 or lumi.sensor_86sw1lu available
Aqara Wireless Remote Switch - Single Multi-function Button WXKG03LM (2018) lumi.remote.b186acn01 available
Aqara Wireless Remote Switch - Double Multi-function Button WXKG02LM (2016) lumi.sensor_86sw2 or lumi.sensor_86sw2Un available
Aqara Wireless Remote Switch - Double Multi-function Button WXKG02LM (2018) lumi.remote.b286acn01 available
Aqara Vibration Sensor Accelerometer Sensor DJT11LM lumi.vibration.aq1 beta driver
MiJia Honeywell Smoke Detector Smoke Detector JTYJ-GD-01LM/BW lumi.sensor_smoke available
MiJia Honeywell Natural Gas Sensor Natural Gas Detector JTQJ-BF-01LM/BW lumi.sensor_natgas or lumi.gas beta driver

NOTE: For some devices listed above, there are combined drivers, so you only need to install one driver for all of its supported devices. This includes the drivers for:

  • both models of Door/Window sensors
  • both Temperature/Humidity sensors
  • the 1 & 2 button Aqara Smart Wireless Remote Switches (2016/2018 versions)
  • the 1 & 2 button Aqara w/Neutral Wired Wall Switches
    and Aqara Two-Way Wireless Control Relay
  • the 1 & 2 button Aqara Wired No Neutral Wall Switches
  • all three currently shipping variations of the Aqara Wireless Mini Switch
39 Likes
2

[RELEASE] v0.5 of unified Xiaomi Temperature/Humidity sensor Device Driver
Works with both the Xiaomi “original” and Aqara models

For convenience please copy the T/H sensor device driver code from this direct link.

I have finished work on a single unified Hubitat Device Driver for both the Xiaomi “original” and Aqara T/H (Temperature/Humidity) sensor models. This device driver is based on the SmartThings device handlers in the bspranger/Xiaomi GitHub repository, but has been significantly modified to work with Hubitat.

Features:

  • The Hubitat hub will correctly select this custom device driver for both T/H sensor models when paired
  • Temperature (C/F), humidity, pressure (Aqara model only), and battery values correctly reported
  • The date/time of the most recent report of any kind is stored as lastCheckin (human readable) and lastCheckinDate (java format). This may be useful in determining whether the sensor is still connected, since a status report including battery voltage is sent every 50-60 minutes.
  • Battery replacement date tracking, stored in batteryLastReplaced state
  • Preferences include:
    • offsets for temperature, humidity, pressure (Aqara model only)
    • Aqara model only: Selectable pressure unit (mbar, kPa, inHg, or mmHg)
    • Toggle to reset battery replacement date (when you replace the battery!)
    • Date / 24-hour clock settings for display of lastCheckin
    • Min/Max voltage values used to calculate the battery percentage

Note:

  • This device driver is not final, and some features or preferences may be added / removed
4 Likes
3

Worked right away. You’re a superstar. Now to wait and see if they still timeout or not.

2 Likes
4

This is very exciting, I found them to be useless for me in ST, They would work for weeks and then fall off. Pairing was and nightmare process. This driver is great, Pulled 9 temp/humd sensors out of the “I give up drawer” and the paired right away, I found that you need to be patient and not except the device to show up in discovery right away, Most of mine took about 15 - 20 seconds. Will checking on status and reporting back. I was excited to see re-pair process if there is a drop off which might make it more bearable. But with the quick pairing process I am confident this is a great start and leaps and bounds better than it was in ST! There are plenty motion sensors from the same place.

1 Like
5

My pairing technique was the same as recommended for smartthings… Set the hubitat in search mode. Hold the button to reset until 3 short flashes. then single press the button every 2-3 seconds until you get 3 short flashes again. Pairing complete.

2 Likes
6

Glad to hear that! Yes, the pairing process works much much better. Just be warned that although the Hubitat engineers are well aware of the connection drop off issue, it's not easy to diagnose. It may take a while, and there's no promises.

I'm already working on the motion sensor device driver, currently testing.

2 Likes
7

No problem at all. Like I said I was ready to toss them. You may have given them new life!

And crud, I missed the repeated clicking to keep the sensor alive. Hence why they took longer.
Since I am not doing anything with them I will leave and lets see what happens.

8

No guarantees we will be able to get these working. But the next update will have a change in our zigbee stack that should help.

I’ve been researching these quite extensively and they do seem to have a proven track record of being inconsistent and problematic for other platforms if they work at all.

2 Likes
9

Wow, you have been busy @veeceeoh! Glad to see that you already published a version!

Here’s an update from my side, consolidating the multiple reports I shared across other threads.

Xiaomi Motion Sensor

  • Pairing took a few tries.
  • None of the sensors have fallen off after 48 hours.
  • Motion reporting works perfect with ST handler. Battery reporting does not work.

Xiaomi Temperature/Humidity Sensor

  • Pairing succeeded in the very first try.
  • Sensors fell off multiple tries, in intervals of 3-6 hours.
  • No reporting worked with ST handler. Reporting works flawlessly with your new handler.

Aqara Contact Sensor

  • Pairing succeeded in the very first try.
  • None of the sensors have fallen off after 24 hours.
  • No reporting worked with ST handler. Does not work using the Generic Zigbee handler either.

P.S: As you had mentioned earlier, I too follow the same method to get fallen off device back online. Simply pressing the pairing button while a device scan is in progress, resuscitates the device.

1 Like
10

So my results are: Both my Xiaomi original temperature/moisture sensors reported for almost exactly 30 minutes, then stopped, with the reports getting further apart. My suspicion is that there’s some acknowledgement that the Xiaomi hub sends to the device after receiving the values that it’s not getting, but I have no way to confirm that from here. Hopefully the next update will have a positive effect.

11

[RELEASE] v0.5 of device drivers for Xiaomi “Original” & Aqara Motion Sensors

Links:
• Xiaomi “Original” Motion Sensor device driver code
• Xiaomi Aqara Motion Sensor device driver code

Unlike with the Temperature/Humidity Sensors, there needs to be separate device drivers for the two motion sensor models, because the Aqara model supports the Illuminance Measurement capability that can be accessed by apps such as Rule Machine, while the “original” model does not have that capability.

Features:

  • The Hubitat hub will correctly select the custom device driver for the appropriate sensor model when paired
  • The date/time of the most recent detected motion is stored as lastMotion (human readable) and lastMotionDate (java format).
  • The date/time of the most recent report of any kind is stored as lastCheckin (human readable) and lastCheckinDate (java format). This may be useful in determining whether the sensor is still connected, since a status report including battery voltage is sent every 50-60 minutes.
  • Battery replacement date tracking, stored in batteryLastReplaced state
  • Commands / Preferences include:
    • A Reset Battery Replaced Date command to track battery life
    • A Reset To Motion Inactive command for override of detected motion
    • A time delay to set how long the driver waits after motion is detected to reset to motion inactive state (see notes below for more information)
    • Date & 24-hour clock settings for display of lastCheckin
    • Min/Max voltage values used to calculate the battery percentage

Notes:

  • These device drivers are not final, and some features or preferences may be added / removed

  • Both models of Xiaomi Motion Sensors only send a “motion detected” message, and do not send a “motion inactive” message. Because of this, the device driver sets the motion inactive state using a countdown timer in its code.
    There is a user preference setting for this, with a default of 60 seconds. This is because in normal operating mode, the hardware is designed to be “blind” to any motion for 60 seconds after a motion detected message is sent, in order to reduce battery consumption.
    This 60-second reset delay cannot be changed, however, when the sensor is paired, and also when the reset button is short-pressed, the sensor goes into “testing mode”, and will report any detected motion every 3-5 seconds, for a period of about 2 hours. Use the testing mode time period to determine the best placement for the use of the motion detector. Placement is very important, because there is no ability to change the sensitivity level of the sensor.

  • I do not have an Xiaomi “original” Motion Sensor to test with, but when my Aqara Motion sensor’s connection with the Hubitat hub is dropped, I had to LONG-press the reset button while Hubitat is in “Device Discovery” mode in order to reconnect. Although it is effectively re-pairing the sensor, I did not have to remove it from my Hubitat’s device list, and after the LED flashed 3 times to indicate a successful connection, I saw reporting resume as normal.

2 Likes
12

Perhaps, but from the months of working with these sensors and doing research on other people's exploits with connecting them to non-Xiaomi hubs, I believe the connection issue relates to the regular "status" report that they send, about every 50 minutes for the Aqara models, and every 60 minutes for the Xiaomi "Original" models.

These "status" reports are what all of the device drivers use to parse the battery voltage data to calculate the battery percentage. So when used with the SmartThings hub, looking at recent battery reports in the events list for an otherwise idle device is the best indicator of whether its still "awake" and connected to the hub. This will also be true with the Hubitat hub, if the dropped connection issue can be worked out.

In all of my testing, over 90% of the instances of dropping the connection was just before the "status" report was to be sent. In fact, when I reconnect the sensors using the reset button short-press method, the very first thing they do is send that "status" report and the battery percentage is updated by the device driver (as seen in the device's Events List or the Hubitat Hub's Logs webpage.

2 Likes
13

[UPDATE] v0.5.1 of device driver for Xiaomi Aqara Motion Sensor

Changes:
• Added a second fingerprint for another revision of the Aqara model, as identified with @bomountjoy’s help. (Thanks!!) This should help the Hubitat to select the correct device driver when pairing either revision of the Aqara model. Please let me know if it works.

Link:
• Xiaomi Aqara Motion Sensor device driver code

14

@veeceeoh Really great work! You seem to be actively pushing out updates :+1:t3:
I have had not had issues with either of the drivers you have published until now, except that the Temperature sensors do not seem to have reported their battery levels to the Hubitat interface ever since they were paired (image below).
07%20PM
Is this a known issue or would this be something wrong at my end alone?

15

working now

16

My bad - I didn't push the updated code from my computer to GitHub. It is updated now, sorry about that!

17

Has anyone tried the Aqara leak sensors yet?

18

Neither. :smile: But now it's possibly a known issue!

Which model of Temp/Humidity Sensor is this - "original" or Aqara?

Also, your screenshot shows a lastCheckin of yesterday evening, which tells me it has probably dropped the connection.

19

After I finish the device driver for both types of Door/Window contact Sensors, I'm going to make one for the leak sensor. That one will be pretty quick to make.

1 Like
20

You’re a Prince Keith! Thank you.