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:
- Xiaomi Vacuum Gen1
- Roborock Vacuum Gen2 S50/S51/S55
We recommend using the following firmware for the ongoing process (the current firmware on your device doesn't matter)
- Xiaomi Vacuum Gen1: FW v11_003468
- Roborock Vacuum Gen2 S50/S51/S55: FW v11_001782
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.
The local Interface
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.
The Cloud Interface
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.
How Valetudo works
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.
How the installation works
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.
There are a few dependencies required for building the image. Please refer to your Linux distributions documentation to find out how to install them.
- openssh (for ssh-keygen)
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 "firstname.lastname@example.org"
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://dustbuilder.xvm.mit.edu
Preparations for building the image
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
wget https://github ... 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://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://cdn.cnbj0.fds.api.mi-img.com/rubys/updpkg/v11_001748.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.
Creating the firmware image
To create the firmware image you should run the following commands:
mkdir image cd image sudo ../dustcloud/devices/xiaomi.vacuum/firmwarebuilder/imagebuilder.sh \ --firmware=../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.
Flashing the firmware image
After the successful build of the firmware image, we can tell the robot to download and flash it.
Using a VM to flash the image might fail with an error like
ERROR:miio.updater:No request was made..
You should than try to flash the image from your Host and not the VM (just copy the firmware image)
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 robots 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.
mirobo --ip 192.168.8.1 --token XXXXXXXXXXXXXXXX update-firmware image/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.
Connect your robot to your Wifi
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.