xiaomi-vacuum

Local control for Xiaomi and Dreame robot vacuums via the MIoT protocol.

If your vacuum gives you user ack timeout when you try to control it locally — this library fixes that. Newer models (2023+) dropped the classic miio protocol. This uses MIoT instead, the same protocol the Mi Home app uses.

Install

pip install xiaomi-vacuum

Usage

Python

from xiaomi_vacuum import XiaomiVacuum

vac = XiaomiVacuum("192.168.1.100", "your_32char_token", "xiaomi.vacuum.d109gl")

vac.start()
vac.stop()
vac.home()

status = vac.status()
print(status)

CLI

xiaomi-vacuum --ip 192.168.1.100 --token YOUR_TOKEN --model xiaomi.vacuum.d109gl status
xiaomi-vacuum --ip 192.168.1.100 --token YOUR_TOKEN --model xiaomi.vacuum.d109gl start

Setup

Get your token

Use Xiaomi Cloud Tokens Extractor to get your device token.

Configuration

Create ~/.xiaomi-vacuum.json:

{
    "token": "your_32char_token",
    "model": "xiaomi.vacuum.d109gl"
}

Or set environment variables:

export XIAOMI_VACUUM_TOKEN=*** XIAOMI_VACUUM_MODEL="xiaomi.vacuum.d109gl"

Supported Devices

Any Xiaomi/Dreame vacuum with a MIoT spec on miot-spec.org. The library fetches the spec automatically.

Tested:

• Xiaomi Robot Vacuum X20 Max (xiaomi.vacuum.d109gl)

How It Works

Newer Xiaomi vacuums dropped support for the classic miio RPC protocol. Commands like get_status and get_prop timeout with user ack timeout.

This library uses the MIoT action protocol instead — the same one the Mi Home app uses internally. It fetches the device spec from Xiaomi's official spec database and maps service/property IDs automatically.

License

MIT