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 (Connectivity → MQTT connectivity). On this page you can also find the exact topic to which to send commands to or from.

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.



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

Home Assistant components controlled by this property:

Basic control (BasicControlCapability)

Node, capability: BasicControlCapability

Operation (operation)

Property, command, not retained

Carpet Mode (CarpetModeControlCapability)

Node, capability: CarpetModeControlCapability

Note: This is an optional exposed capability handle and thus will only be available via MQTT if enabled in the Valetudo configuration.

Carpet Mode (enabled)

Property, readable, settable, retained

Sample value:

OFF

Home Assistant components controlled by this property:

Carpet Sensor Mode (CarpetSensorModeControlCapability)

Node, capability: CarpetSensorModeControlCapability

Note: This is an optional exposed capability handle and thus will only be available via MQTT if enabled in the Valetudo configuration.

Carpet Sensor Mode (mode)

Property, readable, settable, retained

This handle allows setting the Carpet Sensor Mode. It accepts the preset payloads specified in $format or in the HAss json attributes.

Sample value:

lift

Home Assistant components controlled by this property:

Consumables monitoring (ConsumableMonitoringCapability)

Node, capability: ConsumableMonitoringCapability

Note: This is an optional exposed capability handle and thus will only be available via MQTT if enabled in the Valetudo configuration.

Consumable (minutes) (<CONSUMABLE-MINUTES>)

Property, readable, retained

This handle returns the consumable remaining endurance time as an int representing seconds remaining.

Sample value:

29520

Home Assistant components controlled by this property:

Reset the consumable (<CONSUMABLE-MINUTES>/reset)

Property, command, not retained

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:

Reset the consumable (<CONSUMABLE-PERCENT>/reset)

Property, command, not retained

Home Assistant components controlled by this property:

Current Statistics (CurrentStatisticsCapability)

Node, capability: CurrentStatisticsCapability

Note: This is an optional exposed capability handle and thus will only be available via MQTT if enabled in the Valetudo configuration.

Current Statistics Area (area)

Property, readable, retained

Sample value:

630000

Home Assistant components controlled by this property:

Current Statistics Time (time)

Property, readable, retained

This handle returns the current statistics time in seconds

Sample value:

1440

Home Assistant components controlled by this property:

Fan control (FanSpeedControlCapability)

Node, capability: FanSpeedControlCapability

Status attributes managed by this node:

Fan (preset)

Property, readable, settable, retained

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

Sample value:

max

Home Assistant components controlled by this property:

Go to location (GoToLocationCapability)

Node, capability: GoToLocationCapability

Go to location (go)

Property, command, not retained

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

Simply use the Map in the Valetudo UI, place the GoTo marker and then long-press the button that would start the action.
This will open a modal containing the copy-pasteable payload.

Sample payload:

{
  "coordinates": {
    "x": 50,
    "y": 50
  }
}

Lock Keys (KeyLockCapability)

Node, capability: KeyLockCapability

Note: This is an optional exposed capability handle and thus will only be available via MQTT if enabled in the Valetudo configuration.

Lock Keys (enabled)

Property, readable, settable, retained

Sample value:

OFF

Home Assistant components controlled by this property:

Locate (LocateCapability)

Node, capability: LocateCapability

Locate (locate)

Property, command, not retained

Home Assistant components controlled by this property:

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.

Simply use the Map in the Valetudo UI, select the desired segments and iterations and then long-press the button that would start the action.
This will open a modal containing the copy-pasteable payload.

Note: Not all firmwares support customOrder.

Sample payload:

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

Obstacle Avoidance (ObstacleAvoidanceControlCapability)

Node, capability: ObstacleAvoidanceControlCapability

Note: This is an optional exposed capability handle and thus will only be available via MQTT if enabled in the Valetudo configuration.

Obstacle Avoidance (enabled)

Property, readable, settable, retained

Sample value:

ON

Home Assistant components controlled by this property:

Mode control (OperationModeControlCapability)

Node, capability: OperationModeControlCapability

Status attributes managed by this node:

Mode (preset)

Property, readable, settable, retained

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

Sample value:

vacuum

Home Assistant components controlled by this property:

Pet Obstacle Avoidance (PetObstacleAvoidanceControlCapability)

Node, capability: PetObstacleAvoidanceControlCapability

Note: This is an optional exposed capability handle and thus will only be available via MQTT if enabled in the Valetudo configuration.

Pet Obstacle Avoidance (enabled)

Property, readable, settable, retained

Sample value:

ON

Home Assistant components controlled by this property:

Speaker volume control (SpeakerVolumeControlCapability)

Node, capability: SpeakerVolumeControlCapability

Note: This is an optional exposed capability handle and thus will only be available via MQTT if enabled in the Valetudo configuration.

Speaker volume (value)

Property, readable, settable, retained

This handle returns the current speaker volume

Sample value:

80

Home Assistant components controlled by this property:

Total Statistics (TotalStatisticsCapability)

Node, capability: TotalStatisticsCapability

Note: This is an optional exposed capability handle and thus will only be available via MQTT if enabled in the Valetudo configuration.

Total Statistics Area (area)

Property, readable, retained

Sample value:

3150000

Home Assistant components controlled by this property:

Total Statistics Count (count)

Property, readable, retained

Sample value:

5

Home Assistant components controlled by this property:

Total Statistics Time (time)

Property, readable, retained

This handle returns the total statistics time in seconds

Sample value:

7200

Home Assistant components controlled by this property:

Water control (WaterUsageControlCapability)

