This guide describes how I got the Xiaomi Mijia LYWSD03MMC Temperature and Humidity sensors working in September 2022 (updated Dec 2024). This is likely to change soon as Bluetooth functionality is being built into Home Assistant Core, but for now it’s probably fairly accurate. Note that I am not an expert in this area, I read a lot and spent a lot of time on this.
I’m using the XDO BT-802 Bluetooth receiver. There’s an XDO BT-802 Bluetooth Linux tutorial on its use that I wrote here. It took quite a bit of time to get going in Linux, but once I did it’s been good with great range - though I’ve only been using it for a few days.
The PVVX Custom Firmware documentation is where I got a lot of this information. My aim is to make it easier to understand for beginners like myself.
Chrome Configuration
This comes directly from the PVVX page.
If using Android, Windows, Linux: Ensure you enabled “experimental web platform features”. Therefore copy the according link (i.e. chrome://flags/#enable-experimental-web-platform-features for Chrome), open a new browser tab, paste the copied URL. Now set the Experimental Web Platform features flag to Enabled. Then restart the browser.
** Quick Update December 2024 **
I just got a new temperature sensor, same model LYWSD03MMC, new SKU NUN4126GL. I went through the process to activate it using the PVVX flashing tool, then writing custom firmware v4.8, and it’s worked perfectly. Passive BLE Monitor detected the new device, I renamed its entities, it’s working perfectly. All the values I have in the screenshot below still seem to work.
Flash With PVVX Firmware
The Xiaomi sensors use encryption. The custom firmware removes the encryption and makes things a bit more configurable. This step can be worked around, but for that find another guide.
Open the TelinkMiFlasher website on a computer or phone that has Bluetooth available. I found my Android Pixel phone worked well, though my desktop computer also worked well once I attached the WiFi / Bluetooth combined antenna. If you have problems try turning off all other Bluetooth devices such as phones and mice, and move to an area that doesn’t have active Bluetooth transmitters.
- Tick the “Get Advertising MAC” box. Hit the Connect button. A dialog will pop up, wait until your Bluetooth device appears, choose it and hit Pair. This can take quite a while, be patient. You may have to move the Bluetooth devices around, reconnect a bunch of times, etc.
-
Hit “Do Activation” and wait until the three fields below are filled out. If they don’t fill out you may need to disconnect / reconnect / connect again.
-
Hit “Custom Firmware ver xxx” button. You don’t need to select or upload a custom firmware, that’s done for you.
-
Hit the “Start Flashing” button - it’s easy to miss. Wait - be patient. Don’t move devices around.
The flashing log should look something like this.
5:15:16 PM: Searching for devices
5:15:39 PM: Connecting to: LYWSD03MMC
5:15:42 PM: Hardware Revision String: B1.7
5:15:42 PM: Detected Mi device
5:15:42 PM: Get Advertising MAC (Web Experimental Features!)
5:15:42 PM: Connected
5:15:47 PM: MAC: A4C138XXXXXX
5:15:48 PM: Activating now, please wait...
5:15:52 PM: Registration successfull
5:15:52 PM: Send Login, please wait...
5:15:53 PM: Received device infos are correct
5:15:53 PM: Login successfull
5:15:56 PM: Load firmware file 'ATC_v38.bin'...
5:15:56 PM: File: ATC_v38.bin
5:15:56 PM: File size: 67252 bytes
5:15:56 PM: Count: 4204
5:16:37 PM: Start DFU
5:17:47 PM: Update done after 68.811 seconds
5:17:53 PM: Disconnected.
Make a note of the MAC address such as A4C138XXXXXX so you can copy and paste this later if required. It’s more commonly written A4:C1:38:XX:XX:XX
Disconnect, Reconnect, Configure
Once your custom firmware has confirmed it’s written disconnect and reconnect. From here you can configure any settings you like. I’m not an expert on what all these settings do, but I attempted to reduce the reporting frequency because for my application reporting every 5 - 10 minutes would be fine. To achieve that I made the following changes:
- Advertising interval: 7500ms (7.5s). My understanding is this is how often the Bluetooth device sends out “I’m here” pings so a phone / computer can connect to it to alter the configuration. I read it’s meant to be 10 seconds or less.
- Measure interval multiple. I set this to the max, 25, to reduce how often measurements are done. 7.5 * 25 = 187.5s = 3.125 minutes. That’s about how often I would expect to get temperature information. If I could make it less often, I would.
- RF TX Power: turn this down as much as possible while still reliably getting readings. Most of mine I’ve left near zero, but the sensor in the fridge is about +3. If you’re having connection problems you can turn it up, if it’s connecting fine you can turn it down to reduce battery use.
- Smiley: you can change how the face looks, or leave it to “comfort”. The additional settings below lets you configure the temperature thresholds.
- Advertising type: I use “BTHome”.
- Do NOT tick the “LE Long Range Only” box that is available in newer versions of the firmware. If you do this (as of 2023) Home Assistant can’t receive the messages, and you can’t connect to the temperature sensor with any computer, phone, or operating system I’ve tried (multiple Linux computers, multiple Bluetooth adapters, multiple phones that support BT5+). If you tick the box and untick the other box it’s probably unticked. More details here - NB very complicated.
You MUST hit “send config” once you’ve made these changes. The link above to the PVVX Github site has quite a bit more information.
Firmware v4.4
Firmware v3.8
Additional Configuration
There are additional things you can configure. I change the device name to something unique and easy to identify for Home Assistant - e.g. “Fridge” or “Office”. You can tweak the comfort parameters which control how the little face looks.
I also put a label on the back of the sensors so when I have them together I know which is which.
Sensors Configured
At this point your Bluetooth sensors are configured! Go use them!
I’ve found that with a good Bluetooth receiver the range is quite impressive when you use them with a good Bluetooth adapter with an external antenna:
- 10m through three walls seems to work fine
- 6m from inside a fridge and through three walls works fine
- 10m through a house wall and a concrete block wall to my greenhouse gives low strength but works
Integrating the Sensors with Home Assistant
Around Aug / Sept / Oct 2022 Home Assistant is starting to build Bluetooth features into the HA core, under the name BTHome - not to be confused with British Telecom. At the time of writing (HA 2022.09.05 release I think) it works but not as well as Passive BLE Monitor. If your BLE signal strength is low you get gaps in your data, rather than using the previous temperature the sensors show “unavailable” or similar. I have both running, but I only use the data from Passive BLE Monitor, which also provide signal strength.
For now, you can install the Passive BLE monitor integration. Follow its instructions.
As of HA 2022.09 and later, just wait for BTHome to discover the sensors, give you a notification, at which point you can add them to HA.
If there’s anything that needs more explanation post below and I’ll do my best. I can’t always reply quickly, but I will usually reply eventually.
If you would like help
I’m not an expert, but I’ll help if I can. Please read this tutorial I wrote on the Bluetooth XDO BT802 adapter I wrote. Run all the commands from the “Ensure Bluetooth is Enabled” section down, put the output below. I would also need to know the hardware you have HA running on and the Bluetooth adapter in use.
BTHome format seems to work fine without that plugin, I just had to wait 30 minutes after I changed the setting for the temperatures to start showing up.