Skip to content
Erinome edited this page Dec 25, 2020 · 5 revisions

This is an attempt to create a description for MQTT API used in Valetudo RE. Note that it probably won't change over time.

Currently this list matches RE release 0.10.0.

Table of Contents

Input topics

Topic: valetudo/rockrobo/command

These are the simple commands, which you send directly as a plain text.

Payload Description
start Starts full cleaning or resumes paused cleaning of any type
stop Stops cleaning, note that in older firmware may require may need to pause first
pause Pauses running cleaning, as well as returning to base phase. Also cancels some other actions like gotos and spot cleanings
return_to_base Makes the device returning to charging station
clean_spot Runs cleaning around the current device location with high fan power
locate Makes the device loudly cry "I'm here!" to be easily located

Topic: valetudo/rockrobo/set_fan_speed

This allows to switch between different fan power options, just send the wanted payload.

Payload Description
whisper Most silent of possible fan speeds, supported only on Gen1 devices and Gen2 w/ firmware version before 2008
min Slow fan speed
medium Default and recommended fan speed
high Higher max speed
max The maximum possible fan speed, not recommended due to risks of damaging the fan engine
mop Special mode for mopping, some devices don't have it

Topic: valetudo/rockrobo/custom_command

Here are more advanced commands that have additional parameters and should be send as a JSON object. Please see Example payload column for.. er.. illustrative examples, true.

Command Parameters Description Example payload
zoned_cleanup zone_ids (array of strings or objects) Sends the device to zone cleaning. This parameter specifies the zones to be cleaned, may include both strings with plain zone names and objects like {"id":"name","repeats":2}, where id is zone name and repeats is number of iterations
{
"command": "zoned_cleanup",
"zone_ids": [
   "Foo",
   {
        "id": "Bar",
        "repeats": 2
   }
],
"afterCleaning": "Stop"
}
afterCleaning (string) Defines where the device should go when finishes, possible values Base, Stop or any pre-saved Goto Point name. This is optional
segmented_cleanup segment_ids (array of strings or ints) Sends the device to room cleaning. This parameter specifies the room to be cleaned, may include both strings with plain room names and ints of room numeric ids. Requires Gen2 devices or Gen2 with firmware version 2008+
{
"command": "segmented_cleanup",
"segment_ids": [
    16,
    "Room Name 1",
    18
],
"repeats": 2,
"afterCleaning": "Base"
}
repeats (int) Number of iterations for these rooms
afterCleaning (string) Defines where the device should go when finishes, possible values Base, Stop or any pre-saved Goto Point name. This is optional
go_to spot_id (string) Sends the device to the specified pre-saved spot location
{
"command": "go_to",
"spot_id": "Somewhere"
}
reset_consumable consumable (string) Reset specified consumable, which can be one of main_brush_work_time, side_brush_work_time, filter_work_time or sensor_dirty_time
{
"command": "reset_consumable",
"consumable": "main_brush_work_time"
}
store_map name (string) Saves current map with the specified name into valetudo local map archive
{
"command": "store_map",
"name": "Floor1"
}
load_map name (string) Loads map with the specified name from valetudo local map archive
{
"command": "load_map",
"name": "Floor2"
}
get_destinations   Publishes available zones, spots and rooms to valetudo/rockrobo/destinations topic
play_sound file (string) Plays local file using default sound player, which supports only wav files
{
"command": "play_sound",
"location": "http://192.168.1.10/audio.mp3",
"volume": 0.75
}
location (string) Plays either local or remote file. Requires preinstalled sox player
volume (float) Changes the volume for current playback. This is optional. Requires preinstalled sox player

Output topics

Topic: valetudo/rockrobo/state

This is a topic where general device state is published.

Field Description
state Current device state
battery_level Current battery level in percents
fan_speed Currently selected fan mode

Topic: valetudo/rockrobo/attributes

This is a topic where different device attributes are being published.

Field Description
mainBrush Current consumables timers values of each available category
sideBrush
filter
sensor
currentCleanTime Duration and area of currently running (or last finished) cleaning
currentCleanArea
cleanTime Summary duration and area of all the cleaning done by this device for all the time, as well as the number of distinct cleanings
cleanArea
cleanCount
last_run_stats The object containing summary information about last finished cleaning
bin_in_time Number of seconds the dustbin was in use during cleanings since the last removal
last_bin_out Time mark of the last time the dustbin was removed
last_bin_full Time mark of the last time the device send dustbin full notification
last_loaded_map The object containing information of the last manually loaded map
state Current device state in HA state terms
valetudo_state Current device state in firmware terms

Description of last_run_stats object:

Field Description
startTime Time mark of the beginning of this cleaning
endTime Time mark of the ending of this cleaning
duration Duration of this cleaning in seconds
area The area cleaned during this run
errorCode Code of an error if this cleaning was interrupted
errorDescription Readable description of an error
finishedFlag Boolean flag showing whether this cleaning was successfully finished or interrupted

Description of last_loaded_map object:

Field Description
name The user-defined name of the map that was loaded
date Time mark when this map was loaded

Description of valetudo_state object:

Field Description
id numerical device state in firmware codes
name Readable description of this state

Topic: valetudo/rockrobo/destinations

This is a special topic where available destinations the device knows about can be published by user request.

Field Description Example
spots All pre-saved spots in array of objects.
[{"name": "test", "coordinates": [25318,25258]}, {"name": "another", "coordinates": [25200,25600]}]
zones All pre-saved spots in array of objects.
[{"name": "My zone", "coordinates": [[20600,24800,21350,25200,1], [19600,21650,22400,24950,1]]}
rooms All available rooms in array of objects.
[{"name": "My room", "id":22}, {"name": "Area-51", "id":24}]

Spot coordinates array simply defines the (x,y) coordinates of a spot.

Zone coordinates is array of arrays, where each of inner array sequentially defines two pairs of points (upper left corner and lower right corner) and a number of iterations - in other words repeats how many times to clean this (sub-)zone.

Rooms objects simply shows user-defined room name and the digital id of the room.

Topic: valetudo/rockrobo/command_status

This is a special topic, where the device will post logs about how successive the requested commands were run, and may as well post errors occurred while doing MQTT operations.

Field Description
command Related command or function which initiated this entry
message Informative part or null if error happened
error Error description or null if there was no error
updated Time mark of the event