How to use Xiaomi door sensors with Home Assistant and ESPHome

by Pete
12 minutes read

One of the most popular uses of home automation is for security, which often involves motion sensors. MCCGQ02HL sensors are commonly used in motion sensor applications due to their low cost and high sensitivity. However, integrating them with a home automation system like Home Assistant can be daunting for beginners.

In this article, we’ll show you how to use Xiaomi Mi Door and Window (MCCGQ02HL) sensors with Home Assistant and ESPHome, a powerful and easy-to-use firmware for ESP32 boards. We’ll guide you through the process of connecting the sensor to your board, configuring it in ESPHome, and integrating it with Home Assistant. By the end of this article, you’ll have a working motion sensor that you can use to automate your home security.

Let’s get into it

For this to work, you’ll need to the following:

Steps

An overview of the deployment. The dotted lines denote an indirect path mean that ESPHome is hosted onto of Home Assistant, the devices and services will connect via the Home Assistant device, passing the traffic to ESPHome.

Flow

From right to left:

  • The door sensor will connect to the closest ESP32 “BT Hub”
  • The ESP32 will connect to the Wi-Fi network which allows connectivity to Home Assistant and ESPHome
  • The ESP32 will check the bindkey with Xiaomi cloud to allow for communications with the door sensor
  • The ESP32 will handle the communication with Home Assistant and share sensor information for us in dashboards, automations, and scenes, etc

ESPHome doesn’t, out of the box, support Xiaomi door sensors so we’ll need to use an external source for the integration. Fortunately, Dentra on GitHub has created such a plugin for us to use.

Additional to Dentra’s project, you’ll need Xiaomi-cloud-tokens-extractor by Pior Machowski on GitHub to extract your Bind key and tokens from the Xiaomi’s servers.

1
Create a miot_config.yaml config file (optional, but the contents are necessary)

We need to tell ESPHome to download the integration during compilation. You can add the code directly in to the ESP32’s YAML configuration, or you can create a separate file to keep your overall code clean.

You’ll need to specify:

  • Your Xiaomi username and password
  • The github location of the Dentra github page

Here is an example of my common/components/miot/miot_config.yaml file:

miot:
  xiaomi_account:
    username: <your email address?
    password: <your xiaomi account password>
external_components:
  - source: github://dentra/esphome-components

If you, like me, separate out the files, you can use the <<: !include command to add the code in.

<<: !include common/components/miot/miot_config.yaml

2
Add your Xiaomi Door Sensor to your account using your Phone

I could reinvent the wheel – or I can send you to the Xiaomi website where they’ve already created instructions on how to add their products. Follow the instructions down the bottom and you should be good to go onto the next step.

You won’t necessarily need the app after you’ve added the device to your account, however you can use it later on if you ever want to not use ESPHome to connect to your devices. So don’t worry!

3
Extracting the Xiaomi BindKey using Xiaomi-cloud-tokens-extractor

You can obtain both MAC and BindKey (ie: BLE Key) from Xiaomi’s cloud environment with the Xiaomi-cloud-tokens-extractor app. It’s a straightforward little python app that will prompt you for your Xiaomi cloud username and password and it will spit out the already joined devices and their details.

I have many door sensors :P

4
Building YAML files for each sensor

If you’re like me and have more than 5 sensors, and more than 2 or 3 ESP32 devices, it can get a bit messy keeping track of, and maintaining, each sensor’s configuration.

Therefore, I recommend creating a separate YAML file for each sensor – that way you have a central file that can be reused in all ESP32 devices. And saves you time updating each sensor if you want to change the name or add features later, etc.

There are two files, or configuration items, we need to create for each device.

  1. Binary Sensor
  2. Sensor

Here is an example of a binary_sensor I use for my Dining Room Door. I’ve masked the device’s MAC and bindkey. I’ve used the MAC address of the device for the sensor name and created a label to stick onto the device containing the MAC so I can identify what device I’m looking at. The Binary sensor contains the bulk of the code.

# Dining Room Door
  - platform: miot_mccgq02hl
    mac_address: "AA:BB:CC:DD:EE:FF"
    bindkey: "A-LONG-BIND-KEY-HERE"
    name: "AA-BB-CC-DD-EE-FF Sensor"
    light:
      name: "AA-BB-CC-DD-EE-FF Light"
    alert:
      name: "AA-BB-CC-DD-EE-FF Alert"
    battery_level:
      name: "AA-BB-CC-DD-EE-FF Battery Level"
    battery_voltage:
      name: "AA-BB-CC-DD-EE-FF Battery Voltage"

Here is an example of a matching sensor. The purpose of this sensor to keep track to the RSSI signal to determine it’s strength.

# Dining Room Door
  - platform: ble_rssi
    mac_address: "AA:BB:CC:DD:EE:FF"
    name: "AA-BB-CC-DD-EE-FF RSSI"

I save each sensor to its own YAML file (if you have only one ESP32, you can paste the code directly into the YAML of the ESP32 in ESPHome.

My file structure looks like this:

  1. common/components/mccgq02hl/binary_sensor_AA-BB-CC-DD-EE-FF.yaml
  2. common/components/mccgq02hl/sensor_AA-BB-CC-DD-EE-FF.yaml

5
Putting it all togther

Now the fun part – we add the code to our ESP32 YAML and we compile and send it! If you have one or many sensors reporting to the same ESP32, then stack them!

.....
# Enable Home Assistant API
api:
ota:
##### Include Global Custom Files
<<: !include common/components/miot/miot_config.yaml
sensor:
  - <<: !include common/devboards/esp32/esp32_sensor_common.yaml  
  - <<: !include common/components/mccgq02hl/sensor_AA-BB-CC-DD-EE-FF.yaml # Dining Room
  - <<: !include common/components/mccgq02hl/sensor_AB-BB-CC-DD-EE-FF.yaml # Front Door
binary_sensor:  
  - <<: !include common/components/mccgq02hl/binary_sensor_AA-BB-CC-DD-EE-FF.yaml # Dining Room
  - <<: !include common/components/mccgq02hl/binary_sensor_AB-BB-CC-DD-EE-FF.yaml # Front Door
....

6
Validating sensors

Make sure your sensors appear in Home Assistant. If they do – great! If not, check your code and make sure the door sensor is talking to your ESP32, and your ESP32 is talking to Home Assistant.

7
Add a Dashboard Widget

The fruits of your labor can be seen on your dashboard.

I personally like a Lovelace card to only show me when the doors are open and be hidden the remaining of the time. For that, we can use conditional types to show when the state_not: ‘off’.

type: conditional
conditions:
  - condition: state
    entity: binary_sensor.aa_bb_cc_dd_ee_ff_sensor
    state_not: 'off'
card:
  type: tile
  entity: binary_sensor.e4_aa_bb_cc_dd_ee_ff_sensor
  name: Dining Room Door
  icon: mdi:door-sliding-open
  color: purple

Conclusion

There you have its folks, a convenient way to use a cheap ESP32 as a Bluetooth Hub and to track if your doors and / or windows are open or closed.

Of course, you can create further automations based on certain conditions, but this is a good start.