How to Program a Xiaomi Robot Vacuum Cleaner: From Basic Setup to Custom Firmware

Robot vacuum cleaners Xiaomi long ceased to be simple cleaning assistants — they have turned into full-fledged smart devices with open programming capabilities. Alternative OS: Modern models (such as Roborock) S8 Pro Ultra, DreameBot X30 Ultra or Viomi V3) But without the right approach, even basic configuration through Mi Home can be difficult, not to mention working with Python scripts or firmware through the Mi Home. ADB.

In this guide, we will analyze all levels of programming of Xiaomi robot vacuums – from elementary schedule settings to deep customization through the use of a computer. API You will learn how to circumvent the limitations of standard software, what tools you will need to work with access tokens, and why some models (for example, Roborock based on the Internet) STM32) They allow much more freedom than the devices on the MT7688. Special attention will be paid to security: the wrong firmware can turn your vacuum cleaner into a “brick”, and open ports – into a tasty target for hackers.

If you've never programmed IoT devices, start with the first two sections, where we'll break down the basic concepts and official customization methods. API, Python libraries or alternative firmware. For convenience, we have assembled all critical commands, file paths and code examples into separate blocks that can be copied and adapted to your model.

1.Preparation: What to Know Before Programming

Before you start setting up, define your robot vacuum cleaner model and its iron platform, which is critical because programming methods for Rockchip devices are critical. RK3308 (Like DreameBot. D9) and STM32F4 (Roborock S5 Max) are fundamentally different. You can know the platform:

• 🔍 In the device documentation (see Hardware Specifications section).
• 🛠️ Disassembling the vacuum cleaner and looking at the marking on the board (requires accuracy!).
• 📱 Through the Mi Home app: go to Device Settings → About the device → Model.

The second key is the firmware version: Outdated versions (e.g., up to 3.5.8 for Roborock) may not support modern versions. API You can either have a vulnerability:

• 📲 In Mi Home: Device profile → Three points. → Firmware.
• 🖥️ Through SSH (If you have root access: Cat command /etc/version

⚠️ Note: Xiaomi vacuum cleaner robots with Viomi prefix (e.g. Viomi) V2) They often use proprietary protocols that are incompatible with standard Roborock libraries. Before buying or firmware, check for support for your model on forums like XDA Developers.

Also prepare the necessary tools:

2. Basic settings through Mi Home: schedule, zones, virtual walls

Even without deep programming, the official Mi Home app allows you to flexibly customize the vacuum cleaner behavior.

Cleaning schedules by time and conditions, unlike manual start-ups, schedules allow:

• ⏰ Start cleaning depending on the time of day (for example, only during the day when no one is home).
• 🌡️ Weather-related (via Xiaomi Weather integration).
• 🔄 Create chains of action (e.g., “vacuum first, then wash the floor»).

To set up the schedule:

1. Open Mi Home → Choose your vacuum cleaner.
2. Go to Cleanup. → Schedule.
3. Click Add and select the days of the week, time, type of cleaning.
4. In the Additional section, activate the option Auto Cleaning of the dust collector (available for models with a docking station).

Virtual walls and zones help to limit the area of cleaning without physical barriers, for example, you can prevent a vacuum cleaner from entering the children's room or the area with carpets.

1. In Mi Home, open the map of the room.
2. Press Edit. → Add a zone/wall.
3. Draw boundaries on a map and save.

⚠️ Attention: Virtual walls on Roborock models until 2021 may be reset after a firmware update.To avoid this, export the card manually through Settings → Map. → Save.

For advanced users, settings are available through assistant voices (such as Alice or Google Assistant) to connect the vacuum cleaner to the voice assistant:

1. In Mi Home, go to Profile → Settings → Voice Assistants.
2. Select the service (Yandex, Google, Siri) and log in.
3. Say a command like, "Alice, turn on the vacuum cleaner in the kitchen."

Check the connection of the vacuum cleaner to Wi-Fi (2.4 GHz)

Update the Mi Home app to the latest version

Make sure your vacuum cleaner is tied to your Xiaomi account

Download the map of the room (if not already created)-->

3. Obtaining access token: how to unlock API vacuum-driven

Programming through Python or third-party applications (such as Home Assistant) requires an access token, a unique key that allows you to send commands to the device. Officially, Xiaomi does not provide tokens to users, so they have to be extracted independently.

There are three main ways to get a token:

1. Through MITM-Proxies (for Android):
2. Through the script for iOS (bypassing restrictions):
3. Through the developer console (for the web version of Mi Home):

