Integrate the gateway Xiaomi “Mi Smart Home”(Mijia) - and related accessories - a Home Assistant

6 minutes of reading
Guide purposes:
Concepts dealt with:
  • Software use
Software components used:
  • Home Assistant configured and working
  • un BRIDGE/Gateway Xiaomi already configured in Wi-Fi (therefore already surveyed by theapp mobile "Xiaomi Home") and that you mount a firmware version ≤ 1.41.159
  • any accessories ZigBee compatible already connected to gateway after configuration via app "Xiaomi Home"
Physical devices used:
  • The device on which it resides Home Assistant;
  • il gateway Xiaomi to be integrated (no LUMI Aqara);
  • any accessories ZigBee connected to it;
  • a smartphone.
GUIDA most indicated for:

All environments

Notes and disclaimer
  • qualsiasi eventuale modifica agli impianti domestici dev'essere progettata ed realizzata SOLO da personale qualificato;
  • any changes implemented in probefore is a propersonal responsibility as well as a profirst risk and danger (the contents of the present page are purely educational);
  • any changes implemented in proprior to a device it voids the guarantee, quality approvals and certifications.
Driving review: 3.7


As is known, the line Xiaomi Mi Smart Home (Mijia) is composed of many different devices, which - in most cases, specifically those based on proProtocol ZigBee - refer to a BRIDGE/Gateway ZigBee↔︎TCP/IP.

To integrate this gateway a Home Assistant means, first of all, integrate its features proprie (a multicolored LED light, a riprosound generator, a sensor luminosities) as singles entity, atomic, usable in our automations and / or via frontend. Secondly - but also so important, if not more - this integration allows to Home Assistant to inherit, as further new entities, all accessories connected to gateway same which elements "satellite" (sensors, actuators, etc.).

To do this you need to use the components Home Assistant "Xiaomi Gateway", conceived profor this purpose. In this guide we will understand how to integrate the gateway taking advantage of this component.

ATTENZIONE: To make the gateway be integrated in the ways described in this guide is necessario that it is already configured at theapp "Xiaomi Home" as prodotto located at “Mainland China"And not, as you would usually choose,"Italy". In case you have already configured them (as would be logical) like "Italy”It is necessary to reset it and redo the proinstallation certificate, this time indicating "Mainland China".

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.

Il gateway

There are two different models of gateway that are often confused with each other: the Mijia and l 'Aqara. The latter is actually part of the line LUMI "Aqara Smart Automation", is compatible with Appthe HomeKik e no it is possible to integrate it with Home Assistant (nor with others HUB) as it is not possible to activate in any way the LAN mode (o dev mode).

In the first - main node of the line Xiaomi Mi Smart Home (Mijia)it is instead possible activate this mode, as described in the following paragraph.

Nb Alternative (standard) al gateway Xiaomi for integration on personal HUBparts ZigBee are the BRIDGE/Gateway ZigBee↔︎TCP/IP software like deCONZ e zigbee2mqtt, or others.

LAN and KEY integration mode

Il gateway Xiaomi, to work, exploits the cloud of proconductor. This means that communication between theapp "Xiaomi Home" and the gateway (and the devices connected to it) happens using the Internet - which also guarantees an implicit remote control of these components.

To ensure that Home Assistant "Reach" the gateway it is necessary that the latter has activated a secret, hidden, called function LAN mode (o dev-mode). This mode enables the discovery of the gateway over the LAN /Wi-Fi through the door opening TCP 9898, allowing it to bypass the cloud in its entirety proproducer and to connect directly to the gateway.

Once the LAN mode is enabled, it is necessary to provide the subject who wants to contact the gateway (I our case Home Assistant) a key, a sort of password, such to allow control of gateway.

These two operating steps are performed from theapp"Xiaomi Home" (available for Android e iOS), which not only allows the initial configuration of Xiaomi devices, but also the configuration of the gateway in LAN mode as well as the recovery of the access key.

Nb CAUTION: in some situations theapp could do not allow activation of LAN mode. If the model provides it, there is no need to despair: just follow this other guide (spoiler: yes, we need to roll up our sleeves).

Nb CAUTION: in some other situations the integration may not work due to the closed side 9898 TCP port gateway and cannot be activated through theapp. This often happens with i gateway who have address MAC that start with 04:CF:8C (but not only): to verify that the port has actually been opened, run the linux command

sudo nmap -sU IP_DEL_GATEWAY -p 9898

In the case of the proLAN mode activation protocol explained below (opening the 9898 TCP port) DOES NOT work, it is necessary prosee if you can do it manually via physical connection to gateway.

Run theapp"Mi Home" statement and press on the icon relative to the gateway (ie "Mi Control Hub"):

Xiaomi Gateway - LAN and KEY - 1

Subsequently, click on the three dots (...) top right to access the details of gateway:

Xiaomi Gateway - LAN and KEY - 2

After that, press on "About":

Xiaomi Gateway - LAN and KEY - 3

At this point appa fairly meager menu will appear. Now based on the use of Android or iPhone you will need to take different actions:

  • su iPhone, click 4-5 times in the white area below the menu;
  • su Android, click 4-5 times on the last menu item ("Tutorial gameplaythe"):

Xiaomi Gateway - LAN and KEY - 4

This done appa menu will be hidden in Chinese. For profollow, click on the third voce:

Xiaomi Gateway - LAN and KEY - 5

The screen that opens will provide the ability to activate a selector which will activate LAN mode. Furthermore, once activated, the much sought after will be displayed a few lines below Integration KEY:

Xiaomi Gateway - LAN and KEY - 6

In this case the KEY of integration is “41D49ED97B487373"
At this point, click OK to make the LAN mode permanent and the KEY fixed.

Nb CAUTION: in some situations theapp could do not allow activation of LAN mode. If the model provides it, there is no need to despair: just follow this other guide (yes, we have to roll up our sleeves).


At this point it will be possible prosee integration at Home Assistant, simply by entering in configuration:

  discovery_retry: 5
    - key: xxxxxxxxxxxxxxxx

Where is it "key: xxxxxxxxxxxxxxxx"Rappit contains the previously obtained KEY of integration.

Save the configuration e restart Home Assistant.

ATTENZIONE: make sure - to ensure that integration works - that the proProtocol Multicast DNS (MDNS) is active on the router that provides connectivity Wi-Fi housekeeper.

If the reboot will be fine at the complete list of entity di Home Assistant ("Developer tools / States"At the web frontend) appat least one new entity will be created of type "light", that is to say "light.gateway_light_xxxxxxxxxxxx", Where" xxxxxxxxxxxx "is a string that identifies the gateway. This will mean that the gateway was reached and surveyed da Home Assistant. Incidentally, this "light" rappresists the multi-color LED available on the gateway.

In case the gateway have "satellite" components associated with it, post-integration them will be verifiable (always in the list of HA entities) as variable type entities based on their nature.

If for example al gateway there was an associate a flood sensor, in the entity list you will find a new sensor called "binary_sensor.water_leak_sensor_xxxxxxxxxxxx"Where" xxxxxxxxxxxx "is a string that identifies the sensor hardware number. And so on.


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 (subject of the guide to 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 procedura of pairing on 'app "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.

inDomus telegram channel