Node, capability: WaterUsageControlCapability

Status attributes managed by this node:

Water (preset)

Property, readable, settable, retained

This handle allows setting the water. 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,fe80::1ff:fe23:4567:890a,fdff:ffff:ffff:ffff:ffff:ffff:ffff:ffff
Signal (signal)

Property, readable, retained

Sample value:

-23
Wireless network (ssid)

Property, readable, retained

Sample value:

Valetudo Wi-Fi

Zone cleaning (ZoneCleaningCapability)

Node, capability: ZoneCleaningCapability

Start zoned cleaning (start)

Property, command, not retained

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

Simply use the Map in the Valetudo UI, create the desired zones, select the desired iterations and then long-press the button that would start the action.
This will open a modal containing the copy-pasteable payload.

Sample payload:

{
  "zones": [
    {
      "points": {
        "pA": {
          "x": 50,
          "y": 50
        },
        "pB": {
          "x": 100,
          "y": 50
        },
        "pC": {
          "x": 100,
          "y": 100
        },
        "pD": {
          "x": 50,
          "y": 100
        }
      }
    }
  ],
  "iterations": 1
}

Map data

Node

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

Raw map data (map-data)

Property, readable, retained

Raw map data for Home Assistant (map-data-hass)

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:

{
  "16": "Hallway",
  "18": "Bathroom",
  "20": "Kitchen"
}

Home Assistant components controlled by this property:

Valetudo Events

Node

Events (valetudo_events)

Property, readable, retained

This property contains all raised and not yet processed ValetudoEvents.

Sample value:

{
  "3fab7eb3-7bee-4455-a3b8-c4357dab59b6": {
    "__class": "ErrorStateValetudoEvent",
    "metaData": {},
    "id": "3fab7eb3-7bee-4455-a3b8-c4357dab59b6",
    "timestamp": "2026-04-12T14:24:08.240Z",
    "processed": false,
    "message": "This is an error message"
  },
  "pending_map_change": {
    "__class": "PendingMapChangeValetudoEvent",
    "metaData": {},
    "id": "pending_map_change",
    "timestamp": "2026-04-12T14:24:08.240Z",
    "processed": false
  },
  "mop_attachment_reminder": {
    "__class": "MopAttachmentReminderValetudoEvent",
    "metaData": {},
    "id": "mop_attachment_reminder",
    "timestamp": "2026-04-12T14:24:08.240Z",
    "processed": false
  },
  "c936b4d3-5b3e-4e2e-8c7d-1b82930bb53a": {
    "__class": "DustBinFullValetudoEvent",
    "metaData": {},
    "id": "c936b4d3-5b3e-4e2e-8c7d-1b82930bb53a",
    "timestamp": "2026-04-12T14:24:08.240Z",
    "processed": false
  }
}

Home Assistant components controlled by this property:

Interact with Events (valetudo_events/interact)

Property, command, not retained

Note that the interaction payload is event-specific, but for most use-cases, the example should be sufficient.

Sample payload for a dismissible event (e.g. an ErrorStateValetudoEvent):

{
  "id": "b89bd27c-5563-4cfd-87df-2f23e8bbeef7",
  "interaction": "ok"
}

Status

Attachment state (AttachmentStateAttribute)

Node

Status attributes managed by this node:

  • AttachmentStateAttribute
Dust bin (dustbin)

Property, readable, retained

This handle reports whether the dust bin attachment is installed.

Sample value:

true

Home Assistant components controlled by this property:

Mop (mop)

Property, readable, retained

This handle reports whether the mop attachment is installed.

Sample value:

false

Home Assistant components controlled by this property:

Water tank (watertank)

Property, readable, retained

This handle reports whether the water tank attachment is installed.

Sample value:

true

Home Assistant components controlled by this property:

Battery state (BatteryStateAttribute)

Node

Status attributes managed by this node:

Battery level (level)

Property, readable, retained

Sample value:

42

Home Assistant components controlled by this property:

Battery status (status)

Property, readable, retained

Sample value:

charging

Dock state (DockStatusStateAttribute)

Node

Status attributes managed by this node:

Status (status)

Property, readable, retained

Sample value:

idle

Home Assistant components controlled by this property:

Vacuum status (StatusStateAttribute)

Node

Status attributes managed by this node:

Home Assistant components controlled by this node:

Robot Error (error)

Property, readable, retained

This property contains the current ValetudoRobotError (if any)

Sample value:

{
  "severity": {
    "kind": "none",
    "level": "none"
  },
  "subsystem": "none",
  "message": ""
}
Error description (error_description)

Property, readable, retained

Sample value:

No error
Status flag (flag)

Property, readable, retained

Sample value:

segment

Home Assistant components controlled by this property:

Status (status)

Property, readable, retained

Sample value:

cleaning

Meta

Home GitHub

General

Newcomer Guide

Why Valetudo?

Why not Valetudo?

Getting Started

So you've been banned?

Supported Robots

Buying Supported Robots

Media & Content Creators

Installation

Dreame

Midea

Roborock

Usage

Implementation Overview

Capabilities Overview

Upgrading

Firmware Updates

Integrations

MQTT

Autodiscovery Custom integrations

Home Assistant

Companion Apps

Valetudo Companion (Android)

Valetudo Tray Companion

Valeronoi

Lovelace Valetudo Map Card

Fun & Games

Misc

FAQ

Style Guide

Development

Rooting Essentials

Building and Modifying Valetudo

Valetudo core concepts

MQTT Implementation Details