Xiaomi Home Integration for Home Assistant: official MIoT support, cloud by default

What the Xiaomi Home integration solves, and for whom

Home Assistant users with Xiaomi hardware usually face a choice between community-built bridges and whatever Xiaomi itself publishes. This repository is the second option: an official integration component, written in Python, that pulls Xiaomi IoT devices into Home Assistant through the MIoT device model. The README describes it as "an integrated component of Home Assistant supported by Xiaomi official", which is the central fact about the project. You are not relying on a reverse-engineered protocol layer maintained by a volunteer.

The audience is narrow but well defined. You need a Home Assistant instance already running, a Xiaomi account with devices already registered in the Xiaomi Home app, and a willingness to authenticate that account inside Home Assistant. If your devices never touched the Xiaomi Home app, this integration has nothing to import. It is also not a device-firmware project or a hub replacement; it is a bridge between two existing systems.

How login and device import actually flow

The mechanism is an OAuth 2.0 login against Xiaomi's cloud interface. The README states that the integration "does not keep your account password in the Home Assistant application", which is the point of using OAuth rather than storing credentials. After a successful login, the integration retrieves your device list from the cloud and presents a dialog named "Select Home and Devices" where you pick the home whose devices you want to import.

The data flow does not stop at login. The README is explicit that "due to the limitation of the Home Assistant platform, the user information (including device information, certificates, tokens, etc.) of your Xiaomi account will be saved in the Home Assistant configuration file in clear text after successful login." That is a real architectural constraint, not a warning label. Anyone who can read your Home Assistant configuration directory can act as your Xiaomi account. The documented revocation path is in the Xiaomi Home app: Profile, your username, Xiaomi Account management, Basic info: Apps, Xiaomi Home (Home Assistant Integration), Remove.

Control commands have a second path. Without a central hub gateway, the README says "all control commands are sent through Xiaomi Cloud". Local mode requires a Xiaomi Central Hub Gateway at firmware 3.3.0_0023 or above, or a device with a built-in central hub gateway at software version 0.8.9 or above. The gateway is only sold in mainland China, so outside that region the cloud path is the default and there is no documented workaround.

Installing the integration and adding your first device

Check the version requirements first. The README asks for Home Assistant Core 2024.4.4 or later and Operating System 13.0 or later. Three install paths exist: git clone, HACS, or copying the folder manually over Samba or FTPS. The README recommends the git clone method because it makes switching to a tag simple when you want a specific version.

For the clone path, run these commands from your Home Assistant config directory. The install script takes the config path as its argument.

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

After the script finishes, restart Home Assistant. The integration appears under Settings, Devices & services as an addable integration. Adding it opens the login step, and the README describes the flow as NEXT, then "Click here to login", then signing in with your Xiaomi account.

For HACS users, search for Xiaomi Home in the HACS search box, open the detail page and press DOWNLOAD. Manual installation means copying the custom_components/xiaomi_home folder into config/custom_components, which is the same directory the install script populates.

Once logged in, the "Select Home and Devices" dialog appears and you choose which home to import. To add a second Xiaomi account later, open the configured integration page, choose ADD HUB, then NEXT and log in again. Device lists and nicknames are changed later through the CONFIGURE button on the same page.

Local mode is conditional, and LAN control is discouraged

The most consequential limitation is geographic. Xiaomi Central Hub Gateway hardware is only available in mainland China, so users elsewhere cannot buy their way into the documented local mode. Devices with a built-in central hub gateway are the other route, and the README points to a wiki page listing supported models, which means you have to check your specific hardware rather than assume.

There is a partial alternative: Xiaomi LAN control, enabled under CONFIGURE, Update LAN control configuration. It is not restricted by region, but it only reaches IP devices on the same LAN as Home Assistant. BLE Mesh and ZigBee devices are out of reach. The README also says the function "may cause some abnormalities" and recommends against using it. Two further conditions matter. If a central gateway is present on the LAN, LAN control will not take effect even when enabled. And the README states that Bluetooth, infrared and virtual devices are not supported at all, so a Bluetooth thermometer or an IR blaster is outside the scope no matter which mode you pick.

Debug mode for action, and what it is for

Some MIoT devices expose actions that the standard entity mapping does not cover. The integration has a debug mode for action, enabled under CONFIGURE, Debug mode for action. When active, you can send an Action command message with parameters to a device manually, and the interface for doing so appears as a Text entity in Home Assistant.

This is a diagnostic and gap-filling tool rather than a normal control path. The README does not document a schema for the Action command payload, so you are expected to know the MIoT action specification for your device. Treat it as an escape hatch when a device capability is missing from the generated entities, not as the primary way to automate.

How it differs from community Xiaomi bridges

The obvious alternative is a community integration such as the MIoT-focused projects that predate this one, which typically speak to devices over the local network and derive their device definitions from published MIoT specifications. The difference in approach is where the authority sits. This integration is maintained by Xiaomi and authenticates against Xiaomi's cloud, so device support follows Xiaomi's own catalogue and account model rather than a community-maintained mapping table. The trade-off is that the cloud is in the control path for most users.

A second alternative is to skip Home Assistant entirely and automate inside the Xiaomi Home app. That removes the configuration-file exposure described in the README, but it also removes Home Assistant, which is the reason you are here. None of these options is strictly better; the choice is between official cloud-backed support and local-first community code with its own coverage gaps.

Maintenance, releases and licence status

The repository is not archived, and the last push was on 2026-08-18. The most recent tagged release listed is v0.4.7 from 2026-01-07, preceded by v0.4.6 on 2025-12-18 and v0.4.5 on 2025-11-25. That is a steady tag cadence across late 2025 and into 2026, with repository activity continuing after the latest release.

Upgrade cost depends on your install method. With the git clone path, the README shows fetching and checking out a tag and rerunning the install script, which is why that method is recommended. HACS users get the usual HACS update flow. Manual copiers have no update mechanism at all and must repeat the copy.

The licence is recorded as NOASSERTION, meaning GitHub could not match the LICENSE.md file to a recognised licence identifier. The repository also carries a separate LegalNotice.md. Read both files before distributing or modifying the component; this article cannot tell you what they permit.

Editorial conclusion

Adopt it if you already run Home Assistant Core 2024.4.4 or later, keep your Xiaomi devices in the Xiaomi Home app, and accept that commands normally travel through Xiaomi Cloud. Do not adopt it if you need fully offline control without a central hub gateway, or if your devices are Bluetooth, infrared or virtual, which the README lists as unsupported. Before installing, verify your Home Assistant version and operating system version, and decide which install method you want, because the git clone path is the one that makes switching to a release tag straightforward. After login, confirm which Xiaomi account the devices belong to, since device data, certificates and tokens land in your Home Assistant configuration in clear text.

Frequently asked questions

Official sources

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