Metadata-Version: 2.4
Name: python-roborock
Version: 5.12.0
Summary: A package to control Roborock vacuums.
Project-URL: Repository, https://github.com/python-roborock/python-roborock
Project-URL: Documentation, https://python-roborock.readthedocs.io/
Author: Lash-L, allenporter
Author-email: humbertogontijo <humbertogontijo@users.noreply.github.com>
License-Expression: GPL-3.0-only
License-File: LICENSE
Keywords: homeassistant,roborock,vacuum
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries
Requires-Python: <4,>=3.11
Requires-Dist: aiohttp<4,>=3.8.2
Requires-Dist: aiomqtt<3,>=2.5.0
Requires-Dist: click-shell~=2.1
Requires-Dist: click>=8
Requires-Dist: construct<3,>=2.10.57
Requires-Dist: paho-mqtt<3.0.0,>=1.6.1
Requires-Dist: protobuf<8,>=6.31.1
Requires-Dist: pycryptodomex~=3.18; sys_platform == 'darwin'
Requires-Dist: pycryptodome~=3.18
Requires-Dist: pyrate-limiter<5,>=4.0.0
Requires-Dist: vacuum-map-parser-roborock
Description-Content-Type: text/markdown

# Roborock

<p align="center">
  <a href="https://pypi.org/project/python-roborock/">
    <img src="https://img.shields.io/pypi/v/python-roborock.svg?logo=python&logoColor=fff&style=flat-square" alt="PyPI Version">
  </a>
  <img src="https://img.shields.io/pypi/pyversions/python-roborock.svg?style=flat-square&logo=python&amp;logoColor=fff" alt="Supported Python versions">
  <img src="https://img.shields.io/pypi/l/python-roborock.svg?style=flat-square" alt="License">
    <a href="https://codecov.io/github/Python-roborock/python-roborock" >
  <img src="https://codecov.io/github/Python-roborock/python-roborock/graph/badge.svg?token=KEK4S3FPSZ" alt="Code Coverage"/>
 </a>
</p>


Roborock library for online and offline control of your vacuums.

## Installation

Install this via pip (or your favourite package manager):

`pip install python-roborock`

## Example Usage

See [examples/example.py](examples/example.py) for a more full featured example,
or the [API documentation](https://python-roborock.github.io/python-roborock/)
for more details.

Here is a basic example:

```python
import asyncio

from roborock.web_api import RoborockApiClient
from roborock.devices.device_manager import create_device_manager, UserParams


async def main():
    email_address = "youremailhere@example.com"
    web_api = RoborockApiClient(username=email_address)
    # Send a login code to the above email address
    await web_api.request_code()
    # Prompt the user to enter the code
    code = input("What is the code?")
    user_data = await web_api.code_login(code)

    # Create a device manager that can discover devices.
    user_params = UserParams(username=email_address, user_data=user_data)
    device_manager = await create_device_manager(user_params)
    devices = await device_manager.get_devices()

    # Get all vacuum devices. Each device generation has different capabilities
    # and APIs available so to find vacuums we filter by the v1 PropertiesApi.
    for device in devices:
        if not device.v1_properties:
            continue

        # The PropertiesAPI has traits different device commands such as getting
        # status, sending clean commands, etc. For this example we send a
        # command to refresh the current device status.
        status_trait = device.v1_properties.status
        await status_trait.refresh()
        print(status_trait)

asyncio.run(main())
```


## Functionality

The library interacts with devices through specific API properties based on the device protocol:

*   **Standard Vacuums (V1 Protocol)**: Most robot vacuums use this. Interaction is done through `device.v1_properties`, which contains traits like `status`, `consumables`, and `maps`. Use the `command` trait for actions like starting or stopping cleaning.
*   **Wet/Dry Vacuums & Washing Machines (A01 Protocol)**: Devices like the Dyad and Zeo use this. Interaction is done through `device.a01_properties` using `query_values()` and `set_value()`.

You can find detailed documentation for [Devices](https://python-roborock.github.io/python-roborock/roborock/devices/device.html) and [Traits](https://python-roborock.github.io/python-roborock/roborock/devices/traits.html).


## Supported devices

You can find what devices are supported
[here](https://python-roborock.readthedocs.io/en/latest/supported_devices.html).
Please note this may not immediately contain the latest devices.


## Acknowledgements

* Thanks to [@rovo89](https://github.com/rovo89) for [Login APIs gist](https://gist.github.com/rovo89/dff47ed19fca0dfdda77503e66c2b7c7).
* Thanks to [@PiotrMachowski](https://github.com/PiotrMachowski) for [Home-Assistant-custom-components-Xiaomi-Cloud-Map-Extractor](https://github.com/PiotrMachowski/Home-Assistant-custom-components-Xiaomi-Cloud-Map-Extractor).