Xiaomi Home Assistant Integration: What Local Control Actually Gets You
The official Xiaomi Home Assistant integration — ha_xiaomi_home, released by Xiaomi on GitHub — ships with genuine local control support. The problem is that for most users outside mainland China, the mode that delivers real offline-resilient control isn’t actually available. The integration is still worth using. But calling it a local-control solution without qualification is misleading, and the official docs don’t go out of their way to clarify the regional picture.
I’ve been tracking this integration since it launched, and the gap between what the documentation describes and what users outside China actually get is one of the more consistent sources of confusion in the Home Assistant community right now.
The three control modes
ha_xiaomi_home supports three distinct ways to talk to your devices.
Cloud MQTT is the default for anyone outside mainland China. Commands and state updates travel through Xiaomi’s cloud servers using push-based MQTT subscriptions. The push model is genuinely fast (state changes arrive nearly instantly compared to polling-based approaches) but it requires a working internet connection at all times. Cut your internet, and your automations stop.
Hub-based local control uses the 小米中枢网关 (Xiaomi Central Hub Gateway) as a local MQTT broker. When this hardware is present on your network and running firmware 3.3.0_0023 or later, the integration talks directly to the hub over LAN. Latency drops to around 200ms within the local network. This is the mode that gets described when people talk about ha_xiaomi_home delivering proper local control.
LAN control talks directly to individual WiFi/Ethernet devices over your local network without going through any hub. It’s available globally without regional restriction. But it only works for IP-connected devices — anything on Bluetooth Mesh (蓝牙Mesh) or Zigbee can’t be addressed this way. There’s also a documented conflict: when the integration detects a Central Hub Gateway on the network, LAN control doesn’t activate. The two modes are mutually exclusive.
What “local control” actually means outside China
The Central Hub Gateway — the hardware that enables hub-based local control — is sold exclusively in mainland China. It isn’t available through grey-market imports in any meaningful way, and it only controls devices registered to a Chinese mainland region account. For users outside China, hub-based local mode is simply not an option.
That leaves LAN control as the only genuinely local path through the official integration.
LAN control works well enough for WiFi devices. If your Xiaomi setup is mostly smart plugs, fans, air purifiers, and similar IP-connected hardware, LAN control gives you a workable local fallback. Commands go direct to the device IP, no cloud hop required.
The gaps become clearer when you add Zigbee or Bluetooth Mesh devices. Neither protocol is IP-addressed, so neither is reachable via LAN control. Those devices are cloud-routed regardless of your LAN control settings. For a setup with any Zigbee sensors, switches, or locks, a significant chunk of your device fleet stays cloud-dependent.
The hub detection conflict compounds this. If you have a Xiaomi hub on your network — the Multimode Gateway 2, for instance — the integration will detect it and suppress LAN control entirely. Users expecting LAN control to activate alongside their hub find that it doesn’t. The integration treats them as incompatible.
A user who ran a month-long test blocking internet access to their Xiaomi setup (documented in GitHub discussion #786) found that WiFi devices they expected to control locally via LAN control weren’t responding. The only thing that worked was cutting physical power. It’s a useful real-world test, and it lines up with what the documentation says when you read it carefully: LAN control has limitations the official docs flag with a note that using the function may cause anomalies.
The offline resilience question
For most overseas users, ha_xiaomi_home isn’t an offline-resilient integration. Lose internet and you lose most of your device control. The push-based MQTT model that makes state updates fast is the same model that collapses when cloud connectivity goes away.
There’s a real benefit to the push approach for users who are online-only and don’t care about offline resilience. The older unofficial Miot Auto (小米米家 integration via HACS) uses polling every 15 to 30 seconds. Motion sensors and door/window contacts generate instantaneous events, and a 30-second polling interval misses them entirely. The official integration’s push model resolves this for cloud-connected setups. If your goal is reliable automation triggers for event-driven sensors and you accept cloud dependency, ha_xiaomi_home is the better choice over Miot Auto.
But “better than polling” isn’t the same as local.
Unofficial alternatives for local control
Two custom components give overseas users paths to genuine local control.
XiaomiGateway3 (by AlexxIT) communicates directly with the Xiaomi Multimode Gateway over LAN, bypassing cloud entirely. It exploits the gateway’s local telnet interface, a known capability that Xiaomi hasn’t patched out. Zigbee and Bluetooth Mesh devices connected to the Multimode Gateway become locally controllable through it. The tradeoff is that this integration is reverse-engineered and not officially supported, so Xiaomi could break it with a firmware update.
hass-xiaomi-miot (by al-one) supports both cloud and local modes and covers a broader device range, including Bluetooth and Zigbee access via gateway LAN. It’s been maintained long enough to be considered the community-standard unofficial option for broader Xiaomi device coverage.
Neither replaces ha_xiaomi_home entirely. They solve different problems for different device mixes. If you want to skip Xiaomi’s hubs altogether and pair sensors directly to a Zigbee coordinator, our guide on running Aqara and Xiaomi Zigbee devices in Home Assistant without a hub walks through the Zigbee2MQTT path.
Comparing the options by setup type
You’re in China with a Central Hub Gateway. The official integration with hub-based local mode enabled is the right choice. You get MQTT-level local control, 200ms latency, and no cloud dependency for device commands. Enable hub local mode, update the hub firwmare to 3.3.0_0023 minimum, and you’re set.
You’re outside China with only WiFi/Ethernet devices. The official integration with LAN control is workable, with caveats. You get local control for IP-addressable devices, but no offline resilience for the overall setup and the hub detection conflict to manage. Test your specific devices before relying on it for automations you care about.
You’re outside China with Zigbee or Bluetooth Mesh devices. The official integration alone won’t give you local control for those devices. Pair it with XiaomiGateway3 if you’re using the Multimode Gateway, or hass-xiaomi-miot for broader device coverage. Bypassing Xiaomi’s gateway entirely with a dedicated Zigbee coordinator is another route worth weighing.
You have both Aqara and Xiaomi devices. The community approach that seems to have gained traction (based on V2EX thread discussions) is treating the two brands differently at the integration layer. Aqara devices via HomeKit Controller for local control, Xiaomi devices bridged through Home Assistant with the caveat that local control is limited. It’s not elegant, but it’s the honest state of play. Our Aqara Hub E1 local integration guide covers the HomeKit Controller path in detail.
The active unresolved question
As of mid-2025, GitHub issue #1231 on the official repo asks whether an overseas-purchased Central Hub Gateway can achieve local control. The maintainers haven’t answered it, and no workaround has been confirmed. If you’re considering importing a Central Hub Gateway specifically for local control, I wouldn’t act on that plan until the issue gets a definitive response.
The pattern from Chinese community discussions is consistent: ha_xiaomi_home is a real improvement over the older unofficial integrations for cloud-connected setups, but the local control story is genuinely incomplete for overseas users. That’s not a criticism so much as a description of where the project is. The integration is a work in progress on the localization front.
If local control and offline resilience are your primary requirements, the Aqara ecosystem currently has a cleaner answer, as our explainer on whether Aqara works without internet lays out. The Xiaomi ecosystem has more devices and better cloud integration, but the local-first architecture isn’t there yet for most regions.