Important naming clarification up front (this causes a lot of confusion):
The legacy Xiaomi Miio integration in Home Assistant core is now shown in the UI as “Xiaomi Home” (green icon). This is not the same thing as the new official Xiaomi OAuth-based Xiaomi Home integration. In this post, when I say “Miio (now known as Xiaomi Home)”, I mean the legacy token-based integration, not the new OAuth one. This naming overlap is a big part of why this topic is so confusing.
TL;DR
- Xiaomi changed cloud authentication (CAPTCHA / extra verification): home-assistant/core#147122 (comment)
- This broke Miio (now known as Xiaomi Home) login and token workflows
- A community fix does exist, but upstreaming it is non-trivial
- Miio is effectively legacy
- There are working alternatives, including local-only setups
This comment is meant to consolidate information and save future users a lot of time.
Xiaomi changed their cloud login flow (CAPTCHA, extra auth) This broke:
python-miio- Xiaomi cloud token extractors
- HA’s Miio (now known as Xiaomi Home)
config flow
This is not a regression introduced by Home Assistant. The "legacy Miio integration" (in Core) relies on unofficial Xiaomi APIs that Xiaomi keeps changing without notice.
There are three distinct components, often mixed up:
-
Miio (now known as Xiaomi Home) – HA core integration Token-based Handles config flow and device control Does not extract tokens itself
-
python-miioPython library used by the integration Implements MiIO protocol and Xiaomi cloud login This is where login actually breaks -
Xiaomi cloud token extractors External helper tools (not part of HA) Used to log in and retrieve tokens manually
The existing “community fix” people reference here lives at the python-miio / extractor level, not in HA UI code.
Several comments asked for “someone to open a PR with the fix”. In practice, that means: To properly upstream the fix, someone would need to:
- Extract the CAPTCHA-handling logic from community forks
- Cleanly integrate it into python-miio
- Add tests and error handling
- Release a new python-miio version
- Update HA core to bump the dependency
- Be willing to maintain it when Xiaomi changes auth again
This is not a one-liner, and whoever submits it implicitly becomes a long-term maintainer of a fragile integration. That’s the real reason this stalled.
If you want Miio (now known as Xiaomi Home) working today, options exist, but all have trade-offs:
Option A – Patch HA locally (advanced, unsupported)
- Replace Xiaomi cloud login logic inside:
site-packages/miio/- Use
CAPTCHA-handlingcode from community forks - Restart HA
-->
⚠️ Breaks on updates, unsupported.
Option B – Custom integration fork
- Fork Miio
- Vendor a patched python-miio
- Load via custom_components -->More robust, but still maintenance-heavy.
Option C – Manual token extraction + Miio
- Use a patched token extractor
- Manually paste IP + token into the integration
- Avoid cloud login after token retrieval
- Still works for some devices, but increasingly brittle.
🧱 Core / Official
Miio (now known as Xiaomi Home) – legacy, green icon https://www.home-assistant.io/integrations/xiaomi_miio/
- Token-based
- Legacy
- Broken login for many users
Xiaomi Home (official Xiaomi OAuth integration) https://github.com/XiaoMi/ha_xiaomi_home
- Cloud-first
- Official Xiaomi support
- Partial local mode only with specific hubs
Roborock Integration https://www.home-assistant.io/integrations/roborock/
- Integration for Roborock vaccums.
- Roborock integration works for some Roborocks listed as not supported.
- Alternative for old devices can be flashing with Valetudo
🔌 Community / HACS
Xiaomi Miot Auto https://github.com/al-one/hass-xiaomi-miot
- MIoT spec
- Supports many modern devices (Purifier 4 / 4H / 4 Pro)
- Can be forced into LAN-only mode
--> Currently the most robust option
Xiaomi Gateway 3 https://github.com/AlexxIT/XiaomiGateway3
- Gateway-based
- Local control
- Fast and stable for supported gateways
BLE monitor (Xiaomi sensors) https://github.com/custom-components/ble_monitor
- Passive BLE sensors only
ESPHome BLE Proxy https://esphome.io/components/ble_client.html
- BLE via ESP32
- Sensors only
Aqara / Zigbee (ZHA or Zigbee2MQTT)
- Sensors, buttons, presence
- Complements Xiaomi Wi-Fi devices well
Modern Wi-Fi devices (Purifier 4 / 4H / 4 Pro) → Xiaomi Miot Auto, force LAN mode, disable cloud per entity
Roborock devices → Roborock App
Users with existing tokens → Miio (now known as Xiaomi Home) may still work without cloud login
Gateway-based setups → Xiaomi Gateway 3
Sensors only → BLE Monitor, Zigbee, Aqara
Continuing to chase Xiaomi cloud auth changes inside Miio is an uphill battle.
From the outside, realistic long-term options seem to be:
- Soft-deprecate Miio as legacy
- Or move it out of HA core into community maintenance
- Patching around Xiaomi’s cloud login in core does not scale.
### 🧭 TL;DR – Which Xiaomi integration should I use?
Do you have a Xiaomi Wi-Fi device?
│
├─ YES ─► Is it a Roborock vacuum?
│ │
│ ├─ YES ─► Do you want CHINA / cloud access?
│ │ │
│ │ ├─ YES ─► Use Roborock app + Roborock cloud integration
│ │ │
│ │ └─ NO ─► Flash Valetudo (local)
│ │
│ └─ NO (e.g. Air purifier) ─► Do you want LOCAL control (no China / no cloud)?
│ │
│ ├─ YES ─► Use "Xiaomi Miot Auto" (HACS)
│ │ - Force LAN mode
│ │ - Disable miot_cloud
│ │
│ └─ NO ─► Use "Xiaomi Home"
│ (official OAuth, cloud-based, green icon)
│
└─ NO ─► Is it a sensor / button / presence device?
│
├─ BLE device ─► BLE Monitor / ESPHome BLE Proxy
│
├─ Zigbee / Aqara ─► ZHA or Zigbee2MQTT
│
└─ Gateway-based ─► Xiaomi Gateway 3
Avoid unless you know exactly why:
- Miio (now known as Xiaomi Home, green icon)
- Legacy
- Token-based
- Broken login for many users
Thank you for your attention. Please let me if I made any mistakes and help me spread this message in similar issues and posts so the issue stops coming up and people know and easily understand what is going on.
@Crypto-Shroom thanks for the useful info. Your link https://www.home-assistant.io/integrations/xiaomi_home/ doesn't work - it returns 404 from Home Assistant's website