This guide will take you through the required steps to install the latest version of valetudo onto your rooted Roborock Vacuum. Please note that these instructions may or may not apply to any other version than the latest version of Valetudo.
If you’re reusing the folder structure of an old install, don’t forget to
git pull your dustcloud repo to get the latest firmwarebuilder
Currently, the following devices are supported:
We recommend using the following firmware for the ongoing process (the current firmware on your device doesn’t matter)
Before we get to how it’s done lets first take a second and talk about how it even works. There are two Interfaces to control the robot. Both are utilizing the miio protocol.
This is the interface used by the Mobile app to directly talk to the robot if it’s on the same network. It is also used to initially connect the robot to a Wifi Access Point since there are no input devices on the robot to enter Wifi or Xiaomi Account credentials. This process is called provisioning.
Authentication is done via a token which on unprovisioned robots is available by simply asking for it. After a reboot, the unprovisioned robot opens up an unencrypted Wifi Access Point where the user can aquire said token and configure wifi credentials. As a security measure, this Wifi Access Point will vanish 30 Minutes after reboot so if you can’t find it try rebooting the device. It’s always possible to unprovision the robot by shortly pressing the reset button. Then, your token will be available again.
As soon as the robot is connected to a Wi-Fi Access Point, it tries to connect its cloud servers. Communication is encrypted via a Pre-shared Key which is programmed at the factory. There’s also a unique Device ID called did to uniquely identify the robot.
Valetudo (currently) uses both previously described interfaces to control the robot. To be able to use the cloud interface, traffic is redirected to Valetudo which pretends to be the official cloud all while running on the robot itself. Since Roborock implemented some countermeasures against this, it is required to utilize the robots firewall to pretend that Valetudo is the official cloud. This may or may not change in the future if someone finds a better way.
Roborock uses encrypted but unsigned fimware images. The encryption key however was found by Security/IoT Researcher Dennis Giese, which enables us to build custom firmware images for this device and just flash them via the official firmware upgrade interface. Basically we’re just adding another service to the robots OS. No magic here.
Since we don’t have a license to redistribute modified firmware images, the user has to download the firmware image from the manufacturer and patch it by themselves. For this, a Linux based operating system is required, since we need to mount the ext4 file System image of the firmware.
Sadly, neither OSX nor WSL (the Windows Subsystem for Linux) contain ext4 drivers so you definitely need some kind of Linux installation. A VM should be sufficient to build the firmware image, though.
And you need WiFi hardware in your computer because initially you have to connect directly to the Robot-Hotspot to deploy the firmware.
There are a few dependencies required for building the image. Please refer to your Linux distributions documentation to find out how to install them.
If you plan on being able to connect to the robot via SSH, you will need a public/private ssh keypair. This is not required to run valetudo. It’s useful to fetch logs and assist the development if you encounter any bugs, though.
If you do not have a keypair yet, you can generate one with the following command
ssh-keygen -t ed25519 -C "email@example.com"
Per default, the generated keys will be created in
If you choose to create the keys in another location, remember your chosen location for later.
If you just need a basic Valetudo enabled Firmware image, you can skip the Image Building steps here by using Dennis’s Dustbuilder: https://builder.dontvacuum.me/
Create a new directory for your work
mkdir rockrobo cd rockrobo
Clone the dustcloud repository (until imagebuilder > 0.1 is available)
git clone https://github.com/dgiese/dustcloud.git
Create a valetudo directory
mkdir valetudo pushd valetudo
Download the latest valetudo binary from https://github.com/Hypfer/Valetudo/releases/latest
wget https://github.com/Hypfer/Valetudo/releases/latest/download/valetudo mkdir deployment pushd deployment wget https://github.com/Hypfer/Valetudo/raw/master/deployment/valetudo.conf mkdir etc pushd etc wget https://github.com/Hypfer/Valetudo/raw/master/deployment/etc/hosts wget https://github.com/Hypfer/Valetudo/raw/master/deployment/etc/rc.local popd popd popd
Create firmware directory
mkdir firmware pushd firmware
Download the latest firmware (e.g. v001792)
https://cdn.awsbj0.fds.api.mi-img.com/updpkg/[package name] https://cdn.awsde0.fds.api.mi-img.com/updpkg/[package name] Example: https://cdn.awsbj0.fds.api.mi-img.com/updpkg/v11_003468.fullos.pkg
https://dustbuilder.xvm.mit.edu/pkg/s5/[package name] https://cdn.awsbj0.fds.api.mi-img.com/rubys/updpkg/[package name] https://cdn.cnbj2.fds.api.mi-img.com/rubys/updpkg/[package name] https://cdn.cnbj0.fds.api.mi-img.com/rubys/updpkg/[package name] https://cdn.awsde0.fds.api.mi-img.com/rubys/updpkg/[package name] Example: https://dustbuilder.xvm.mit.edu/pkg/s5/v11_001886.fullos.pkg
If you followed the above commands, your
rockrobo directory structure should now look like this:
tree -L 2 rockrobo/ rockrobo/ ├── dustcloud │ ├── cloudprotocol.pdf │ ├── devices │ ├── docker │ ├── dummycloud │ ├── dustcloud │ ├── LICENSE │ ├── Pipfile │ ├── Pipfile.lock │ ├── presentations │ └── README.md ├── firmware │ └── v11_001712.pkg └── valetudo ├── deployment │ ├── valetudo.conf │ └── etc │ ├── hosts │ └── rc.local └── valetudo
Next, we can create the firmware image.
To create the firmware image you should run the following commands while changing the name of the firmware file (after ‘firmware=’) to the one you downloaded:
cd firmware sudo ../dustcloud/devices/xiaomi.vacuum/firmwarebuilder/imagebuilder.sh \ --firmware=v11_001748.fullos.pkg \ --public-key=$HOME/.ssh/id_ed25519.pub \ --valetudo-path=../valetudo \ --disable-firmware-updates \ --ntpserver=192.168.178.1 \ --replace-adbd
Here you need now to remember the location of your generated public ssh-key,
id_ed25519.pub. If you don’t have a public key yet, take a look at the Prerequisites section.
Please note that you need to replace
v11_001748.pkg with the filename of the firmware you have downloaded.
Note that not all options are required. However if your router runs a ntp server you should use it. Also I would recommend to replace adbd so in case something goes really wrong you can still access it via USB.
After the successful build of the firmware image, we can tell the robot to download and flash it.
First, we need to create a virtual environment for it in python. For this the following packages need to be installed:
cd .. mkdir flasher cd flasher python3 -m venv venv
and install the required miio python packages:
source venv/bin/activate pip3 install wheel pip3 install python-miio cd ..
Connect to your robot’s Wi-Fi Access Point and run the following command to aquire your token:
mirobo --debug discover --handshake true
If your robot doesn’t show up check if you have multiple connected network interfaces. Either disable all other (those not connected to your robots Wi-Fi) or use a VM which you explicitly connect to your hosts Wi-Fi interface. Another possibility is an internal firewall blocking it. On RedHat-based Linux systems using Firewalld (CentOS, Fedora, etc.), make sure the firewall zone for your connection to the robot’s Wi-Fi Access Point is set to “trusted” instead of “public”.
mirobo --ip 192.168.8.1 --token XXXXXXXXXXXXXXXX update-firmware --ip YOUR_IP_ADDRESS firmware/output/v11_001748.fullos.pkg
Please note that you need to replace
v11_001748.fullos.pkg with the filename of the firmware image you have built. If you’re upgrading Valetudo to a new version, you need to replace
192.168.8.1 with the robot’s current IP address. Also please keep the distance between your Wi-Fi antenna and your robot as short as possible or the connection might get lost.
After the successful transfer of the image to the robot, the robot will start flashing the image. This will take about 5~10 minutes. After the process is done, the robot will state that the update was successful.
You should then reboot the Robot either via ssh command
ssh firstname.lastname@example.org and typing
reboot or simply by taking it out of dock an push the ON switch to prevent valetudo stuck on LOADING STATE???
To connect the robot to your home Wifi, just connect to http://192.168.8.1 and use Valetudos settings dialog to enter your wifi credentials. Please note that only WPA2-PSK is supported. After updating the Wifi settings, you should reboot your robot.
You need to get the IP of your robot (e.g. from your router) and connect to it using your browser e.g. http://192.168.Y.Z
If you’re upgrading Valetudo to a new version, you don’t need to unprovision your robot since you don’t need to discover your token via handshake. Just open up Valetudo and use the settings page. Other than that it’s basically the same process as the initial installation.