FAQ

This page collects the questions that come up repeatedly on the GitHub issue tracker. Checking here before opening a new issue saves time, as most of these are not bugs but expected behaviors with a documented cause.

Search Existing Issues

None of these? Ensure to search the closed issues on GitHub before opening a new one. If the problem persists, the Issue Reporting page explains how to gather debug logs and open a proper bug report or feature request.

Device is Not Listed / Not Supported

Show Answer

Support is tied to the exact model string (e.g., dreame.vacuum.r2489a), not the marketing name. Many devices share the same name across regions or generations but use a different model string, and only some of them are supported.

1. Check the Supported Devices page for the exact model string, not just the product name.
2. If it is not there, check the Home Assistant Core logs. When the cloud returns an unrecognized device, a warning is automatically logged containing a line starting with Unsupported device: followed by its raw info. This is the information needed to add support.
3. Open a device support request with that log line, the exact model string from the app, and which app (Dreamehome, MOVAhome, TROUVER, or Xiaomi Home) manages the device.

Where to Find the Device Model Number

Show Answer

The method for finding the exact device model number depends on the device's current integration status:

• If the device is already added: The model number is displayed on the device information page in Home Assistant. Navigate to Settings > Devices & Services > Integrations, select the Dreame Vacuum integration, and click on the specific device to view its details under the "Device info" card.
• If the device is unsupported: Attempting to configure an unsupported device will generate a warning in the Home Assistant Core logs (e.g., Unsupported device:). This log entry contains the exact model string required for opening a device support request. This is the most reliable method.
• Before adding the device: The model number can sometimes be inferred from the device's hostname visible in the router settings once connected to the local network, or from the first 5 digits of the serial number printed on the device. However, relying on the serial number can be misleading for submodels, making the log warning method the recommended approach.

How to Check the Integration Version

Show Answer

The installed version of the integration can be checked in Home Assistant by navigating to HACS > Integrations and locating Dreame Vacuum, or by navigating to Settings > Devices & Services > Integrations and viewing the Dreame Vacuum integration details.

How to Get Debug Logs

Show Answer

Instructions for enabling and gathering debug logs are fully documented on the Issue Reporting page.

Setup Fails / "Login Failed" / Cannot Connect

Show Answer

Almost every setup and login failure comes down to one of a handful of causes that are already documented on each connection method's own page:

• Dreamehome Account
• MOVAhome Account
• TROUVER Account
• Xiaomi Home Account
• Local Connection

Each of those pages has a Requirements callout at the top explaining the most common causes of "login failed" or "device not found" errors, such as a mismatched Server Region, using website credentials instead of the mobile app's, or a third-party (Google/Apple) login that needs an app-generated password first. Reading the page for the exact connection type in use resolves the vast majority of setup failures.

If entities intermittently turn unavailable after working correctly for a while, it is almost always the same underlying cloud/network reachability issue rather than a bug. Check the Network & Firewall Requirements section below before reporting it.

Network & Firewall Requirements

• Cloud connections (Dreamehome, MOVAhome, TROUVER, Xiaomi Home) require Home Assistant to reach the manufacturer's cloud over standard outbound HTTPS (port 443) and DNS. Nothing needs to be opened inbound. A strict firewall, proxy, or an isolated VLAN that only allows specific outbound destinations will surface as "device not found", request timeouts, or entities repeatedly going unavailable.

  Dynamic Cloud Endpoints

  Cloud endpoints are hosted on shared, rotating cloud provider IP ranges and are not fixed addresses, so they cannot be reliably documented or allow-listed individually. If an allowlist is required, allowing the Home Assistant host unrestricted outbound HTTPS is the only dependable option.

• Local connection requires the vacuum and Home Assistant to be on the exact same subnet; see the Subnet Requirement callout on the Local Connection page. Routed networks, VLANs, or client isolation between them will always fail, regardless of firewall rules.

"Local Connection" Does Not Work / Has No Map for the Device

