Smart Cleaning Symphony: Integrating Roborock Vacuum with Home Assistant

Introduction

Robotic vacuum cleaners have revolutionized home cleaning, offering convenience and saving precious time. While their native apps provide scheduling and basic control, integrating your Roborock vacuum with Home Assistant elevates its capabilities to a whole new level. Imagine your vacuum automatically cleaning specific areas when you leave the house, pausing when you're on a crucial call, or notifying you proactively about maintenance needs – all orchestrated by your central smart home hub.

Home Assistant's powerful automation engine, combined with the right integration, turns your Roborock from a scheduled appliance into an intelligent participant in your daily routines. This guide will walk you through integrating your Roborock vacuum, focusing on a common and robust method involving its local API, enabling faster response times and potentially more reliable control compared to cloud-dependent methods.

Prerequisites

• A running installation of Home Assistant (OS, Supervised, Container, or Core).
• A Roborock vacuum cleaner connected to your local Wi-Fi network.
• Basic understanding of Home Assistant configuration and automation.
• Access to your local network to find the vacuum's IP address.
• A method to obtain the vacuum's API token (discussed below).

Choosing the Integration Method: Focusing on Local Control

The most common and recommended way to integrate Roborock vacuums with Home Assistant is using the Xiaomi Miio integration. Although named "Xiaomi Miio," this integration supports many devices from the Xiaomi ecosystem, including Roborock vacuums, often utilizing a local API token for communication. This local method is generally preferred over cloud-based alternatives due to lower latency, increased reliability (not dependent on external servers), and better privacy.

The key to using this integration locally is obtaining the device's unique API token.

Obtaining the Roborock API Token

The API token is a 32-character hexadecimal string that acts as a password for local control. Obtaining this token can be a bit technical, as it's not readily displayed in the standard Roborock or Mi Home apps. Here are a few common methods:

1. Using the miio Command-Line Tool: This is often the most direct method if you are comfortable with command-line interfaces. You can install the Python miio library (pip install python-miio) and use commands like miio --ip <vacuum_ip> --token <placeholder_token> discover or other specific commands based on the tool's documentation to retrieve the token. Note: Some newer devices or firmware might make this harder.
2. Android Backup Method: For Android users, you can often find the token within a backup created by the Mi Home app. This involves using tools to extract data from the backup file. Search online for detailed, device-specific guides for this method.
3. Third-Party Apps/Tools: Various unofficial apps or scripts exist online designed to help retrieve Xiaomi device tokens. Use these with caution and ensure they are from reputable sources.
4. Router Monitoring: In some cases, monitoring network traffic from the vacuum using tools like Wireshark while it communicates with the Mi Home app during setup or operation can reveal the token, but this is complex.

Once you have the token (it looks something like 1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p), keep it secure, as it grants full local control over the device.

Integrating Roborock with Home Assistant (Xiaomi Miio)

Assuming you have your vacuum's local IP address and its API token, follow these steps to integrate it into Home Assistant:

