Provides a map changing functionality for rooted vacuum robots running Valetudo, controllable via MQTT. This project currently supports Dreame robots, see the supported model list below. A similar project for Xiaomi/Roborock vacuums (without further affiliation) can be found here: Thyraz/MapLoader.
The map changing process used in this project is based on observations and testing. It is not officially supported by Dreame or Valetudo. It's recommended to back up your map before using the maploader. Map changes should not be done during cleaning tasks but may be done when the robot is not docked.
The maploader is a program running on the robot. It communicates with a configured MQTT broker to manage map changes.
When a new map name is received, the robot backs up the current map, removes all map files, and loads the new map if it exists. The robot's relevant processes are then restarted to apply the new map.
In case of issues, backup archives for each map are available in /data/maploader.
The default map name is "main".
After map change, Valetudo restarts and may temporarily show an empty or the old map. This process can be sped up by starting the cleaning (and stopping it immediately).
Maploader now supports playing a WAV audio file for status changes. This feature is particularly useful for audible notifications when the map is loaded or changed. The audio file path and arguments for the aplay command are configurable via environment variables.
- WAV_FILE_MAP_LOADED: Set the path to the WAV file. You can use
{map_name}as a placeholder in the path, which will be replaced with the current map name. If the specific map's WAV file does not exist, a default file (with "default" replacing{map_name}) will be used. - WAV_APLAY_ARGS: Optionally set the arguments for the
aplaycommand. Defaults to-Dhw:0,0if not set.
Below is an example of the filenames for the WAV files, showcasing different audio files for different maps:
/data/maploader/wavmap_change_default.wavmap_change_livingroom.wavmap_change_main.wav
This can be used with this environment variable:
WAV_FILE_MAP_LOADED=/data/maploader/wav/map_change_{map_name}.wav
The wav directory includes a default file (map_change_default.wav) and specific files for different map names (e.g., livingroom, main).
The WAV file will be played automatically after map changes to provide auditory feedback.
| Topic | Publisher | Payload | Description |
|---|---|---|---|
valetudo/{identifier}/maploader/map |
Robot + Home | Map name | Maploader publishes the current map name to this topic after a map switch. Can be used to set the current map name without changing the active map. |
valetudo/{identifier}/maploader/map/set |
Home | Map name | Stores the active map and switches to the given map. A backup of the current map file is made before the active map is stored. If no map is stored under the given map name a blank map is loaded. |
valetudo/{identifier}/maploader/map/save |
Home | Map name | Saves the active map under the given name and switches to that map. A backup of the map file is made before it is overwritten. |
valetudo/{identifier}/maploader/map/load |
Home | Map name | Switches to the given map without storing the active map. If no map is stored under the given map name a blank map is loaded. |
valetudo/{identifier}/maploader/status |
Robot | see below | Maploader publishes its current status to this topic. |
The identifier is set in the MQTT settings in Valetudo.
The maploader status can change to the following value:
| Status | Description |
|---|---|
| idle | Maploader is started and awaiting commands |
| loading_map | The map is currently being loaded |
| saving_map | The map is currently being saved |
| starting_services | Waiting for robot services to restart |
| error | An error occurred, logs need to be checked |
| offline | The maploader process exited / lost the MQTT connection |
This project does not support Home Assistant auto discovery as I am using the sensor to define the list of possible maps. To allow Home Assistant to work with maploader add the section below to your configuration.yaml. To create a new map, just add a new value to the field and set the entity to that new value.
mqtt:
sensor:
- state_topic: valetudo/foo/maploader/status
name: "vacuum_maploader_status"
select:
- command_topic: valetudo/foo/maploader/map/set
state_topic: valetudo/foo/maploader/map
name: "vacuum_maploader_map"
options:
- "main"
- "second_floor"
The following models are known to work with the maploader:
| Model | binary |
|---|---|
| Dreame L10 Pro | maploader-arm64 |
| Dreame Z10 Pro | maploader-arm64 |
| Dreame D10S Pro | maploader-arm64 |
| Dreame L10s Ultra | maploader-arm64 |
| Dreame F9 | maploader-arm |
| Dreame D9 | maploader-arm |
| Dreame D9 Pro | maploader-arm |
| Dreame W10 | maploader-arm |
If your Dreame robot is not listed here, you need to find out the arch of your robot (e.g. with uname -m, where aarch64 -> ...-arm64 binary).
Please open an issue, if your Dreame robot is not listed here but works or you need assistance.
The binary must be placed in the /data folder and it needs to be started with the system.
Make sure that Valetudo is working and MQTT is also setup in Valetudo.
Open a SSH terminal
Download the binary: (check the supported robots section for the correct filename in the URL)
wget -O /data/maploader-binary https://github.com/pkoehlers/maploader/releases/latest/download/maploader-arm64
Add execution permissions:
chmod +x /data/maploader-binary
Open the postboot script:
vi /data/_root_postboot.sh
Search for the valetudo start block and add the maploader binary after the start of Valetudo so that it looks like this:
if [[ -f /data/valetudo ]]; then
VALETUDO_CONFIG_PATH=/data/valetudo_config.json /data/valetudo > /dev/null 2>&1 &
VALETUDO_CONFIG_PATH=/data/valetudo_config.json /data/maploader-binary > /dev/null 2>&1 &
fi
Reboot
The following things can be customized with environment variables:
| Variable | Default value | Description |
|---|---|---|
| VALETUDO_CONFIG_PATH | /data/valetudo_config.json | Path to the valetudo config file |
| MAPLOADER_RESTART_VALETUDO | Set to any value to restart Valetudo after map changes | |
| MAPLOADER_DIR | /data/maploader | Directory to store the maps and logs |
| DEFAULT_MAP_NAME | main | Name of the main map (for first use) |
| ROTATION_KEEP_MAPS | 5 | Number of map backups to keep per map |
| WAV_FILE_MAP_LOADED | Path to WAV file for audio notification (supports placeholders) | |
| WAV_APLAY_ARGS | -Dhw:0,0 | Arguments for the aplay command (audio playback) |
As mentioned this is only tested with the Dreame L10 Pro but other Dreame robots should work just fine. Currently, these files/directories are considered "map files":
/data/ri/data/map/data/DivideMap/data/config/ava/mult_map.json
Basically these are all the files that will be cleared by resetting the map via Valetudo.
Build the project with
env GOOS=linux GOARCH=arm64 go build -o maploader-binary