This is expected for most current devices, not a bug. The Local Connection method only works for devices manufactured before 2022 that can still be added to the Xiaomi Home app and keep local API access there; see the Device Compatibility callout on that page. Once a device is linked to the Dreamehome cloud (or any device that never had Xiaomi Home/Miio support to begin with), its firmware disables the local API entirely and there is no way for the integration to reach it locally. A cloud connection method must be used instead. Local connection also never has map data available over the local API, so it cannot support features like Cleaning History, Map Recovery, or dynamic Room Entities under any circumstances. This is a device-side limitation, not something an update can add.

Setup Fails When "Prefer Cloud" is Unchecked Map Support

Show Answer

When configuring via the Xiaomi Home account, unchecking the Prefer Cloud option forces the integration to attempt a direct local connection to the device. If the device firmware does not support local API access (which is the case for most devices manufactured after 2022), this connection will fail. In this scenario, the configuration must be retried with the Prefer Cloud option checked. More details are available on the Xiaomi Home Account page.

How to Use the Vacuum Offline

Show Answer

Offline or fully local usage without internet access is only possible for devices that support the Local Connection method. As noted on that page, this is generally restricted to devices manufactured before 2022 that can be added to the Xiaomi Home app. For newer devices or those using the Dreamehome cloud, continuous internet access is required for the integration to communicate with the device.

How to Retrieve the Token and IP Address

Show Answer

The procedures for retrieving a device's token and IP address are fully documented on the Local Connection page. This involves using third-party tools like the Xiaomi Cloud Tokens Extractor or modified Android applications.

An Option, Entity, or Attribute is Missing, Greyed Out, or Behaves Differently Than the App

Show Answer

Not every difference from the official app is a bug:

• Firmware capability differences: The available cleaning modes, routes, and settings are reported by the vacuum's own firmware. If a mode shown in the app is missing in Home Assistant, or a previously available option has disappeared after a device firmware update, this is a firmware-side change/limitation rather than something the integration can restore.
• Attributes hidden during certain modes: Some attributes, such as the fan speed/suction level, are intentionally removed while modes like CleanGenius or Customized Cleaning are active and controlling that value dynamically, since there is no single fixed value to report in that state. This is expected, not a missing entity.
• Third-party dashboard cards: Behavior specific to a community map card (such as the Xiaomi Vacuum Map Card) after changing the map rotation, or other card-specific quirks, are limitations of that card's own implementation and not something this integration controls. See the Dashboard page for the full list of compatible cards.

If an option is genuinely missing on a device where the official app clearly exposes it (and it is not one of the cases above), that is worth reporting.

Start Clean Services Do Not Have a Cleaning Mode Parameter. How Can I Set It to Mopping or Sweeping?

Show Answer

The start clean services do not accept a cleaning mode parameter because passing the cleaning mode directly alongside the start command is not supported by the robot's firmware. Therefore, the mode must be set using the relevant select entity first before triggering the start command.

The following Home Assistant script examples demonstrate how to set the cleaning mode dynamically before starting a clean. Make sure to replace robot_vacuum with your actual device's entity name.

1. Set global cleaning mode and start a full clean:

alias: "Full clean with specific mode"
sequence:
  - service: select.select_option
    target:
      entity_id: select.robot_vacuum_cleaning_mode
    data:
      option: "Sweeping and mopping"
  - service: vacuum.start
    target:
      entity_id: vacuum.robot_vacuum

2. Set global cleaning mode and clean specific rooms:

alias: "Clean rooms with specific mode"
sequence:
  - service: select.select_option
    target:
      entity_id: select.robot_vacuum_cleaning_mode
    data:
      option: "Mopping"
  - service: dreame_vacuum.vacuum_clean_segment
    target:
      entity_id: vacuum.robot_vacuum
    data:
      segments:
        - 1
        - 2

3. Enable customized cleaning, set different modes per room, and start room cleaning:

alias: "Customized room cleaning"
sequence:
  - service: switch.turn_on
    target:
      entity_id: switch.robot_vacuum_customized_cleaning
  - service: select.select_option
    target:
      entity_id: select.robot_vacuum_room_1_cleaning_mode
    data:
      option: "Sweeping"
  - service: select.select_option
    target:
      entity_id: select.robot_vacuum_room_2_cleaning_mode
    data:
      option: "Mopping"
  - service: dreame_vacuum.vacuum_clean_segment
    target:
      entity_id: vacuum.robot_vacuum
    data:
      segments:
        - 1
        - 2

