Xiaomi’s Official Home Assistant Integration: What “Local” Actually Means
Xiaomi open-sourcing an official Home Assistant integration was, by most accounts, a genuinely surprising move. ha_xiaomi_home (github.com/XiaoMi/ha_xiaomi_home) is Xiaomi’s own first-party project, not a community reverse-engineering effort like hass-xiaomi-miot or AlexxIT/XiaomiGateway3. As of v0.4.7 (Jan 7, 2026) it’s up to 28 releases, sitting around 21.8k GitHub stars and 108 open issues — an actively maintained project, not a one-off PR dump.
Chinese tech media treated the release as a milestone. Zhihu (知乎, a Chinese Q&A and blogging platform) ran pieces with headlines like “小米有格局——官方正式开源「Home Assistant米家集成」” — roughly, “Xiaomi shows real character: officially open-sources the Home Assistant Xiaomi Home integration.” CSDN and 小众软件 (appinn.com) picked up the same framing: after years of running Mi Home as a closed garden, Xiaomi was finally meeting the open-source home automation community where it lives.
I went looking for the catch, because there’s almost always one when “local control” and “official vendor integration” show up in the same sentence. There is one here, and it’s a big enough gap that I think most non-China readers installing this integration expecting local control are going to be disappointed.
How it actually works: OAuth, MIoT Cloud, and what lands in your config
Setup starts with an OAuth 2.0 login to your Xiaomi account, done from inside Home Assistant. The integration doesn’t store your account password directly, which is the good part. The less good part: it does store “user information including device information, certificates, tokens, etc.” in your Home Assistant configuration file, in plain text, according to the project’s own README. GitHub issue #1156 (“The OAuth login might not be safe”) raises the same concern from a different angle.
Worth knowing: this isn’t a hypothetical. If your HA config gets backed up somewhere unencrypted, or your config directory ends up in a public repo by accident (it happens more than people admit), those tokens go with it. Treat your Home Assistant config the same way you’d treat a file with API keys in it, because that’s functionally what it now contains.
By default, here’s the command path for any device that isn’t routed through a hub gateway: your device publishes a state change to Xiaomi’s MIoT Cloud MQTT broker, the broker pushes that to the HA integration, and commands from HA go back out the same route in reverse. Every toggle, every automation trigger, round-trips through Xiaomi’s cloud. That’s the default for most devices most people will connect through this integration — not an edge case.
If you want the deeper breakdown of exactly what data crosses that cloud link and how the token storage compares mode-to-mode, we covered it separately in our Xiaomi Home integration privacy investigation.
The local-mode requirement most write-ups skip past
Here’s the part that the top-ranking English coverage — a Hacker News thread, a couple of thin “integration guide” posts, the bare README — mostly glosses over. True local mode, where device commands never leave your LAN, requires a Xiaomi Central Hub Gateway running firmware ≥3.3.0_0023, or another Xiaomi device with a built-in hub gateway on software ≥0.8.9.
The Central Hub Gateway hardware itself is only sold in mainland China. The README says this plainly: it “is not available” in other regions. If you’re reading this from Singapore, Australia, the UK, the US, or basically anywhere outside mainland China, the fully-local path the project documents isn’t hardware you can buy. It’s not a firmware limitation you can work around. It’s a SKU that doesn’t ship to your region.
That’s a meaningful gap for a project whose entire pitch, repeated uncritically across Chinese tech blogs, is “official local integration for Home Assistant.” For most of this site’s readers, the actual local path is closed at the hardware layer before you’ve written a single line of YAML.
What “LAN control” gets you if you’re outside China
The integration does offer a fallback called LAN control, and it’s the option most non-China readers will actually end up using. It only reaches Wi-Fi and Ethernet IP devices on the same network as Home Assistant. It does not cover Zigbee devices, and it does not cover BLE Mesh devices — which rules out a meaningful chunk of the Xiaomi ecosystem right there.
I cross-referenced this against Home Assistant Community forum threads and the Hacker News discussion mirror, and the reliability commentary is not encouraging. Multiple threads describe LAN control as flaky enough that some users recommend leaving it off entirely and accepting the cloud round-trip instead — on the logic that an unreliable local mode that silently falls back to cloud anyway is worse than just knowing you’re on cloud from the start. One HN comment described the local-control claim as reading like “a marketing way to print compatible with home assistant on the box.” I won’t quote it further than that, but the sentiment tracks with what I found digging through the issue tracker.
So the practical reality: outside mainland China, “local mode” in this integration means “some of your Wi-Fi devices, maybe, with a chance of falling back to cloud.” That’s a genuinely different claim than the one implied by the marketing and by most of the coverage I read while building this piece.
Device support gaps that apply regardless of region
A few categories are entirely unsupported no matter which mode you’re in:
- Bluetooth devices
- Infrared devices
- Virtual devices
If your Xiaomi ecosystem leans on any of these — and BLE-based sensors are common in the cheaper end of Xiaomi’s catalog — this integration doesn’t cover them at all. Not a local/cloud distinction, just a hard no.
Should you use this, or a community alternative instead?
If you own a Central Hub Gateway (mainland China only) or another Xiaomi device with a built-in hub, ha_xiaomi_home gets you closer to genuine local control than anything Xiaomi has shipped before, and I think that’s worth acknowledging even with everything above. That’s the one opinion I’ll stake out here: I think Xiaomi open-sourcing this at all, warts and all, is a better outcome than the alternative of community projects perpetually reverse-engineering a closed API — even though the regional gap undercuts the “local” framing for most readers outside China.
If you’re outside China and your devices are modern Wi-Fi units, hass-xiaomi-miot (al-one/hass-xiaomi-miot on GitHub) is the option that keeps coming up in English HA community threads for readers who want to force LAN-only control and disable cloud fallback as a hard setting — something the official integration doesn’t offer as a toggle. If your goal is a genuinely local path for Multimode Gateway hardware you already own, the community XiaomiGateway3 local integration is the route most international users land on. And if your actual goal is local Zigbee control, neither of the official-vs-miot options is the right tool at all — that’s a Zigbee2MQTT or ZHA question, not a MIoT-cloud-account question, and we compare those two directly in our ZHA vs Zigbee2MQTT guide for Aqara devices.
For a rundown of Mi Home’s own internal hub/sub-gateway/blind-gateway hardware tiers — a separate, older taxonomy question from the one this article covers — we have a companion piece breaking down which of those gateway tiers actually runs automations locally.
FAQ
Does Xiaomi’s official Home Assistant integration work without the cloud?
Only partially, and only under specific conditions. Devices routed through a Central Hub Gateway (mainland China only) or a compatible built-in hub can run local. Everything else round-trips through Xiaomi’s MIoT Cloud MQTT broker by default.
Can I get local control from Xiaomi’s official HA integration outside China?
Partially, via “LAN control” — but that’s limited to Wi-Fi/Ethernet IP devices, excludes Zigbee and BLE Mesh entirely, and multiple community threads report reliability problems significant enough that some users disable it.
Is the Xiaomi Central Hub Gateway available outside mainland China?
No. The project’s own README states it directly: the hardware isn’t sold in other regions.
What’s the difference between the official Xiaomi Home integration and hass-xiaomi-miot?
The official integration is first-party and maintained by Xiaomi; hass-xiaomi-miot is community-maintained and, per community discussion, offers a hard LAN-only setting the official version doesn’t.
Is it safe to log into my Xiaomi account through this integration?
Your password isn’t stored, but tokens and certificates are written to your HA config in plain text. Home Assistant doesn’t encrypt its configuration at rest by default — the !secret mechanism only moves values into a separate secrets.yaml, which is itself plain text — so there’s no built-in setting that neutralizes this. Treat that config file, and any backup of it, like it contains credentials, because it does.
Does “LAN control” mode really keep my Xiaomi devices off the cloud?
For the specific Wi-Fi/Ethernet devices it supports, yes, when it’s working. Community reports suggest it doesn’t always work reliably, and it was never designed ti cover Zigbee or BLE Mesh devices in the first place.
Xiaomi’s next moves worth watching: whether the Central Hub Gateway restriction changes as the project’s international install base grows, and whether LAN control reliability improves enough that community threads stop recommending against it. Neither looks imminent as of this writing, so for now, check which hardware tier you’re actually running before you assume “official integration” means “local by default.”