The Xiaomi Smart Home kit is very well supported by the Open Source Home Assistant home automation server. This very economical kit is very well adapted to begin in home automation. In this tutorial, we will configure step by step the main devices of the kit: gateway, temperature and humidity sensor, door and window switch, motion detector and connected button. This tutorial has been developed a Home Assistant server running on an Orange Pi + 2e under Armbian. The installation is identical on Raspberry Pi.

Configure Devices and the Gateway from the Mi Home App

Before adding Xiaomi devices to Home Assistant, it is necessary to configure them from the iOS or Android mobile app. For this, I invite you to follow this article which explains step by step how to do.

Note on security and personal data

Everything must pass through a gateway. The gateway makes the link between the Aqara devices that generally operate in Zigbee and the mobile application. You understand, everything passes necessarily through the servers of Xiaomi in China. Even by connecting the devices to a home automation server, the data will necessarily pass through these servers. At the moment, there is not yet (to my knowledge) hack firmware that would keep control of personal data passing through the gateway (probes, voice, video, sensor status …).

Install components to support Xiaomi devices in Home Assistant

There are several projects on GitHub to add support for Xiaomi devices to Home Assistant. For this tutorial, I used the lazcad project available here which is a fork of the homeassistant-aqara project of foxxy. The name of Xiaomi products is not always very clear. This kit is often called aqara (or aquara, or Mijia, or MiHome!). Lazcas (http://lazcad.com) went further than the original project by supporting a larger number of devices. Here is the current list from the source code analysis:

• Binary sensors (binary_sensor)
  • Motion Sensor
  • Smoke sensor (no CE/FC)
  • Door and Window Sensor: door and window opening detector
  • Connected button
  • Cube: cube of command by gesture (not all gestures are yet supported)
• Light (light)
  • Gateway Light
  • Yeelight RGB Bulbs (no CE/FC)
• Sensors
  • Temperature and humidity
• Switch
  • Aqara Wall Switch (Single): single flush switch (no CE/FC)
  • Aqara Wall Switch (Double): dual flush-mounted switch (no CE/FC)
  • Aqara Wireless Switch (Single): single switch (no CE/FC)
  • Aqara Wireless Switch (Double): double switch to switch (no CE/FC)
  • Plug connected (no CE/FC)

Let’s move on to the installation of the components. Open a Terminal or connect SSH to the home automation server. Put yourself in a directory, for example / home / ft / Desktop then retrieve the sources of the project

Then copy the files into the components directory of Home Assistant. The procedure is different depending on the installation chosen.

Classic installation

The destination directory is

The directory of components can also be found in the folder  /home/USER/.local/lib/python3.5/site-packages/homeassistant/components/

You can delete the source files. You can also recover the files from another computer and download the files in FTP.

Installation in a virtual environment (since December 2016)

It’s a bit longer because you have to change user before copying files

You can disconnect (exit) and then delete the source files.

Configuring the Gateway Xiaomi Mijia in Home Assistant

The first thing to do is to configure the Xiaomi Gateway. To do this, open the Mi Home application on your smartphone or tablet and open the Gateway. In the previous tutorial, we saw how to configure devices on the Mi Home application. Now, to be able to integrate them to a home automation server, it is necessary to activate the developer mode.

How to enable the develop mode on the Mi Home app?

The developer mode will expose the frames on the LAN to UDP. To enable developer mode, select the gateway and click the three points in the upper right corner of the screen.

Click about

Now do a double tap (do not hesitate to repeat several times!) To bring up the hidden options. It took me hours to find the trick! Previously, it was necessary to go through the version number present at the bottom of the screen.

As if by magic, the hidden options are displayed :-). Select the 4th line (do not ask me for the exact translation, it’s also Chinese for me).

Activate developer mode (1) and note the key (2)

Confirm and open the 5th menu. You get a technical report on the gateway (1) and the devices connected to it (2).

Find device IDs with a Nodejs script from a computer

It is also possible (and easier for configuration) to retrieve the identifiers of devices connected to the gateway using a Nodejs script. Read this article to install Nodejs on your computer.

Recover the project here. Launch the listeners.js script (with the node listeners.js command) to retrieve identifiers and other information. Here is an example of my configuration (some identifiers are truncated). Ctrl + C to interrupt the script. The gateway is displayed first (iam). Then we find the temperature and humidity sensor (th), the door opening sensor (magnet) and finally the motion detector. The script also retrieves the status (or value) of each device and the battery voltage. If Javascript programming interests you, it is a good starting point to learn more.

