[Release] Xiaomi / Aqara device drivers



100K lux is pretty much sitting on the face of the sun. For all practical purposes 10K is the most you would need to resolve.


Totally understand. It looks like the Xiaomi driver though reports a range of 0-100 (I have to double check this). I have another driver that reports different ranges (0-255). Makes it kind of hard to use in rules with these differences in the values they report.

But I guess lux is not a percentage per say but an actual measurement. I need to look at this other driver again and see what it's reporting.

The 100k range though is what I pulled up from the ST lux definition.


Isn't that interpretable as just the maximum range of values that ST will accept for that measurement? I don't think it needs to be interpreted as the range across which every device that implements that capability must report. One sensor's maximum ability to distinguish is unlikely to be the same as the next's, so expanding any sensor's reports to span the entire gamut of possibilities is not necessarily a good solution. This is compounded by the fact that that the upper extreme of this range is both unlikely to happen on this planet, and many sensors also stop distinguishing at lux levels brighter than whatever their manufacturer decided was "bright enough" (a recent, particularly notable offender is the HomeSeer FLS100+ that stops after 250 lux, probably easily achieved shortly before sunrise on a clear day)--and this may vary between different sensors.

Theoretically, with lux being a standard unit, two different sensors should report similar values in under the same conditions. But in my experience. I don't think I've seen two different brands of sensors report the same values for this measurement. This is a different problem but also one that simply expanding the gamut across which they report is unlikely to solve. Unfortunately, the best "solution" for us seems to be just to test the measurements under the desired conditions for any sensor planned to be used where lux readings play a role.

