Setup with Xiaomi Home Account

This method should be used if the robot vacuum is currently managed via the Xiaomi Home application. To ensure compatibility, it can be verified against the official Xiaomi Home app available for iOS and Android.

Requirements

• Credentials: Must be the exact username and password used to log into the mobile application (not the official website).
• Server Region: The selected country must match the region where the device is registered in the app. Mismatched regions will result in "login failed" or "device not found" errors.

Third-Party Logins

If the account was created using a third-party service (such as Google or Apple), a dedicated password must be generated within the application's user settings first. Third-party account passwords cannot be used for authentication.

App Selection Recommendation

Some devices can be configured using either the Dreamehome or Xiaomi Home application. Unless a local connection is strictly required, it is highly recommended to use the Dreamehome app instead of Xiaomi Home for supported devices:

• Camera Stream: The camera stream feature is not available for devices configured via Xiaomi Home.
• Push Updates: The Dreamehome connection utilizes Cloud Push for real-time updates, eliminating the need for periodic polling requests.

Prefer Cloud Option

During the configuration step, an additional Prefer Cloud option is available and is checked by default.

• When checked (Default): Forces all communication through the cloud (if supported by the device). This is the default behavior because on newer devices, Xiaomi has disabled local access capabilities. Furthermore, if the device and Home Assistant reside on different subnets, local communication will fail.
• When unchecked (Recommended for supported setups): The integration retrieves the required token from the cloud but establishes a direct local connection with the device (similar to the Local Connection method). This provides the benefit of automatic token and IP renewal while keeping all communications (except map data) local. If this method results in a "cannot reach device" error at the final configuration step, the configuration should be retried with the Prefer Cloud option checked.

  Subnet Requirement

  For security reasons, the device only responds to requests originating from its own subnet. Therefore, the robot vacuum and Home Assistant must be on the exact same subnet for local communication to work. See this python-miio article for troubleshooting cross-subnet issues.

Captcha Verification

If the Xiaomi Home servers flag the login attempt or IP address as untrusted, a captcha verification step will be required. When this occurs, the captcha image must be solved to proceed to the next step.

Two-Factor Authentication (2FA)

In addition to a captcha, an untrusted login attempt may also trigger Two-Factor Authentication (2FA). The integration will automatically request a 2FA code from the Xiaomi Home servers, which is sent to the registered phone number (prioritized) or email address.

This code must be retrieved and entered into the configuration step to complete the login.

2FA Limitations

• Code Validity: If the configuration window is closed and a new login attempt is made, a new 2FA code will be generated. The most recently received code must always be used.
• Rate Limiting: Xiaomi strictly limits the number of 2FA codes that can be requested per day. Repeated login attempts may result in a temporary block.

Periodic State Updates

Unlike other cloud connection methods that support push notifications, the Xiaomi Home connection relies entirely on background polling to fetch the latest state. To optimize network usage, the polling interval is dynamically calculated based on the time elapsed since the last state change; requests are sent frequently while the device is actively running, but the interval gradually increases as more time passes while the device remains idle.

Re-authentication

The integration securely stores an authentication token after a successful login to communicate with the cloud servers. If this token expires or is invalidated by the cloud service for any reason, Home Assistant will automatically trigger a re-authentication flow, prompting for the account credentials to be entered again.