PyPI Version Supported Python versions License Code Coverage
Roborock library for online and offline control of your vacuums.
Install this via pip (or your favourite package manager):
pip install python-roborock
See examples/example.py for a more full featured example, or the API documentation for more details.
Here is a basic example:
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())
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 likestatus,consumables, andmaps. Use thecommandtrait 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_propertiesusingquery_values()andset_value().
You can find detailed documentation for Devices and Traits.
You can find what devices are supported here. Please note this may not immediately contain the latest devices.
- Thanks to @rovo89 for Login APIs gist.
- Thanks to @PiotrMachowski for Home-Assistant-custom-components-Xiaomi-Cloud-Map-Extractor.