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

cd /home/pi/Desktop/
git clone https://github.com/lazcad/homeassistant

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

cp -rv /home/pi/Desktop/homeassistant/components/* /home/homeassistant/.homeassistant/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

sudo su -s /bin/bash homeassistant
cp -rv /home/pi/Desktop/homeassistant/components/* /srv/homeassistant/lib/python3.5/site-packages/homeassistant/components/

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.

node listeners.js 
{ cmd: 'iam',
  port: '9898',
  sid: '286c078XXXXX',
  model: 'gateway',
  ip: '192.168.1.28' }
{ cmd: 'get_id_list', sid: '286c078XXXXX' }
{ cmd: 'get_id_list_ack',
  sid: '286c078XXXXX',
  token: 'D5M1ElWcNl5XXXXX',
  data: 
   [ '158d000156cbfa',
     '158d000155d2b7',
     '158d000149a352',
     '158d000159a218' ] }
th 158d000156cbfa 18.71 59.87
{ cmd: 'read_ack',
  model: 'sensor_ht',
  sid: '158d000156cbfa',
  short_id: 16853,
  data: { voltage: 2975, temperature: '1871', humidity: '5987' } }
{ cmd: 'read_ack',
  model: 'switch',
  sid: '158d000155d2b7',
  short_id: 33826,
  data: { voltage: 3142 } }
MAGNET 158d000149a352 true
{ cmd: 'read_ack',
  model: 'magnet',
  sid: '158d000149a352',
  short_id: 41765,
  data: { voltage: 3055, status: 'close' } }
motion 158d000159a218 false
{ cmd: 'read_ack',
  model: 'motion',
  sid: '158d000159a218',
  short_id: 11179,
  data: { voltage: 3055, status: 'no_motion' } }

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

cd /home/homeassistant/.homeassistant/
sudo nano configuration.yaml

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

#Xiaomi
xiaomi:
  gateways:
    - sid:
      key: 4057E52D9XXXXXXX

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

group: !include group.yaml

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

customize: !include customize.yaml

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.

sudo nano customize.yaml

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

temperature:
  name: Température et humidité
  entities:
    - sensor.temperature_158d000156cbfa
    - sensor.humidity_158d000156cbfa

This one the state of the motion detector

motion_sensors:
  name: Mouvements
  entities:
    - binary_sensor.motion_sensor_158d000159a218

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

desk:
  name: Bureau
  entities:
    - light.gateway_light_286c07891571
    - sensor.temperature_158d000156cbfa
    - sensor.humidity_158d000156cbfa
    - binary_sensor.switch_158d000155d2b7  #bouton connecté

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.

default_view:
  name: Maison
  view: yes
  entities:
    - sun.sun
    - group.security
    - group.desk

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

#######################################
#          Views - Vues               #
#######################################
default_view:
  name: Maison
  view: yes
  entities:
    - sun.sun
    - group.security
    - group.desk

sensor_view:
  name: Capteurs
  view: yes
  icon: mdi:gauge
  entities:
    - group.temperature
    - group.motion_sensors
    - group.doors_windows
    - group.lights

#######################################
#    grouped by type of sensor        #
#######################################
temperature:
  name: Température et humidité
  entities:
    - sensor.temperature_158d000156cbfa
    - sensor.humidity_158d000156cbfa

motion_sensors:
  name: Mouvements
  entities:
    - binary_sensor.motion_sensor_158d000159a218

switchs:
  name: Commandes
  entities:
    - binary_sensor.switch_158d000155d2b7

lights:
  name: Eclairages à Led
  entities:
    - light.gateway_light_286c07891571
    #Xiaomi Gateway Led Ring

doors_windows:
  name: Portes et fenêtres
  entities:
    - binary_sensor.door_window_sensor_158d000149a352

#######################################
#   grouped by localization           #
#######################################
security:
  name: Sécurité
  entities:
    - binary_sensor.motion_sensor_158d000159a218
    - binary_sensor.door_window_sensor_158d000149a352

desk:
  name: Bureau
  entities:
    - light.gateway_light_286c07891571
    - sensor.temperature_158d000156cbfa
    - sensor.humidity_158d000156cbfa
    - binary_sensor.switch_158d000155d2b7  #bouton connecté

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

#################################################################################################################
# Xiaomi sensors customization                                                                                  #
# General settings : https://home-assistant.io/docs/configuration/customizing-devices/                          #
# device_class : https://home-assistant.io/components/binary_sensor/                                            #
# After modification, go to developer tools (phone icon) and choose homeassistant/reload_core_config then apply #
# projetsdiy.fr | diyprojects.io | May 2017                                                                     #
#################################################################################################################
sensor.temperature_158d000156cbfa:
  friendly_name: Température bureau
sensor.humidity_158d000156cbfa:
  friendly_name: Humidité bureau
  icon: mdi:water-percent
binary_sensor.motion_sensor_158d000159a218:
  friendly_name: Présence bureau
binary_sensor.door_window_sensor_158d000149a352:
  friendly_name: Porte d'entrée
  device_class: opening
binary_sensor.switch_158d000155d2b7:
  friendly_name: Bouton connecté
light.gateway_light_286c07891571:
  friendly_name: Anneau lumineux Gateway Xiaomi

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

sudo systemctl restart home-assistant

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.

• Home Assistant. Install the snap on Synology NAS on an Ubuntu Virtual Machine
• Home Assistant. Essential plugins to install. Samba, HACS, File Editor, MQTT Mosquitto
• Home Assistant Community Store (HACS), easily install themes and components
• Home Assistant. Get started on Raspberry Pi 4. Procedure 2020
• ESP8266 + DHT22 + MQTT: make a connected object IoT and include it in Home Assistant
• How to Include RFLink Radio Home Automation Devices at Home Assistant (HASS)