Components Home Assistant "Xiaomi Gateway”

6 minutes of reading
Proconductor: Home Assistant Community
Availability: included in theHUB
Category: software
Type: components Home Assistant
Implementation difficulties: low
Card revision: 2.3

The "Xiaomi" component Gateway” di Home Assistant it is necessary to integrate il BRIDGE/Gateway ZigBee↔︎TCP/IP of the line Xiaomi Mi Smart Home (Mijia).

Tale gateway has the function BRIDGE/Gateway (in practice, of centralizer) for all devices ZigBee of the Xiaomi line composed from sensors, switches, pulses, devices and more as well as all those compatible (for example some of the line IKEA TRÅDFRI, or some Aqara).

The full name of the component actually it would be "Xiaomi Gateway (Aqara)", But it is a name extremely misleading. In fact, the component allows ONLY the integration of gateway Xiaomi Mi (Mijia) e NO the gateway LUMI Aqara which, although conceptually very similar (it is also a BRIDGE/Gateway ZigBee↔︎TCP/IP), cannot be integrated.

The presence of the name "Aqara"Refers to the fact that any components (sensors, actuators, etc.) marked Aqara compatible with gateway Xiaomi, when the latter is integrated with Home Assistant are in turn integrated. The reverse is not true: Xiaomi components compatible with a gateway Aqara NO can be indirectly integrated with Home Assistant as above, as the latter NO can be integrated with Home Assistant.

Il gateway is initially configured (for access to proman Wi-Fi) through theapplished here "Xiaomi Mi Home" (available for Android e iOS) and, once this configuration has been made, always via theapp it is possible to connect to it "satellite" components connected to him through proProtocol ZigBee. The behaviors (ie notifications, alarms, adjustments) of these components with respect to gateway (emission of audible, visual or notifications towards theapp) are administered and managed by Gateway through theapp "Xiaomi Mi Home".

Once configured the gateway at the proman Wi-Fi through theapp "Xiaomi Mi Home", it will be possible to integrate it - through the component "Xiaomi Gateway"Described here - with the propetition for Home Assistant in order to:

  • integrate the same functions as the gateway (emission of sound effects, lighting - chromatic - of its LED light);
  • integrate the devices / sensors / components possibly connected to the gateway same.
ATTENTION: To perform this integration it is necessary that the firmware version of the component is equal to or less than the 1.41.159. Higher firmware does not allow the integration described here, except the implementation of this guide.

Once the integration is completed il Gateway and any satellite components will emerge on Home Assistant How entity of various types, based on their nature (appgrease sensors, buttons etc.).

Supported devices
  • Gatewa Xiaomi (lumi.gateway.v2, lumi.gateway.v3)
  • LUMI Aqara Air Conditioning Companion (lumi.acpartner.v3)
  • LUMI Aqara Intelligent Door Lock (lock.aq1)
  • Temperature and Humidity Sensor (first and second generation)
  • Motion Sensor (first and second generation)
  • Door and Window Sensor (first and second generation)
  • Button 1st generation (manageable: single, double, long press)
  • Button 2nd generation (manageable: single, double press)
  • Plug aka Socket (version ZigBee: reports consumed power, instantaneous, status and if the device is in use)
  • Wall Plug (shows consumed power, snapshot, status)
  • LUMI Aqara Wall Switch (single pressure)
  • LUMI Aqara Wall Switch (double pressure)
  • LUMI Aqara Wall Switch LN (single pressure)
  • LUMI Aqara Wall Switch LN (double press)
  • LUMI Aqara Wireless Switch (single pressure)
  • LUMI Aqara Wireless Switch (double pressure)
  • LUMI/ Xiaomi Cube
  • Gas Leak Detector (reports alarm and density)
  • Smoke Detector (reports alarm and density)
  • Gateway (manageable: light, sensor of luminosiness, riproduction sounds)
  • Intelligent Curtain
  • Water Leak Sensor
  • Vibration Sensor
  • Battery
Unsupported devices
  • Gateway LUMI Aqara
  • Gateway Radio
  • Gateway Button
  • Xiaomi Mi Air Conditioning Companion (lumi.acpartner.v2)
  • LUMI Aqara Intelligent Air Conditioner Controller Hub (lumi.acpartner.v1)
  • Decoupled mode of the Aqara Wall Switches (single and double press)
  • Additional alarm events of the Gas and Smoke Detector: Analog alarm, battery fault alarm, sensitivity fault alarm, I2C communication failure

Nb The list is constantly evolving at the official component page.


The detailed guide to the integration is as follows:

Integrate the Gateway Xiaomi Mi Smart Home a Home Assistant


The code block to be entered at the configuration of Home Assistant which allows to integrate the gateway is the following:

  discovery_retry: 5
    - key: xxxxxxxxxxxxxxxx

In case more are present gateway, the syntax is as follows:

    - mac: xxxxxxxxxxxx
      key: xxxxxxxxxxxxxxxx
    - mac: xxxxxxxxxxxx
      key: xxxxxxxxxxxxxxxx

The variables available for configuration customization are the following:

interface(string, optional) - The network interface from which to search for the presence of gateway.
discovery_retry(internal, optional) - The number of times for which Home Assistant retry the connection to gateway in case of bankruptcy. Default: 3
gateway(map, required) - The list of gateway to be integrated.