That being said, the Xiaomi devices do indeed seem to report significantly lower readings than I'd expect from most of my other sensors, though I'm not sure I've ever put them in the same place to compare. But it looks like the driver is just using the exact value it gets from the sensor and not manipulating it in any way (besides any user configured +/- offset). So, we're probably stuck with what Xiaomi chose--unless someone did want to put it through testing and see how its reported values correspond to "standard" lux values (in the unlikely event you'd get a consensus from other sensors or any way you have to measure lux), then see if you can generalize some function to map the sensor's reported value to those.


Just a side note for those interested in sniffing the Xiaomi devices. P.s Xiaomi security key in the video.


Yes, Lux is a real unit. If you're intending to use Lux in automations, make sure your sensor is capable of measuring to at least 6K for outside use. Values generated from interior lighting will seldom go above 500.


Encryption keys are managed by the hub, not the device or manufacturer, and they are unique per zigbee network.


We might be referring to 2 different things:


Yup. This is the problem I'm seeing. Different devices are not reporting as a lux but more a range. So one device may use 0-100 and another 0-255. This of course means I have to take it into consideration for my automations. My office may only turn on the light below 30 but my laundry I'll have to do it when below 80. I guess there is no consistency but this is the hw vendors fault. Since lux is an actual measurement it may not be easy to translate 0-100 into any sort of lux value without measuring the device as you said and knowing that 100 may mean 8K.

This is exactly the other device I was referring too. I have 4 of these outside.

Looks like I just have to deal with this on a per device basis in the automatons. Just because they all implement it differently. Thanks for your input.


yes, there are crappy Lux implementations.
Zigbee devices tend to implement this properly since the attributes and their values are governed by the spec, however very few sensors provide this.

With Z-Wave devices its a crap shoot.
Aeon and Fibaro provide accurate readings.

If your intending to use Lux, its best to review the specs of the device before purchase, as I've mentioned, unless its capable of reporting 0 to 10K Lux, chances are the measurement units produced aren't Lux, I mean how could they be, think about it. 0 to 100, or zero to 255?

The only thing a sensor like that is capable of telling you is that it's dark, its of no value in telling you how bright it is.

Not all sensors implement this differently, only the ones that are implemented incorrectly....


These are about as simple as it gets. I have a whole bunch of both the older Xiaomi Door/Window Sensors and the newer Aqara ones, and have never had any problems other than where magnet placement or direction of travel is concerned. Maybe it's stating the obvious, but the indented groove in the plastic housing of the sensor must face the groove in the magnet side.

If the magnet is not moving away in opposition from the sensor portion (i.e., the magnet "slides" horizontally away from the sensor), then I have seen false readings or multiple repeated events of open/close/open/close, etc. In some PM discussions with @gavincampbell about that issue, I had started working on code that would prevent false positives (or negatives), but didn't complete it. I think I should revisit that because as you've pointed out the manual open / close reset "buttons" in the device details page aren't working correctly.

@mike.maxwell and @bertabcd1234 have already replied with excellent points, but I'd like to add few things specifically about the Aqara Motion Sensor's illuminance sensor and the way it reports illuminance:

  • Lux values are on a logarithmic curve. So an ill-placed or incorrectly aligned sensor is potentially going to give increasingly incorrect readings as you go up in brightness. Looking at photos of the Aqara Sensor's PCB here, it appears the illuminance sensor is at the top, just above the LED, and so illuminance reading of lights above the sensor would be affected by the fact that it is in the shadows under the circular top of the plastic case, as opposed to lights shining directly towards the face of the sensor. So my guess is that the angle of the sensor relative to the position of lighting is going to make a significant difference in readings seen.

  • Depending on the hardware revision, the Aqara Motion sensors will report values as high as 1000 lux or above 1400 lux, if you hold a light right up to the sensor. So it's not on a scale of 1-100, nor 1-255.

  • The lux values reported in events is simply the value received from the Aqara sensor. There is no conversion whatsoever, because it does not follow the Zigbee standards for Illuminance Level reporting (on cluster `0x0400) of Illuminance = 10^((Reported Value - 1) / 10000). This was confirmed by a SmartThings Community member who used a light measurement device to validate the unconverted values reported by his multiple Aqara sensors (see this post) I can confirm it just by running a "high" example value of 1000 through that calculation: 10^((1000-1)/10000) = 1.2586. There's no way that holding a light right up to the sensor would result in a illuminance reading of 1.2586 lux.

  • The Aqara Motion Sensor sends an illuminance report message in two cases:

  1. When motion is detected - more precisely, some milliseconds prior to the motion detected message being sent, which can create a chicken & egg situation depending on how your automation is set up, for example if some lights in the same room as the sensor are switched on with motion detection used as a trigger, the lux value state will still be a low value (because the illuminance report message was received before the motion detection message triggered the lights to turn on.)

  2. When it checks in every 50-60 minutes (along with the battery voltage report). I never bothered to add parsing of this illuminance report in the driver because it's simply too infrequent to be of much use. If people really want it added, I can see about doing that.

Based on the above, I would first recommend zero expectations that the cheap light sensor placed inside (and in a shadow region of overhead lighting) of these Aqara sensors is going to give any kind of tremendously accurate results. Definitely not accurate when compared with readings from a bonafide illuminance sensor device.

Second, I would recommend against using the reported illuminance value for automations without giving consideration to the fact that the sensor does not send illuminance reports on a regular basis or when there's an "X" value change in illuminance, but rather mainly reports it only when motion is detected (just some milliseconds before the motion detected message is sent).

Third, if you are going to use the reported illuminance values for automations, then I'd recommend doing thorough testing in situ before finalizing your automation.

Xiaomi / Aqara uses the standard Trust Center Link Key (5A: 69: 67: 42: 65: 65: 41: 6C: 6C: 69: 61: 6E: 63: 65: 30: 39), the same as all the other ZigBee Home Automation devices we're using with our Hubitat (or SmartThings, etc.) hubs.

The video link shows how to first add the Trust Center Link Key to then gain access your ZigBee network's encryption key (the "Transport" key, given while pairing a device), which is managed by the hub as @mike.maxwell points out.

These steps are necessary for doing sniffing of any ZigBee network, regardless of whether there's Xiaomi / Aqara devices on it or not.

Thank you for pointing it out, though!


Are this true? I don't see that my aqara humidity sensors reports lux.




That was a mistake. A "brain fart". I meant to type "Motion sensors". Now fixed.

Thank you for being my proofreader!


Thanks Keith. I don't honestly know what was causing the issue, but a few hours later, it all just started working. Reporting fine, both with the magnet, and by shorting the two wires I soldered to the reed switch. The open/close reset buttons are also working now too. Been working fine a few hours after pairing it on the January 25.


Wonder if I'm doing something wrong pairing a couple of Aqara Temp/Humidity sensors? I've got the latest, v0.8, of this driver but the only command I see is resetBatteryReplacedDate.

It's not updating, so I was looking for something like Refresh. Is there some other way to update the measured values? Thanks, Keith (@veeceeoh) for supporting these little fellas.


Nope, no refresh. Either they talk, or they don't... One of the reasons the Xiaomi devices aren't a lot of fun sometimes.

If they don't communicate reliably, consider getting some Xiaomi compatible repeaters and repairing. The Ikea Tradfri are my personal choice.


I blow them with my mouth to see if they are updating. If not, clicking discover devices and one click to the sensor button... but no problems now after creating a separate mesh just for Xiaomi and Tradfri.


Seems inevitable, but I just hate paying $10 shipping for a $10 item. Obviously, the answer is to buy a bunch to spread the shipping cost. :blush:

Thanks for the idea!


For me, small-item shipping is technically only $9 (as in $9.00, not $9.99 like the outlet). That brings the total to $18.99, which is a lot for a $9.99 item but sounds like a lot less than $20 even though isn't. I justified this as still being less than the price of almost any other ZigBee outlet I can find (except Peanut, which doesn't play well with Xiaomi) and far less than almost any Z-Wave Plug I'd trust (except Coolcam, the older version of which was reported to have an open neutral when "off" and the newer version of which I'm still not sure I'd trust for that reason). It's also less than everything you'd need to put an XBee together (the only other option I felt comfortable with).

Now that I know they work well. I'm thinking about getting more--but I might combine a couple together to spread the cost and justify it as you suggest. Or I could visit an Ikea (hours away), as I've been saying for years...

I'm not sure if wrote this to convince you or to justify my past, but hopefully it helps someone consider their options. :slight_smile:


Sure thing. What do you mean by "not updating?" I see humidity / pressure / temp readings in that screenshot. You should also see a battery percentage event within 2-3 hours of pairing. If not, then it means that it may have paired through an incompatible repeating ZigBee device ("incompatible" not meaning the repeaters' fault but rather the Aqara sensors'). If you have any repeating ZigBee devices, that is.

To get the Xiaomi / Aqara temp/humidity sensors reporting immediately, I always do exactly what @vjv does, blow on them. Also, a short-press of the reset button (without the hub in discover devices mode) will do a forced check-in that includes a battery report. But note that doing this won't guarantee that the sensor will stay connected, if it's going through an incompatible repeater. It will tell you straight way if it is still connected though.


I paired two of the humidity sensors and placed then in the same location. One updated periodically overnight; one did not. My hot humid breath registered on the former, nothing on the latter. So, I've re-paired it and it's responding now.

But, I've yielded to the advice I've been doing my best to ignore, and ordered three Tradfrì outlets. I've had decent luck with the original motion sensors, but really poor success with the vibration sensors. Hopefully, this will give me a good mesh and enable me to rely upon all the Xiaomi products.