-
-
Notifications
You must be signed in to change notification settings - Fork 74
MQTT API
Erinome edited this page Aug 25, 2022
·
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.8.
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 |
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 |
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"
}
OR
{
"command": "zoned_cleanup",
"zone_coordinates": [
{
"x1": 123,
"y1": 234,
"x2": 345,
"y2": 456
},
{
"x1": 567,
"y1": 678,
"x2": 789,
"y2": 890,
"repeats": 2
}
]
}
|
| zone_coordinates (array of objects) | Alternative way to specify zones to clean, you don't need to have predefined zones to use this. Just drop an array of zones which should be cleaned. Each zone is defined as object like {"x1": 123, "y1": 234, "x2": 345, "y2": 456, "repeats":2}, where coordinates correspond to upper left and lower right points of the zone and repeats is optional number of iterations. You can either specify zone_ids or zone_coordinates, if you specify both then only zone_ids would be used | ||
| 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"
}
OR
{
"command": "go_to",
"spot_coordinates": {"x": 123, "y": 123}
}
|
| spot_coordinates (object) | Alternative way to specify target to go to, you don't need to have a predefined spot to use this. Just drop an object like {"x1": 123, "y1": 123} and you are ready to go. You can either specify spot_id or spot_coordinates, if you specify both then only spot_id would be used | ||
| 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. Use a string none to stop currently running playback |
{
"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 | ||
| remote_control | angle (float) | Sends a RC mode command to the device. Starting and stopping RC mode is done automatically, you can try sending multiple commands in a row. This parameter defines the angle to turn at, zero means don't rotate. Applicable values are from -3.14 to 3.14 |
{
"command": "remote_control",
"angle": -1.3,
"velocity": 0.0,
"duration": 1000,
"startdelay": 7500
}
|
| velocity (float) | Defines the speed to move at, zero means don't move. Applicable values are from -0.3 to 0.3 | ||
| duration (int) | Defines for how long to operate in this mode in milliseconds. Probably makes sense only when moving, but who knows? | ||
| startdelay (int) | A workaround parameter which means for how long to wait in milliseconds before sending the first internal RC command after turning the RC mode on. We need this because it seems all RC commands sent when device isn't ready are being ignored. This is optional and default is 8 seconds. You can try lower values if you feel your device is faster than mine. |
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 |
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 |
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.
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 |