Cloud replacement for vacuum robots enabling local-only operation
View the Project on GitHub Hypfer/Valetudo
Newcomer Guide Why Valetudo? Why not Valetudo? Getting Started Supported Robots Rooting Essentials Buying Supported Robots
Implementation Overview Capabilities Overview Upgrading Firmware Updates
Valetudo Companion (Android) Valetudo Tray Companion Valeronoi Lovelace Valetudo Map Card I Can't Believe It's Not Valetudo node-red-contrib-valetudo Fun & Games Other Noteworthy Projects
MQTT Home Assistant Node-RED openHAB
FAQ Style Guide Troubleshooting
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.
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.
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.
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.
Tip: It is recommended to leave Homie autodiscovery enabled, even if you’re not planning to use it, if you want to develop custom integrations or access the MQTT topics directly: the Homie protocol is very readable and self-documenting. It will provide additional context and information on how to use specific APIs.
Homie autodiscovery info is best viewed with something like MQTT Explorer.
AutoEmptyDockManualTriggerCapability
)
BasicControlCapability
)
ConsumableMonitoringCapability
)
CurrentStatisticsCapability
)
FanSpeedControlCapability
)
GoToLocationCapability
)
LocateCapability
)
KeyLockCapability
)
OperationModeControlCapability
)
ObstacleAvoidanceControlCapability
)
MapSegmentationCapability
)
SpeakerVolumeControlCapability
)
TotalStatisticsCapability
)
WaterUsageControlCapability
)
WifiConfigurationCapability
)
ZoneCleaningCapability
)
sensor.mqtt
)sensor.mqtt
)sensor.mqtt
)sensor.mqtt
)sensor.mqtt
)binary_sensor.mqtt
)sensor.mqtt
)sensor.mqtt
)select.mqtt
)switch.mqtt
)camera.mqtt
)sensor.mqtt
)select.mqtt
)binary_sensor.mqtt
)switch.mqtt
)button.mqtt
)number.mqtt
)sensor.mqtt
)sensor.mqtt
)sensor.mqtt
)sensor.mqtt
)button.mqtt
)vacuum.mqtt
)select.mqtt
)binary_sensor.mqtt
)sensor.mqtt
)Device
Home Assistant components controlled by this device:
vacuum.mqtt
)AutoEmptyDockManualTriggerCapability
) Node, capability: AutoEmptyDockManualTriggerCapability
trigger
) Property, command, not retained
<TOPIC PREFIX>/<IDENTIFIER>/AutoEmptyDockManualTriggerCapability/trigger/set
<TOPIC PREFIX>/<IDENTIFIER>/AutoEmptyDockManualTriggerCapability/trigger
PERFORM
)Home Assistant components controlled by this property:
button.mqtt
)BasicControlCapability
) Node, capability: BasicControlCapability
operation
) Property, command, not retained
<TOPIC PREFIX>/<IDENTIFIER>/BasicControlCapability/operation/set
<TOPIC PREFIX>/<IDENTIFIER>/BasicControlCapability/operation
START
, STOP
, PAUSE
, HOME
)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.
Warning: Some information contained in this document may not be exactly what is sent or expected by actual robots, since different vendors have different implementations. Refer to the table below.
What | Reason |
---|---|
Properties | Consumables depend on the robot model. |
Property datatype and units | Some robots send consumables as remaining time, others send them as endurance percent remaining. |
Status attributes managed by this node:
<CONSUMABLE-MINUTES>
) Property, readable, retained
This handle returns the consumable remaining endurance time as an int representing seconds remaining.
<TOPIC PREFIX>/<IDENTIFIER>/ConsumableMonitoringCapability/<CONSUMABLE-MINUTES>
Sample value:
29520
Home Assistant components controlled by this property:
sensor.mqtt
)<CONSUMABLE-MINUTES>/reset
) Property, command, not retained
<TOPIC PREFIX>/<IDENTIFIER>/ConsumableMonitoringCapability/<CONSUMABLE-MINUTES>/reset/set
<TOPIC PREFIX>/<IDENTIFIER>/ConsumableMonitoringCapability/<CONSUMABLE-MINUTES>/reset
PERFORM
)Home Assistant components controlled by this property:
<CONSUMABLE-PERCENT>
) Property, readable, retained
This handle returns the consumable remaining endurance percentage.
<TOPIC PREFIX>/<IDENTIFIER>/ConsumableMonitoringCapability/<CONSUMABLE-PERCENT>
Sample value:
59
Home Assistant components controlled by this property:
sensor.mqtt
)<CONSUMABLE-PERCENT>/reset
) Property, command, not retained
<TOPIC PREFIX>/<IDENTIFIER>/ConsumableMonitoringCapability/<CONSUMABLE-PERCENT>/reset/set
<TOPIC PREFIX>/<IDENTIFIER>/ConsumableMonitoringCapability/<CONSUMABLE-PERCENT>/reset
PERFORM
)Home Assistant components controlled by this property:
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.
Warning: Some information contained in this document may not be exactly what is sent or expected by actual robots, since different vendors have different implementations. Refer to the table below.
What | Reason |
---|---|
Properties | Available statistics depend on the robot model. |
area
) Property, readable, retained
<TOPIC PREFIX>/<IDENTIFIER>/CurrentStatisticsCapability/area
Sample value:
630000
Home Assistant components controlled by this property:
sensor.mqtt
)time
) Property, readable, retained
This handle returns the current statistics time in seconds
<TOPIC PREFIX>/<IDENTIFIER>/CurrentStatisticsCapability/time
Sample value:
1440
Home Assistant components controlled by this property:
sensor.mqtt
)FanSpeedControlCapability
) Node, capability: FanSpeedControlCapability
Status attributes managed by this node:
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.
<TOPIC PREFIX>/<IDENTIFIER>/FanSpeedControlCapability/preset
<TOPIC PREFIX>/<IDENTIFIER>/FanSpeedControlCapability/preset/set
off
, min
, low
, medium
, high
, turbo
, max
)Warning: Some information contained in this document may not be exactly what is sent or expected by actual robots, since different vendors have different implementations. Refer to the table below.
What | Reason |
---|---|
Enum payloads | Different robot models have different fan presets. Always check $format /json_attributes during startup. |
Sample value:
max
Home Assistant components controlled by this property:
select.mqtt
)GoToLocationCapability
) Node, capability: GoToLocationCapability
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
}
}
<TOPIC PREFIX>/<IDENTIFIER>/GoToLocationCapability/go/set
<TOPIC PREFIX>/<IDENTIFIER>/GoToLocationCapability/go
same json as the REST interface
)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.
enabled
) Property, readable, settable, retained
<TOPIC PREFIX>/<IDENTIFIER>/KeyLockCapability/enabled
<TOPIC PREFIX>/<IDENTIFIER>/KeyLockCapability/enabled/set
ON
, OFF
)Sample value:
OFF
Home Assistant components controlled by this property:
switch.mqtt
)LocateCapability
) Node, capability: LocateCapability
locate
) Property, command, not retained
<TOPIC PREFIX>/<IDENTIFIER>/LocateCapability/locate/set
<TOPIC PREFIX>/<IDENTIFIER>/LocateCapability/locate
PERFORM
)Home Assistant components controlled by this property:
button.mqtt
)MapSegmentationCapability
) Node, capability: MapSegmentationCapability
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.
Sample payload:
{
"segment_ids": [
"20",
"18",
"16"
],
"iterations": 2,
"customOrder": true
}
<TOPIC PREFIX>/<IDENTIFIER>/MapSegmentationCapability/clean/set
<TOPIC PREFIX>/<IDENTIFIER>/MapSegmentationCapability/clean
same json as the REST interface
)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.
enabled
) Property, readable, settable, retained
<TOPIC PREFIX>/<IDENTIFIER>/ObstacleAvoidanceControlCapability/enabled
<TOPIC PREFIX>/<IDENTIFIER>/ObstacleAvoidanceControlCapability/enabled/set
ON
, OFF
)Sample value:
ON
Home Assistant components controlled by this property:
switch.mqtt
)OperationModeControlCapability
) Node, capability: OperationModeControlCapability
Status attributes managed by this node:
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.
<TOPIC PREFIX>/<IDENTIFIER>/OperationModeControlCapability/preset
<TOPIC PREFIX>/<IDENTIFIER>/OperationModeControlCapability/preset/set
mop
, vacuum
, vacuum_and_mop
)Warning: Some information contained in this document may not be exactly what is sent or expected by actual robots, since different vendors have different implementations. Refer to the table below.
What | Reason |
---|---|
Enum payloads | Different robot models have different mode presets. Always check $format /json_attributes during startup. |
Sample value:
vacuum
Home Assistant components controlled by this property:
select.mqtt
)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.
value
) Property, readable, settable, retained
This handle returns the current speaker volume
<TOPIC PREFIX>/<IDENTIFIER>/SpeakerVolumeControlCapability/value
<TOPIC PREFIX>/<IDENTIFIER>/SpeakerVolumeControlCapability/value/set
Sample value:
80
Home Assistant components controlled by this property:
number.mqtt
)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.
Warning: Some information contained in this document may not be exactly what is sent or expected by actual robots, since different vendors have different implementations. Refer to the table below.
What | Reason |
---|---|
Properties | Available statistics depend on the robot model. |
area
) Property, readable, retained
<TOPIC PREFIX>/<IDENTIFIER>/TotalStatisticsCapability/area
Sample value:
3150000
Home Assistant components controlled by this property:
sensor.mqtt
)count
) Property, readable, retained
<TOPIC PREFIX>/<IDENTIFIER>/TotalStatisticsCapability/count
Sample value:
5
Home Assistant components controlled by this property:
sensor.mqtt
)time
) Property, readable, retained
This handle returns the total statistics time in seconds
<TOPIC PREFIX>/<IDENTIFIER>/TotalStatisticsCapability/time
Sample value:
7200
Home Assistant components controlled by this property:
sensor.mqtt
)WaterUsageControlCapability
) Node, capability: WaterUsageControlCapability
Status attributes managed by this node:
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.
<TOPIC PREFIX>/<IDENTIFIER>/WaterUsageControlCapability/preset
<TOPIC PREFIX>/<IDENTIFIER>/WaterUsageControlCapability/preset/set
off
, min
, low
, medium
, high
, max
)Warning: Some information contained in this document may not be exactly what is sent or expected by actual robots, since different vendors have different implementations. Refer to the table below.
What | Reason |
---|---|
Enum payloads | Different robot models have different water presets. Always check $format /json_attributes during startup. |
Sample value:
min
Home Assistant components controlled by this property:
select.mqtt
)WifiConfigurationCapability
) Node, capability: WifiConfigurationCapability
Home Assistant components controlled by this node:
sensor.mqtt
)frequency
) Property, readable, retained
<TOPIC PREFIX>/<IDENTIFIER>/WifiConfigurationCapability/frequency
Sample value:
2.4ghz
ips
) Property, readable, retained
<TOPIC PREFIX>/<IDENTIFIER>/WifiConfigurationCapability/ips
Sample value:
192.168.100.100,fe80::1ff:fe23:4567:890a,fdff:ffff:ffff:ffff:ffff:ffff:ffff:ffff
signal
) Property, readable, retained
<TOPIC PREFIX>/<IDENTIFIER>/WifiConfigurationCapability/signal
Sample value:
-54
ssid
) Property, readable, retained
<TOPIC PREFIX>/<IDENTIFIER>/WifiConfigurationCapability/ssid
Sample value:
Valetudo Wi-Fi
ZoneCleaningCapability
) Node, capability: ZoneCleaningCapability
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
}
<TOPIC PREFIX>/<IDENTIFIER>/ZoneCleaningCapability/start/set
<TOPIC PREFIX>/<IDENTIFIER>/ZoneCleaningCapability/start
same json as the REST interface
)Node
This handle groups access to map data. It is only enabled if provideMapData
is enabled in the MQTT config.
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.
<TOPIC PREFIX>/<IDENTIFIER>/MapData/map
map-data
) Property, readable, retained
<TOPIC PREFIX>/<IDENTIFIER>/MapData/map-data
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.
<TOPIC PREFIX>/<IDENTIFIER>/MapData/map-data-hass
Home Assistant components controlled by this property:
camera.mqtt
)segments
) Property, readable, retained
This property contains a JSON mapping of segment IDs to segment names.
<TOPIC PREFIX>/<IDENTIFIER>/MapData/segments
Sample value:
{
"16": "Hallway",
"18": "Bathroom",
"20": "Kitchen"
}
Home Assistant components controlled by this property:
sensor.mqtt
)Node
valetudo_events
) Property, readable, retained
This property contains all raised and not yet processed ValetudoEvents.
<TOPIC PREFIX>/<IDENTIFIER>/ValetudoEvents/valetudo_events
Sample value:
{
"6ac59c61-349b-4c18-9e4f-f89be959ba19": {
"__class": "ErrorStateValetudoEvent",
"metaData": {},
"id": "6ac59c61-349b-4c18-9e4f-f89be959ba19",
"timestamp": "2024-02-14T19:35:20.283Z",
"processed": false,
"message": "This is an error message"
},
"pending_map_change": {
"__class": "PendingMapChangeValetudoEvent",
"metaData": {},
"id": "pending_map_change",
"timestamp": "2024-02-14T19:35:20.283Z",
"processed": false
},
"mop_attachment_reminder": {
"__class": "MopAttachmentReminderValetudoEvent",
"metaData": {},
"id": "mop_attachment_reminder",
"timestamp": "2024-02-14T19:35:20.283Z",
"processed": false
},
"e8061d9a-a8d8-4438-8186-600eeee456f9": {
"__class": "DustBinFullValetudoEvent",
"metaData": {},
"id": "e8061d9a-a8d8-4438-8186-600eeee456f9",
"timestamp": "2024-02-14T19:35:20.283Z",
"processed": false
}
}
Home Assistant components controlled by this property:
sensor.mqtt
)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"
}
<TOPIC PREFIX>/<IDENTIFIER>/ValetudoEvents/valetudo_events/interact/set
<TOPIC PREFIX>/<IDENTIFIER>/ValetudoEvents/valetudo_events/interact
AttachmentStateAttribute
) Node
Status attributes managed by this node:
dustbin
) Property, readable, retained
This handle reports whether the dust bin attachment is installed.
<TOPIC PREFIX>/<IDENTIFIER>/AttachmentStateAttribute/dustbin
Sample value:
true
Home Assistant components controlled by this property:
binary_sensor.mqtt
)mop
) Property, readable, retained
This handle reports whether the mop attachment is installed.
<TOPIC PREFIX>/<IDENTIFIER>/AttachmentStateAttribute/mop
Sample value:
false
Home Assistant components controlled by this property:
binary_sensor.mqtt
)watertank
) Property, readable, retained
This handle reports whether the water tank attachment is installed.
<TOPIC PREFIX>/<IDENTIFIER>/AttachmentStateAttribute/watertank
Sample value:
true
Home Assistant components controlled by this property:
binary_sensor.mqtt
)BatteryStateAttribute
) Node
Status attributes managed by this node:
level
) Property, readable, retained
<TOPIC PREFIX>/<IDENTIFIER>/BatteryStateAttribute/level
Sample value:
42
Home Assistant components controlled by this property:
sensor.mqtt
)status
) Property, readable, retained
<TOPIC PREFIX>/<IDENTIFIER>/BatteryStateAttribute/status
none
, charging
, discharging
, charged
)Sample value:
charging
StatusStateAttribute
) Node
Status attributes managed by this node:
Home Assistant components controlled by this node:
sensor.mqtt
)error
) Property, readable, retained
This property contains the current ValetudoRobotError (if any)
<TOPIC PREFIX>/<IDENTIFIER>/StatusStateAttribute/error
Sample value:
{
"severity": {
"kind": "none",
"level": "none"
},
"subsystem": "none",
"message": ""
}
error_description
) Property, readable, retained
<TOPIC PREFIX>/<IDENTIFIER>/StatusStateAttribute/error_description
Sample value:
No error
flag
) Property, readable, retained
<TOPIC PREFIX>/<IDENTIFIER>/StatusStateAttribute/flag
none
, zone
, segment
, spot
, target
, resumable
, mapping
)Sample value:
segment
Home Assistant components controlled by this property:
sensor.mqtt
)status
) Property, readable, retained
<TOPIC PREFIX>/<IDENTIFIER>/StatusStateAttribute/status
error
, docked
, idle
, returning
, cleaning
, paused
, manual_control
, moving
)Sample value:
cleaning
Cloud replacement for vacuum robots enabling local-only operation
View the Project on GitHub Hypfer/Valetudo
Newcomer Guide Why Valetudo? Why not Valetudo? Getting Started Supported Robots Rooting Essentials Buying Supported Robots
Implementation Overview Capabilities Overview Upgrading Firmware Updates
Valetudo Companion (Android) Valetudo Tray Companion Valeronoi Lovelace Valetudo Map Card I Can't Believe It's Not Valetudo node-red-contrib-valetudo Fun & Games Other Noteworthy Projects
MQTT Home Assistant Node-RED openHAB
FAQ Style Guide Troubleshooting