Metadata-Version: 2.4
Name: xiaomi-vacuum
Version: 0.1.0
Summary: Local control for Xiaomi/Dreame robot vacuums via MIoT protocol
Author: Amir Ghasemi
License-Expression: MIT
Project-URL: Homepage, https://github.com/amirghm/Xiaomi-Vacuum-Controller
Project-URL: Issues, https://github.com/amirghm/Xiaomi-Vacuum-Controller/issues
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: python-miio>=0.5.12
Requires-Dist: requests>=2.28.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

# 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

```bash
pip install xiaomi-vacuum
```

## Usage

### Python

```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

```bash
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](https://github.com/PiotrMachowski/Xiaomi-cloud-tokens-extractor) to get your device token.

### Configuration

Create `~/.xiaomi-vacuum.json`:

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

Or set environment variables:

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

## Supported Devices

Any Xiaomi/Dreame vacuum with a MIoT spec on [miot-spec.org](https://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