mac(string) - Il MAC Address of the gateway. Optional in case there is only one gateway.
key(string, request) - The LAN access key to gateway (explained in guide dedicated to the integration of Gateway su Home Assistant).
host(string, optional) - The IP address of the gateway. Used in case you do not want to use automatic multicast discovery.
disable(Boolean, optional) - Disable the gateway. Used to not integrate a given gateway in the case of more co-presence gateway.


The integration of this component includes four services:

xiaomi_aqara.play_ringtoneRiprogives a specific sound effect
xiaomi_aqara.stop_ringtoneStop the reproduction of a sound effect
xiaomi_aqara.add_deviceActivate the mode of adding satellite devices to the gateway. It is the same as doing it through theapp "Mi Home"
xiaomi_aqara.remove_deviceRequires al gateway to remove any satellite devices on the gateway. It is the same as doing it through theapp "Mi Home"

"Xiaomi_aqara.play_ringtone" service

If evoked, it imposes on the gateway of riproduce a specific sound among those available from the factory. This service only works on gateway with firmware starting from the version 1.4.1_145. This is a useful function, for example, as an acoustic notification in our automations Home Assistant.

Service data attributesOptionalDescription
gw_macNo.MAC address of gateway
ringtone_idNo.The ID of the sound to be reproduce
ringtone_volAnd it isThe volume in percentage

Accepted values ​​for the fieldringtone_id I'm:

  • Alarms
    • 0 - Police car 1
    • 1 - Police car 2
    • 2 - Accident
    • 3 - Countdown
    • 4 - Ghost
    • 5 - Sniper rifle
    • 6 - Battle
    • 7 - Air raid
    • 8 - Bark
  • Campanelli
    • 10 - Doorbell
    • 11 - Knock at a door
    • 12 - Amuse
    • 13 - Alarm clock
  • Wake
    • 20 - MiMix
    • 21 - Enthusiastic
    • 22 - GuitarClassic
    • 23 - IceWorldPiano
    • 24 - LeisureTime
    • 25 - ChildHood
    • 26 - MorningStreamLiet
    • 27 - MusicBox
    • 28 - Orange
    • 29 - Thinker
  • Custom sounds (added via theapp "Mi Home") starting from the ID 10001, to grow.

"Xiaomi_aqara.stop_ringtone" service

If evoked, it imposes on the gateway to interrupt the riproproduction of any sound in the course of reproduction.

Service data attributesOptionalDescription
gw_macNo.MAC address of gateway

Service "xiaomi_aqara.add_device”

If evoked, it imposes on the gateway to activate the mode of adding satellite devices to the gateway. It is the same as doing it through theapp "Mi Home"

Service data attributesOptionalDescription
gw_macNo.MAC address of gateway

Service "xiaomi_aqara.remove_device”

If evoked, it imposes on the gateway to remove any satellite devices on the gateway. It is the same as doing it through theapp "Mi Home"

Service data attributesOptionalDescription
gw_macNo.MAC address of gateway
No.Hardware address of the satellite device to be removed

Examples of use in automation

Let's look at an example:

- alias: Doppio click
    platform: event
      entity_id: binary_sensor.switch_158d000xxxxxc2
      click_type: double
    service: light.toggle
      entity_id: light.living_room_lamp

In this example, the double click of an Aqara button (entity named "binary_sensor.switch_158d000xxxxxc2") Integrated through Gateway and the present component "Xiaomi Gateway (Aqara) "causes a lamp (entity of name"light.living_room_lamp") Turn on / off.


You may find on the logs of Home Assistant voices of this type:

2017-08-20 16:51:19 ERROR (SyncWorker_0) [homeassistant.components.xiaomi] No gateway discovered
2017-08-20 16:51:20 ERROR (MainThread) [homeassistant.setup] Setup failed for xiaomi: Component failed to initialize.

This means that the gateway was not recognized by Home Assistant.

To try to solve, appurge the following aspects:

  • Make sure you have enabled LAN access on the gateway (See guide to the integration on Home Assistant).
  • Disable the firewall on the device where it is running Home Assistant.
  • Make sure the router Wi-Fi supports (and has activated) the multicast service (mDNS).
  • Proto set the field "mac"Empty.
  • Proto set the field "discovery_retry"To 10.
  • Proto disable and re-enable LAN access on the gateway.
  • Perform a hard reset of the gateway: press its button for 30 seconds and perform the propairing on theapp "Xiaomi Mi Home".
  • In case Home Assistant is running on Docker, make sure to use the "–net=host"(Must be added to the file"/boot/cmdline.txt").
  • In the event that an attempt is made to check the light of the light gateway, the error{ "error" : "Invalid key" }, regenerate the key (subject of the guide to integration on Home Assistant) using an Android smartphone (some instances have proproblems with the keys generated by iOS) or, alternatively, an emulator such as bluestacks.
  • In case the requested library “PyXiaomiGateway”Cannot be installed, some necessary dependencies will need to be installed first such aspython3-dev,libssl-dev,libffi-dev in manual mode (eg, $ sudo apt-get install python3-dev libssl-dev libffi-dev).

Home Assistant Official LogoATTENZIONE: remember that there is on our FORUM community an ad hoc section dedicated to Home Assistant, for any doubt, question, information on the specific merit of these components.