Home | Difficulty level | Advanced | Installing and Including the Xiaomi Smart Home Kit on Home Assistant (HASS)

Installing and Including the Xiaomi Smart Home Kit on Home Assistant (HASS)

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:

Warning. Xiaomi devices are marketed only in China. It is possible to buy them outside of China. Some devices can be used for leisure or learning purposes (sensors, probes, connected buttons, cameras …). Other devices should not be used as they are CE, NF or FC certified (depending on your country). This is the case for all devices that use a 110V or 220V supply voltage (connected socket, connected switch, connected bulbs …), smoke detector. This list is not exhaustive. You are responsible for the use of Xiaomi devices in your home. Projects DIY can not be held responsible in case of accident, personal injury or deterioration of material.

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

/home/homeassistant/.homeassistant/custom_components
The destination directory may change (custom_components)

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

The destination folder will be able to evolve with the versions of Python used. Here it is 3.5

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.

xiaomi mi home gateway acces developper

Click about

 xiaomi mi home gateway acces developper 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.

 xiaomi mi home gateway acces developper double tap

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).

xiaomi mi home gateway activate developper tools

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

xiaomi mi home gateway developper mode sid

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

xiaomi mi home gateway developper identifiants

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).

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.

Note. It is not possible to display the same elements more than once in a view. For example, display the temperature of a room in the probe bar and in a group.

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

For each device, several parameters (documentation) can be added:

  • 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).

hass home assistant reload configuration restart server

In case of error, do not hesitate to re-start the server before starting your search.

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

home assistant xiaomi smart home mijia aqara default view

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.

 home assistant xiaomi smart home mijia aqara led ring gateway

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.