ha_xiaomi_home and the hub gateway your local control depends on

install.sh is the install, and HACS and Samba reach the same folder

The recommended route is a clone plus a shell script. From inside the Home Assistant config directory:

cd config
git clone https://github.com/XiaoMi/ha_xiaomi_home.git
cd ha_xiaomi_home
./install.sh /config

The README recommends this one for a specific reason: it is convenient to switch to a tag when updating xiaomi_home to a certain version. The README also offers two other routes. HACS, at hacs.xyz, does a one-click install: search for Xiaomi Home, open the detail page, press DOWNLOAD. Manual install goes through the Samba or FTPS addons, where you download and copy the custom_components/xiaomi_home folder into config/custom_components.

So the component is not a package you install. It is a folder of Python placed next to the other custom components, and the script's job is to put it there. The stated floor before any of this works is Home Assistant Core 2024.4.4 or above, on Operating System 13.0 or above.

Upgrades are a tag checkout, and the README's example tag leads the release list

There is no upgrade command. Because the install is a git clone, an update is a checkout of a tag followed by running the script again:

cd config/ha_xiaomi_home
git fetch
git checkout v1.0.0
./install.sh /config

Two things a reader should notice here. The script takes the config path as an argument every time, so the same command works whether Home Assistant keeps its configuration at /config or somewhere else. And the example tag in the README is v1.0.0, while the three most recent releases in the repository are v0.5.0 on 2026-09-28, v0.4.7 on 2026-01-07 and v0.4.6 on 2025-12-18. The example is ahead of anything in that list, so copy a tag you have confirmed exists in your own clone rather than the one printed in the documentation.

For a reader who pinned v0.4.7 in January, the gap between that tag and v0.5.0 is nearly nine months.

OAuth 2.0 keeps your password out of Home Assistant and your tokens in clear text

Login uses OAuth 2.0, which means your Xiaomi account password is not stored in the Home Assistant application. The catch is stated in the same paragraph and it is not small. Because of a limitation of the Home Assistant platform, the user information of your Xiaomi account, including device information, certificates and tokens, is saved in the Home Assistant configuration file in clear text after a successful login.

So the file that holds the integration is also the file that holds credentials for your smart home. The exposure risk named is direct: exposure of that configuration file may result in others logging in with your identity. Nothing in this integration encrypts it, so what protects you is whatever already protects your Home Assistant configuration directory, backups of it, and any copy of it you have sent to a colleague.

Revocation is done on Xiaomi's side, not in Home Assistant: Xiaomi Home APP, then Profile, then your username into the Xiaomi Account management page, then Basic info: Apps, then Xiaomi Home (Home Assistant Integration), then Remove.

Local mode needs a central hub gateway, and that hub is sold only in mainland China

Local control is not a setting. It is a property of hardware. Local mode is implemented by the Xiaomi Central Hub Gateway running firmware version 3.3.0_0023 or above, or by Xiaomi smart devices with a built-in central hub gateway running software version 0.8.9 or above. If you have neither, every control command goes through Xiaomi Cloud, and the README states that plainly rather than describing a degraded offline mode.

The geographic consequence is harder than the version numbers. The Xiaomi central hub gateway is only available in mainland China; in other regions it is not available. A reader in Europe or the USA who reads the local mode paragraph first will conclude their installation can work without the cloud, and it cannot, unless one of their existing devices already carries a built-in hub.

A list of device models with a built-in central hub gateway lives in the project's wiki. That list is the thing to check before planning a local mode setup, and it is a wiki page rather than anything in the repository.

The LAN control switch is documented as something to leave off

There is a middle path between full local mode and pure cloud, and the project tells you not to use it. Enabling Xiaomi LAN control through Settings, Devices & services, Configured, Xiaomi Home, then CONFIGURE and Update LAN control configuration lets the integration reach IP devices, meaning devices connected to the router by WiFi or an ethernet cable, on the same local network as Home Assistant. It cannot control BLE Mesh or ZigBee devices.

The README says this function may cause some abnormalities and recommends NOT using it. Two further details decide the case for a reader outside China. Unlike the central hub gateway, LAN control is not restricted by region, so it is the only partially local path available everywhere. And if a central gateway exists anywhere on the same local area network as Home Assistant, LAN control will not take effect even when it is enabled.

An option that is not region restricted, does nothing when a hub is present, cannot reach ZigBee, and is documented as a source of abnormalities is worth understanding before you toggle it, not after.

Debug mode for action turns a Text entity into a live command channel

Under CONFIGURE there is a debug mode for action. When it is activated, you can manually send an Action command message with parameters to the device, and the interface for doing so is presented as a Text entity in Home Assistant.

That detail decides how careful you need to be. A Text entity is something automations, scripts and voice assistants also write to. Once the debug option is on, anything that can set the state of that entity can issue a real command to a real piece of hardware, and the entity does not know the difference between you typing a command and a script firing one. The README's debug-mode section gives no description of a dry run, a confirmation step, or a list of devices the mode covers, so the blast radius of the setting is whatever your automations can reach.

It is a debugging aid for a specific device, and the config path to reach it is Settings, Devices & services, Configured, Xiaomi Home, then CONFIGURE.

Bluetooth, infrared and virtual devices never reach the import list

Import is a device list you choose from, and part of that list will never appear. Most smart device categories are supported. The exceptions named are Bluetooth devices, infrared devices and virtual devices.

The import step itself is one dialog. After signing in, a box titled Select Home and Devices appears, and you pick the home that contains the device you want to bring in. You can add more accounts later through Settings, Devices & services, Configured, Xiaomi Home, then ADD HUB, and devices belonging to different accounts can end up in the same area.

Regions work the same way. The integration is usable in the mainland of China, Europe, India, Russia, Singapore and the USA, but user data in Xiaomi Cloud is isolated per region, so the region is chosen during import rather than in a global settings page. Devices from different regions can also be added to a single area. The practical consequence for a reader with devices bought in two places is that each region has to be imported separately, and an area can hold the result of both.

Licence metadata reads NOASSERTION while the repository ships LICENSE.md and LegalNotice.md

The licence question needs the repository rather than the badge. There is a LICENSE.md and a LegalNotice.md in the root, and the project is described as an integrated component of Home Assistant supported by Xiaomi official. What the repository metadata does not give you is a licence identifier: it resolves to NOASSERTION, which means the detected licence could not be classified. Read LICENSE.md before you redistribute the component or build it into a product, and do not assume from the metadata that any particular licence applies.

The project is not archived and the last push was on 2026-09-28, the same day as the v0.5.0 tag. Around it sit CHANGELOG.md, CONTRIBUTING.md, a .pylintrc, a CLAUDE.md, hacs.json, install.sh, and the test/ and tools/ directories, so the change history and the contribution rules live in the repository rather than on a separate site. The default branch is main and no homepage is published, which for a Home Assistant component means the integration is found the way HACS finds it rather than through a project page of its own.

Editorial conclusion

Adopt ha_xiaomi_home if your devices are MIoT and you want them in Home Assistant with an officially supported component rather than a community one. Do not adopt it if your kit is Bluetooth, infrared or virtual, and treat the local mode promise as conditional on hub hardware that is only sold in mainland China. Before anything else, read LICENSE.md yourself, because the licence metadata for this repository resolves to NOASSERTION, then decide who on your network can read the configuration file that holds the tokens.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. XiaoMi/ha_xiaomi_home on GitHub