1. Navigate to your Home Assistant UI.
2. Go to Settings > Devices & Services.
3. Click the + Add Integration button.
4. Search for "Xiaomi Miio" and select it.
5. When prompted, choose "Connect to a Xiaomi Miio device".
6. Enter the Host (the vacuum's local IP address).
7. Enter the Token you obtained.
8. Click Submit.
9. Home Assistant should now detect your Roborock vacuum. You may be asked to select a device type; choose the appropriate vacuum model if listed, or a generic vacuum type.
10. Assign the device to an Area if desired and click Finish.

Home Assistant will now create a device and several entities related to your vacuum, such as:

• vacuum.your_vacuum_name: The main vacuum entity with controls (start, pause, stop, return to dock, clean spot, locate).
• Sensor entities: Battery level, status (cleaning, charging, idle), dustbin status, filter status, brush status, cleaning area, cleaning duration.
• Select entities: Fan speed, cleaning mode.
• Number entities: Volume (if supported).
• Camera entity: For map visualization (requires specific vacuum models and potentially extra configuration or custom components for advanced map features).

Unlocking Automation Possibilities

With your Roborock integrated, you can now create powerful automations. Here are a few ideas:

Automation 1: Auto-Clean When Away

Trigger the vacuum to start cleaning when the last person leaves home.

alias: Auto-Clean when Away
description: Start the vacuum when everyone leaves the house
trigger:
  - platform: state
    entity_id: group.all_users_home
    from: 'home'
    to: 'not_home'
condition: [] # Add conditions like battery level > 20% if needed
action:
  - service: vacuum.start
    entity_id: vacuum.your_vacuum_name
mode: single

Requires a presence detection setup, e.g., using group.all_users_home.

Automation 2: Pause Cleaning on Important Call

Pause the vacuum if your phone state changes to "ringing" or "offhook" (requires Home Assistant Companion App with phone state sensors).

alias: Pause Vacuum on Call
description: Pause vacuum if a phone call is detected
trigger:
  - platform: state
    entity_id: sensor.your_phone_ringer_mode # Example sensor from companion app
    to: 'normal' # Or 'vibrate', 'silent' - depending on trigger need
  - platform: state
    entity_id: sensor.your_phone_call_state # Example sensor from companion app
    to: 'ringing'
  - platform: state
    entity_id: sensor.your_phone_call_state
    to: 'offhook'
condition:
  - condition: state
    entity_id: vacuum.your_vacuum_name
    state: 'cleaning' # Only pause if it's currently cleaning
action:
  - service: vacuum.pause
    entity_id: vacuum.your_vacuum_name
  - service: persistent_notification.create # Optional: notify user
    data:
      title: Vacuum Paused
      message: Your vacuum has been paused due to an incoming/outgoing call.
mode: single

Automation 3: Zone Cleaning via Dashboard Button

Create a button on your dashboard that triggers cleaning a specific room or zone. This requires identifying the zone IDs or coordinates, which can be tricky and often requires experimentation or using custom map features.

# Example script to clean a specific zone (requires knowing zone coordinates/IDs)
# You'd trigger this script from a dashboard button
alias: Clean Kitchen Zone
description: Tell the vacuum to clean the kitchen area
sequence:
  - service: vacuum.clean_zone
    target:
      entity_id: vacuum.your_vacuum_name
    data:
      # Example data format - specific format depends on vacuum model and integration version
      # Often requires [x1, y1, x2, y2, iterations] coordinates or specific zone names/IDs
      zone:
        - [23700, 22000, 28000, 26500, 1] # Replace with actual zone coordinates
      retries: 2 # Number of times to retry if initial command fails
mode: single
icon: mdi:floor-plan

Finding zone coordinates or IDs can be challenging. Custom components like vacuum-card or xiaomi-vacuum-map-card often provide visual tools to help with this.

Automation 4: Dustbin Full Notification

Receive a notification when the vacuum reports its dustbin needs emptying.

alias: Vacuum Dustbin Full Notification
description: Notify when the vacuum dustbin needs emptying
trigger:
  - platform: state
    entity_id: sensor.your_vacuum_name_dustbin_status # Check your sensor names
    to: 'full' # Or 'needs_emptying' depending on sensor states
condition: []
action:
  - service: notify.mobile_app_your_phone # Replace with your notification service
    data:
      title: Roborock Maintenance
      message: "{{ state_attr('vacuum.your_vacuum_name', 'friendly_name') }} dustbin needs emptying!"
mode: single

Check your vacuum's sensor entities for the exact dustbin status sensor and its state values.

Best Practices for a Reliable Integration

• Assign a Static IP: Configure your router to always assign the same internal IP address to your Roborock vacuum. This prevents the integration from breaking if the vacuum's IP changes.
• Secure Your Token: The API token grants control. Do not share it or expose it publicly. Use Home Assistant's built-in secrets management if you put configuration in configuration.yaml.
• Test After Firmware Updates: Roborock/Xiaomi occasionally update vacuum firmware. While updates are important for security and features, they can sometimes break local API control or change how the token is obtained. Test the integration after any vacuum firmware update. Deferring firmware updates on the vacuum might be considered if stability of local control is paramount, but this comes with security risks.
• Monitor Network Stability: Ensure your vacuum has a strong, stable Wi-Fi connection. Poor connectivity is a common cause of integration issues.
• Use Home Assistant Helpers: Create an input_boolean helper (e.g., input_boolean.allow_vacuum_automation) that you can use in conditions of your automations. This provides a quick toggle on your dashboard to disable all automated cleaning if needed (e.g., during holidays, or when expecting guests).
• Review Entity States/Attributes: Explore the device and entities Home Assistant creates. Check the states and attributes available (Developer Tools -> States) to understand what information you can use in conditions or templates.

Troubleshooting Common Issues

• Integration Fails to Connect:
  • Double-check the IP address and token. Typos are common.
  • Ensure the vacuum is powered on and connected to the same network subnet as Home Assistant.
  • Verify the token is correct and still valid (some tokens might expire or change after factory resets or firmware updates, requiring you to re-obtain it).
  • Firewall issues: Ensure your network firewall isn't blocking communication between the Home Assistant machine and the vacuum on the necessary ports (often 8053 or 54321, but the miio integration handles the specifics).
• Commands Don't Work:
  • Verify the vacuum is in a state where it can receive commands (e.g., not already cleaning if you're sending a start command, not stuck).
  • Check the Home Assistant logs for errors related to the xiaomi_miio integration.
• Vacuum Map Not Showing / Zone Cleaning Issues:
  • Map features and zone cleaning commands are highly dependent on the specific vacuum model and firmware. Not all models support these features via the local API or the standard integration.
  • Custom components might be required for full map functionality or easier zone selection.
  • Zone coordinates are often tricky; ensure you are using the correct format and values for your model.

Conclusion

Integrating your Roborock vacuum with Home Assistant opens up a world of possibilities beyond simple scheduling. By leveraging local control with the Xiaomi Miio integration and its API token, you gain responsive and reliable control. From smart automations based on presence and events to custom cleaning routines and proactive notifications, your smart cleaning setup becomes a truly integrated part of your connected home. Embrace the power of Home Assistant to make your Roborock vacuum work intelligently for you, contributing to a more convenient and automated household.