⚠️ Note: Access tokens are valid until the device is untied from the account or the firmware updates with a change in the security protocol. Store the token in a safe place (for example, in KeePass) and do not transfer it to third parties - this gives full control over your vacuum cleaner.

Example of the received token:

70:7f:2c:1c:4f:9a:7a:d8:6f:b1:5d:c4:3a:8f:ee:9b

To check the token’s performance, use the Python script:

from miio import Vacuum


vacuum = Vacuum(ip="192.168.1.100", token="YOUR_TOKEN_HERE")




print(vacuum.status)

If the script returns the device status (e.g., {'state': 8,'battery': 100}), the token is valid. DeviceException error means that the token is incorrect or the device is offline.

Programming through Python: Python-miio library and script examples

The python-miio library is Xiaomi’s most popular robot vacuum automation tool, and supports most models (including Roborock, Dreame, Viomi) and allows you to send commands over a local network.

Install the library:

pip install python-miio --upgrade

Basic script for vacuum control:

from miio import Vacuum


import time




Connection to the device



vacuum = Vacuum(ip="192.168.1.100", token="YOUR_TOKEN_HERE")




Major teams



vacuum.start # Start cleaning




time.sleep(10) #Passage 10 seconds




vacuum.pause # Suspend cleaning




vacuum.home #Go back to base




vacuum.status # Getting Status

A more complicated example is cleaning according to the schedule, taking into account the level of the battery:

from miio import Vacuum


import schedule




import time





def check_and_clean:




vacuum = Vacuum(ip="192.168.1.100", token="YOUR_TOKEN_HERE")




status = vacuum.status




if status.battery > 50: # If the charge is greater than 50%




vacuum.start




print("Cleaning has begun")




else:




print("charge too low")




Launch every day at 14:00



schedule.every.day.at("14:00").do(check_and_clean)





while True:




schedule.run_pending




time.sleep(60)

To work with maps of premises and cleaning areas, use advanced methods:

# Getting a card (requires firmware with support for API cards)


map_data = vacuum.get_map




print(map_data)




Cleaning in a specific area (coordinates in the format [x1, y1, x2, y2])



vacuum.clean_zone([18000, 22000, 22000, 26000])

⚠️ Attention: Coordinates of cleaning areas depend on the vacuum cleaner model and firmware version. S7 coordinate system starts at the lower left corner of the map (0,0), A for DreameBot. X30 — To get the exact values, export the card through the vacuum.get_map And study the data structure.

To integrate with Home Assistant, add configuration.yaml to the configuration:

vacuum:


- platform: xiaomi_miio




host: 192.168.1.100




token: YOUR_TOKEN_HERE

After that, the vacuum cleaner will appear in the Home Assistant interface as a full-fledged device that can be controlled through automation.

💡

If a Python script (suddenly interrupts), check the firewall settings on the router. Some models (such as TP-Link Archer) block frequent firewalls. UDP-query that Miio uses. Add IP Disable or disable DoS Protection.

5. Alternative firmware: Valetudo, OpenMiHome and the risks of custom firmware

Xiaomi’s official software has limitations: no local management without the cloud, closed API For new models, forced updates. Alternative firmware like Valetudo or OpenMiHome solves these problems, but installing them requires caution.

Valetudo is the most popular open source firmware. It supports:

• 🌐 Local management without the cloud Xiaomi.
• 📊 Advanced maps with the ability to edit zones.
• 🔧 Full access to API through REST or MQTT.
• 🛡️ Security: No forced data transfer to China.

Installation Valetudo is possible on the following models:

Instructions for installing Valetudo on Roborock S5:

1. Download the latest version of Valetudo from the official website.
2. Connect to the vacuum cleaner SSH (Logins/passwords for different models here).
3. Download the valetudo file to your device: scp valetudo root@192.168.1.100:/mnt/UDISK/
4. Make it executable: chmod +x /mnt/UDISK/valetudo
5. Add to autoload: echo"/mnt/UDISK/valetudo" >> /mnt/default/autostart.sh
6. Reboot the vacuum cleaner: reboot

After installation, Valetudo will be available at the address http://[IP_vacuumer]:8080. The interface allows:

• 🗺️ Edit maps in real time.
• 📡 Control the vacuum cleaner through MQTT.
• 🔄 Automation without the cloud.

⚠️ Warning: Installing alternative firmware will void Xiaomi’s warranty and may cause permanent damage to the device. S7 Make it impossible to restore through official tools. Before installation, back up the original firmware with the command: dd if=/dev/mtdblock0 of=/mnt/UDISK/backup.bin

OpenMiHome is another project, but it’s focused on integrating with Home Assistant and supports fewer models, and its main advantage is a simple web interface to manage Xiaomi devices without the cloud.

