Mastering Local Robot Vacuum Control: Integrating Valetudo with Home Assistant

Mastering Local Robot Vacuum Control: Integrating Valetudo with Home Assistant

In the evolving landscape of smart home technology, the desire for local control and enhanced privacy is paramount. While many robot vacuums offer impressive features, they often rely heavily on cloud services, raising concerns about data privacy and dependency on external servers. This is where Valetudo steps in – an incredible, open-source firmware replacement for a range of Roborock and Xiaomi robot vacuums, designed to provide complete local control. When paired with Home Assistant, Valetudo transforms your cleaning robot into a fully integrated, privacy-respecting, and highly automatable smart home appliance.

This guide will walk you through the process of integrating Valetudo with Home Assistant, leveraging MQTT for seamless communication, and establishing a robust, cloud-independent robot vacuum control system.

Why Valetudo? The Power of Local Control

• Privacy & Security: Eliminates reliance on manufacturer cloud servers, ensuring your mapping data and cleaning schedules remain within your local network.
• Reliability: Your vacuum's functionality is no longer dependent on internet connectivity or external server uptime.
• Advanced Features: Valetudo exposes a wealth of data and control points via MQTT, allowing for intricate automations not typically available through official apps. This includes precise segment cleaning, detailed status reporting, and fine-grained fan speed control.
• Open Source: A thriving community supports Valetudo, ensuring continuous development and responsiveness to user needs.

Prerequisites for Integration

Before diving into Home Assistant configuration, ensure you have the following in place:

1. Compatible Robot Vacuum: Check the Valetudo website for a list of supported devices (primarily Roborock and Xiaomi models).
2. Valetudo Flashed on Your Vacuum: The process of flashing Valetudo onto your robot vacuum can be complex and varies by model. It often involves disassembling the vacuum, connecting via serial, or using specific tools. This guide will not cover the flashing process itself. Please refer to the detailed guides on the Valetudo website and its community forums for your specific model. Ensure your vacuum is successfully running Valetudo and accessible on your network.
3. Home Assistant Instance: A running Home Assistant installation (any installation method is fine).
4. MQTT Broker: Valetudo communicates primarily via MQTT. You'll need an MQTT broker (like Mosquitto) running on your network, preferably as an add-on within Home Assistant or as a separate Docker container/service.

Setting Up Your MQTT Broker in Home Assistant

If you don't already have an MQTT broker configured, the Mosquitto broker add-on is the recommended choice for Home Assistant users.

1. Install Mosquitto Broker Add-on: Go to Home Assistant > Settings > Add-ons > Add-on Store. Search for "Mosquitto broker" and install it.
2. Configure Mosquitto: Before starting, go to the Configuration tab of the add-on. You'll likely need to create an ACL file and define a user/password. An example configuration might look like this (adjust users as needed):

   logins: []
   customize:
     active: true
     folder: mosquitto
   acl: []

   Then, create a user specifically for MQTT in Home Assistant via Settings > People & Zones > Users. Remember this username and password.
3. Start the Add-on: Go to the Info tab of the Mosquitto add-on and start it. Ensure "Start on boot" and "Watchdog" are enabled for reliability.
4. Configure MQTT Integration in Home Assistant: Go to Settings > Devices & Services > Add Integration. Search for "MQTT" and configure it. Point it to your Home Assistant's IP address (or core-mosquitto if running as an add-on) and provide the MQTT user credentials you created.

Configuring Valetudo for MQTT Communication

