Valetudo

Valetudo aims to be a vendor-agnostic abstraction and cloud replacement for vacuum robots which started as a standalone binary on rooted roborock vacuums.

View the Project on GitHub Hypfer/Valetudo

General

Newcomer Guide Late 2021 Supported Robots Capabilities Overview Rooting instructions Upgrading

Installation

Roborock OTA Viomi

Companion Apps

Valetudo Companion (Android) Valeronoi Lovelace Valetudo Map Card I can't believe it's not Valetudo node-red-contrib-valetudo Fun & Games Other Noteworthy Projects

Integrations

MQTT Home Assistant Node-RED openHAB

Misc

FAQ Frequently requested features Roborock, Files to backup Troubleshooting

Development

Building and Modifying Valetudo Valetudo core concepts MQTT

Archive

Supported Dreame Devices Supported Roborock Devices Supported Viomi Devices Newcomer Guide Early 2021

MQTT integration

To make your robot talk to your MQTT broker and integrate with home automation software, such as but not limited to Home Assistant, openHAB and Node-RED, configure MQTT via Valetudo’s web interface (Settings → MQTT).

Autodiscovery

See the specific integration pages for instructions on how to set up autodiscovery for your home automation software platform:

Other home automation software that follows the Homie convention should also be able to automatically discover your Valetudo instance.



Map

Note that, in order to view the map provided over MQTT, you additionally need I Can’t Believe It’s Not Valetudo to generate PNG maps. You can then configure it to serve the PNG map over HTTP for openHAB and other software, or install the Lovelace Valetudo Card Map for Home Assistant.

Custom integrations

If you’re planning to use one of the home automation platforms listed above, this is all you need to know to get started.

If you’re instead planning to do something more custom, in this document you will find a reference to all MQTT topics provided by this software. Values such as <TOPIC PREFIX> and <IDENTIFIER> are those configured in the MQTT settings page.

Table of contents

State attributes index

Home Assistant components index

MQTT API reference

Robot

Device

Home Assistant components controlled by this device:

Capabilities

Auto Empty Dock Manual Trigger (AutoEmptyDockManualTriggerCapability)

Node, capability: AutoEmptyDockManualTriggerCapability

Auto Empty Dock Manual Trigger (trigger)

Property, command, not retained

Basic control (BasicControlCapability)

Node, capability: BasicControlCapability

Operation (operation)

Property, command, not retained

Consumables monitoring (ConsumableMonitoringCapability)

Node, capability: ConsumableMonitoringCapability

Status attributes managed by this node:

Consumable (minutes) (<CONSUMABLE-MINUTES>)

Property, readable, retained

This handle returns the consumable remaining endurance time as an ISO8601 duration. The controlled Home Assistant component will report it as seconds instead.

Sample value:

PT8H12M0S

Home Assistant components controlled by this property:

Consumable (percent) (<CONSUMABLE-PERCENT>)

Property, readable, retained

This handle returns the consumable remaining endurance percentage.

Sample value:

59

Home Assistant components controlled by this property:

Refresh consumables (refresh)

Property, command, not retained

If set to PERFORM, it will attempt to refresh the consumables from the robot. Note that there’s no need to do it manually, consumables are refreshed automatically every 30 seconds by default.

Fan speed control (FanSpeedControlCapability)

Node, capability: FanSpeedControlCapability

Status attributes managed by this node:

Fan speed (preset)

Property, readable, settable, retained

This handle allows setting the fan speed. It accepts the preset payloads specified in $format or in the HAss json attributes.

Sample value:

max

Go to location (GoToLocationCapability)

Node, capability: GoToLocationCapability

Home Assistant components controlled by this node:

Go to location preset (go)

Property, command, not retained

Use this handle to make the robot go to a configured preset location. It accepts one single preset UUID as a regular string.

Presets (presets)

Property, readable, retained

This handle provides a set of configured Go-to-location presets as a JSON object.

Sample value:

{
  "a9666386-7041-4bd4-a823-ebefa48665eb": {
    "__class": "ValetudoGoToLocation",
    "metaData": {},
    "name": "SpotA",
    "coordinates": {
      "x": 2589,
      "y": 2364
    },
    "id": "a9666386-7041-4bd4-a823-ebefa48665eb"
  },
  "6c74ac84-dfe9-4c4c-8bec-836ff268d630": {
    "__class": "ValetudoGoToLocation",
    "metaData": {},
    "name": "SpotB",
    "coordinates": {
      "x": 2186,
      "y": 2262
    },
    "id": "6c74ac84-dfe9-4c4c-8bec-836ff268d630"
  }
}