💡

Alternative firmware gives you full control of the vacuum cleaner, but it requires technical skills. If you only need local work without the cloud, you just need to set up a python-miio with a token. Valetudo is good for deep customization (for example, changing cleaning algorithms). + MQTT.

6. Advanced Features: Integration with Smart Home and Voice Assistants

A robot vacuum cleaner can be made part of the smart home ecosystem by linking it to Home Assistant, Node-RED, or voice assistants.

Integration with Home Assistant allows:

• 📅 Start cleaning under difficult conditions (e.g., “if no one is home and the battery is charged»).
• 🔄 Link the vacuum cleaner to other devices (e.g., “if the window is open, stop cleaning»).
• 📊 Visualize statistics of cleaning on the dashboard.

Example of automation in Home Assistant (automations.yaml file):

- alias: "Schedule cleaning with window check"


trigger:




platform: time




at:"15:00:00"




condition:




- condition: state




entity_id: binary_sensor.window_contact




state: "off" #Window closed




- condition: numeric_state




entity_id: sensor.roborock_battery




above: 50




action:




- service: vacuum.start




target:




entity_id: vacuum.roborock_s7

Voice control through Alice/Google Assistant is configured via Yandex IoT or Google Home:

1. In Mi Home, link the vacuum cleaner to the voice assistant (Settings section) → Voice assistants).
2. In the Assistant app (Alice or Google Home) add the device via Add → The device.
3. Set up routines (e.g., “Alice, start cleaning the kitchen”).

For advanced users, integration via Node-RED is available. Example flow for vacuum cleaner control:

1. Install the node-red-contrib-mi-home node.
2. Create a thread with a trigger (e.g. inject or inject) MQTT).
3. Add the mi-vacuum node and configure it with IP token.
4. Set up actions (e.g. start, pause, zone_clean).

Integration with the Telegram bot allows you to control the vacuum cleaner through the messenger.

import telebot


from miio import Vacuum





bot = telebot.TeleBot("YOUR_TELEGRAM_BOT_TOKEN")




vacuum = Vacuum(ip="192.168.1.100", token="YOUR_TOKEN_HERE")





@bot.message_handler(commands=['start'])




def start(message):




vacuum.start




bot.reply_to (message, "Vacuum cleaner starts cleaning!")





@bot.message_handler(commands=['stop'])




def stop(message):




vacuum.pause




bot.reply_to (message, "Vacuum is stopped").





bot.polling

⚠️ Note: When setting up remote access (for example, via Telegram or MQTT) Never open the vacuum cleaner ports directly to the Internet. VPN (For example, WireGuard or Cloudflare Tunnel for secure connectivity.

7. Problem Solving: Connection Errors, Setting Reset, Recovery

When programming Xiaomi robot vacuums, users often encounter common mistakes, and let's look at the most common ones and how to solve them.

Error: Unable to connect to the vacuum

• 🔌 Check that the vacuum cleaner and the Python script device are on the same network.
• 🔄 Restart the vacuum cleaner (hold the power button for 5 seconds).
• 📡 Make sure the token has not changed (check through Mi Home).
• 🛡️ Turn off the firewall on the router (sometimes it blocks) UDP-packet).

Mistake: "Invalid token"

• 🔑 Get a new token (the old one could expire).
• 📱 Re-attach the vacuum cleaner to your Xiaomi account.
• 🔄 Renovate the Python-miio library:

The vacuum cleaner is not returning to base

• 🧭 Check if the map is lost (recreate it in Mi Home).
• 🔋 Make sure the battery is at least 20 times charged%.
• 📡 Move the docking station to a more open location (minimum 1.5 m of free space in front).

After the firmware, the vacuum cleaner is not turned on ("brick")

• 🔌 Try resetting: Hold the power button for 10-15 seconds.
• 🖥️ Connect through UART (need USB-TTL adapter) and re-show the loader.
• 📧 Go to GitHub issue with error logs.

If the vacuum cleaner has stopped responding to commands after updating the firmware, try to roll back to the previous version.

1. Download the old firmware from the repository.
2. Connect the vacuum cleaner to the PC via USB.
3. Run the firmware through ADB: adb push firmware.bin /sdcard/ adb shell"flash_image misc /sdcard/firmware.bin"

⚠️ Warning: If a vacuum cleaner flashes red after a failed firmware and does not respond to the buttons, it means damage to the loader. JTAG Or you can go to a service center, and you can try it yourself and you can actually put the device out of action.

8 Security: How to Protect Your Vacuum from Hackers

Robot vacuum cleaners with Internet connection are a potential target for hackers