Once Valetudo is flashed and running, access its web interface (usually by navigating to your vacuum's IP address in a web browser).

1. Navigate to MQTT Settings: In the Valetudo web interface, find the "Connectivity" or "MQTT" section.
2. Enter Broker Details:
   • Broker IP/Hostname: Enter the IP address of your Home Assistant instance (or the server running Mosquitto).
   • Port: Typically 1883.
   • Username & Password: Enter the MQTT user credentials you created earlier in Home Assistant.
   • Topic Prefix: This is crucial. It's the base topic for all MQTT messages from your vacuum. A common choice is valetudo/your_vacuum_name (e.g., valetudo/roborock_s7). Make sure it's unique if you have multiple Valetudo vacuums.
3. Test Connection: Valetudo usually provides a button to test the MQTT connection. Ensure it connects successfully. Save your settings.

Integrating Valetudo with Home Assistant via YAML

While some integrations might auto-discover, Valetudo's rich feature set is best harnessed through manual YAML configuration in Home Assistant, allowing you to define exactly what sensors, switches, and commands you want.

You'll typically add these configurations to your configuration.yaml file or a separate file referenced by it (e.g., vacuum.yaml under vacuum: !include vacuum.yaml).

Basic Vacuum Entity and Sensors

First, define the main vacuum entity and essential sensors:

# configuration.yaml or vacuum.yaml
vacuum:
  - platform: mqtt
    name: "Valetudo Robot Vacuum"
    unique_id: "valetudo_robot_vacuum_main"
    command_topic: "valetudo/roborock_s7/command"
    state_topic: "valetudo/roborock_s7/status"
    set_fan_speed_topic: "valetudo/roborock_s7/set_fan_speed"
    fan_speed_topic: "valetudo/roborock_s7/state"
    fan_speed_template: "{{ value_json.fan_speed }}"
    send_command_topic: "valetudo/roborock_s7/command"
    json_attributes_topic: "valetudo/roborock_s7/state"
    supported_features:
      - start
      - pause
      - stop
      - return_home
      - battery
      - status
      - locate
      - clean_spot
      - fan_speed
      - send_command

# Sensors for detailed status
sensor:
  - platform: mqtt
    name: "Valetudo Status"
    state_topic: "valetudo/roborock_s7/status"
    value_template: "{{ value }}"
    icon: mdi:robot-vacuum
  - platform: mqtt
    name: "Valetudo Battery"
    state_topic: "valetudo/roborock_s7/state"
    value_template: "{{ value_json.battery_level }}"
    unit_of_measurement: "%"
    device_class: battery
    icon: mdi:battery
  - platform: mqtt
    name: "Valetudo Error"
    state_topic: "valetudo/roborock_s7/state"
    value_template: "{{ value_json.error_description | default('No Error') }}"
    icon: mdi:alert

Explanation:

• platform: mqtt: Specifies that this entity uses the MQTT integration.
• name: The display name in Home Assistant.
• unique_id: A unique identifier for the entity, good for GUI editing later.
• command_topic: Topic to send commands to (e.g., start, pause).
• state_topic: Topic where the vacuum publishes its current status.
• set_fan_speed_topic & fan_speed_topic: For managing fan speed.
• json_attributes_topic: A topic (often the state topic) from which Home Assistant can extract additional attributes.
• supported_features: Crucial for defining what actions the vacuum entity can perform in Home Assistant's UI (e.g., start, pause, battery level).

Fan Speed Selection

You can create a `select` helper or manually define a select entity if you want more granular control over fan speeds:

select:
  - platform: mqtt
    name: "Valetudo Fan Speed"
    unique_id: "valetudo_fan_speed_select"
    state_topic: "valetudo/roborock_s7/state"
    value_template: "{{ value_json.fan_speed }}"
    command_topic: "valetudo/roborock_s7/set_fan_speed"
    options:
      - "off"
      - "min"
      - "medium"
      - "high"
      - "max"
      - "custom" # Valetudo can support custom fan speeds, check your version's topics
    retain: false

Note: Valetudo's specific fan speed options might vary (e.g., low, medium, high, turbo, or numerical values). Check your Valetudo web interface or MQTT explorer for the exact values your vacuum publishes.

Cleaning Specific Segments (Rooms)

Valetudo exposes clean_segment command, allowing you to clean specific rooms. You'll need to find the segment IDs from your Valetudo web interface (often under "Map" or by inspecting MQTT messages on valetudo/roborock_s7/map_data when a map update occurs).

You can create a script for each room:

script:
  clean_kitchen:
    alias: "Clean the Kitchen"
    sequence:
      - service: vacuum.send_command
        target:
          entity_id: vacuum.valetudo_robot_vacuum
        data:
          command: clean_segment
          params:
            segment_ids: ["17"] # Replace with your kitchen's segment ID
            repetitions: 1
  clean_living_room:
    alias: "Clean the Living Room"
    sequence:
      - service: vacuum.send_command
        target:
          entity_id: vacuum.valetudo_robot_vacuum
        data:
          command: clean_segment
          params:
            segment_ids: ["22"] # Replace with your living room's segment ID
            repetitions: 1

These scripts can then be exposed as buttons on your Lovelace dashboard or called from automations.

Lovelace Dashboard Integration

Once your entities are configured, you can add them to your Home Assistant dashboard.

• Vacuum Card: The standard Home Assistant Vacuum card works well for basic controls.
• Custom Vacuum Card: For a more feature-rich interface, consider installing the vacuum-card from HACS. This card provides a cleaner interface and often better support for advanced commands like segment cleaning or displaying map data from valetudo_re_map.
• Buttons for Scripts: Use `button` cards to trigger your `clean_kitchen` or `clean_living_room` scripts.

Device Integration Tips & Automations

• Automate Based on Presence: Create an automation that starts the vacuum when everyone leaves the house (using presence detection entities like device trackers or router presence).
• Schedule Cleaning: Use the Home Assistant time trigger to schedule daily or weekly cleaning routines.
• Error Notifications: Create an automation that sends a notification to your phone (via companion app or Telegram) if the sensor.valetudo_error changes to something other than "No Error."
• Bin Full/Filter Status: Valetudo exposes consumable status (brush, filter, dustbin full) via MQTT. You can create sensors for these to get reminders to clean/replace them. The topics are usually under valetudo/roborock_s7/state as attributes like main_brush_life_percent, filter_life_percent, etc.
• Map Visualization: Valetudo can publish map data (valetudo/roborock_s7/map_data). While integrating directly into Lovelace is complex, tools like valetudo_re_map (a separate companion project) can render these maps, and you can embed its output as a local iframe or camera entity in Home Assistant.
• Zone Cleaning: For specific rectangular zones (not just segments), Valetudo supports clean_zone. This requires specific coordinates. You can define these in Home Assistant scripts and send them via vacuum.send_command.

Best Practices for Managing a Reliable Ecosystem

• Static IP for Vacuum: Assign a static IP address to your Valetudo-enabled vacuum via your router's DHCP reservation. This ensures consistent communication and prevents issues if the vacuum reboots and gets a new IP.
• Robust MQTT Broker: Ensure your Mosquitto broker (or chosen alternative) is stable, has sufficient resources, and is configured for auto-start and watchdog.
• Monitor MQTT Topics: Use an MQTT client (like MQTT Explorer) to monitor the topics from your Valetudo vacuum. This is invaluable for debugging and understanding the data structure, especially when setting up new sensors or commands.
• Test Automations Thoroughly: Always test your vacuum automations in a controlled environment before relying on them for daily cleaning.
• Regular Valetudo Updates: Keep an eye on the Valetudo GitHub repository or community for new firmware releases. Updates often bring bug fixes, performance improvements, and new features. Follow the recommended update procedures carefully.
• Network Stability: Ensure your Wi-Fi network is stable and provides good coverage to where your vacuum operates, minimizing dropped connections.

Conclusion

By integrating Valetudo with Home Assistant, you gain unparalleled control over your robot vacuum, breaking free from cloud dependencies and unlocking a world of advanced automation possibilities. This setup not only enhances your smart home's privacy and reliability but also empowers you to tailor your cleaning routine with precision and creativity. Embrace the power of local control and transform your smart cleaning experience!