Declare the Xiaomi gateway in the configuration.yaml file

Now log on to the server and go to the Home Assistant directory and open the configuration.yaml file

Paste this block (at the end for example) replacing the key value with the developer key obtained in the Mi Home app.

Other parameters

It is possible to add the devices directly to the configuration.yaml file, but it is better to separate the elements for easier maintenance. As the configuration evolves, the file may become very large and therefore more difficult to maintain. In addition, it is easier to refresh the interface without having to restart HASS every time.

To do this, we will tell HASS that it must use an external configuration file for the groups, add this option

We will do the same for the customization of the displays. Add this option in the homeassistant block: (1st block)

Finally, comment (#) the introduction option to disable the information block displayed on the main view. Save with Ctrl + X and then O.

Creating views and groups

So we’ll create a file called customize.yaml. We will see in more detail how Home Assistant works in a future tutorial. Here we go to the basics. Views are thematic tabs that are displayed at the top of the screen. For example, groups can be grouped into pieces. Here, we will simply create groups by sensor types and two views: Home and Sensors.

To call the different devices, one must refer to its type and then associate its identifier. Here are the types of devices. They are easily found in the xiaomi.py file from the source code (one file per sensor type).

• Binary sensors (binary_sensor)
  • Motion Sensor
  • Smoke sensor (no CE/FC, not tested here)
  • Door and Window Sensor: door and window opening detector
  • switch (connected button, wall switch)
  • Cube: cube of command by gesture (not all gestures are yet supported)
• Light (light)
  • Gateway Light
  • Yeelight RGB Bulbs (no CE/FC, not tested here)
• Sensors
  • Temperature
  • humidity
• Switch
  • Plug connected (no CE/FC)

This gives for the main sensors

• Motion : binary_sensor.motion_sensor_XXXXXXXXXXXXXX
• Temperature : sensor.temperature_XXXXXXXXXXXXXX
• Humidity : sensor.humidity_XXXXXXXXXXXXXX
• Switch : binary_sensor.switch_XXXXXXXXXXXXXX

To create a group, simply label it and define its name and its contents (entities). For example, this group displays temperature measurements

This one the state of the motion detector

One can also group by location. Here the devices in the office

Now, all you have to do is create the views that will contain the groups. It is possible to override the default view of HASS (default_view). Entities can contain groups or directly measurements / states.

Here is the complete configuration file that you just need to paste

Change device display (customize.yaml)

If you restart HASS to take the configuration into account, you will see that HASS uses the variable names to create the labels of the sensors / actuators. We’ll fix it. Create a new file called customize.yaml and paste the contents of this block

• Friendly_name: the label of the device that will be displayed on the screen
• Hidden: hides or shows the item
• Entity_picture: path to an image to use instead of the icon
• Icon: icon to use. You have to put a prefix. For example mdi: home. Compatible with Google Material Design icons
• Device_class: allows you to change the label according to the type of sensor. The complete list here and there
• Assumed_state: when a sensor returns a known state. For example, a switch on/off

Updating the configuration

Everything is ready. To take account of the configuration, it is possible to re-start HASS from the Terminal

The first startup will take a little time because ASS will recover and install the necessary dependencies (pycrypto in particular).

It is also possible from the interface by going to the Configuration tab. You can reload the configuration (reload core or reload groups) or restart the server (restart).

So, everything is perfectly functional. Here the home screen.

And the screen (the view) of the sensors

You can even turn on and change the color and intensity of the light ring of the Gateway Xiaomi.

Configuring Home Assistant may seem complicated. It is true that compared to the other servers (Domotoicz, Jeedom …) that you can fully (or almost) configure with the mouse, it is a bit confusing. HASS is completely free (including plugins). The Xiaomi kit is very easy to integrate into Home Assistant. Available online from China, it is often promoted at Gearbest (about €70) or Aliexpress (from €62 without connected plug). In the next tutorial, we’ll see how to handle events.

• Include ESP8266 + DHT22 + Homie MQTT IoT in Home Assistant (HASS)
• How to include MySensors v2 IoT objects in Home Assistant (HASS)
• Installing and Including the Xiaomi Smart Home Kit on Home Assistant (HASS)
• Soma Smart Shades, Wazombi Labs Solar Connected Curtain Motorization
• Install Home Assistant (HASS) on an Orange Pi running under Armbian