Locate (LocateCapability)

Node, capability: LocateCapability

Locate (locate)

Property, command, not retained

Segment cleaning (MapSegmentationCapability)

Node, capability: MapSegmentationCapability

Clean segments (clean)

Property, command, not retained

This handle accepts a JSON object identical to the one used by the REST API.

Sample payload:

{
  "segment_ids": [
      "20",
      "18",
      "16"
  ],
  "iterations": 2,
  "customOrder": true
}

Water grade control (WaterUsageControlCapability)

Node, capability: WaterUsageControlCapability

Status attributes managed by this node:

Water grade (preset)

Property, readable, settable, retained

This handle allows setting the water grade. It accepts the preset payloads specified in $format or in the HAss json attributes.

Sample value:

min

Home Assistant components controlled by this property:

Wi-Fi configuration (WifiConfigurationCapability)

Node, capability: WifiConfigurationCapability

Home Assistant components controlled by this node:

Frequency (frequency)

Property, readable, retained

Sample value:

2.4ghz
IP addresses (ips)

Property, readable, retained

Sample value:

192.168.100.100
Refresh configuration (refresh)

Property, command, not retained

Signal (signal)

Property, readable, retained

Sample value:

-54
Wireless network (ssid)

Property, readable, retained

Sample value:

Valetudo WiFi

Zone cleaning (ZoneCleaningCapability)

Node, capability: ZoneCleaningCapability

Home Assistant components controlled by this node:

Presets (presets)

Property, readable, retained

This handles provides the list of configured zone presets as a JSON object.

Sample value:

{}
Start zone preset (start)

Property, command, not retained

This handle accepts a zone preset UUID to start. You can retrieve them from the /presets handle.

Sample value: 25f6b7fe-0a28-477d-a1af-937ad91b2df4

Map data

Node

This handle groups access to map data. It is only enabled if provideMapData is enabled in the MQTT config.

Map (map)

Property, readable, retained

This handle is only enabled if interfaces.homie.addICBINVMapProperty is enabled in the config. It does not actually provide map data, it only adds a Homie autodiscovery property so that ‘I Can’t Believe It’s Not Valetudo’ can publish its map within the robot’s topics and be autodetected by clients.

ICBINV should be configured so that it publishes the map to this topic.

Raw map data (map-data)

Property, readable, retained

Raw map data with Home Assistant hack (map-data-hass-hack)

Property, readable, retained

This handle is added automatically if Home Assistant autodiscovery is enabled. It provides a map embedded in a PNG image that recommends installing the Valetudo Lovelace card.

Home Assistant components controlled by this property:

Map segments (segments)

Property, readable, retained

This property contains a JSON mapping of segment IDs to segment names.

Sample value:

{}

Home Assistant components controlled by this property:

Status

Attachment state (AttachmentStateAttribute)

Node

Status attributes managed by this node:

Dust bin (dustbin)

Property, readable, retained

This handle reports whether the dust bin is installed. Attachments not compatible with your robot may be included (but set to false) and you can safely ignore them.

Sample value:

true
Mop (mop)

Property, readable, retained

This handle reports whether the mop is installed. Attachments not compatible with your robot may be included (but set to false) and you can safely ignore them.

Sample value:

false
Water tank (watertank)

Property, readable, retained

This handle reports whether the water tank is installed. Attachments not compatible with your robot may be included (but set to false) and you can safely ignore them.

Sample value:

true

Battery state (BatteryStateAttribute)

Node

Status attributes managed by this node:

Battery level (level)

Property, readable, retained

Sample value:

42
Battery status (status)

Property, readable, retained

Sample value:

charging

Vacuum status (StatusStateAttribute)

Node

Status attributes managed by this node:

Status detail (detail)

Property, readable, retained

Sample value:

segment
Error description (error)

Property, readable, retained

The error description will only be populated when the robot reports an error. Errors in Valetudo not reported by the robot won’t be sent here.

Home Assistant components controlled by this property:

Status (status)

Property, readable, retained

Sample value:

cleaning