Can Notifications Be Pushed to a Phone?

Show Answer

Not directly. By default, the integration only creates persistent notifications inside the Home Assistant dashboard; they are not automatically forwarded to the Home Assistant Companion App on a mobile device, since that requires a specific per-device notification target that the integration does not have.

To receive them on a phone, a custom automation must be created that listens to the integration's events (or the generated persistent notifications) and forwards them to the notify target for the mobile device.

More about configuring which notifications are generated

Obstacle / AI Detection Photos Are Not Showing Map Support

Show Answer

If obstacle images stay empty even with AI Obstacle Image Upload enabled in the app, and the account connected to Home Assistant is a shared/family account rather than the account that originally added and owns the device, the manufacturer's cloud API can silently block obstacle image access for that shared account. Using the actual owning account, or checking that camera access has been explicitly granted to the shared account within the app, resolves this in most cases.

Can the Map Camera Be Streamed to HomeKit / Apple Home? Map Support

Show Answer

Not reliably as a live view. The map camera streams as genuine MJPEG, the same method Home Assistant's own camera platform uses, so the static preview image in Apple Home displays correctly. A new frame is only generated when the map actually changes, and the stream produces nothing while the vacuum sits idle. HomeKit's live view needs a continuously refreshing source to stay connected, and Home Assistant has to convert the MJPEG stream through an additional layer before HomeKit can display it at all, since HomeKit does not accept MJPEG directly. When the map stream goes quiet, that conversion layer treats the connection as lost, and Home Assistant reports that the camera has no stream source or shows a blank feed instead of a live picture.

This has been reported multiple times. Attempts using the ffmpeg camera platform, go2rtc, and the Generic Camera integration all produce the same result: the static preview works, but a continuously updating live feed inside HomeKit does not. No fully working setup has been confirmed for this integration or for similar vacuum map streams elsewhere.

Home Assistant Crashes, Restarts, or Uses a Lot of Memory Map Support

Show Answer

The integration renders zoomable, full-resolution map images similar to the official app, which can use a significant amount of memory. On systems with limited RAM, such as a Raspberry Pi, a small VM, or a container capped around 2-3GB, this can exhaust the available memory and cause Home Assistant to freeze, restart, or fail to start entirely, typically right after adding a device with map support or when opening its device page or map camera.

Fix

Enable Low Resolution Map Image from the device's configuration options. This resolves the vast majority of these cases.

If it still crashes after enabling that option, the map data itself may have become corrupted or unusually large over time, which can also drive up memory use during rendering. Restoring an older, healthy map from Backup and Recovery can resolve this. If neither helps, gather debug logs and open a bug report, since that points to a different underlying cause.

Integration Fails to Load After a Home Assistant Update, Mentioning py_mini_racer Map Support

Show Answer

The integration depends on py-mini-racer, a JavaScript engine used to optimize and render maps so they match the official app. This dependency is installed by Home Assistant itself, not by the integration, and it occasionally fails to install or fails to load its native binary after a Home Assistant Core update, particularly on musl-based systems (such as HAOS on some platforms) or right after an upgrade.

Environment Issue

This is an environment/dependency installation problem, not something the integration's code can detect or work around. It shows up repeatedly across unrelated Home Assistant versions and installation types.

Restarting Home Assistant (to let it retry installing dependencies) resolves it in some cases. If it persists, check the Home Assistant log around startup for the actual pip/dependency installation error; that error is what needs to be resolved (including as a Home Assistant Core issue, if it looks like a platform-level installation failure).

Can a Device Running Valetudo be Used with this Integration?

Show Answer

Yes and no. Technically, there is no restriction preventing the integration from operating alongside Valetudo. Valetudo does not disable the local miIO API, so the device can be controlled via Local Connection as long as the token can be acquired. However, map data cannot be retrieved over the local API, and Valetudo does not expose raw map data via a service. Therefore, the integration can only function without map support.

Without map support, the functionality provided by this integration becomes largely redundant, as all remaining features can already be utilized through the native Valetudo Home Assistant MQTT integration.